From 1b08732fa77d02cd442da37e41d035983b2311eb Mon Sep 17 00:00:00 2001
From: j <0x006A@0x2620.org>
Date: Wed, 23 May 2012 01:17:17 +0200
Subject: [PATCH] - add loadAsync and use in Ox.loadFile, Ox.getJSON - add
 Ox.getJSONP - fix Ox.parseHTML - fix Ox.Doc - add more documentation

---
 source/Ox.UI/js/List/Ox.TreeList.js |   6 +-
 source/Ox/js/Array.js               |   3 +-
 source/Ox/js/Collection.js          |  66 ++++++-----------
 source/Ox/js/DOM.js                 |  11 +--
 source/Ox/js/HTML.js                |   2 +-
 source/Ox/js/JavaScript.js          |   2 +-
 source/Ox/js/Math.js                |   8 +-
 source/Ox/js/Request.js             | 111 +++++++++++++++++-----------
 8 files changed, 106 insertions(+), 103 deletions(-)

diff --git a/source/Ox.UI/js/List/Ox.TreeList.js b/source/Ox.UI/js/List/Ox.TreeList.js
index ebcb291a..806f40e4 100644
--- a/source/Ox.UI/js/List/Ox.TreeList.js
+++ b/source/Ox.UI/js/List/Ox.TreeList.js
@@ -47,7 +47,7 @@ Ox.TreeList = function(options, self) {
                 max: self.options.max,
                 min: self.options.min,
                 unique: 'id'
-            }, Ox.copy(self))
+            }, Ox.clone(self))
             .addClass('OxTextList OxTreeList')
             .css({
                 width: self.options.width + 'px',
@@ -160,8 +160,8 @@ Ox.TreeList = function(options, self) {
         if (type == 'array' || type == 'object') {
             ret.title += Ox.toTitleCase(type)
                 + ' <span class="OxLight">[' + Ox.len(value) + ']</span>';
-            ret.items = Ox.sort(Ox.keys(value).map(function(k) {
-                return parseData(k, value[k]);
+            ret.items = Ox.sort(Ox.map(value, function(v, k) {
+                return parseData(k, v);
             }));
         } else {
             ret.title += (
diff --git a/source/Ox/js/Array.js b/source/Ox/js/Array.js
index 3288efe3..91a46ec5 100644
--- a/source/Ox/js/Array.js
+++ b/source/Ox/js/Array.js
@@ -344,7 +344,6 @@ Ox.flatten <f> Flattens an array
     [1, 2, 3, 2, 1]
 @*/
 Ox.flatten = function(arr) {
-    // fixme: can this work for objects too?
     var ret = [];
     arr.forEach(function(val) {
         if (Ox.isArray(val)) {
@@ -579,4 +578,4 @@ Ox.zip = function() {
         });
     });
     return arr;
-};
\ No newline at end of file
+};
diff --git a/source/Ox/js/Collection.js b/source/Ox/js/Collection.js
index 5c3f3265..1c5fce29 100644
--- a/source/Ox/js/Collection.js
+++ b/source/Ox/js/Collection.js
@@ -188,8 +188,8 @@ Ox.forEach = function(col, fn, that) {
             }
         } else {
             for (i = 0; i < col.length; i++) {
-                // fn.call(that, col[i], i, col);
-                if (fn.call(that, col[i], i, col) === false) {
+                // i in col && fn.call(that, col[i], i, col);
+                if (i in col && fn.call(that, col[i], i, col) === false) {
                     console.warn('Returning false in Ox.forEach is deprecated.')
                     break;
                 }
@@ -304,8 +304,12 @@ Ox.indexOf = function(col, fn) {
     return index == col.length ? -1 : index;
 };
 
-// FIXME: use this instead of `Ox.filter(Ox.map())` when it's just about getting
-// the original indices
+/*@
+Ox.indicesOf <f> return indices of array elements that pass a test
+    > Ox.indicesOf([1, 2, 3, 4], function(val) { return val % 2 == 0; })
+    [1, 3]
+
+@*/
 Ox.indicesOf = function(col, fn) {
     return Ox.map(col, function(val, i) {
         return fn(val) ? i : null;
@@ -339,31 +343,6 @@ Ox.isEmpty = function(val) {
     return Ox.len(val) === 0;
 };
 
-/*@
-Ox.keys <f> Returns the keys of a collection
-    Unlike <code>Object.keys()</code>, <code>Ox.keys()</code> works for arrays,
-    objects and strings.
-    > Ox.keys([1, 2, 3])
-    [0, 1, 2]
-    > Ox.keys([1,,3])
-    [0, 2]
-    # fixme?
-    # > Ox.keys([,])
-    # [0]
-    > Ox.keys({a: 1, b: 2, c: 3})
-    ['a', 'b', 'c']
-    > Ox.keys('abc')
-    [0, 1, 2]
-@*/
-// fixme: is this really needed? arrays... ok... but strings??
-Ox.keys = function(obj) {
-    var keys = [];
-    Ox.forEach(obj, function(v, k) {
-        keys.push(k);
-    });
-    return keys.sort();
-};
-
 /*@
 Ox.last <f> Gets or sets the last element of an array
     Unlike <code>arrayWithALongName[arrayWithALongName.length - 1]</code>,
@@ -395,7 +374,7 @@ Ox.last = function(arr, val) {
 Ox.len <f> Returns the length of an array, node list, object or string
     Not to be confused with <code>Ox.length</code>, which is the
     <code>length</code> property of the <code>Ox</code> function
-    (<code>1</code>). // FIXME: 1 becomes 67 in DocPanel
+    (<code>1</code>).
     > Ox.len((function() { return arguments; }(1, 2, 3)))
     3
     > Ox.len([1, 2, 3])
@@ -480,9 +459,8 @@ Ox.map <f> Transforms the values of an array, object or string
     [true, false, false]
     > Ox.map([0, 1, 2, 4], function(v, i) { return v ? i == v : null; })
     [true, true, false]
-    # fixme?
-    # > Ox.map([,], function(v, i) { return i; })
-    # [0]
+    > Ox.map([,], function(v, i) { return i; })
+    [,]
 @*/
 Ox.map = function(col, fn, that) {
     var type = Ox.typeOf(col), ret;
@@ -593,23 +571,25 @@ Ox.shuffle <f> Randomizes the order of values within a collection
     > Ox.shuffle('123').split('').sort().join('')
     '123'
 @*/
-// FIXME: this doesn't actually randomize the order
 Ox.shuffle = function(col) {
     var keys, ret, type = Ox.typeOf(col), values;
-    function sort() {
-        return Math.random() - 0.5;
-    }
-    if (type == 'array') {
-        ret = col.sort(sort);
-    } else if (type == 'object') {
+    if (type == 'object') {
         keys = Object.keys(col);
-        values = Ox.values(col).sort(sort);
+        values = Ox.shuffle(Ox.values(col));
         ret = {};
         keys.forEach(function(key, i) {
             ret[key] = values[i]
         });
-    } else if (type == 'string') {
-        ret = col.split('').sort(sort).join('');
+    } else {
+        ret = [];
+        Ox.toArray(col).forEach(function(v, i) {
+            var random = Math.floor(Math.random() * (i + 1));
+            ret[i] = ret[random];
+            ret[random] = v;
+        });
+        if (type == 'string') {
+            ret = ret.join('');
+        }
     }
     return ret;
 };
diff --git a/source/Ox/js/DOM.js b/source/Ox/js/DOM.js
index 230a64bf..9cafd053 100644
--- a/source/Ox/js/DOM.js
+++ b/source/Ox/js/DOM.js
@@ -78,13 +78,10 @@ Ox.$ <f> Generic HTML element, mimics jQuery
     'red'
 @*/
 Ox.$ = Ox.element = function(val) {
-    // fixme: remove click and mousedown,
-    // add native css selector
-    // take all matches of getElementsBy...
     var element = !Ox.isString(val) ? val // window or document
-        : val[0] == '<' ? document.createElement(Ox.sub(val, 1, -1))
-        : val[0] == '#' ? document.getElementById(Ox.sub(val, 1))
-        : val[0] == '.' ? document.getElementsByClassName(Ox.sub(val, 1))[0]
+        : val[0] == '<' ? document.createElement(val.slice(1, -1))
+        : val[0] == '#' ? document.getElementById(val.slice(1))
+        : val[0] == '.' ? document.getElementsByClassName(val.slice(1))[0]
         : document.getElementsByTagName(val)[0];
     return element ? {
         //@ 0 <e> The DOM element itself
@@ -327,4 +324,4 @@ Ox.$ = Ox.element = function(val) {
             return this[0].offsetWidth;            
         }
     } : null;
-};
\ No newline at end of file
+};
diff --git a/source/Ox/js/HTML.js b/source/Ox/js/HTML.js
index c7615c7b..897f5fb4 100644
--- a/source/Ox/js/HTML.js
+++ b/source/Ox/js/HTML.js
@@ -99,7 +99,7 @@ Ox.parseHTML = (function() {
         //html = Ox.parseURLs(html);
         //html = Ox.parseEmailAddresses(html);
         matches.forEach(function(match, i) {
-            html = html.replace(new RegExp(tab + i + tab, 'gi'), match);
+            html = html.replace(new RegExp(tab + i + tab), match);
         });
         html = html.replace(/\n\n/g, '<br/><br/>');
         // close extra opening (and remove extra closing) tags
diff --git a/source/Ox/js/JavaScript.js b/source/Ox/js/JavaScript.js
index 2812f5a2..4081d1ca 100644
--- a/source/Ox/js/JavaScript.js
+++ b/source/Ox/js/JavaScript.js
@@ -42,7 +42,7 @@ Ox.doc <f> Generates documentation for annotated JavaScript
 Ox.doc = (function() {
     // fixme: dont require the trailing '@'
     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*$/,
diff --git a/source/Ox/js/Math.js b/source/Ox/js/Math.js
index e266cff4..7391edc9 100644
--- a/source/Ox/js/Math.js
+++ b/source/Ox/js/Math.js
@@ -3,9 +3,10 @@
 /*@
 Ox.asinh <f> Inverse hyperbolic sine
     Missing from <code>Math</code>.
+    > Ox.asinh(0)
+    0
 @*/
 Ox.asinh = function(x) {
-    // fixme: no test
     return Math.log(x + Math.sqrt(x * x + 1));
 };
 
@@ -137,8 +138,9 @@ Ox.round = function(num, dec) {
 /*@
 Ox.sinh <f> Hyperbolic sine
     Missing from <code>Math</code>.
+    > Ox.sinh(0)
+    0
 @*/
 Ox.sinh = function(x) {
-    // fixme: no test
     return (Math.exp(x) - Math.exp(-x)) / 2;
-};
\ No newline at end of file
+};
diff --git a/source/Ox/js/Request.js b/source/Ox/js/Request.js
index 9bdc03fb..bce61bcb 100644
--- a/source/Ox/js/Request.js
+++ b/source/Ox/js/Request.js
@@ -27,29 +27,51 @@ Ox.get = function(url, callback) {
 
 /*@
 Ox.getJSON <f> Get and parse one or more remote JSON files
-    # fixme: remote? same-origin-policy? jsonp?
+    # fixme: remote? same-origin-policy?
     (url, callback) -> <u> undefined
     url <s|[s]> One or more remote URLs
     callback <f> Callback function
         data <o> The parsed contents of the remote resource(s)
             For multiple URLs, keys are file names, values are contents
 @*/
-Ox.getJSON = (function() {
-    function getJSON(url, callback) {
+Ox.getJSON = function(url, callback) {
+    var urls = Ox.makeArray(url);
+    Ox.loadAsync(urls, function(url, callback) {
         Ox.get(url, function(data) {
-            callback(JSON.parse(data));
+            var result = {};
+            result[url] = JSON.parse(data);
+            callback(result);
         });
-    }
-    return function(url, callback) {
-        var urls = Ox.makeArray(url), data = {}, i = 0, n = urls.length;
-        urls.forEach(function(url) {
-            getJSON(url, function(data_) {
-                data[url] = data_;
-                ++i == n && callback(n == 1 ? data[url] : data);
-            });
-        });
-    };
-}());
+    }, function(results) {
+        callback(urls.length == 1 ? results[url] : results);
+    });
+}
+
+/*@
+Ox.getJSONP <f> Get and parse one or more remote JSONP files
+    (url, callback) -> <u> undefined
+    url <s|[s]> One or more remote URLs,
+        {callback} gets replaced with jsonp callback function name
+    callback <f> Callback function
+        data <o> The parsed contents of the remote resource(s)
+            For multiple URLs, keys are file names, values are contents
+@*/
+Ox.getJSONP = function(url, callback) {
+    var urls = Ox.makeArray(url);
+    Ox.loadAsync(urls, function(url, callback) {
+        var id = 'callback' + Ox.uid();
+        Ox.getJSONP[id] = function(data) {
+            delete Ox.getJSONP[id];
+            callback(data);
+        }
+        Ox.$('body').append(Ox.$('<script>').attr({
+            'src': url.replace('{callback}', 'Ox.getJSONP.' + id),
+            'type': 'text/javascript'
+        }));
+    }, function(results) {
+        callback(urls.length == 1 ? results[url] : results);
+    });
+}
 
 /*@
 Ox.getJSONC <f> Get and parse a remote JSONC file
@@ -77,9 +99,16 @@ Ox.loadFile <f> Loads a file (image, script or stylesheet)
 Ox.loadFile = (function() {
     // fixme: this doesn't handle errors yet
     // fixme: rename to getFile?
-    // fixme: what about array of files?
     var cache = {};
-    return function (file, callback) {
+    return function(files, callback) {
+        Ox.loadAsync(files, function(file, callback) {
+            loadFile(file, function(images) {
+                callback(images ? {file: images} : {});
+            });
+        }, callback);
+    }
+    
+    function loadFile(file, callback) {
         var element,
             head = document.head || document.getElementsByTagName( "head" )[0] || document.documentElement,
             request,
@@ -152,35 +181,31 @@ Ox.loadFile = (function() {
 }());
 
 /*@
-Ox.loadFiles <f> Loads multiple files (images, scripts or stylesheets)
-    (files, callback) -> <u> undefined
-    files <[s]|[[s]]> Array of files, or array of arrays of files
-        Multiple files in the same array will be loaded simultaneously, but
-        multiple arrays of files will be loaded in that order.
+Ox.loadAsync <f> run map function on all array items and call callback with results
+    (arr, map, callback) -> <u> undefined
+    arr <s|[s]|[[s]]> string, Array of strins, or array of arrays of strings
+        Multiple strings in the same array will be processed simultaneously, but
+        multiple arrays of strings will be processed in that order.
     callback <f> Callback function
-        images <o> DOM elements (if any file was an image)
-            Keys are the file names, values are the DOM elements
+        results <o> result
 @*/
-Ox.loadFiles = (function() {
-    function loadFiles(files, callback) {
-        files = Ox.makeArray(files);
-        var i = 0, n = files.length, images = {};
-        Ox.makeArray(files).forEach(function(file) {
-            Ox.loadFile(file, function(image) {
-                if (image) {
-                    images[file] = image;
-                }
-                ++i == n && callback(images);
+Ox.loadAsync = function(arr, map, callback) {
+    arr = Ox.makeArray(arr);
+    var i = 0, n = arr.length, results = {};
+    if(arr.some(Ox.isArray)) {
+        iterate();
+    } else {
+        arr.forEach(function(item) {
+            map(item, function(result) {
+                Ox.extend(results, result);
+                ++i == n && callback(results);
             });
         });
     }
-    return function(files, callback) {
-        var i = 0, n = files.length, images = {};
-        files.forEach(function(file) {
-            loadFiles(file, function(images_) {
-                Ox.extend(images, images_)
-                ++i == n && callback(Ox.len(images) ? images : void 0);
-            });
+    function iterate() {
+        Ox.loadAsync(arr.shift(), function(result) {
+            Ox.extend(results, result);
+            arr.length ? iterate() : callback(results);
         });
-    };
-}());
+    }
+};