cabbageJsonGet

This opcode queries a JSON document using dot-notation paths (nodes.0.params.rate, where numeric segments index arrays). The output variable determines the expected type: assign to a string, number, or array and the matching overload runs. Invalid documents, missing paths, and type mismatches degrade gracefully to empty/zero values — use cabbageJsonType and cabbageJsonHas when the distinction matters.

Syntax

val:S = cabbageJsonGet(json:S, path:S)
val:k = cabbageJsonGet(json:S, path:S)
val:i = cabbageJsonGet(json:S, path:S)
val:S, trig:k = cabbageJsonGet(json:S, path:S)
res:CabbageStrTrig = cabbageJsonGet(json:S, path:S)
arr:S[] = cabbageJsonGet(json:S, path:S)
arr:k[] = cabbageJsonGet(json:S, path:S)

Initialization

• json:S – a string holding a valid JSON document
• path:S – dot-notation path into the document
• val:S – strings come back verbatim; numbers, booleans, and containers come back as compact JSON; missing paths yield ""
• val:i – numbers direct; numeric strings parsed ("42" → 42); booleans → 1/0; anything else → 0
• arr:S, arr:k – per-element rules as above (i-time only); missing paths and non-arrays yield empty arrays

Performance

• val:k – as val:i, re-evaluated each k-cycle (the document is re-parsed only when the input text changes)
• val:S – as i-time; the document is re-parsed only when the input text changes
• trig:k – fires 1 for a single k-cycle whenever the result string changes
• res:CabbageStrTrig – the built-in trigger struct form: res.val mirrors val:S and res.trig fires 1 for a single k-cycle whenever the result string changes. k-rate only.

Example:

instr 1
    doc:S = "{\"nodes\":[{\"id\":\"n1\",\"params\":{\"freq\":440}}]}"
    id:S = cabbageJsonGet(doc, "nodes.0.id")
    freq:k = cabbageJsonGet(doc, "nodes.0.params.freq")
    printf("node %s runs at %f Hz\n", 1, id, freq)

    ; trigger struct form: fires when the fetched string changes
    res:CabbageStrTrig cabbageJsonGet(doc, "nodes.0.id")
    if res.trig == 1 then
        printf("id changed to %s\n", 1, res.val)
    endif
endin

Full example

The following instrument exercises the JSON opcodes against a patcher-style state document:

cabbageJson.csd

<Cabbage>
{
    "pluginId": "jsonUtils",
    "widgets": [
        {"type":"form","caption":"JSON Utilities","size":{"width":500,"height":200}}
    ]
}
</Cabbage>
<CsoundSynthesizer>
<CsOptions>
-n -d
</CsOptions>
<CsInstruments>
ksmps = 32
nchnls = 2
0dbfs = 1

instr 1
    ; A patcher-style state document: voices with params plus a mix list.
    json:S = "{\"voices\":[{\"id\":\"vco1\",\"params\":{\"freq\":440,\"amp\":0.5,\"wave\":\"sine\"}},{\"id\":\"lfo1\",\"params\":{\"rate\":2.5}}],\"mix\":[0.8,0.6]}"

    ; --- typed queries: the output variable selects the overload ---
    wave:S = cabbageJsonGet(json, "voices.0.params.wave")
    freq:k = cabbageJsonGet(json, "voices.0.params.freq")
    amp:k = cabbageJsonGet(json, "voices.0.params.amp")
    mix:k[] = cabbageJsonGet(json, "mix")
    has:i = cabbageJsonHas(json, "voices.1.params.rate")
    n:i = cabbageJsonLen(json, "voices")
    type:S = cabbageJsonType(json, "voices.0.params.freq")
    prints("wave=%s type=%s voices=%d has(rate)=%d\n", wave, type, n, has)

    ; --- play voice 0, scaled by the mix list ---
    sig:a = oscili(amp, freq)
    outs(sig*mix[0], sig*mix[1])

    ; --- trigger variant: fires when the result changes ---
    id:S, changed:k = cabbageJsonGet(json, "voices.0.id")
    printks("active voice: %s\n", changed, id)

    ; --- builders: patch the document, read it back ---
    patched:S = cabbageJsonSet(json, "voices.0.params.freq", 880)
    patched = cabbageJsonSet(patched, "voices.0.params.wave", "saw")
    newfreq:i = cabbageJsonGet(patched, "voices.0.params.freq")
    newwave:S = cabbageJsonGet(patched, "voices.0.params.wave")
    prints("patched voice: %s at %f Hz\n", newwave, newfreq)
endin

</CsInstruments>
<CsScore>
i1 0 z
</CsScore>
</CsoundSynthesizer>

Download cabbageJson.csd