JSON::object

Description

This command is a group of subcommands that operate on a JSON object (first parameter of each subcommand).

Note

In most cases, it is best to avoid replicate keys within a JSON object. If you want to avoid replicate keys, use JSON::object set exclusively rather than JSON::object add. If the use-case permits, avoiding the possibility of replicate keys will make object access and manipulation much easier.

Syntax

JSON::object size <object> [<key>]
JSON::object type <object> <key>
JSON::object get <object> <key> [<type>]
JSON::object set <object> <key> <type> [<value>]
JSON::object add <object> <key> <type> [<value>]
JSON::object remove <object> <key> [<type> <value>]
JSON::object keys <object>
JSON::object values <object> [<key>]

JSON::object size <object> [<key>]

  • Return the current number of key:value pairs (entries) in the object. If a key is given, filter on the key to return the number of entries with that key (replicate keys).

JSON::object type <object> <key>

  • Return a string representing the type of the value stored at a key in an object. If there are replicates of the key, which occurrence gets selected is undefined. The strings returned follow the same pattern as described for the ‘JSON::type’ command.

JSON::object get <object> <key> [<type>]

  • Return the value stored at a given key in the object. When type is supplied, return a type-specific Tcl representation of the data within the JSON element (see ‘JSON::get’ return values). When type is not given, return the JSON element handle. If the object contains multiple entries with the given key (replicates), which value is returned is undefined. In cases where replicates are possible, use the ‘JSON::object values’ subcommand.

JSON::object set <object> <key> <type> [<value>]

  • Store a value in an object at the given key, replacing any previous value (there does not need to be a previous value). The value is described by a type and (depending on the type) a value (see ‘JSON::set’ for more details). Return a JSON element handle for the newly created and stored value. If the object contains multiple values with the given key (replicates), which value is affected is undefined. If you want to replace a particular value, use ‘JSON::object remove’ (specifying the old value) then add a new value with ‘JSON::object add’.

JSON::object add <object> <key> <type> [<value>]

  • Add a new key:value pair to an object. The key is not required to be unique. The value is described by a type and (depending on the type) a value (see ‘JSON::set’ for more details). FIXME: If an identical value is already stored with the same key, a new key:value pair is not added. Return a JSON element handle for the newly created and added value.

JSON::object remove <object> <key> [<type> <value>]

  • Removes a key:value pair from an object, if the specified key is present. If a value is specified (with its type), it must exactly match a value stored at the key in the object. Otherwise, it is not removed. This is useful in cases where an object may have multiple values with the same key.

JSON::object keys <object>

  • Returns a Tcl list of the keys within the object. The order is undefined.

JSON::object values <object> [<key>]

  • Returns a Tcl list of all the values stored at the given key in the object. If the key has multiple values, the list contains all of them (FIXME make it so: they are each unique at the key, because replicate values are not stored at the same key). If the key is omitted or empty, the returned list contains all values in the object.

Examples

when JSON_REQUEST {
    set rootval [JSON::root]
    set obj [JSON::get $rootval object]

    set size [JSON::object size $obj]
    set type_at_key [JSON::object type $obj somekey]
    set myint [JSON::object get $obj intkey integer]
    JSON::object set $obj intkey integer 500
    JSON::object add $obj namekey string John
    JSON::object remove $obj intkey
    set mykeylist [JSON::object keys $obj]
    set myvaluelist [JSON::object values $obj]
}