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.
- 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
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.
Some examples are provided in the examples directory.
Parse a JSON string and load to an object handle for use in other opcodes.
- iJson loaded JSON object handle
- Sjson string to parse
Parse JSON from a file and load to an object handle for use in other opcodes.
- iJson loaded JSON object handle
- Sfile file path containing JSON data
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
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
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
Initialise an empty JSON object (equivalent to iJson jsonloads "{}").
Delete a JSON object and free memory.
- iJson JSON object handle to destroy
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.
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
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
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
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
Get the keys of a JSON object handle, if available (ie, if the type is object).
- Skeys[] the keys
- iJson JSON object handle to evaluate
Get the keys of a JSON object handle at k-rate, if available (ie, if the type is object).
- Skeys[] the keys, at k-rate
- iJson JSON object handle to evaluate
Get the size of a JSON object handle (ie, the array size or number of object keys).
- isize number of elements
- iJson JSON object handle to evaluate
Get the size of a JSON object handle at k-rate (ie, the array size or number of object keys).
- ksize number of elements
- iJson JSON object handle to evaluate
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
Remove an object specified by the JSON Pointer expression Spointer.
jsonptrrm iJson, Spointer
- iJson JSON object handle to remove from
- Spointer JSON pointer expression
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
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
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
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
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
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
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