From 36d6b4e5549dc45baf890105de5ef487211f0144 Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Tue, 6 Feb 2024 05:22:12 +0200
Subject: Add experimental support for JSON value types

New types:

  json
  json_array
  json_object

New functions:

  $json.value_type(<json>)
  $json.value_size(<json>)
  $json.member_{name,value}(<json-member>)
  $json.object_names(<json-object>)
  $json.array_size(<json-array>)
  $json.array_find(<json-array>, <json>)
  $json.array_find_index(<json-array>, <json>)
  $json.load(<path>)
  $json.parse(<text>)
  $json.serialize(<json>[, <indentation>])

For example, to load a JSON value from a file:

j = $json.load($src_base/board.json)

Or to construct it in a buildfile:

j = [json] one@1 two@([json] 2 3 4) three@([json] x@1 y@-1)

This can also be done incrementally with append/prepend:

j = [json_object]
j += one@1
j += two@([json] 2 3 4)
j += three@([json] x@1 y@-1)

Instead of using this JSON-like syntax, one can also specify valid JSON
input text:

j = [json] '{"one":1, "two":[2, 3, 4], "three":{"x":1, "y":-1}'

Besides the above set of functions, other handy ways to access components
in a JSON value are iteration and subscript. For example:

for m: $j
  print $member_name($m) $member_value($m)

print ($j[three])

A subscript can be nested:

print ($j[two][1])
print ($j[three][x])

While a JSON value can be printed directly like any other value, the
representation will not be pretty-printed. As a result, for complex
JSON values, printing a serialized representation might be a more
readable option:

info $serialize($j)
---
 doc/buildfile  |  1 +
 doc/manual.cli | 23 +++++++++++++++++++++++
 2 files changed, 24 insertions(+)

(limited to 'doc')

diff --git a/doc/buildfile b/doc/buildfile
index 633505b..5508ddb 100644
--- a/doc/buildfile
+++ b/doc/buildfile
@@ -76,6 +76,7 @@ xhtml{*}: extension = xhtml
 for ff: functions-builtin        \
         functions-string         \
         functions-integer        \
+        functions-json           \
         functions-bool           \
         functions-path           \
         functions-name           \
diff --git a/doc/manual.cli b/doc/manual.cli
index 66d0ffb..cd77bfe 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -6113,6 +6113,29 @@ if $regex.match($name, '(.+)-(.+)')
 "
 source <functions-regex.cli>;
 
+// $json.*()
+//
+"
+\h#functions-json|JSON Functions|
+
+The \c{$json.*()} function family contains function that operate on the JSON
+types: \c{json}, \c{json_array}, and \c{json_object}. For example:
+
+\
+j = [json] one@1 two@abc three@([json] x@1 y@-1)
+
+for m: $j
+{
+  n = $member_name($m)
+  v = $member_value($m)
+
+  info $n $value_type($v) $v
+}
+\
+
+"
+source <functions-json.cli>;
+
 
 // $process.*()
 //
-- 
cgit v1.1