This is a library for use by scripters. It provides functions to parse JSON object definitions and to get/set values within JSON objects.
Download: JSON parser library spk (or zip)
Additional download link from xdownloads (plus google and onedrive mirror):
[ external image ]
[ external image ]
Introduction
JSON: JavaScript Object Notation is a lightweight general purpose data exchange format. It's basically an alternative to XML. If you aren't familiar with it, the examples below should make it pretty obvious, also there is a huge wealth of information to be found via google.
Features: The plugin includes a 'parse' script, which will take a string containing a JSON object definition and return what I call a jsonobj - basically a hierarchy of arrays, with the lowest level being 2-element key-value pair arrays. The next most important script is the 'get' script, which allows you to navigate the jsonobj to get a specific value. Then there is the 'set' script, allowing you to modify the value within the jsonobj's hierarchy. Finally there is the 'union' script, allowing you to join together two jsonobjs.
Terminology:
- jsonobj : a complete hierarchy of objects, arrays and values.
- object : a set of key-value pairs, where value can be either integer, string, object or array.
- member : a specific key-value pair within an object.
- element : a specific value at a given index in an array.
JSON object definition stored in t-file:
Code: Select all
<t id="10000">
{
"astring" : "mystring",
"anumber" : 42,
"anobject" : { "param1" : "myobject", "param2" : 99 },
"anarray" :
[
"str",
11,
{ "id" : "myarrobj"},
],
}
</t>
Code: Select all
$jsondef = read text: page=$page.id id=10000
$jsonobj = $nul -> call script 'plugin.JSON.parse' : json=$jsondef
Fetching values:
Code: Select all
$string = $nul -> call script 'plugin.JSON.get' : json object=$jsonobj member='astring' idx0=null idx1=null idx2=null
$objparam = $nul -> call script 'plugin.JSON.get' : json object=$jsonobj member='anobject.param2' idx0=null idx1=null idx2=null
$arrnum = $nul -> call script 'plugin.JSON.get' : json object=$jsonobj member='anarray[%s]' idx0=1 idx1=null idx2=null
$arrobj = $nul -> call script 'plugin.JSON.get' : json object=$jsonobj member='anarray[%s].id' idx0=2 idx1=null idx2=null
jsonobjs form a nested hierarchy:
Code: Select all
$anobj.jsonobj = $nul -> call script 'plugin.JSON.get' : json object=$jsonobj member='anobject' idx0=null idx1=null idx2=null
$objparam = $nul -> call script 'plugin.JSON.get' : json object=$anobj.jsonobj member='param2' idx0=null idx1=null idx2=null
Code: Select all
$idx = $nul -> call script 'plugin.JSON.get' : json object=$jsonobj member='anarray.length' idx0=null idx1=null idx2=null
while $idx
dec $idx =
$val = $nul -> call script 'plugin.JSON.get' : json object=$jsonobj member='anarray[%s]' idx0=$idx idx1=null idx2=null
end
Arrays are stored as 1D arrays, so can be used normally as well as within jsonobj hierarchies:
Code: Select all
$arr = $nul -> call script 'plugin.JSON.get' : json object=$jsonobj member='anarray' idx0=null idx1=null idx2=null
$idx = size of array $arr
while $idx
dec $idx =
$val = $arr[$idx]
end
- $idx = 0, $val = "str"
- $idx = 1, $val = "11"
- $idx = 2, $val is a jsonobj!
Code: Select all
= $nul -> call script 'plugin.JSON.set' : json object=$jsonobj member='anumber' value=223 idx0=null idx1=null
$plyship = [PLAYERSHIP]
= $nul -> call script 'plugin.JSON.set' : json object=$jsonobj member='anarray[%s]' value=$plyship idx0=1 idx1=null
Union - source is merged with target. If any members match, then target's values take precedence:
Code: Select all
<t id="10001">
{
"anobject" :
{
"param1" : "unionme",
"param2" : 0,
"newparam" : "newparameter"
},
}
</t>
Code: Select all
$new.jsondef = read text: page=$page.id id=10001
$new.jsonobj = $nul -> call script 'plugin.JSON.parse' : json=$jsondef
= $nul -> call script 'plugin.JSON.union' : target jsonobj=$jsonobj source jsonobj=$new.jsonobj
$obj.param1 = $nul -> call script 'plugin.JSON.get' : json object=$jsonobj member='anobject.param1' idx0=null idx1=null idx2=null
$obj.newparam = $nul -> call script 'plugin.JSON.get' : json object=$jsonobj member='anobject.newparam' idx0=null idx1=null idx2=null
- $obj.param1 = "myobject"
- $obj.newparam = "newparameter"
- JSON stadard types true, false and null are not supported. For true/false use integer 0/1. The null value is used as an error return in case, for example, you pass an invalid member to the 'get' script.
- Badly formatted JSON can, very easily, cause an infinite loop lockup. You can enable debugging by modifying the line in plugin.JSON.parse. This will enable infinite loop detection and log a verbose status in log10000.txt. It will take much longer to run the json parser/get functions in debug mode.
- All jsonobjs are passed by reference, no array cloning takes place.
Changelog
v1.2:
- Modified: union script will only append additional elements to json arrays, not all.
- Fixed: bug in reading numbers within json arrays.
v1.1:
- Modifed: incorporated Lit's suggested optimization, cheers for that.
- Fixed: accessing non-jsonobj array elements didn't work.
v1.0:
- inital release