"JSONlib" is a small LiveCode "library stack" with functions for serialization of LiveCode values into a JSON string and deserializing JSON strings into LiveCode data.

The "JSONlib" is available as an unencrypted LiveCode stack and can be downloaded from here:

• JSONlib.livecode

The "JSONlib" has been implemented as a LiveCode "library stack" and must therefore be attached to a "MainStack" prior to its use using

Appropriately, this statement is executed in the context of a preOpenStack procedure of a MainStack.

Should the MainStack later be converted into a standalone application, the "JSONlib" must also become part of the list of "Stack Files" in this MainStack (this is easiest done by using the "Standalone Application Settings" from the LiveCode development environment).

The "JSONlib" can also be used in mobile applications. However - and unlike for standalone desktop applications - it must then be included in the list of "non-stack files" and attached to the MainStack using

The list of "non-stack files" can likewise be found on the "Copy Files" page in the "Standalone Application Settings" of the LiveCode development environment.

The "JSONlib" contains the following two functions:

JSON_stringified serializes the given LiveCodeValue into a JSON string and returns it to the caller. Formatting of the JSON output can be controlled using the optional parameter maxIndentation:

• maxIndentation < 0 
  JSON_stringified returns a single line of text (which therefore contains no newlines);
   
• maxIndentation = 0 
  JSON_stringified returns multiple lines of text (with approx. one value per line) but without any indentations;
   
• maxIndentation > 0 
  JSON_stringified returns multiple lines of text (with approx. one value per line) and indents the contents of (numerically indexed) arrays and objects (i.e., literal indexed LiveCode arrays) with a total of up tomaxIndentation spaces. The current indentation per nesting level is a single space.

JSON_stringified may throw the following exceptions:

• "UninitializedLibrary: ..." 
  is thrown if the "JSONlib" was not included as a library stack (see above);
   
• "MissingArgument: ..." 
  is thrown if LiveCodeValue is missing;
   
• "InvalidArgument: ..." 
  is thrown if the given maxIndentation is not an integer.

JSON_parsed analyses a given JSONstring and returns the information contained therein as a LiveCode value.

JSON_parsed may throw the following Exceptions:

• "UninitializedLibrary: ..." 
  is thrown if the "JSONlib" was not included as a library stack (see above);
   
• "EmptyArgument: ..." 
  is thrown if the JSONstring is missing or empty;
   
• "UnexpectedCharacter: ..." 
  is thrown if JSON_parsed encounters an unexpected character;
   
• "UnexpectedEOF: ..." 
  is thrown if JSON_parsed reaches the end of JSONstring although it still expects additional input;
   
• "InvalidNumber: ..." 
  is thrown if JSON_parsed encounters a value that actually looks like a number, but can not be converted to a valid LiveCode number.

Since LiveCode differs significantly from JavaScript (and many other programming languages), the conversion of LiveCode values to and from JSON is subject to a number of restrictions:

• LiveCode does not support any null references 
  JSON_parsed converts null into an empty string instead;
   
• LiveCode does not support any "empty" arrays or objects 
  JSON_parsed converts them into an empty string instead;
   
• the indices of JSON arrays always start at 0 
  JSON_parsed uses the same form of indexing for deserialization of numerically indexed arrays - and JSON_stringified expects indices starting at 0 whenever it has to decide whether a LiveCode array has to be serialized as a JavaScript array or object.

The "JSONlib" requires LiveCode 6.x or later, and works regardless of the operating system on both stationary and mobile platforms.

The "JSONlib" does not depend on any other stack.

There are currently no known bugs in the "JSONlib".

The "JSONlib" and its tests are licensed under a "Creative Commons Attribution 4.0 Unported license", which essentially means that you may both use and modify them (even in a commercial context) - provided that your changes have been marked as such and there is a reference to me as the original author at an appropriate place.