[ Impressum ]

LiveCode JSONlib

www.Rozek.de > LiveCode > JSONlib
"JSONlib" is a small LiveCode [1] "library stack" with functions for serialization of LiveCode values into a JSON [2] string and deserializing JSON strings into LiveCode data.

Download and Installation

The "JSONlib" is available as an unencrypted LiveCode stack and can be downloaded from here:
After downloading, just place the "JSONlib" in a directory of your choice - an explicit installation is not required.

Usage Instructions

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

start using stack "JSONlib"

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).

Usage Instructions for mobile Applications

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

start using stack (specialFolderPath("engine") & "/JSONlib.livecode")

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.

Function Overview

The "JSONlib" contains the following two functions:

JSON_stringified (<LiveCodeValue> [, <maxIndentation>])


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 to maxIndentation spaces. The current indentation per nesting level is a single space.
"Primitive" values (such as booleans, numbers and strings) are always serialized into a single line - only arrays and objects may be shown in multiple lines if desired (i.e., depending on maxIndentation).

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 (<JSONstring>)


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.
Caveats

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.

System Requirements

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

Dependencies

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

Known Bugs

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

License Information

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.

                       
Have fun with LiveCode and the "JSONlib"! Creative Commons License

Bibliography

[1]
(RunRev Ltd.)
LiveCode | Create apps for multiple platforms. Quickly. Easily. Free
LiveCode is a development environment for both stationary (Windows, Linux, MacOS X) and mobile (iOS, Android) applications modeled after the legendary Apple HyperCard. A visual editor allows fast design of user interfaces, a programming language inspired by the english language allows even non-professional programmers to develop professional applications and the concept of "modifying a running program" simplifies testing and troubleshooting.
[2]
Douglas Crockford
JSON (JavaScript Object Notation)
JSON is a compact text format for representing and exchanging structured data (like XML). It is similar in its syntax to the JavaScript programming language and can therefore be read and processed with ease.