aboutsummaryrefslogtreecommitdiff

csound-json : JSON parsing and manipulation for Csound

Overview

csound-json provides over fifty permutations of opcodes for the parsing and manipulation of JSON. Data can be deserialised from a string or file, and similarly serialised and output to string or file. Simple key/index access is available, as are more powerful query expressions using JSONPath and JSON Pointer. Arrays can be easily translated to native Csound arrays and reinserted to JSON structures. Mostly all operations are performed on object handles, which are Csound references to JSON objects stored internally. All opcodes are available at init time, and those feasible for k-rate performance are additionally provided.

Requirements

  • Cmake >= 2.8.12
  • Csound with development headers >= 6.14.0
  • Compiler with C++11 support
    • If using G++, >= 4.8.5 is needed due to std::regex implementation

Installation

Create a build directory at the top of the source tree, execute cmake .., make and optionally make install as root. If the latter is not used/possible then the resulting library can be used with the --opcode-lib flag in Csound. eg:

git clone https://git.1bpm.net/csound-json
cd csound-json
mkdir build && cd build
cmake ..
make && sudo make install

Cmake should find Csound and any other required libraries using the modules in the cmake/Modules directory and installation should be as simple as above.

Examples

Some examples are provided in the examples directory.

Opcode reference

jsonloads

Parse a JSON string and load to an object handle for use in other opcodes.

iJson jsonloads Sjson
  • iJson loaded JSON object handle
  • Sjson string to parse

jsonload

Parse JSON from a file and load to an object handle for use in other opcodes.

iJson jsonload Sfile
  • iJson loaded JSON object handle
  • Sfile file path containing JSON data

jsondumps

Output a JSON object handle as a string.

Soutput jsondumps iJson [, ipretty=1]
  • Soutput the serialised object contents
  • iJson JSON object handle to evaluate
  • ipretty 1=pretty print with formatting and indenting, 0=raw

jsondumpsk

Output a JSON object handle as a string at k-rate

Soutput jsondumpsk iJson [, ipretty=1]
  • Soutput the serialised object contents, at k-rate
  • iJson JSON object handle to evaluate
  • ipretty 1=pretty print with formatting and indenting, 0=raw

jsondump

Output a JSON object handle to a text file.

jsondump iJson, Sfile [, ipretty=1]
  • iJson JSON object handle to evaluate
  • Sfile file path to write serialised object contents to
  • ipretty 1=pretty print with formatting and indenting, 0=raw

jsoninit

Initialise an empty JSON object (equivalent to iJson jsonloads "{}").

iJson jsoninit
  • iJson new empty object

jsondestroy

Delete a JSON object and free memory.

jsondestroy iJson
  • iJson JSON object handle to destroy

jsonmerge

Shallow merge two JSON object handles, from iJsonSource into iJsonTarget. If iupdate = 1, then any existing keys will be altered, otherwise existing keys will not be merged.

jsonmerge iJsonTarget, iJsonSource [, iupdate=0]
  • iJsonTarget JSON object handle to be merged into.
  • iJsonSource JSON object handle to be merged from.
  • iupdate 1=update and replace any keys that exist in iJsonTarget; 0=skip merging existing keys.

jsoninsert

Insert a JSON object handle to another JSON object handle with a specified key. An array of JSON object handles can be provided as iJsonInsert[], which are then inserted as their relevant types under the key Skey.

jsoninsert iJson, Skey, iJsonInsert
jsoninsert iJson, Skey, iJsonInsert[]
  • iJson JSON object handle to insert to
  • Skey key name under which the objects will be added
  • iJsonInsert single JSON object handle
  • iJsonInsert[] array of JSON object handles

jsoninsertval

Insert a single value or a set of values to a JSON object handle. When Skeys[] and (Svalues[] or ivalues[]) are both provided, the array lengths must match and are inserted as a set of individual key/value pairs. When Skey and (Svalues[] or ivalues[]) are provided, the values are inserted into Skey as an array.

jsoninsertval iJson, Skey, Svalue
jsoninsertval iJson, Skey, ivalue
jsoninsertval iJson, Skey, ivalues[]
jsoninsertval iJson, Skey, Svalues[]
jsoninsertval iJson, Skeys[], ivalues[]
jsoninsertval iJson, Skeys[], Svalues[]
  • iJson JSON object handle to insert to
  • Skey key name under which the value(s) will be added
  • Svalue string value to be added
  • ivalue numeric value to be added
  • Svalues[] array of string values to be added
  • ivalues[] array of numeric values to be added
  • Skeys[] array of keys to be used for key/value operation

jsoninsertvalk

Insert a single value or a set of values to a JSON object handle, at k-rate When Skeys[] and (Svalues[] or kvalues[]) are both provided, the array lengths must match and are inserted as a set of individual key/value pairs. When Skey and (Svalues[] or kvalues[]) are provided, the values are inserted into Skey as an array.

jsoninsertvalk iJson, Skey, Svalue
jsoninsertvalk iJson, Skey, kvalue
jsoninsertvalk iJson, Skey, kvalues[]
jsoninsertvalk iJson, Skey, Svalues[]
jsoninsertvalk iJson, Skeys[], kvalues[]
jsoninsertvalk iJson, Skeys[], Svalues[]
  • iJson JSON object handle to insert to
  • Skey key name under which the value(s) will be added
  • Svalue string value to be added
  • kvalue numeric value to be added
  • Svalues[] array of string values to be added
  • kvalues[] array of numeric values to be added
  • Skeys[] array of keys to be used for key/value operation

jsontype

Get the type of a JSON object handle.

itype jsontype iJson
Stype jsontype iJson
  • itype numeric type:
    • -1 unknown
    • 0 null
    • 1 string
    • 2 number
    • 3 boolean
    • 4 array
    • 5 object
  • Stype string type, as listed above
  • iJson JSON object handle to evaluate

jsonkeys

Get the keys of a JSON object handle, if available (ie, if the type is object).

Skeys[] jsonkeys iJson
  • Skeys[] the keys
  • iJson JSON object handle to evaluate

jsonkeysk

Get the keys of a JSON object handle at k-rate, if available (ie, if the type is object).

Skeys[] jsonkeysk iJson
  • Skeys[] the keys, at k-rate
  • iJson JSON object handle to evaluate

jsonsize

Get the size of a JSON object handle (ie, the array size or number of object keys).

isize jsonsize iJson
  • isize number of elements
  • iJson JSON object handle to evaluate

jsonsizek

Get the size of a JSON object handle at k-rate (ie, the array size or number of object keys).

ksize jsonsizek iJson
  • ksize number of elements
  • iJson JSON object handle to evaluate

jsonget

Get a JSON object handle of the object contained in the specified key or index.

iJsonOutput jsonget iJson, Skey
iJsonOutput jsonget iJson, index
  • iJsonOutput the JSON object handle as contained in Skey or index
  • iJson JSON object handle to evaluate
  • Skey key for accessing an object
  • index index for accessing an array

jsongetval

Get a numeric or string value from an object by string key or numeric index.

Svalue jsongetval iJson, Skey
ivalue jsongetval iJson, Skey
Svalue jsongetval iJson, index
ivalue jsongetval iJson, index
  • Svalue string value returned
  • ivalue numeric value returned
  • iJson JSON object handle to evaluate
  • Skey key for accessing an object
  • index index for accessing an array

jsongetvalk

Get a numeric or string value from an object by string key or numeric index, at k-rate.

Svalue jsongetvalk iJson, Skey
kvalue jsongetvalk iJson, Skey
Svalue jsongetvalk iJson, kindex
kvalue jsongetvalk iJson, kindex
  • Svalue string value returned
  • kvalue numeric value returned
  • iJson JSON object handle to evaluate
  • Skey key for accessing an object
  • kindex index for accessing an array

jsonpath

Perform a JSONPath query and obtain the resulting JSON object handle.

iJsonOutput jsonpath iJson, Spath
  • iJsonOutput JSON object handle specified by Spath
  • iJson JSON object handle to evaluate
  • Spath JSONPath expression

jsonpathrplval

Replace a value in a location specified by the JSONPath expression Spath

jsonpathrplval iJson, Spath, ivalue
jsonpathrplval iJson, Spath, Svalue
  • iJson JSON object handle to evaluate
  • Spath JSONPath expression
  • ivalue numeric value to replace target with
  • Svalue string value to replace target with

jsonpathrplvalk

Replace a value in a location specified by the JSONPath expression Spath at k-rate.

jsonpathrplvalk iJson, Spath, kvalue
jsonpathrplvalk iJson, Spath, Svalue
  • iJson JSON object handle to evaluate
  • Spath JSONPath expression
  • kvalue numeric value to replace target with
  • Svalue string value to replace target with

jsonptr

Perform a JSON Pointer query and obtain the resulting JSON object handle.

iJsonOutput jsonptr iJson, Spointer
  • iJsonOutput JSON object handle specified by Spointer
  • iJson JSON object handle to evaluate
  • Spointer JSON Pointer expression

jsonptrval

Use a JSON Pointer query to obtain a string/numeric value, or an array of string/numeric.

ivalue jsonptrval iJson, Spointer
Svalue jsonptrval iJson, Spointer
ivalues[] jsonptrval iJson, Spointer
Svalues[] jsonptrval iJson, Spointer
  • ivalue numeric output value
  • Svalue string output value
  • ivalues[] numeric array output values
  • Svalues[] string array output values
  • iJson JSON object handle to evaluate
  • Spointer JSON Pointer expression

jsonptrvalk

Use a JSON Pointer query to obtain a string/numeric value, or an array of string/numeric, at k-rate.

kvalue jsonptrvalk iJson, Spointer
Svalue jsonptrvalk iJson, Spointer
kvalues[] jsonptrvalk iJson, Spointer
Svalues[] jsonptrvalk iJson, Spointer
  • kvalue numeric output value
  • Svalue string output value
  • kvalues[] numeric array output values
  • Svalues[] string array output values
  • iJson JSON object handle to evaluate
  • Spointer JSON Pointer expression

jsonptrarr

Get an array of JSON object handles from a JSON Pointer query.

iJsonObjects[] jsonptrarr iJson, Spointer
  • iJsonObjects[] array of JSON object handles
  • iJson JSON object handle to evaluate
  • Spointer JSON Pointer expression

jsonptrhas

Check if a JSON Pointer query results in a valid existing object.

iexists jsonptrhas iJson, Spointer
  • iexists 1 if existing, 0 if not
  • iJson JSON object handle to evaluate
  • Spointer JSON Pointer expression

jsonptrhask

Check if a JSON Pointer query results in a valid existing object, at k-rate

kexists jsonptrhask iJson, Spointer
  • kexists 1 if existing, 0 if not
  • iJson JSON object handle to evaluate
  • Spointer JSON Pointer expression

jsonptraddval

Add a value at a location specified by the JSON Pointer expression Spointer.

jsonptraddval iJson, Spointer, ivalue
jsonptraddval iJson, Spointer, Svalue
  • iJson JSON object handle to add value to
  • Spointer JSON Pointer expression
  • ivalue numeric value to add
  • Svalue string value to add

jsonptraddvalk

Add a value at a location specified by the JSON Pointer expression Spointer.

jsonptraddvalk iJson, Spointer, kvalue
jsonptraddvalk iJson, Spointer, Svalue
  • iJson JSON object handle to add value to
  • Spointer JSON Pointer expression
  • kvalue numeric value to add
  • Svalue string value to add

jsonptradd

Add a JSON object handle to a location specified by the JSON Pointer expression Spointer.

jsonptradd iJson, Spointer, iJsonNew
  • iJson JSON object handle to add to
  • Spointer JSON pointer expression
  • iJsonNew JSON object handle to add to iJson

jsonptrrm

Remove an object specified by the JSON Pointer expression Spointer.

jsonptrrm iJson, Spointer
  • iJson JSON object handle to remove from
  • Spointer JSON pointer expression

jsonptrrmk

Remove an object specified by the JSON Pointer expression Spointer, at k-rate.

jsonptrrmk iJson, Spointer
  • iJson JSON object handle to remove from
  • Spointer JSON pointer expression, at k-rate

jsonptrrplval

Replace a value specified by the JSON Pointer expression Spointer.

jsonptrrplval iJson, Spointer, ivalue
jsonptrrplval iJson, Spointer, Svalue
  • iJson JSON object handle to replace in
  • Spointer JSON Pointer expression
  • ivalue numeric value to set
  • Svalue string value to set

jsonptrrplvalk

Replace a value specified by the JSON Pointer expression Spointer, at k-rate.

jsonptrrplvalk iJson, Spointer, kvalue
jsonptrrplvalk iJson, Spointer, Svalue
  • iJson JSON object handle to replace in
  • Spointer JSON Pointer expression
  • kvalue numeric value to set
  • Svalue string value to set

jsonptrrpl

Replace an object specified by the JSON Pointer expression Spointer.

jsonptrrpl iJson, Spointer, iJsonNew
  • iJson JSON object handle to replace in
  • Spointer JSON Pointer expression
  • iJsonNew JSON object handle to set

jsonarrval

Get an array of values from a JSON object handle.

ivalues[] jsonarrval iJson
Svalues[] jsonarrval iJson
  • ivalues[] returned numeric values
  • Svalues[] returned string values
  • iJson JSON object handle to evaluate

jsonarrvalk

Get an array of values from a JSON object handle, at k-rate.

kvalues[] jsonarrvalk iJson
Svalues[] jsonarrvalk iJson
  • kvalues[] returned numeric values
  • Svalues[] returned string values
  • iJson JSON object handle to evaluate

jsonarr

Get an array of JSON object handles from a JSON object handle.

iJsonObjects[] jsonarr iJson
  • iJsonObjects[] array of JSON object handles
  • iJson JSON object handle to evaluate
generated by cgit v1.2.3 (git 2.25.1) at 2024-04-20 05:14:28 +0000