RapidBson

Warning

RapidBson is underdeveloped for now. The features which it should have aren't fully implemented yet.

Important

RapidBson is a Blitz3D TSS exclusive library.

It contains Userlib Exception Capturing for handling errors. This feature will help developers to catch and handle exceptions, but in non-Blitz3D-TSS-engine, throws "Unknown runtime exception", even exceptions that shouldn't crash the program.

If you want to use this library in other engines, see Suppressing warnings.

RapidBson is a library that introduced RapidJSON to Blitz3D.

Glossary

Handle

Handle is an abstract reference to a resource that is used when application software references blocks of memory or objects.

See also: https://en.wikipedia.org/wiki/Handle_(computing)

JsonVariable

JsonVariable is an object that contains handle's type (VariableType) and data. JsonParseFromString, JsonParseFromFile, JsonGetValue, and JsonGetArrayValue returns JsonVariable.

VariableType

VariableType is an enum that contains in JsonVariable for indicating the type of handle. There are four types available in RapidBson.

Document

Document is a JSON document.

Value

Value is a JSON value. It can be a string, number, array, another JSON value, or null.

Array

Array is a JSON array.

Null

Null is a placeholder that the function returns when it meets an error. This makes sure that RapidBson won't crash the program.

Suppressing warnings

There are two platforms throwing exceptions for RapidBson: Userlib Exception and Standard Error Stream.

Userlib Exception is a Blitz3D-TSS-exclusive feature, allows RapidBson send mild errors to the engine. This feature will crash the program for other engines.

Standard Error Stream output exceptions to standard error stream. This feature is compatible with all engines. Note that the standard error stream is not visible for most environments.

To disable platforms or make RapidBson compatible with non-Blitz3D-TSS-engines, invoke JsonSuppressWarning.

JsonSuppressWarning allows pass in the flags. To pass in multiple codes, use Or to link them.

For example:

JsonSuppressWarning(JsonNoRuntimeExceptions Or JsonNoExceptionLogs)

Or in Blitz3D TSS:

JsonSuppressWarning(JsonNoRuntimeExceptions | JsonNoExceptionLogs)

Platforms

Code	Name	Description
0	JsonNoSuppressedWarnings	No suppressed warnings.
1	JsonNoRuntimeExceptions	Disable Userlib Exceptions.
2	JsonNoExceptionLogs	Disable outputs to Standard Error Stream.

Parsing the JSON

RapidBson allows comments (// and /* */).

Invoke JsonParseFromString, JsonParseFromFile or JsonParseFromStream to parse a JSON document.

If the parsing encounters an error, JsonHasParseError returns true. The error code can be gotten by JsonGetParseErrorCode.

To get detailed information by error codes, invoke JsonGetParseErrorMessage. All possible errors are listed down below.

Parse errors

Code	Name	Message
-1	JsonParseErrorInvalidDocumentHandle	Invalid JSON document handle.
0	JsonParseErrorNone	No error.
1	JsonParseErrorDocumentEmpty	The document is empty.
2	JsonParseErrorDocumentRootNotSingular	The document root must not be followed by other values.
3	JsonParseErrorValueInvalid	Invalid value.
4	JsonParseErrorObjectMissName	Missing a name for object member.
5	JsonParseErrorObjectMissColon	Missing a colon after a name of object member.
6	JsonParseErrorObjectMissCommaOrCurlyBracket	Missing a comma or '}' after an object member.
7	JsonParseErrorArrayMissCommaOrSquareBracket	Missing a comma or ']' after an array element.
8	JsonParseErrorStringUnicodeEscapeInvalidHex	Incorrect hex digit after \u escape in string.
9	JsonParseErrorStringUnicodeSurrogateInvalid	The surrogate pair in string is invalid.
10	JsonParseErrorStringEscapeInvalid	Invalid escape character in string.
11	JsonParseErrorStringMissQuotationMark	Missing a closing quotation mark in string.
12	JsonParseErrorStringInvalidEncoding	Invalid encoding in string.
13	JsonParseErrorNumberTooBig	Number too big to be stored in double.
14	JsonParseErrorNumberMissFraction	Miss fraction part in number.
15	JsonParseErrorNumberMissExponent	Miss exponent in number.
16	JsonParseErrorTermination	Terminate parsing due to Handler error.
17	JsonParseErrorUnspecificSyntaxError	Unspecific syntax error.

Functions List

Function	Description
JsonParseFromString%(json$)	Get a document instance by parsing a string.
JsonParseFromFile%(path$)	Get a document instance by parsing a file.
JsonParseFromStream%(stream%)	Get a document instance by parsing a Blitz3D stream.
JsonHasParseError%(document%)	Check whether the document is being parsed correctly.
JsonGetParseErrorCode%(document%)	Get parse-error-code of the document.
JsonGetParseErrorMessage$(code%)	Get the parse-error-message from the code.
JsonHasMember%(object%, name$)	Check whether the value exists in the object.
JsonGetValue%(object%, name$)	Get a value instance by an value or document.
JsonIsString%(value%)	Check the value is a string.
JsonIsInt%(value%)	Check the value is an integer.
JsonIsFloat%(value%)	Check the value is a float.
JsonIsBoolean%(value%)	Check the value is a boolean.
JsonIsArray%(value%)	Check the value is an array.
JsonIsObject%(value%)	Check the value is a JSON object.
JsonIsNull%(object%)	Check the value or document is null, or is null.
JsonGetString$(value%)	Returns the value as a string, or returns "" if the value is not a string.
JsonGetInt%(value%)	Returns the value as an integer, or returns 0 if the value is not an integer.
JsonGetFloat#(value%)	Returns the value as a float, or returns 0 if the value is not a float.
JsonGetBoolean%(value%)	Returns the value as a boolean, or returns false if the value is not a boolean.
JsonGetArray%(value%)	Returns the value as an array, or returns null if the value is not an array.
JsonGetArraySize%(value%)	Get the size of the array.
JsonGetArrayValue%(array%, index%)	Get the specific value from the array. The index starts from 0.
JsonGetArrayCapacity%(array%)	Get the capacity of the array.