json(n)

NAME
json - Parse and manipulate JSON documents

SYNOPSIS
package require rl_json ?0.9.7?
json exists jsonValue ?key ... ?modifier??
json extract jsonValue ?key ... ?modifier??
json foreach varlist1 jsonValue1 ?varlist2 jsonValue2 ...? script
json get jsonValue ?key ... ?modifier??
json get_typed jsonValue ?key ... ?modifier??
json lmap varlist1 jsonValue1 ?varlist2 jsonValue2 ...? script
json new type value
json normalize jsonValue
json pretty jsonValue
json set jsonVariableName ?key ...? value
json template jsonValue ?dictionary?
json unset jsonVariableName ?key ...?

DESCRIPTION

This package adds a command json to the interpreter, and defines a new Tcl_Obj type to store the parsed JSON document. The json command directly manipulates values whose string representation is valid JSON, in a similar way to how the dict command directly manipulates values whose string representation is a valid dictionary. It is similar to dict in performance.

json get jsonValue ?key ... ?modifier??
    Extract the value of a portion of the jsonValue, returns the closest native Tcl type (other than JSON) for the extracted portion. The key ... arguments are a path, as described in PATHS below.

json get_typed jsonValue ?key ... ?modifier??
    Extract the value of a portion of the jsonValue, returning a two element list: the first element is the value that would be returned by json get and the second element is the JSON type of the extracted portion. The key ... arguments are a path, as described in PATHS below.

json extract jsonValue ?key ... ?modifier??
    Extract the value of a portion of the jsonValue, returns the JSON fragment. The key ... arguments are a path, as described in PATHS below.

json exists jsonValue ?key ... ?modifier??
    Tests whether the supplied key path (see PATHS below) and modifier resolve to something that exists in jsonValue (i.e., that it can be used with json get without error).

json set jsonVariableName ?key ...? value
    Updates the JSON value stored in the variable jsonVariableName, replacing the value referenced by key ... (a path as described in PATHS below) with the JSON value value.

json unset jsonVariableName ?key ...?
    Updates the JSON value stored in the variable jsonVariableName, removing the value referenced by key ..., a path as described in PATHS below.

json normalize jsonValue
    Return a version of the input jsonValue, i.e., with all optional whitespace trimmed.

json template jsonValue ?dictionary?
    Return a JSON value by interpolating the values from dictionary into the template, or from variables in the current scope if dictionary is not supplied, in the manner described in the section TEMPLATES.

json new type value
    Return a JSON fragment of type type and value value.

json foreach varList1 jsonValue1 ?varList2 jsonValue2 ...? script
    Evaluate script in a loop in a similar way to the foreach command. In each iteration, the values stored in the iterator variables in each varList are the JSON fragments from jsonValue. This command supports iterating over JSON arrays and JSON objects. In the JSON object case, the corresponding varList must be a two element list, with the first specifiying the variable to hold the key and the second the value. In the JSON array case, the rules are the same as the foreach command.

json lmap varList1 jsonValue1 ?varList2 jsonValue2 ...? script
    As for json foreach, except that it is collecting; the result from each evaluation of script is added to a Tcl list and returned as the result of the json lmap command. If the script results in a TCL_CONTINUE code (e.g., the script does continue), that iteration is skipped and no element is added to the result list. If it results in TCL_BREAK (e.g., the script does break) the iterations are stopped and the results accumulated so far are returned.

json pretty jsonValue
    Returns a pretty-printed string representation of jsonValue. Useful for debugging or inspecting the structure of JSON data.

PATHS

Several of the commands (e.g., json get, json exists, json set and json unset) accept a path specification that names some subset of the supplied jsonValue. The rules are similar to the equivalent concept in the dict command, except that the paths used by json allow indexing into JSON arrays by the integer key (or a string matching the regex

Some of the commands also accept an optional modifier at the end of the path, which is defined to be one of the following:

?type
    Returns the type of the named fragment.

?length
    When the path refers to an array, this returns the length of the array. When the path refers to a string, this returns the number of characters in the string. All other types throw an error.

?size
    Valid only for objects, returns the number of keys defined in the object.

?keys
    Valid only for objects, returns a list of the keys in the object.

A literal value that would match one of the above modifiers can be used as the last element in the path by doubling the ?. For example:

json get {
    {
        "foo": {
            "?size": "quite big"
        }
    } } foo ??size

Returns

TEMPLATES

The command json template generates JSON documents by interpolating values into a template from a supplied dictionary or variables in the current call frame, a flexible mechanism for generating complex documents. The templates are valid JSON documents containing string values which match the regex The second character determines what the resulting type of the substituted value will be:

    S   A string.

    N   A number.

    B   A boolean.

    J   A JSON fragment.

    T   A JSON template (substitutions are performed on the inserted fragment).

    L   A literal. The resulting string is simply everything from the fourth character onwards (this allows literal strings to be included in the template that would otherwise be interpreted as the substitutions above).

None of the first three characters for a template may be escaped.

The value inserted is determined by the characters following the substitution type prefix. When interpolating values from a dictionary they name keys in the dictionary which hold the values to interpolate. When interpolating from variables in the current scope, they name scalar or array variables which hold the values to interpolate. In either case if the named key or variable doesn't exist, a JSON null is interpolated in its place.

EXAMPLES

Produce a JSON value from a template:

json template {
    {
        "thing1": "~S:val1",
        "thing2": ["a", "~N:val2", "~S:val2", "~B:val2",
                   "~S:val3", "~L:~S:val1"],
        "subdoc1": "~J:subdoc",
        "subdoc2": "~T:subdoc"
    } } {
    val1 hello
    val2 1e6
    subdoc {
        { "thing3": "~S:val1" }
    } }

The result (with formatting for readability):

{
    "thing1":"hello",
    "thing2":["a",1000000.0,"1e6",true,null,"~S:val1"],
    "subdoc1":{"thing3":"~S:val1"},
    "subdoc2":{"thing3":"hello"} }

KEYWORDS
json, parsing, formatting