General Remarks

All Operations from the JSONXOP_ namespace exist as Functions in the JSON_ namespace. Operations reside in the XOP while functions are defined directly in Igor Pro. For typical applications, functions are preferred over operations.

All operations accept the /Z=1 flag to not generate a runtime error. If set, the error information is stored in V_flag. A value of V_flag = 0 means no error. If /Z is not set, the value of V_flag is not altered and a runtime error is thrown that can be read using GetRTError(1).

Create and Release

When interacting with the JSON XOP, you have to instantiate a representation of your JSON object:

register a new object
JSONXOP_New [ /Q[=q] /Z[=z] ]

Creating a new JSON object returns the registered identification number (id) in V_Value. This id is internally resolved to a pointer in the cpp representation and kept in memory. The user should store this id in a variable and remove the object from memory after using it with JSONXOP_Release.

The initial string representation of this JSON object is identical to a null string "" and will not contain any data.

Calling the operation in this manner serves as an entry point for most XOP interactions, it is linked to the function JSON_New() which directly returns the id.

Releasing unused instances from memory is recommended in user function code as all instantiated objects will be kept in memory during an Igor Pro session.

release an existing object
JSONXOP_Release [ /Q[=q] /Z[=z] ] jsonID

Releasing can also be done using the linked wrapper function JSON_Release().

Here is a complete example of creating and releasing the object:

JSONXOP_New
Variable jsonID = V_Value

JSONXOP_Release jsonID

Parse and Dump

The parse operation takes care of converting a JSON string representation to the corresponding JSON object. The operation returns an id referencing a pointer to the object in V_Value.

parse a JSON string
JSONXOP_Parse [ /Q[=q] /Z[=z] ] jsonStr

The dump operation converts the content of a JSON object representation to a string representation and stores the output in S_Value. The dump function will accept a valid JSON object specified by its jsonID. The corresponding function is JSON_Parse().

dump a JSON object
JSONXOP_Dump [ /Q[=q] /Z[=z] /IND=indent] jsonID

These operations follow the defined Mappings to convert Strings and Numbers into JSON representations. You can specify the number of spaces for each level of indentation using the /IND flag. Here is an example of parsing and dumping a JSON string:

parsing and dumping
JSONXOP_Parse "{\"a complex json\" : \"string\" }"
Variable jsonID = V_Value
JSONXOP_Dump jsonID
print S_Value
JSONXOP_Release jsonID

The corresponding function is JSON_Dump().

Structured Types

Structured types are either objects or arrays. Objects and arrays contain a list of items. In arrays, these items are called elements and for objects, they are called members.

While an array is a collection of a strictly ordered but unnamed list of values, objects contain a named but unordered dictionary of unique entries. These object entries are arbitrary collections of (name, value) pairs. A name is not necessarily defined as unique within JSON but duplicate entries will not lead to reproducible behavior in the context of this XOP. We will call these pairs members in the following context. Only objects contain members.

Both types can be created using the same operation while specifying the object type with a numeric constant using the /T flag. The flag is mandatory and can be one of the following define constants:

add structured types
JSONXOP_AddTree [ /Q[=q] /Z[=z] ] /T=type jsonID, jsonPath

The path has to point to a non-existing entity or an empty object. Existing path elements will not be overwritten and would need to get deleted manually using JSONXOP_Remove to avoid overwriting and data loss. If an existing path element leads to such an exception, the XOP will respond with an error.

create structured types
JSONXOP_New
Variable jsonID = V_Value
JSONXOP_AddTree/T=(JSON_OBJECT) jsonID, "/object"
JSONXOP_AddTree/T=(JSON_ARRAY) jsonID, "/array"
JSONXOP_AddTree/T=(JSON_ARRAY) jsonID, "/array/0"
JSONXOP_Release jsonID
JSON representation
{
  "object": {},
  "array": [[]]
}

Non-existing child elements in the specified path tree are recursively created as objects:

creating children
JSONXOP_New
Variable jsonID = V_Value
JSONXOP_AddTree/T=(JSON_OBJECT) jsonID, "/object/child"
JSONXOP_AddTree/T=(JSON_ARRAY) jsonID, "/array/child"
JSONXOP_Release jsonID
JSON representation
{
  "object": {
    "child": {}
  },
  "array": {
    "child": []
  },
}

To remove an object, array or any child entity from an instance you need to specify the numeric jsonID of the main representation along with its full JSON pointer as string jsonPath. The complete entity is then removed from the JSON representation. JSONXOP_Remove then recursively deletes all elements at the given jsonPath.

remove entities
JSONXOP_Remove [ /Q[=q] /Z[=z] ] jsonID, jsonPath

The corresponding function is JSON_Remove(). For more details on how to specify paths, see JSON path.

Array elements and object member values can contain all primitive and structured JSON Types as well as literal names. To add values to a generated structured type, use the JSONXOP_AddValue operation.

Add and Get Values

add value

The JSONXOP_AddValue operation adds a (name, value) pair to an object and can also be used to add elements to an array.

add a value
JSONXOP_AddValue [/Q[=q] /Z[=z] /O /JOIN=childID /OBJ[=objCount] /WAVE=wave /L=64bitIntegerWave /B=boolean /I=number /N /S=significance /T=string /V=number] jsonID, jsonPath

Within objects, the last element of the JSON path specifies the new name which must be a unique string and the value must be one of the accepted Igor Pro Types. When adding values to arrays, the last element within the JSON path has to exist and has to be an array. The add value operation does not create non-existing objects in the path. Use JSONXOP_AddTree to create structured types in the path. To overwrite existing non-null elements, use the /O flag.

{
  "array": [
    0,
    1,
    2,
    3,
    4
  ]
}
JSONXOP_AddValue/O/T="text" jsonID, "/array/0"
{
  "array": [
    "text",
    1,
    2,
    3,
    4
  ]
}

Array elements can be removed using the JSONXOP_Remove operation:

JSONXOP_Remove jsonID, "/array/0"
JSON String after removal of the first element
{
  "array": [
    1,
    2,
    3,
    4
  ]
}

The value type is further specified using operation flags. The behavior of these flags is described in the following sections:

The following functionalities for the add value operation exist:

add string

Adding Strings is done using the /T flag (text) of the JSONXOP_AddValue Operation. The equivalent function is JSON_AddString(). Overwriting can be achived with JSON_SetString()

add a string value as member
JSONXOP_New
Variable jsonID = V_Value
String path = "string"
String value = "abcd"

JSONXOP_AddValue/T=value jsonID, path
JSON representation
{
  "string": "abcd"
}

add numeric

Adding Numbers can be achieved using the /V flag (variable) or the /I flag (integer) of the JSONXOP_AddValue Operation. The equivalent function is JSON_AddVariable(). Adding 64bit values can be accomplished using JSON_AddInt64() and JSON_AddUInt64(). Overwriting can be achived with JSON_SetVariable(), JSON_SetInt64(), and JSON_SetUInt64().

The number of significant digits for floating point numbers that are written to the JSON representation can be specified by the optional /S flag (significance). The string generated with the /S flag uses exponential notation and specifies the number of digits after the decimal separator.

The output data type of Numbers can be controlled with the following flags:

  • /I → number without a fractional part
  • /V → number with an optional fractional part
add numeric values as members
JSONXOP_New
Variable jsonID = V_Value
String path
Variable value
Variable significance

path = "key1"
value = 42
JSONXOP_AddValue/I=value jsonID, path

path  = "key2"
value = 42.000123
significance = 6
JSONXOP_AddValue/V=value/S=significance jsonID, path
JSON representation
{
  "key1": 42,
  "key2": 4.20001E1
}

add null

A null value is added using the /N flag of the JSONXOP_AddValue Operation. The equivalent function is JSON_AddNull(). Overwriting can be achieved with JSON_SetNull().

add the null type as member
JSONXOP_New
Variable jsonID = V_Value
String path = "null type"

JSONXOP_AddValue/N jsonID, path
JSON representation
{
  "null type": null
}

Null values can be overwritten with other values without the explicit use of the /O flag.

add boolean

Adding boolean values is done with the /B flag of the JSONXOP_AddValue Operation. The equivalent function is JSON_AddBoolean(). Overwriting can be achieved with JSON_SetBoolean().

add a boolean type as member
JSONXOP_New
Variable jsonID = V_Value
String path = "boolean"
Variable value = 0

JSONXOP_AddValue/B=value jsonID, path
JSON representation
{
  "boolean": false
}

add wave

Arrays of elements with the same primitive type can be added as waves. N-dimensional waves are transferred row-oriented into JSON. This means that a 2 column wave will be transferred into an array of two sub-arrays of equal length. The equivalent function is JSON_AddWave(). Overwriting can be achieved with JSON_SetWave().

add a wave as array
JSON_New
Variable jsonID = V_Value
String path = "/path/to/array"
WAVE wv

JSONXOP_AddValue/WAVE=wv jsonID, path

Waves of data folders or wave references are not supported.

Mixed-type arrays can contain different JSON Types and are therefore incompatible to be read or written as waves. They have to be built and read one element at a time.

get value

The JSONXOP_GetValue Operation is designed for retrieving both strings, and numeric variables from a JSON structured type. It can read primitive types into their Igor Pro representation and arrays to waves. If the corresponding object is read as string, the return p S_Value will be filled. If it is a numeric representation, the variable V_Value will be filled. To determine the type of an object that you want to read, use the JSONXOP_GetType operation or the JSON_GetType() function. Path accepts any existing entity using JSON path.

The equivalent functions are

get a value
JSONXOP_GetValue [/Q[=q] /Z[=z] /V /T /WAVE=wave /TWAV=textWave /L=64bitIntegerWave] jsonID, jsonPath

Booleans, null and Numbers are converted according to the defined Mappings.

Since special numeric values like NaN and Inf are stored as strings, you may force-read to a specific output format. Use /T and /V to explicitly read as String or Variable.

The get value operation also supports reading waves from arrays. Use the flags /T or /V to specify the wave type. You can also define the output wave type by creating a wave with the target output format and passing it to the flag.

get type

The JSONXOP_GetType operation returns one of the JSON Types for a specific named value in the object referenced by jsonID. jsonPath can be a full POSIX compatible path.

get the type of the path element
JSONXOP_GetType [ /Q[=q] /Z[=z] ] jsonID, jsonPath

Valid return values for JSON Types are

get keys

The JSONXOP_GetKeys operation lists all members that belong to the same level in a specified json path. The result is stored in a text wave, which is given with the third input parameter. The wave is automatically created if it does not exist.

get the keys for all members
JSONXOP_GetKeys [ /ESC[=esc] /Q[=q] /Z[=z] ] jsonID, jsonPath, keys

Reading the following JSON string will give a wave with two elements:

JSON representation
{
  "element1": null,
  "element2": null
}
usage example of the get keys operation
JSONXOP_GetKeys jsonID, "", keys
print keys
 keys[0]= {"element1","element2"}

The JSONXOP_GetKeys operation can be useful if the structure of an input JSON string is unknown or if the presence of a specific named member has to be checked.

The corresponding function is JSON_GetKeys().

Array Operations

The following operations are specific to array interactions.

get array size

It is possible to return the number of elements in an array. The first dimension is specified by /path/to/array. If there are any nested arrays within this array, they can be read by specifying the parent element. The second dimension is accessed by /path/to/array/0 and the third by /path/to/array/0/0.

Note that arrays can be of mixed size. To get the maximum for a given dimension, use the get maximum array size operation.

get the array size
JSONXOP_GetArraySize [ /Q[=q] /Z[=z] ] jsonID, jsonPath

The corresponding function is JSON_GetArraySize().

get maximum array size

Since arrays can be of mixed size, the maximum dimension of an array can be retrieved using the following operation:

get maximum array size
JSONXOP_GetMaxArraySize [ /Q[=q] /Z[=z] ] jsonID, jsonPath, wave

This outputs a free wave with the maximum size for each dimension found in the array at jsonPath.

The corresponding function is JSON_GetMaxArraySize()

Version Information

This operation outputs version information useful for issue reports.

generate version information
JSONXOP_Version [ /Z[=z] ]

The corresponding function is JSON_Version() which also includes Igor Pro and operating system version information.