The json Command

The json command is used to facilitate network communication by means of exchanging JSON-RPC messages. JSON message objects are also useful to parse other styles of JSON -formatted data which are not really JSON-RPC but use basic JSON encodings.

JSON objects are created like other toolkit objects, and have internal state, so it is possible to communicate with multiple sources simultaneously by creating a JSON object for every channel.

JSON objects share many characteristics with SOAP objects, and many commands are identical or at least very similar.

Only interpreters compiled with JSON support contain this command.

These are the currently supported JSON object commands:

json append

json append jsonhandle ?attribute value?...
json append jsonhandle dict
j.append(?attribute,value?,...)
j.append(?attribute=value?,...)
j.append(dict)

This is a variant of the json set command. The difference is that the supplied data is appended to the current attribute value instead of replacing it. In case appending is not a possible operation, the result is the same as using json set .

The set of supported attributes is explained in the paragraph on json set .

The command returns the original handle or reference.

json create

json create ?attribute value?...
json create dict
Json(?attribute,value?,...)
Json(dict)
Json(?attribute=value?,...)
Json.Create(?attribute,value?,...)
Json.Create(dict)
Json.Create(?attribute=value?,...)

Create a new JSON object. The return value is the object handle or reference. If no additional attributes are specified, an object with default settings is created. Processing of specified optional attribute/value pairs is performed in as an identical fashion to the json set command.

json delete

json delete ?jsonhandle?...
json delete all
j.delete()
Json.Delete(?jsonhandle/jref?,...)
Json.Delete(“all”)

Destroy one or more JSON objects. The special handle all can be used to remove all JSON objects currently existing in the application.

For the sake of consistency with commands of similar objects, json close is an alias to this command.

The return value is the number of successfully deleted JSON objects.

json error

json error jsonhandle ?errormessage? ?channel? ?errorcode? ?errordata? ?id?
j.error(?errormessage=?,?channel=?,?errorcode=?,?errordata=?,?id=?)

Assemble and potentially send a properly formatted JSON-RPC error message. The formatted message is stored in the result attribute of the JSON object, returned as command result, and also sent via the channel if either the argument is a valid Tcl or Python channel handle, or the object has an associated channel in the internal attribute set.

All message parameters are taken from the internal object attribute set if they are not explicitly set in the arguments. If arguments are set, the corresponding object attributes are also updated. Any arguments must be properly formatted - the error code and ID are an integer, the error message a simple string, and the error data a complete JSON object encoding.

Since this command is a reply to a specific message ID, the internal object ID attribute is not incremented, as in the json request command.

json get

json get jsonhandle attribute
j.get(attribute)
j.attribute
j[attribute]

Query the value of an attribute of a JSON object. The list of recognized attributes is explained in the paragraph on the json set command.

The return value of the command is the value of the attribute.

json list

json list ?pattern?
Json.List(?pattern=?)

Return a list of the handles of all currently existing JSON objects in the application. If desired, the list can be filtered by a string pattern.

json parse

json parse jsonhandle ?data?
j.parse(?data=?)

Parse a JSON-RPC message. If the data argument is set, its value is used. Otherwise the parsed data is the value currently stored in the body object attribute, which is for example set by the json read command. The command does not replace the body attribute of the object if an explicit argument is set.

The command resets the ID, error code, error message, error data and result attributes of the object and then re-populates those object fields for which data is found in the message.

The return value of the command is one, if the message was a valid result reply, and zero if the message was an error report. In case of a syntax error in the parsed data, a Tcl or Python error is generated.

After parsing, the result and errordata object attributes, if they were set during the parse, are still JSON object encodings. In most cases these are further dissected by the application of a decode -json command.

json read

json read jsonhandle ?channel?
j.read(?channel=?)

Read one JSON-RPC message from the channel. If no channel argument is supplied, the internal channel handle of the object is used. It the channel argument is set, the internal attribute is also updated.

The command recognizes HTTP headers in the input stream and stores these separately from the message body in the internal header object attribute. Only a single message is read from the channel, so in case there are multiple messages queued, the command must be repeatedly invoked. The complete message text, without header if there was one, is stored in the body object attribute.

The command returns the full message text, which is the same as the body attribute. It is not parsed or analyzed further. This command does not alter the errorcode , errormessage , errordata or result fields of the object. In most cases, the next step after reading a message is to analyses it with a json parse command.

json ref

Json.Ref(identifier)

Python -only method to get a reference of the JSON object from its handle.

json request

json request jsonhandle ?method? ?channel? ?parameterdict?
j.request(?method=?,?channel=?,?parameters=?)

Assemble a properly formatted JSON-RPC request and potentially send it. The formatted message is returned as command result, and also sent via the channel if either that argument is a valid Tcl or Python channel handle, or the object has an associated channel in the internal attribute set.

All parameters are taken from the internal object attribute set if they are not explicitly set in the arguments. If arguments are supplied, the corresponding object attributes are also updated. Any arguments must be properly formatted - the method name is a simple string, and the parameters are a dictionary.

The internal message ID attribute of the object is incremented when this command is run, and the new value is transmitted. The first message ID of a newly created JSON object is one. To send a message without an ID, use the json send command.

json respond

json respond jsonhandle ?message? ?channel? ?id?
j.respond(?message=?,?channel=?,?id=?)

Assemble and potentially send a properly formatted JSON-RPC result message. The formatted message is stored in the result attribute of the JSON object, returned as command result, and also sent via the channel if either the argument is a valid Tcl or Python channel handle, or the object has an associated channel in the internal attribute set.

All parameters are taken from the internal object attribute set if they are not explicitly set in the arguments. If arguments are supplied, the corresponding object attributes are also updated. Any arguments must be properly formatted - the message argument is a JSON object encoding and the ID is an integer.

Since this command is a reply to a specific message ID, the internal object ID attribute is not incremented as in the json request command.

The command can also be spelled as json reply .

json send

json send jsonhandle ?method? ?channel? ?parameterdict?
j.send(?method=?,?channel=?,?parameters=?)

This command is essentially the same as json request , except that this is a notification for which no response is expected. The ID value in the message text is therefore always NULL , and internal ID attribute of the object is not incremented.

json set

json set jsonhandle ?attribute value?...
json set jsonhjandle dict
j.set(?attribute,value?,...)
j.set(dict)
j.set(?attribute=value?,...)
j.attribute = value
j[attribute] = value

Set one or more attributes of a JSON object. Since this paragraph is also referenced from the json get subcommand, the attribute set listed here includes attributes which cannot be set, or for which setting them to a scripted value does not usually make sense.

The currently supported set of attributes is:

json subcommands

json subcommands
dir(Json)

This command returns a list of all the defined subcommands of the json command.