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:

• body
  The body part of the last received or sent JSON-RPC message. This attribute is not usually set.
• bodylength
  The length of the body in bytes. This is a read-only attribute.
• channel
  The communication channel associated with the JSON object. This is a standard Tcl channel handle. It is possible to set it to an empty string, which indicates that no channel is set.
• errorcode
  The error code from the last JSON parsing step as integer value. If no error occurred, the value is 0.
• errormsg
  The message of a JSON error, either as extracted from a JSON-RPC message, or set in preparation of sending an error message. If set, it must be formatted as a simple string.
• errordata
  Auxiliary informative data in an JSON error message, as per the JSON-RPC specification. This information is either extracted from a JSON message, or set in preparation for sending an error report. If set, it must be a properly formatted JSON object.
• handle
  A read-only attribute to get the Tcl handle of the object.
• header
  The header part of the last received JSON-RPC message. This attribute is not usually set.
• headerlength
  The length of the header in bytes. This is a read-only attribute.
• host
  The host the JSON object communicates with.
• id
  The JSON-RPC message ID. For sent messages, this is automatically incremented. If a received message contains a NULL ID, the value is set to zero.
• method
  The method name extracted either from the last received JSON-RPC message, or set in preparing to transmit a message.
• parameters
  The JSON-RPC method parameters. If queried, this is a dictionary of name/value pairs. In order to set these, a properly formatted dictionary must be supplied. The formatting is the same as for the parameters attribute of property definitions.
• port
  The port the JSON object uses for network communication. The default is 80, the standard HTTP port.
• result
  The method invocation result data extracted from the last received JSON-RPC message, or the data which is sent with the next response. If set, its format must be a properly formed JSON object. For further analysis, this value is usually decoded with a decode -json statement.
• uri
  The URI associated with a JSON-RPC service.

json subcommands

json subcommands

dir(Json)

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