added utils.foreach() and utils.nicely() functions

docs/api.md

@@ -1050,6 +1050,104 @@ Miscellaneous utility functions and classes to help with programming.
  * getPlayerObject(playerName) - returns the Player object for a named
    player or `self` if no name is provided.
 
+utils.foreach() function
+========================
+The utils.foreach() function is a utility function for iterating over
+an array of objects and processing each one in turn. Where
+utils.foreach() differs from other similar functions found in
+javascript libraries, is that utils.foreach can process the array
+immediately or can process it *nicely* by processing one item at a
+time then delaying processing of the next item for a given number of
+server ticks (there are 20 ticks per second on the minecraft main
+thread).  This method relies on Bukkit's [org.bukkit.scheduler][sched]
+package for scheduling processing of arrays.
+
+[sched]: http://jd.bukkit.org/beta/apidocs/org/bukkit/scheduler/package-summary.html
+
+Parameters
+----------
+
+ * array : The array to be processed
+ * callback : The function to be called to process each item in the
+   array. The callback function should have the following signature
+   `callback(item, index, object, array)`. That is the callback will
+   be called with the following parameters....
+
+   - item : The item in the array
+   - index : The index at which the item can be found in the array.
+   - object : Additional (optional) information passed into the foreach method.
+   - array : The entire array.
+
+ * object (optional) : An object which may be used by the callback.
+ * delay (optional, numeric) : If a delay is specified (in ticks - 20
+   ticks = 1 second), then the processing will be scheduled so that
+   each item will be processed in turn with a delay between the completion of each
+   item and the start of the next. This is recommended for big builds (say 200 x 200 x 200
+   blocks) or any CPU-intensive process.
+ * onDone (optional, function) : A function to be executed when all processing 
+   is complete. This parameter is only used when the processing is delayed. (It's optional even if a 
+   delay parameter is supplied).
+
+If called with a delay parameter then foreach() will return
+immediately after processing just the first item in the array (all
+subsequent items are processed later). If your code relies on the
+completion of the array processing, then provide an `onDone` parameter
+and put the code there.
+
+Example
+-------
+The following example illustrates how to use foreach for immediate processing of an array...
+
+    var players = ["moe", "larry", "curly"];
+    foreach (players, function(item){ 
+        server.getPlayer(item).sendMessage("Hi " + item);
+    });
+    
+The following example is a more complex use case - The need to build an enormous structure
+without hogging CPU usage...
+
+    // build a structure 200 wide x 200 tall x 200 long
+    // (That's 8 Million Blocks - enough to tax any machine!)
+
+    var a = []; 
+    a.length = 200; 
+    var drone = new Drone();
+    var processItem = function(item, index, object, array){
+        // build a box 200 wide by 200 long then move up
+        drone.box(blocks.wood, 200, 1, 200).up();
+    };
+    // by the time the job's done 'self' might be someone else 
+    // assume this code is within a function/closure
+    var player = self;
+    var onDone = function(){ 
+        player.sendMessage("Job Done!");
+    };
+    foreach (a, processItem, null, 10, onDone);
+    
+utils.nicely() function
+=======================
+The utils.nicely() function is for performing processing using the
+[org.bukkit.scheduler][sched] package/API. utils.nicely() lets you
+process with a specified delay between the completion of each `next()`
+function and the start of the next `next()` function.
+`utils.nicely()` is a recursive function - that is - it calls itself
+(schedules itself actually) repeatedly until `hasNext` returns false.
+
+Parameters
+----------
+
+ * next : A function which will be called if processing is to be done. 
+ * hasNext : A function which is called to determine if the `next`
+   callback should be invoked. This should return a boolean value -
+   true if the `next` function should be called (processing is not
+   complete), false otherwise.
+ * onDone : A function which is to be called when all processing is complete (hasNext returned false).
+ * delay : The delay (in server ticks - 20 per second) between each call.
+
+Example
+-------
+See the source code to utils.foreach for an example of how utils.nicely is used.
+
 String class extensions
 -----------------------
 The following chat-formatting methods are added to the javascript String class..

src/main/javascript/utils/utils.js

@@ -20,5 +20,131 @@ var utils = utils || {
         if (typeof playerName == "string")
             return org.bukkit.Bukkit.getPlayer(playerName);
         return player;
+    },
+/************************************************************************
+utils.foreach() function
+========================
+The utils.foreach() function is a utility function for iterating over
+an array of objects and processing each one in turn. Where
+utils.foreach() differs from other similar functions found in
+javascript libraries, is that utils.foreach can process the array
+immediately or can process it *nicely* by processing one item at a
+time then delaying processing of the next item for a given number of
+server ticks (there are 20 ticks per second on the minecraft main
+thread).  This method relies on Bukkit's [org.bukkit.scheduler][sched]
+package for scheduling processing of arrays.
+
+[sched]: http://jd.bukkit.org/beta/apidocs/org/bukkit/scheduler/package-summary.html
+
+Parameters
+----------
+
+ * array : The array to be processed
+ * callback : The function to be called to process each item in the
+   array. The callback function should have the following signature
+   `callback(item, index, object, array)`. That is the callback will
+   be called with the following parameters....
+
+   - item : The item in the array
+   - index : The index at which the item can be found in the array.
+   - object : Additional (optional) information passed into the foreach method.
+   - array : The entire array.
+
+ * object (optional) : An object which may be used by the callback.
+ * delay (optional, numeric) : If a delay is specified (in ticks - 20
+   ticks = 1 second), then the processing will be scheduled so that
+   each item will be processed in turn with a delay between the completion of each
+   item and the start of the next. This is recommended for big builds (say 200 x 200 x 200
+   blocks) or any CPU-intensive process.
+ * onDone (optional, function) : A function to be executed when all processing 
+   is complete. This parameter is only used when the processing is delayed. (It's optional even if a 
+   delay parameter is supplied).
+
+If called with a delay parameter then foreach() will return
+immediately after processing just the first item in the array (all
+subsequent items are processed later). If your code relies on the
+completion of the array processing, then provide an `onDone` parameter
+and put the code there.
+
+Example
+-------
+The following example illustrates how to use foreach for immediate processing of an array...
+
+    var players = ["moe", "larry", "curly"];
+    foreach (players, function(item){ 
+        server.getPlayer(item).sendMessage("Hi " + item);
+    });
+    
+The following example is a more complex use case - The need to build an enormous structure
+without hogging CPU usage...
+
+    // build a structure 200 wide x 200 tall x 200 long
+    // (That's 8 Million Blocks - enough to tax any machine!)
+
+    var a = []; 
+    a.length = 200; 
+    var drone = new Drone();
+    var processItem = function(item, index, object, array){
+        // build a box 200 wide by 200 long then move up
+        drone.box(blocks.wood, 200, 1, 200).up();
+    };
+    // by the time the job's done 'self' might be someone else 
+    // assume this code is within a function/closure
+    var player = self;
+    var onDone = function(){ 
+        player.sendMessage("Job Done!");
+    };
+    foreach (a, processItem, null, 10, onDone);
+    
+***/
+    foreach: function(array, callback, object, delay, onCompletion){
+        var i = 0;
+        var len = array.length;
+        if (delay){
+            var next = function(){ callback(array[i],i,object,array); i++;};
+            var hasNext = function(){return i < len;};
+            utils.nicely(next,hasNext,onCompletion,delay);
+        }else{
+            for (;i < len; i++){
+                callback(array[i],i,object,array);
+            }
+        }
+    },
+/************************************************************************
+utils.nicely() function
+=======================
+The utils.nicely() function is for performing processing using the
+[org.bukkit.scheduler][sched] package/API. utils.nicely() lets you
+process with a specified delay between the completion of each `next()`
+function and the start of the next `next()` function.
+`utils.nicely()` is a recursive function - that is - it calls itself
+(schedules itself actually) repeatedly until `hasNext` returns false.
+
+Parameters
+----------
+
+ * next : A function which will be called if processing is to be done. 
+ * hasNext : A function which is called to determine if the `next`
+   callback should be invoked. This should return a boolean value -
+   true if the `next` function should be called (processing is not
+   complete), false otherwise.
+ * onDone : A function which is to be called when all processing is complete (hasNext returned false).
+ * delay : The delay (in server ticks - 20 per second) between each call.
+
+Example
+-------
+See the source code to utils.foreach for an example of how utils.nicely is used.
+
+***/
+    nicely: function(next, hasNext, onDone, delay){
+        if (hasNext()){
+            next();
+            server.scheduler.runTaskLater(__plugin,function(){
+                utils.nicely(next,hasNext,onDone,delay);
+            },delay);
+        }else{
+            if (onDone)
+                onDone();
+        }
     }
 };