A fix to JSON parsing (especially more complex JSON objects) in the next public release. Reviewing code samples/docs it did cause me to update and better cross-link articles on JSON operators.
So for export we have:
- String.jsonEncode().
- This replaces
String.json()(do not use the latter though it still works, for legacy code support purposes only).
- This replaces
For reading JSON data we have
- String.captureJSON(). Only needed if ‘String’, e.g. $Text, contains a mix of text and valid JSON code (can only capture the first JSON section, should there be more than one - avoid the latter scenario!).
- JSON.operators —here ‘JSON’ is the same as 'String’ above except the string’s contents is assumed to be only JSON code and nothing else (q.v. .captureJSON()):
JSON.json[]. Primary tool, documented for using .json[keyname] for a given key and .json[N] for array-numbered item access.- JSON.jsonValue(). Getting a value via its JSON path.
- JSON.each().{}. Allows iterations of arrays (lists) in the JSON
Better documented now are why/when to use .captureJSON() and to avoid using trailing ( )parentheses (and thus mistakenly calling the old .json() export operator). Parentheses are the reflexive syntax norm for operators, but here [ ] square brackets are needed!
If the latter seems a bit artisanal or quirky, Tinderbox is not alone in this. These issues occur for any code system maintained and incrementally enhanced over time. New users want less ambiguity, existing users don’t want working code suddenly breaking for—to them—not good reason. However, I think that with care—and feedback as to what isn’t guessable before the fact, documentation can fill the gap.
These updates are a further reflection on the good point surfaced in @dmrogers’s blog http://nice-marmot.net about the unguessables for first time use of some operator code. I don’t think we can remove ambiguity entirely—above is a good example of why—but I have taken on board the need to flag some of the hard-to-guess facts. they are generally obvious only after doing the task successfully the once.
I welcome feedback about other such areas. I have an article part done for (first use of) functions: what is it called, where does it live (and why), how it is called, etc. In part the aim is to get the first-time user to the point where the ‘main’ documentation articles—general longer/more dense) will now make sense. Otherwise you try something and—in the no-error-dialog action code context—you get … nothing. Very off-putting when trying to learn. I suspect the above might also result in a ‘working with JSON’ article, but I’ll likely to that after the next public release with the fixed/improved JSON parsing.