aboutsummaryrefslogtreecommitdiff
path: root/README.md
blob: a6a574210c6abf799caa7e0f3ad5a58d1387d49c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412

   

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

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