Improved documentation of the utils module and fixed bug in signs module due to changes to serialization/deserialization of locations.

docs/API-Reference.md

@@ -646,21 +646,11 @@ The following example illustrates how to use http.request to make a request to a
 
 ## Utilities Module
 
-Miscellaneous utility functions and classes to help with programming.
+The `utils` module is a storehouse for various useful utility
+functions which can be used by plugin and module authors. It contains
+miscellaneous utility functions and classes to help with programming.
 
- * locationToString(Location) - returns a [bukkit Location][bkloc] object in string form.
+### utils.player() function
-  
- * player(playerName) - returns the Player object for a named player or `self` if no name is provided.
-
- * getPlayerPos(playerName) - returns the player's x,y,z and yaw (direction) for a named player
-   or player or `self` if no parameter is provided.
- 
- * getMousePos(playerName) - returns the x,y,z of the current block being targeted by the named player
-   or player or `self` if no paramter is provided.
-
-[bkloc]: http://jd.bukkit.org/dev/apidocs/org/bukkit/Location.html
-
-### player() function
 
 The utils.player() function will return a [bukkit Player][bkpl] object
 with the given name. This function takes a single parameter
@@ -670,17 +660,110 @@ String, then it tries to find the player with that name.
 
 #### Parameters
 
- * playerName : A String or Player object. If no parameter is provided then player() will try to return the `self` variable . It is strongly recommended to provide a parameter.
+ * playerName : A String or Player object. If no parameter is provided
+   then player() will try to return the `self` variable . It is 
+   strongly recommended to provide a parameter.
 
 #### Example
 
     var utils = require('utils');
-    var player = utils.player('walterh');
+    var name = 'walterh';
-    player.sendMessage('Got you!');
+    var player = utils.player(name);
+    if (player) {
+        player.sendMessage('Got ' + name);
+    }else{
+        console.log('No player named ' + name);
+    }
 
 [bkpl]: http://jd.bukkit.org/dev/apidocs/org/bukkit/entity/Player.html
+[bkloc]: http://jd.bukkit.org/dev/apidocs/org/bukkit/Location.html
 
-### foreach() function
+### utils.locationToJSON() function
+
+utils.locationToJSON() returns a [org.bukkit.Location][bkloc] object in JSON form...
+
+    { world: 'world5',
+      x: 56.9324,
+      y: 103.9954,
+      z: 43.1323,
+      yaw: 0.0,
+      pitch: 0.0
+    }
+
+This can be useful if you write a plugin that needs to store location data since bukkit's Location object is a Java object which cannot be serialized to JSON by default.
+
+#### Parameters
+ 
+ * location: An object of type [org.bukkit.Location][bkloc]
+
+#### Returns
+
+A JSON object in the above form.
+ 
+### utils.locationToString() function
+
+The utils.locationToString() function returns a
+[org.bukkit.Location][bkloc] object in string form...
+
+    '{"world":"world5",x:56.9324,y:103.9954,z:43.1323,yaw:0.0,pitch:0.0}'
+
+... which can be useful if you write a plugin which uses Locations as
+keys in a lookup table.
+
+#### Example
+    
+    var utils = require('utils');
+    ...
+    var key = utils.locationToString(player.location);
+    lookupTable[key] = player.name;
+
+### utils.locationFromJSON() function
+
+This function reconstructs an [org.bukkit.Location][bkloc] object from
+a JSON representation. This is the counterpart to the
+`locationToJSON()` function. It takes a JSON object of the form
+returned by locationToJSON() and reconstructs and returns a bukkit
+Location object.
+
+### utils.getPlayerPos() function
+
+This function returns the player's [Location][bkloc] (x, y, z, pitch
+and yaw) for a named player.  If the "player" is in fact a
+[org.bukkit.command.BlockCommandSender][bkbcs] then the attached
+Block's location is returned.
+
+#### Parameters
+
+ * player : A [org.bukkit.command.CommandSender][bkbcs] (Player or BlockCommandSender) or player name (String).
+
+#### Returns
+
+An [org.bukkit.Location][bkloc] object.
+
+[bkbcs]: http://jd.bukkit.org/dev/apidocs/org/bukkit/command/BlockCommandSender.html
+[bksndr]: http://jd.bukkit.org/dev/apidocs/index.html?org/bukkit/command/CommandSender.html
+### utils.getMousePos() function
+
+This function returns a [org.bukkit.Location][bkloc] object (the
+x,y,z) of the current block being targeted by the named player. This
+is the location of the block the player is looking at (targeting).
+
+#### Parameters
+
+ * player : The player whose targeted location you wish to get.
+
+#### Example
+
+The following code will strike lightning at the location the player is looking at...
+
+    var utils = require('utils');
+    var playerName = 'walterh';
+    var targetPos = utils.getMousePos(playerName);
+    if (targetPos){
+       targetPos.world.strikeLightning(targetPos);
+    }
+
+### utils.foreach() function
 
 The utils.foreach() function is a utility function for iterating over
 an array of objects (or a java.util.Collection of objects) and processing each object in turn. Where

src/main/javascript/modules/signs/menu.js

@@ -1,4 +1,4 @@
-var _utils = require('utils');
+var utils = require('utils');
 var stringExt = require('utils/string-exts');
 var _store = {};
 /*
@@ -78,7 +78,7 @@ signs.menu = function(
             save = true;
 
         if (typeof sign == "undefined"){
-            var mouseLoc = _utils.getMousePos();
+            var mouseLoc = utils.getMousePos();
             if (mouseLoc){
                 sign = mouseLoc.block.state;
             }else{
@@ -105,7 +105,7 @@ signs.menu = function(
            get a unique ID for this particular sign instance
         */
         var signLoc = sign.block.location;
-        var menuSignSaveData = [""+signLoc.world.name, signLoc.x,signLoc.y,signLoc.z];
+        var menuSignSaveData = utils.locationToJSON(signLoc);
         var menuSignUID = JSON.stringify(menuSignSaveData);
         /*
           keep a reference to the update function for use by the event handler
@@ -177,7 +177,7 @@ events.on('player.PlayerInteractEvent',function(listener, event) {
 
     if (! event.clickedBlock.state instanceof org.bukkit.block.Sign)
         return;
-    var evtLocStr = _utils.locationToString(event.clickedBlock.location);
+    var evtLocStr = utils.locationToString(event.clickedBlock.location);
     var signUpdater = _updaters[evtLocStr]
     if (signUpdater)
         signUpdater(event.player, event.clickedBlock.state);

src/main/javascript/modules/utils/utils.js

@@ -1,23 +1,11 @@
 /************************************************************************
 ## Utilities Module
 
-Miscellaneous utility functions and classes to help with programming.
+The `utils` module is a storehouse for various useful utility
+functions which can be used by plugin and module authors. It contains
+miscellaneous utility functions and classes to help with programming.
 
- * locationToString(Location) - returns a [bukkit Location][bkloc] object in string form.
+### utils.player() function
-  
- * player(playerName) - returns the Player object for a named player or `self` if no name is provided.
-
- * getPlayerPos(playerName) - returns the player's x,y,z and yaw (direction) for a named player
-   or player or `self` if no parameter is provided.
- 
- * getMousePos(playerName) - returns the x,y,z of the current block being targeted by the named player
-   or player or `self` if no paramter is provided.
-
-[bkloc]: http://jd.bukkit.org/dev/apidocs/org/bukkit/Location.html
-
-***/
-/************************************************************************
-### player() function
 
 The utils.player() function will return a [bukkit Player][bkpl] object
 with the given name. This function takes a single parameter
@@ -27,15 +15,23 @@ String, then it tries to find the player with that name.
 
 #### Parameters
 
- * playerName : A String or Player object. If no parameter is provided then player() will try to return the `self` variable . It is strongly recommended to provide a parameter.
+ * playerName : A String or Player object. If no parameter is provided
+   then player() will try to return the `self` variable . It is 
+   strongly recommended to provide a parameter.
 
 #### Example
 
     var utils = require('utils');
-    var player = utils.player('walterh');
+    var name = 'walterh';
-    player.sendMessage('Got you!');
+    var player = utils.player(name);
+    if (player) {
+        player.sendMessage('Got ' + name);
+    }else{
+        console.log('No player named ' + name);
+    }
 
 [bkpl]: http://jd.bukkit.org/dev/apidocs/org/bukkit/entity/Player.html
+[bkloc]: http://jd.bukkit.org/dev/apidocs/org/bukkit/Location.html
 
 ***/
 var _player = function ( playerName ) {
@@ -52,7 +48,30 @@ var _player = function ( playerName ) {
             return playerName; // assumes it's a player object
     }
 };
+/*************************************************************************
+### utils.locationToJSON() function
 
+utils.locationToJSON() returns a [org.bukkit.Location][bkloc] object in JSON form...
+
+    { world: 'world5',
+      x: 56.9324,
+      y: 103.9954,
+      z: 43.1323,
+      yaw: 0.0,
+      pitch: 0.0
+    }
+
+This can be useful if you write a plugin that needs to store location data since bukkit's Location object is a Java object which cannot be serialized to JSON by default.
+
+#### Parameters
+ 
+ * location: An object of type [org.bukkit.Location][bkloc]
+
+#### Returns
+
+A JSON object in the above form.
+ 
+***/
 var _locationToJSON = function(location){
     return { 
         world: ''+location.world.name, 
@@ -63,14 +82,49 @@ var _locationToJSON = function(location){
         pitch: location.pitch
     };
 };
+/*************************************************************************
+### utils.locationToString() function
+
+The utils.locationToString() function returns a
+[org.bukkit.Location][bkloc] object in string form...
+
+    '{"world":"world5",x:56.9324,y:103.9954,z:43.1323,yaw:0.0,pitch:0.0}'
+
+... which can be useful if you write a plugin which uses Locations as
+keys in a lookup table.
+
+#### Example
+    
+    var utils = require('utils');
+    ...
+    var key = utils.locationToString(player.location);
+    lookupTable[key] = player.name;
+
+***/
 exports.locationToString = function(location){
     return JSON.stringify(_locationToJSON(location));
 };
 exports.locationToJSON = _locationToJSON;
 
+/*************************************************************************
+### utils.locationFromJSON() function
+
+This function reconstructs an [org.bukkit.Location][bkloc] object from
+a JSON representation. This is the counterpart to the
+`locationToJSON()` function. It takes a JSON object of the form
+returned by locationToJSON() and reconstructs and returns a bukkit
+Location object.
+
+***/
 exports.locationFromJSON = function(json){
+    if (json.constuctor == Array){ 
+        // for support of legacy format
+        var world = org.bukkit.Bukkit.getWorld(json[0]);
+        return new org.bukkit.Location(world, json[1], json[2] , json[3]);
+    }else{
         var world = org.bukkit.Bukkit.getWorld(json.world);
         return new org.bukkit.Location(world, json.x, json.y , json.z, json.yaw, json.pitch);
+    }
 };
 
 exports.player = _player;
@@ -78,7 +132,25 @@ exports.getPlayerObject = function(player){
     console.warn('utils.getPlayerObject() is deprecated. Use utils.player() instead.');
     return _player(player);
 };
+/*************************************************************************
+### utils.getPlayerPos() function
 
+This function returns the player's [Location][bkloc] (x, y, z, pitch
+and yaw) for a named player.  If the "player" is in fact a
+[org.bukkit.command.BlockCommandSender][bkbcs] then the attached
+Block's location is returned.
+
+#### Parameters
+
+ * player : A [org.bukkit.command.CommandSender][bkbcs] (Player or BlockCommandSender) or player name (String).
+
+#### Returns
+
+An [org.bukkit.Location][bkloc] object.
+
+[bkbcs]: http://jd.bukkit.org/dev/apidocs/org/bukkit/command/BlockCommandSender.html
+[bksndr]: http://jd.bukkit.org/dev/apidocs/index.html?org/bukkit/command/CommandSender.html
+***/
 exports.getPlayerPos = function( player ) {
     player = _player(player);
     if (player){
@@ -90,7 +162,29 @@ exports.getPlayerPos = function( player ) {
     else
         return null;
 };
+/************************************************************************
+### utils.getMousePos() function
 
+This function returns a [org.bukkit.Location][bkloc] object (the
+x,y,z) of the current block being targeted by the named player. This
+is the location of the block the player is looking at (targeting).
+
+#### Parameters
+
+ * player : The player whose targeted location you wish to get.
+
+#### Example
+
+The following code will strike lightning at the location the player is looking at...
+
+    var utils = require('utils');
+    var playerName = 'walterh';
+    var targetPos = utils.getMousePos(playerName);
+    if (targetPos){
+       targetPos.world.strikeLightning(targetPos);
+    }
+
+***/
 exports.getMousePos = function (player) {
     
     player = _player(player);
@@ -106,7 +200,7 @@ exports.getMousePos = function (player) {
     return targetedBlock.location;
 };
 /************************************************************************
-### foreach() function
+### utils.foreach() function
 
 The utils.foreach() function is a utility function for iterating over
 an array of objects (or a java.util.Collection of objects) and processing each object in turn. Where