Fortunately enough, JSONScript, once added to your website, adds one new object with only one new function to memorize.
JSONScript.parse( jsonArray [, scope ] );
The parse() function holds two arguments: jsonArray which is mandatory and scope which can be added voluntarily. The former argument contains all the parsable objects stored in a JSON array which the API will evaluate. The latter defines the scope to which the parsed JSON objects will be appended. If no scope is defined, then the global scope will be selected.
When called, the parse() function will evaluate all the objects provided by the jsonArray argument and add them to the defined scope. That's everything you need to know. Long story short, the API really does a lot so you don't need to remember long and uberly complicated function and object names.
Every JSON object within the jsonArray argument needs to follow a certain structure as follows.
{
type : "yourTypeHere",
name : "yourNameHere"
}
type and name are the two keys every JSON object requires in order to be considered parsable by the API no matter the objects' type. Of course, there are several other keys which are exclusive to several different types, but those are named in the list of types below. There's one exception to said rule referring to the array type which is mentioned in the section concerning the array type itself.
type tells the API how to parse the JSON object. There are five different types as of the current version: object, string, number, array and function which are explained in detail below. name declares the variables' name to which the parsed JSON object will be assigned to. So basically ...
{
type : "object",
name : "myCoolObject"
}
.. is equivalent to ...
var myCoolObject = {}
Although you might think that the first example is way too over-complicated, then you shall not worry. This example just shows how beautiful your code will look using JSONScript as your new favorite API.
Every JSON object can define a children array which is structurally the same like the root array. Its purpose is to add children to JSON objects of your choice. For example, here's one working example on how to define a person object with a certain age.
JSONScript.parse([
{
type : "object",
name : "prettyNiceGuy",
children : [
{
type : "number",
name : "age",
value : "23"
}
]
}
]);
In pure Javascript, it would look like this. The result those two operations return would be the same.
var prettyNiceGuy = { age : 23 };
The object type requires no further keys to be set apart from the default ones. This type is most useful when used together with the optional children key.
// example to demonstrate the type "object". in pure js it looks like this:
// var foobar = {};
JSONScript.parse([
{
type : "object",
name : "foobar"
}
]);
The string type requires the value key to be set including the default ones. The value of the value key represents the content of the string once parsed.
// example to demonstrate the type "string". in pure js it looks like this:
// var theanswer = "fortytwo";
JSONScript.parse([
{
type : "string",
name : "theanswer",
value : "fortytwo"
}
]);
The number type requires the value key to be set including the default ones. The value of the value key represents the numerical value once parsed. The number type differentiates integers from floats. If value is a float, then it will automatically switch to the float type instead of the integer type. However, this procedure will only be executed if needed at all. If value isn't a float, then it will be parsed as a normal integer.
// example to demonstrate the type "number". in pure js it looks like this:
// var someinteger = 23;
JSONScript.parse([
{
type : "number",
name : "someinteger",
value : "23"
}
]);
// here, the number returned is actually a float without changing the JSON object type
// var somefloatwhichactuallyisntafloatbutitmightbetrue = 23.4;
JSONScript.parse([
{
type : "number",
name : "somefloatwhichactuallyisntafloatbutitmightbetrue",
value : "23.4"
}
]);
// doing something with radix (result is 157)
JSONScript.parse([
{
type : "number",
name : "radixNumber",
value : "94",
radix : "17"
}
]);
The array type requires the children key to be set including the default ones. The value of the children key represents an array similar to the root array with the only exception that the JSON objects contained within don't require a name key since they're being indexed by the result array itself.
// example to demonstrate the type "array". in pure js it looks like this:
// var coolArray = [ 1234, "much wow" ];
JSONScript.parse([
{
type : "array",
name : "coolArray",
children : [
{
type : "number",
value : "1234"
},
{
type : "string",
value : "much wow"
}
]
}
]);
The function type requires the args key and the body key to be set including the default ones. The value of the args key represents an array containing strings for the functions' argument names. The value of the body key represents an array containing strings for the functions' code to run once executed. Every new line must be separated by creating a new item in the body array. Apart from that, there's no big difference comparing to writing normal JS code.
// example to demonstrate the type "function". in pure js it looks like this:
// function tellMe(something) { alert(something); }
JSONScript.parse([
{
type : "function",
name : "tellMe",
args : [
"something"
],
body : [
"alert(something);"
]
}
]);