A full-featured JSON parsing and serialization library for TorqueScript.
Basic usage:
if (jettisonParse(...)) {
// Error position is available through $JSON::Index
error("Failed to parse JSON: " @ $JSON::Error);
return;
}
echo("Type: " @ $JSON::Type @ " | Value: " @ $JSON::Value);
// Cleanup is simple
if ($JSON::Type $= "object") {
$JSON::Value.delete();
}
Serialization:
%data = JettisonObject();
%data.set("position", "object", JettisonArray());
%data.position.push("number", 1);
%data.position.push("number", 2);
%data.set("health", "number", 0);
%json = jettisonStringify("object", %data);
%json -> "{\"position\":[1,2],\"health\":0}"
Data structures:
// Where `data` is `$JSON::Value` from parsing the below structure:
// {
// "admins": [
// {"name": "Bob", "level": 3},
// {"name": "Joe", "level": 2}
// ]
// }
data.class -> "JettisonObject"
data.keyCount -> 1
data.keyName[0] -> "admins"
data.value["admins"] -> [{...}, {...}]
data.admins -> [{...}, {...}]
data.admins.length -> 2
data.admins.value[0] -> {"name": "Bob", ...}
data.admins.value[1] -> {"name": "Joe", ...}
data.admins.value[0].name -> "Bob"
data.admins.value[0].level -> 3
All the valid type names you can expect to get from $JSON::Type
, and which can be used as valid arguments to the various functions expecting type names:
"null"
"boolean"
"number"
"string"
"object"
- Value should be an object that implements::toJSON()
Note: Objects and arrays share the same type name. They can be disambiguated between using the class
field ("JettisonObject"
versus "JettisonArray"
).
Attempt to parse an arbitrary JSON string, ignoring any whitespace around it.
Returns true
if an error occurred while parsing. In this case, $JSON::Error
will contain a short error message, and $JSON::Index
will point to the character position where the error occurred.
If there was no error, false
is returned, $JSON::Value
is set to the result, and $JSON::Type
is set to the type of value that was parsed.
Example:
if (jettisonParse(%text)) {
error("Parse error at " @ $JSON::Index @ ": " @ $JSON::Error);
return;
}
echo("Parsed a " @ $JSON::Type @ ": " @ $JSON::Value);
The only cleanup required is when this function returns true and $JSON::Value
is "object"
. In this case, deleting $JSON::Value
when it's no longer needed is all that's necessary.
Serialize an arbitrary value into a JSON string.
Will never fail or display errors except for the following cases:
type
is not a valid type name: returns a special string describing the error which is intentionally invalid JSON. Any attempt to parse it will fail. You can detect this by checking if the result starts with"<"
.type
is"object"
andvalue
does not implement::toJSON()
: The typical method call failure message is displayed in the console and an empty string is returned.
Example:
jettisonStringify("boolean", true) -> "true"
jettisonStringify("number", 3.14) -> "3.14"
jettisonStringify("string", "hello\nworld") -> "\"hello\\nworld\""
jettisonStringify("object", JettisonObject()) -> "{}"
Helper functions for parsing JSON from/serializing JSON to a file.
jettisonReadFile
behaves exactly like jettisonParse
.
jettisonWriteFile
returns ""
on success or an error message on failure.
Represents a plain JSON object (key-value store).
Note: Keys names are case insensitive! There may be a case sensitive version (hashing keys with
sha1
) in the future, however.The total number of keys stored in this object.
Has a value been assigned to this key name?
The name of the
index
th key in the list of existing keys.index
must be>= 0
and< keyCount
.The type name of the value associated with a given key.
The value associated with a given key.
Direct access to the value of a key by name.
.value["foo"]
can be substituted with.foo
.Note: Certain keys cannot be accessed this way. Any key whose name is
"class"
,"className"
,"keyCount
", or whose name starts with any of the above field prefixes will not have a shorthand field.Serialize this object into a JSON string. Should not be used directly (use
jettisonStringify
instead).Add or update a key-value pair in the object.
Remove a key-value pair from the object by the key name.
Represents a JSON array (list/vector).
The total number of values in the array.
The type name of the indexed value. See
value[]
.The value at a certain index (position) in the array.
index
must be>= 0
and< length
.Serialize this array into a JSON string. Should not be used directly (use
jettisonStringify
instead).Append a value to the end of the array, increasing
length
by one.