forked from 0x2620/oxjs
prototype of a documentation page
This commit is contained in:
rolux
parent
a6ed310087
commit
b1d171282c
8 changed files with 476 additions and 85 deletions
179
source/Ox.js
179
source/Ox.js
|
|
@ -1,12 +1,14 @@
|
|||
// vim: et:ts=4:sw=4:sts=4:ft=js
|
||||
// todo: check http://ejohn.org/blog/ecmascript-5-strict-mode-json-and-more/
|
||||
|
||||
// OxJS (c) 2007-2011 Ox2620, dual-licensed (GPL/MIT), see oxjs.org for details
|
||||
|
||||
// todo: check http://ejohn.org/blog/ecmascript-5-strict-mode-json-and-more/
|
||||
// also see https://github.com/tlrobinson/narwhal/blob/master/lib/util.js
|
||||
|
||||
|
||||
/*@
|
||||
Ox <f> The Ox object
|
||||
See Ox.wrap for details.
|
||||
Ox <f> The <code>Ox</code> object
|
||||
See <code>Ox.wrap</code> for details.
|
||||
(value) -> <o> wrapped value
|
||||
value <*> any value
|
||||
@*/
|
||||
|
|
@ -51,10 +53,11 @@ Ox.KEYS = {
|
|||
85: 'u', 86: 'v', 87: 'w', 88: 'x', 89: 'y', 90: 'z',
|
||||
// fixme: this is usually 91: window.left, 92: window.right, 93: select
|
||||
91: 'meta.left', 92: 'meta.right', 93: 'meta.right',
|
||||
96: '0.numpad', 97: '1.numpad', 98: '2.numpad', 99: '3.numpad',
|
||||
100: '4.numpad', 101: '5.numpad', 102: '6.numpad', 103: '7.numpad',
|
||||
104: '8.numpad', 105: '9.numpad', 106: 'asterisk.numpad', 107: 'plus.numpad',
|
||||
109: 'minus.numpad', 108: 'enter.numpad', 110: 'dot.numpad', 111: 'slash.numpad',
|
||||
96: '0.numpad', 97: '1.numpad', 98: '2.numpad',
|
||||
99: '3.numpad', 100: '4.numpad', 101: '5.numpad',
|
||||
102: '6.numpad', 103: '7.numpad', 104: '8.numpad', 105: '9.numpad',
|
||||
106: 'asterisk.numpad', 107: 'plus.numpad', 109: 'minus.numpad',
|
||||
108: 'enter.numpad', 110: 'dot.numpad', 111: 'slash.numpad',
|
||||
112: 'f1', 113: 'f2', 114: 'f3', 115: 'f4', 116: 'f5',
|
||||
117: 'f6', 118: 'f7', 119: 'f8', 120: 'f9', 121: 'f10',
|
||||
122: 'f11', 123: 'f12', 124: 'f13', 125: 'f14', 126: 'f15', 127: 'f16',
|
||||
|
|
@ -89,7 +92,7 @@ Ox.PATH = Array.prototype.slice.apply(
|
|||
).filter(function(element) {
|
||||
return /Ox\.js$/.test(element.src);
|
||||
})[0].src.replace('Ox.js', '');
|
||||
//@ Ox.PREFIXES <arr> ['K', 'M', 'G', 'T', 'P']
|
||||
//@ Ox.PREFIXES <[str]> <code>['K', 'M', 'G', 'T', 'P']</code>
|
||||
Ox.PREFIXES = ['K', 'M', 'G', 'T', 'P'];
|
||||
//@ Ox.SYMBOLS <obj> Unicode characters for symbols
|
||||
Ox.SYMBOLS = {
|
||||
|
|
@ -117,7 +120,7 @@ Ox.SYMBOLS = {
|
|||
CLOSE: '\u2715', BALLOT: '\u2717', WINDOWS: '\u2756',
|
||||
EDIT: '\uF802', CLICK: '\uF803', APPLE: '\uF8FF'
|
||||
};
|
||||
//@ Ox.TYPES <[str]> list of types, as returned by Ox.type()
|
||||
//@ Ox.TYPES <[str]> list of types, as returned by <code>Ox.type()</code>
|
||||
Ox.TYPES = [
|
||||
'Arguments', 'Array', 'Boolean', 'Date', 'Element', 'Function', 'Infinity',
|
||||
'NaN', 'Null', 'Number', 'Object', 'RegExp', 'String', 'Undefined'
|
||||
|
|
@ -143,13 +146,13 @@ Core functions
|
|||
Ox.doc <f> Generates documentation for annotated JavaScript
|
||||
(source) <a> Array of documentation objects
|
||||
source <s> JavaScript source code
|
||||
> Ox.doc("//@ Ox.foo <s> bar")
|
||||
[{"name": "Ox.foo", "summary": "bar", "type": "string"}]
|
||||
> Ox.doc("//@ Ox.foo <string> just some string")
|
||||
[{"name": "Ox.foo", "summary": "just some string", "type": "string"}]
|
||||
@*/
|
||||
|
||||
Ox.doc = (function() {
|
||||
var re = {
|
||||
item: /^(.+) <(.+)> (.+)$/,
|
||||
item: /^(.+?) <(.+?)> (.+)$/,
|
||||
multiline: /^\/\*\@.*?\n([\w\W]+)\n.*?\@\*\/$/,
|
||||
script: /\n(\s*<script>s*\n[\w\W]+\n\s*<\/script>s*)/g,
|
||||
singleline: /^\/\/@\s*(.*?)\s*$/,
|
||||
|
|
@ -157,29 +160,47 @@ Ox.doc = (function() {
|
|||
usage: /\(.*?\)/
|
||||
},
|
||||
types = {
|
||||
b: 'boolean', d: 'date', e: 'element',
|
||||
f: 'function', n: 'number', o: 'object',
|
||||
r: 'regexp', s: 'string', u: 'undefined',
|
||||
'*': 'any', '!': 'event'
|
||||
a: 'array', b: 'boolean', d: 'date',
|
||||
e: 'element', f: 'function', n: 'number',
|
||||
o: 'object', r: 'regexp', s: 'string',
|
||||
u: 'undefined', '*': 'any', '!': 'event'
|
||||
}
|
||||
return function(source) {
|
||||
var blocks = [],
|
||||
items = [],
|
||||
tokens = [];
|
||||
Ox.tokenize(source).forEach(function(token) {
|
||||
var match;
|
||||
token.source = source.substr(token.offset, token.length);
|
||||
if (token.type == 'comment' && (match =
|
||||
re.multiline(token.source) || re.singleline(token.source)
|
||||
)) {
|
||||
blocks.push(match[1]);
|
||||
tokens.push([]);
|
||||
} else if (tokens.length) {
|
||||
tokens[tokens.length - 1].push(token);
|
||||
}
|
||||
});
|
||||
/*
|
||||
var blocks = Ox.map(Ox.tokenize(source), function(token) {
|
||||
// filter out tokens that are not comments
|
||||
// or don't match the doc comment pattern
|
||||
var match;
|
||||
token.source = source.substr(token.offset, token.length);
|
||||
return token.type == 'comment' && (match =
|
||||
re.multiline(token.source) || re.singleline(token.source)
|
||||
) ? match[1] : null;
|
||||
}),
|
||||
items = [];
|
||||
blocks.forEach(function(block) {
|
||||
*/
|
||||
blocks.forEach(function(block, i) {
|
||||
var item, lastItem,
|
||||
lines = block
|
||||
.replace(re.script, encodeLinebreaks)
|
||||
.replace(re.test, encodeLinebreaks)
|
||||
.split('\n');
|
||||
.replace(re.script, encodeLinebreaks)
|
||||
.replace(re.test, encodeLinebreaks)
|
||||
.split('\n');
|
||||
// create a tree and parse its root node
|
||||
item = parseNode(parseTree(lines));
|
||||
item = Ox.extend(parseNode(parseTree(lines)), {source: tokens[i]});
|
||||
if (/^[A-Z]/.test(item.name)) {
|
||||
items.push(item);
|
||||
} else {
|
||||
|
|
@ -266,7 +287,8 @@ Ox.doc = (function() {
|
|||
var lines = decodeLinebreaks(str).split('\n');
|
||||
return {
|
||||
statement: lines[0].substr(2),
|
||||
result: JSON.parse(lines[1].trim())
|
||||
// result: JSON.parse(lines[1].trim())
|
||||
result: lines[1].trim()
|
||||
};
|
||||
}
|
||||
function parseTree(lines) {
|
||||
|
|
@ -332,7 +354,7 @@ Ox.doc = (function() {
|
|||
str = str.substr(1, str.length - 2) : str;
|
||||
}
|
||||
function wrap(str) {
|
||||
return isArray ? 'array[' + str + 's]' : str;
|
||||
return isArray ? '[' + str + ']' : str;
|
||||
}
|
||||
return ret;
|
||||
}
|
||||
|
|
@ -375,7 +397,7 @@ Ox.getset <f> Generic getter and setter function
|
|||
for every key/value pair that was added or modified
|
||||
# Arguments ----------------------------------------------------------------
|
||||
options <obj> Options object (key/value pairs)
|
||||
args <[*]> The arguments "array" of the caller function
|
||||
args <arr> The arguments "array" of the caller function
|
||||
callback <fun> Callback function
|
||||
The callback is called for every key/value pair that was added or
|
||||
modified.
|
||||
|
|
@ -530,15 +552,13 @@ Ox.print <f> Prints its arguments to the console
|
|||
@*/
|
||||
|
||||
Ox.print = function() {
|
||||
if (window.console) {
|
||||
var args = Ox.makeArray(arguments),
|
||||
date = new Date();
|
||||
args.unshift(
|
||||
Ox.formatDate(date, '%H:%M:%S.') + (+date).toString().substr(-3),
|
||||
arguments.callee.caller.name || '(anonymous)'
|
||||
);
|
||||
window.console.log.apply(window.console, args);
|
||||
}
|
||||
var args = Ox.makeArray(arguments),
|
||||
date = new Date();
|
||||
args.unshift(
|
||||
Ox.formatDate(date, '%H:%M:%S.') + (+date).toString().substr(-3),
|
||||
arguments.callee.caller.name || '(anonymous)'
|
||||
);
|
||||
window.console && window.console.log.apply(window.console, args);
|
||||
return args.join(' ');
|
||||
};
|
||||
|
||||
|
|
@ -601,14 +621,16 @@ Array and Object functions
|
|||
================================================================================
|
||||
*/
|
||||
|
||||
Ox.avg = function(obj) {
|
||||
/***
|
||||
returns the average of an array's values, or an object's properties
|
||||
>>> Ox.avg([-1, 0, 1])
|
||||
/*@
|
||||
Ox.avg <f> returns the average of an array's values, or an object's properties
|
||||
(collection) -> <n> average
|
||||
collection <[n]|o> An array or object with numerical values
|
||||
> Ox.avg([-1, 0, 1])
|
||||
0
|
||||
>>> Ox.avg({a: 1, b: 2, c: 3})
|
||||
> Ox.avg({a: 1, b: 2, c: 3})
|
||||
2
|
||||
***/
|
||||
@*/
|
||||
Ox.avg = function(obj) {
|
||||
return Ox.sum(obj) / Ox.len(obj);
|
||||
};
|
||||
|
||||
|
|
@ -764,6 +786,20 @@ Ox.flatten = function(arr) {
|
|||
return ret;
|
||||
}
|
||||
|
||||
/*@
|
||||
Ox.forEach <f> forEach loop
|
||||
<code>Ox.forEach()</code> loops over arrays, objects and strings.
|
||||
Returning <code>false</code> from the iterator function acts like a
|
||||
<code>break</code> statement (unlike <code>[].forEach()</code>, like
|
||||
<code>$.each()</code>). The arguments of the iterator function are
|
||||
<code>(value, key)</code> (like <code>[].forEach()</code>, unlike
|
||||
<code>$.each()</code>).
|
||||
(collection, callback) <a|o|s> The collection
|
||||
collection <a|o|s> An array, object or string
|
||||
callback <f> Callback function
|
||||
value <*> Value
|
||||
key <n|s> Key
|
||||
@*/
|
||||
Ox.forEach = function(obj, fn) {
|
||||
/*
|
||||
Ox.forEach() works for arrays, objects and strings,
|
||||
|
|
@ -1238,15 +1274,18 @@ Color functions
|
|||
================================================================================
|
||||
*/
|
||||
|
||||
Ox.hsl = function(rgb) {
|
||||
/*
|
||||
>>> Ox.hsl([0, 0, 0])
|
||||
/*@
|
||||
Ox.hsl <f> Takes RGB values and returns HSL values
|
||||
(rgb) <[n]> HSL values
|
||||
rgb <[n]> RGB values
|
||||
> Ox.hsl([0, 0, 0])
|
||||
[0, 0, 0]
|
||||
>>> Ox.hsl([255, 255, 255])
|
||||
> Ox.hsl([255, 255, 255])
|
||||
[0, 0, 1]
|
||||
>>> Ox.hsl([0, 255, 0])
|
||||
> Ox.hsl([0, 255, 0])
|
||||
[120, 1, 0.5]
|
||||
*/
|
||||
@*/
|
||||
Ox.hsl = function(rgb) {
|
||||
rgb = rgb.map(function(v) {
|
||||
return v / 255;
|
||||
});
|
||||
|
|
@ -1274,15 +1313,19 @@ Ox.hsl = function(rgb) {
|
|||
return hsl;
|
||||
};
|
||||
|
||||
Ox.rgb = function(hsl) {
|
||||
/*
|
||||
>>> Ox.rgb([0, 0, 0])
|
||||
/*@
|
||||
Ox.rgb <f> Takes HSL values and returns RGB values
|
||||
(hsl) <[n]> RGB values
|
||||
hsl <[n]> HSL values
|
||||
> Ox.rgb([0, 0, 0])
|
||||
[0, 0, 0]
|
||||
>>> Ox.rgb([0, 0, 1])
|
||||
> Ox.rgb([0, 0, 1])
|
||||
[255, 255, 255]
|
||||
>>> Ox.rgb([120, 1, 0.5])
|
||||
> Ox.rgb([120, 1, 0.5])
|
||||
[0, 255, 0]
|
||||
*/
|
||||
@*/
|
||||
|
||||
Ox.rgb = function(hsl) {
|
||||
hsl[0] /= 360;
|
||||
var rgb = [0, 0, 0],
|
||||
v1, v2, v3;
|
||||
|
|
@ -1328,11 +1371,11 @@ Date functions
|
|||
Ox.getDateInWeek <f> Get the date that falls on a given weekday in the same week
|
||||
# Usage
|
||||
(date, weekday) -> <dat> Date
|
||||
(date, weekday, utc) -> <dat> UTC Date
|
||||
(date, weekday, utc) -> <dat> Date
|
||||
# Arguments
|
||||
date <d> Date
|
||||
weekday <n|s> 1-7 (Monday-Sunday) or name, full ("Monday") or short ("Sun")
|
||||
utc <b> if true, all dates are UTC
|
||||
utc <b> If true, all dates are UTC
|
||||
# Examples
|
||||
> Ox.formatDate(Ox.getDateInWeek(new Date("January 1 2000"), "Sunday"), "%A, %B %e, %Y")
|
||||
"Sunday, January 2, 2000"
|
||||
|
|
@ -1356,15 +1399,24 @@ Ox.getDateInWeek = function(date, weekday, utc) {
|
|||
return Ox.setDate(date, Ox.getDate(date, utc) - sourceWeekday + targetWeekday, utc);
|
||||
}
|
||||
|
||||
Ox.getDayOfTheYear = function(date, utc) {
|
||||
/*
|
||||
>>> Ox.getDayOfTheYear(new Date("12/31/2000"))
|
||||
/*@
|
||||
Ox.getDayOfTheYear <f> Get the day of the year for a given date
|
||||
# Usage
|
||||
(date) -> <d> Date
|
||||
(date, utc) -> <d> Date
|
||||
# Arguments
|
||||
date <d> Date
|
||||
utc <b> If true, all dates are UTC
|
||||
# Examples
|
||||
> Ox.getDayOfTheYear(new Date("12/31/2000"))
|
||||
366
|
||||
>>> Ox.getDayOfTheYear(new Date("12/31/2002"))
|
||||
> Ox.getDayOfTheYear(new Date("12/31/2002"))
|
||||
365
|
||||
>>> Ox.getDayOfTheYear(new Date("12/31/2004"))
|
||||
> Ox.getDayOfTheYear(new Date("12/31/2004"))
|
||||
366
|
||||
*/
|
||||
@*/
|
||||
|
||||
Ox.getDayOfTheYear = function(date, utc) {
|
||||
date = Ox.makeDate(date);
|
||||
var month = Ox.getMonth(date, utc),
|
||||
year = Ox.getFullYear(date, utc);
|
||||
|
|
@ -1607,7 +1659,7 @@ Ox.documentReady = (function() {
|
|||
}());
|
||||
|
||||
/*@
|
||||
Ox.Element <f> Generic HTML element, mimics jQuery
|
||||
Ox.element <f> Generic HTML element, mimics jQuery
|
||||
(str) -> <o> Element object
|
||||
str <s> Tagname ('<tagname>') or selector ('tagname', '.classname', '#id')
|
||||
> Ox.element("<div>").addClass("red").addClass("red")[0].classname
|
||||
|
|
@ -1638,7 +1690,7 @@ Ox.element = function(str) {
|
|||
return this;
|
||||
},
|
||||
/*@
|
||||
append() <f> Appends another element to this element
|
||||
append <f> Appends another element to this element
|
||||
(element) -> <o> This element
|
||||
element <o> Another element
|
||||
@*/
|
||||
|
|
@ -2751,7 +2803,7 @@ Ox.parseHTML = (function() {
|
|||
return function(html, tags, wikilinks) {
|
||||
var matches = [],
|
||||
tags = tags || defaultTags;
|
||||
html = Ox.clean(html);
|
||||
// html = Ox.clean(html); fixme: can this be a parameter?
|
||||
if (tags.indexOf('[]') > -1) {
|
||||
html = html.replace(/\[(https?:\/\/.+?) (.+?)\]/gi, '<a href="$1">$2</a>');
|
||||
tags = tags.filter(function(tag) {
|
||||
|
|
@ -3374,7 +3426,8 @@ Ox.tokenize = (function() {
|
|||
}
|
||||
tokenize[type]();
|
||||
tokens.push({
|
||||
source: source.substr(start, cursor - start),
|
||||
length: cursor - start,
|
||||
offset: start,
|
||||
type: type,
|
||||
});
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue