| 1 |
|
| 2 |
# guile-json |
| 3 |
|
| 4 |
guile-json is a JSON module for Guile. It supports parsing and building JSON |
| 5 |
documents according to the http://json.org specification. |
| 6 |
|
| 7 |
- Complies with http://json.org specification. |
| 8 |
|
| 9 |
- Supports JSON Text Sequences (RFC 7464). |
| 10 |
|
| 11 |
- Supports parsing concatenated JSON documents. |
| 12 |
|
| 13 |
- Builds JSON documents programmatically using scheme data types. |
| 14 |
|
| 15 |
- Allows JSON pretty printing. |
| 16 |
|
| 17 |
|
| 18 |
# Installation |
| 19 |
|
| 20 |
Download the latest tarball and untar it: |
| 21 |
|
| 22 |
- [guile-json-4.7.3.tar.gz](https://download.savannah.gnu.org/releases/guile-json/guile-json-4.7.3.tar.gz) |
| 23 |
|
| 24 |
If you are cloning the repository make sure you run this first: |
| 25 |
|
| 26 |
$ autoreconf -vif |
| 27 |
|
| 28 |
Then, run the typical sequence: |
| 29 |
|
| 30 |
$ ./configure --prefix=<guile-prefix> |
| 31 |
$ make |
| 32 |
$ sudo make install |
| 33 |
|
| 34 |
Where `<guile-prefix>` should preferably be the same as your system Guile |
| 35 |
installation directory (e.g. /usr). |
| 36 |
|
| 37 |
If everything installed successfully you should be up and running: |
| 38 |
|
| 39 |
$ guile |
| 40 |
scheme@(guile-user)> (use-modules (json)) |
| 41 |
scheme@(guile-user)> (scm->json #(1 2 3)) |
| 42 |
[1,2,3] |
| 43 |
|
| 44 |
It might be that you installed guile-json somewhere differently than your |
| 45 |
system's Guile. If so, you need to indicate Guile where to find guile-json, |
| 46 |
for example: |
| 47 |
|
| 48 |
$ GUILE_LOAD_PATH=/usr/local/share/guile/site guile |
| 49 |
|
| 50 |
|
| 51 |
# Usage |
| 52 |
|
| 53 |
guile-json provides a few procedures to parse and build a JSON document. A |
| 54 |
JSON document is transformed into or from native Guile values according to the |
| 55 |
following table: |
| 56 |
|
| 57 |
| JSON | Guile | |
| 58 |
|--------|--------| |
| 59 |
| string | string | |
| 60 |
| number | number | |
| 61 |
| object | alist | |
| 62 |
| array | vector | |
| 63 |
| true | #t | |
| 64 |
| false | #f | |
| 65 |
| null | 'null | |
| 66 |
|
| 67 |
Why are JSON arrays converted to vectors and JSON objects to alists? See this |
| 68 |
[discussion](https://lists.gnu.org/archive/html/guile-user/2018-12/msg00039.html) |
| 69 |
for details. |
| 70 |
|
| 71 |
By default the value of JSON "null" is mapped to the symbol 'null. However, |
| 72 |
all guile-json functions allow changing the default null value by specifying |
| 73 |
the #:null keyword argument with another value. This other value needs to be |
| 74 |
recognized by *eq?*. |
| 75 |
|
| 76 |
To start using guile-json procedures and macros you first need to load |
| 77 |
the module: |
| 78 |
|
| 79 |
scheme@(guile-user)> (use-modules (json)) |
| 80 |
|
| 81 |
|
| 82 |
## Reading JSON documents |
| 83 |
|
| 84 |
- (**json->scm** #:optional port #:key null ordered concatenated) : Reads a JSON |
| 85 |
document from the given port, or from the current input port if none is given. |
| 86 |
|
| 87 |
Optional arguments: |
| 88 |
|
| 89 |
- *port* : is optional, it defaults to the current input port. |
| 90 |
|
| 91 |
Keyword arguments: |
| 92 |
|
| 93 |
- *null* : value for JSON's null, it defaults to the 'null symbol. |
| 94 |
|
| 95 |
- *ordered* : indicate whether JSON objects order should be preserved or not |
| 96 |
(the default). |
| 97 |
|
| 98 |
- *concatenated* : if true it tells the parser that more JSON documents might |
| 99 |
be present after a properly parsed document, otherwise the parser will fail |
| 100 |
if additional data is present after the first document (this is the |
| 101 |
default). |
| 102 |
|
| 103 |
- (**json-string->scm** str #:key null ordered) : Reads a JSON document from the |
| 104 |
given string. |
| 105 |
|
| 106 |
Keyword arguments: |
| 107 |
|
| 108 |
- *null* : value for JSON's null, it defaults to the 'null symbol. |
| 109 |
|
| 110 |
- *ordered* : indicate whether JSON objects order should be preserved or not |
| 111 |
(the default). |
| 112 |
|
| 113 |
|
| 114 |
## Building JSON documents |
| 115 |
|
| 116 |
- (**scm->json** native #:optional port #:key solidus unicode null validate |
| 117 |
pretty) : Creates a JSON document from the given native Guile value. The JSON |
| 118 |
document is written into the given port, or to the current output port if non |
| 119 |
is given. |
| 120 |
|
| 121 |
Optional arguments: |
| 122 |
|
| 123 |
- *port* : it defaults to the current output port. |
| 124 |
|
| 125 |
Keyword arguments: |
| 126 |
|
| 127 |
- *solidus* : if true, the slash (/ solidus) character will be escaped |
| 128 |
(defaults to false). |
| 129 |
|
| 130 |
- *unicode* : if true, additional to control characters, non-ASCII |
| 131 |
characters will be escaped as well (defaults to false). |
| 132 |
|
| 133 |
- *null* : value for JSON's null (defaults to the 'null symbol). |
| 134 |
|
| 135 |
- *validate* : if true, the native value will be validated before starting |
| 136 |
to print the JSON document (defaults to true). |
| 137 |
|
| 138 |
- *pretty* : if true, the JSON document will be pretty printed (defaults to |
| 139 |
false). |
| 140 |
|
| 141 |
- (**scm->json-string** native #:key solidus unicode null validate pretty) : |
| 142 |
Creates a JSON document from the given native Guile value into a string. |
| 143 |
|
| 144 |
See keyword arguments for *scm->json*. |
| 145 |
|
| 146 |
Note that when using alists to build JSON objects, symbols or numbers might |
| 147 |
be used as keys and they both will be converted to strings. |
| 148 |
|
| 149 |
|
| 150 |
## Reading JSON Text Sequences |
| 151 |
|
| 152 |
- (**json-seq->scm** #:optional port #:key null ordered handle-truncate |
| 153 |
truncated-object) : Reads a stream of JSON documents from the given port, or |
| 154 |
from the current input port if none is given. |
| 155 |
|
| 156 |
Optional arguments: |
| 157 |
|
| 158 |
- *port* : is optional, it defaults to the current input port. |
| 159 |
|
| 160 |
Keyword arguments: |
| 161 |
|
| 162 |
- *null* : value for JSON's null, it defaults to the 'null symbol. |
| 163 |
|
| 164 |
- *ordered* : indicate whether JSON objects order should be preserved or not |
| 165 |
(the default). |
| 166 |
|
| 167 |
- *handle-truncate* : defines how to handle data loss. Possible values: |
| 168 |
|
| 169 |
- *'throw*: throw an exception. |
| 170 |
- *'stop*: stop parsing and end the stream. |
| 171 |
- *'skip*: skip corrupted fragment and return next object (default). |
| 172 |
- *'replace*: skip corrupted fragment and return object specific by |
| 173 |
*truncated-object*. |
| 174 |
|
| 175 |
- *truncated-object* : use this object if an object could not be parsed (to be |
| 176 |
used when setting *handle-truncate* to *'replace* value). |
| 177 |
|
| 178 |
- (**json-seq-string->scm** str #:key null ordered handle-truncate |
| 179 |
truncated-object) : Reads a stream of JSON documents from the given string. |
| 180 |
|
| 181 |
See keyword arguments for *json-seq->scm*. |
| 182 |
|
| 183 |
|
| 184 |
## Building JSON Text Sequences |
| 185 |
|
| 186 |
- (**scm->json-seq** objects #:optional port #:key solidus null validate) : |
| 187 |
Creates a JSON document sequence from the given list of native Guile |
| 188 |
objects. The JSON document sequence is written into the given port, or to the |
| 189 |
current output port if non is given. |
| 190 |
|
| 191 |
Optional arguments: |
| 192 |
|
| 193 |
- *port* : it defaults to the current output port. |
| 194 |
|
| 195 |
Keyword arguments: |
| 196 |
|
| 197 |
- *solidus* : if true, the slash (/ solidus) character will be escaped |
| 198 |
(defaults to false). |
| 199 |
|
| 200 |
- *null* : value for JSON's null (defaults to the 'null symbol). |
| 201 |
|
| 202 |
- *validate* : if true, the native value will be validated before starting |
| 203 |
to print the JSON document (defaults to true). |
| 204 |
|
| 205 |
- (**scm->json-seq-string** objects #:key solidus null validate) : Creates a |
| 206 |
JSON document sequence from the given list of native Guile objects into a |
| 207 |
string. |
| 208 |
|
| 209 |
See keyword arguments for *scm->json-seq*. |
| 210 |
|
| 211 |
|
| 212 |
## Exceptions |
| 213 |
|
| 214 |
A *json-invalid* exception is thrown if an error is found during the JSON |
| 215 |
parsing with a single port argument. The line or column where the error |
| 216 |
occured can be easily obtained from the port by calling *port-line* or |
| 217 |
*port-column*. |
| 218 |
|
| 219 |
When building a JSON document from a native type a *json-invalid* exception |
| 220 |
might be thrown with the offending value as an argument (see table above for |
| 221 |
supported types). |
| 222 |
|
| 223 |
|
| 224 |
## JSON Objects and Records |
| 225 |
|
| 226 |
guile-json 4.5.0 introduces JSON types, a new feature that allows converting |
| 227 |
JSON objects into record types and vice versa in a very straight forward |
| 228 |
way. This was built on top of *define-json-mapping* which was introduced in |
| 229 |
version 4.2.0. |
| 230 |
|
| 231 |
Let's take a look at an example. Imagine we have the following user account |
| 232 |
information: |
| 233 |
|
| 234 |
``` |
| 235 |
{ |
| 236 |
"id": 1234, |
| 237 |
"username": "jane" |
| 238 |
} |
| 239 |
``` |
| 240 |
|
| 241 |
We can easily create a |
| 242 |
[record](https://www.gnu.org/software/guile/manual/html_node/Records.html) |
| 243 |
representing that data with *define-json-type* by simply doing: |
| 244 |
|
| 245 |
``` |
| 246 |
> (define-json-type <account> |
| 247 |
(id) |
| 248 |
(username)) |
| 249 |
``` |
| 250 |
|
| 251 |
This will define the record constructor, the predicate and conversion procedures |
| 252 |
like *json->account* or *account->json* (see *define-json-type* for more |
| 253 |
details). |
| 254 |
|
| 255 |
We can now create a new account and check its contents as with regular records: |
| 256 |
|
| 257 |
``` |
| 258 |
> (define account (make-account "1234" "jane")) |
| 259 |
> (account-id account) |
| 260 |
"1234" |
| 261 |
> (account-username account) |
| 262 |
"jane" |
| 263 |
``` |
| 264 |
|
| 265 |
Or we can use the auto-generated *scm->account* to create the account: |
| 266 |
|
| 267 |
``` |
| 268 |
> (define account (scm->account '(("id" . "1234") ("username" . "jane")))) |
| 269 |
``` |
| 270 |
|
| 271 |
It is also possible to convert the record to a JSON string: |
| 272 |
|
| 273 |
``` |
| 274 |
> (account->json account) |
| 275 |
"{\"id\":\"1234\",\"username\":\"jane\"}" |
| 276 |
``` |
| 277 |
|
| 278 |
Or from a JSON string to a new record: |
| 279 |
|
| 280 |
``` |
| 281 |
> (define json-account "{\"id\":\"1234\",\"username\":\"jane\"}") |
| 282 |
> (json->account json-account) |
| 283 |
#<<account> id: "1234" username: "jane"> |
| 284 |
``` |
| 285 |
|
| 286 |
### Macros |
| 287 |
|
| 288 |
- (**define-json-type** rtd (field key type) ...) : Define a new mapping between |
| 289 |
a JSON object and a record type. This will automatically define the record |
| 290 |
constructor, the predicate, all field getters and record to/from JSON |
| 291 |
conversions. For more control use *define-json-mapping*. |
| 292 |
|
| 293 |
- *rtd* : the name of the record type. |
| 294 |
|
| 295 |
- *((field key type) ...)* : a series of field specifications. |
| 296 |
|
| 297 |
- *field* : the name of a JSON object field. |
| 298 |
|
| 299 |
- *key* : a different name for the field of this JSON object. If given, this |
| 300 |
name will be used instead of the field name when serializing or |
| 301 |
deserializing. |
| 302 |
|
| 303 |
- *type* : indicates that this field contains a record type. It is also |
| 304 |
possible to indicate that the field contains an array of objects of the |
| 305 |
same record type by using the vector syntax *#(type)*. |
| 306 |
|
| 307 |
- (**define-json-mapping** rtd ctor pred json->record [<=> record->json [<=> |
| 308 |
scm->record]] (field getter key ...) ...) : Define a new mapping between a |
| 309 |
JSON object and a record type, à la SRFI-9. |
| 310 |
|
| 311 |
- *rtd* : the name of the record type. |
| 312 |
|
| 313 |
- *ctor* : the name for the record constructor procedure. |
| 314 |
|
| 315 |
- *pred* : a predicate procedure to check if a given argument holds a record |
| 316 |
of this type. |
| 317 |
|
| 318 |
- *json->record* : the name of the procedure to convert a JSON object, read |
| 319 |
from a port, string, or alist, into a record of this type. |
| 320 |
|
| 321 |
- *<=> record->json* : optional name of the procedure to convert a record of |
| 322 |
this type to a JSON string. |
| 323 |
|
| 324 |
- *<=> scm->record* : optional name of the procedure to convert a JSON object, |
| 325 |
represented as an alist, into a record of this type. This is equivalent to |
| 326 |
*json->record* when an alist is passed. |
| 327 |
|
| 328 |
- *<=> record->scm* : optional name of the procedure to convert a record of |
| 329 |
this type to a JSON objected represented as an alist. |
| 330 |
|
| 331 |
- *((field getter ...) ...)* : a series of field specifications. |
| 332 |
|
| 333 |
- *field* : the name of a JSON object field. |
| 334 |
|
| 335 |
- *getter* : the name of the procedure to get the value of this field |
| 336 |
given a record of this type. |
| 337 |
|
| 338 |
- *key* : a different name for the field of this JSON object. If given, this |
| 339 |
name will be used instead of the field name when serializing or |
| 340 |
deserializing. |
| 341 |
|
| 342 |
- *scm->value* : an optional procedure that will be used to convert native |
| 343 |
values supported by guile-json to the value contained in the record. Used |
| 344 |
when reading JSON. |
| 345 |
|
| 346 |
- *value->scm* : an optional procedure that will be used to convert the |
| 347 |
value contained in the record to a native value supported by guile-json |
| 348 |
Used when writing JSON. |
| 349 |
|
| 350 |
### Records and null fields |
| 351 |
|
| 352 |
When serializing a record to a JSON object it is possible to set a field to the |
| 353 |
\*unspecified\* value in order to omit it from serialization. Also, when |
| 354 |
deserializing a JSON object to a record, missing record fields in the JSON |
| 355 |
object will be set to \*unspecified\* in the record. |
| 356 |
|
| 357 |
|
| 358 |
# Examples |
| 359 |
|
| 360 |
- Build the string "hello world": |
| 361 |
|
| 362 |
``` |
| 363 |
> (scm->json "hello world") |
| 364 |
"hello world" |
| 365 |
``` |
| 366 |
|
| 367 |
- Build the [1, 2, 3] array: |
| 368 |
|
| 369 |
``` |
| 370 |
> (scm->json #(1 2 3)) |
| 371 |
[1,2,3] |
| 372 |
``` |
| 373 |
|
| 374 |
- Build the object { "project" : "foo", "author" : "bar" } using an alist: |
| 375 |
|
| 376 |
``` |
| 377 |
> (scm->json '(("project" . "foo") ("author" . "bar"))) |
| 378 |
{"project":"foo","author":"bar"} |
| 379 |
``` |
| 380 |
|
| 381 |
- Build the same object but this time using symbols: |
| 382 |
|
| 383 |
``` |
| 384 |
> (scm->json '((project . foo) ("author" . "bar"))) |
| 385 |
{"project":"foo","author":"bar"} |
| 386 |
``` |
| 387 |
|
| 388 |
- Build the object { "values" : [ 234, 98.56 ] }: |
| 389 |
|
| 390 |
``` |
| 391 |
> (scm->json '(("values" . #(234 98.56)))) |
| 392 |
{"values":[234,98.56]} |
| 393 |
``` |
| 394 |
|
| 395 |
- Build the object { "values" : [ 234, 98.56 ] } again, this time using |
| 396 |
a variable: |
| 397 |
|
| 398 |
``` |
| 399 |
> (define values #(234 98.56)) |
| 400 |
> (scm->json `(("values" . ,values))) |
| 401 |
{"values":[234,98.56]} |
| 402 |
``` |
| 403 |
|
| 404 |
- Default null value is the 'null symbol: |
| 405 |
|
| 406 |
``` |
| 407 |
> (scm->json 'null) |
| 408 |
null |
| 409 |
``` |
| 410 |
|
| 411 |
- The default null value can be changed to something else: |
| 412 |
|
| 413 |
``` |
| 414 |
> (scm->json #nil #:null #nil) |
| 415 |
null |
| 416 |
``` |
| 417 |
|
| 418 |
# License |
| 419 |
|
| 420 |
Copyright (C) 2013-2022 Aleix Conchillo Flaque <[email protected]> |
| 421 |
|
| 422 |
guile-json is free software: you can redistribute it and/or modify it |
| 423 |
under the terms of the GNU General Public License as published by the |
| 424 |
Free Software Foundation; either version 3 of the License, or (at your |
| 425 |
option) any later version. |
| 426 |
|
| 427 |
guile-json is distributed in the hope that it will be useful, but |
| 428 |
WITHOUT ANY WARRANTY; without even the implied warranty of |
| 429 |
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
| 430 |
General Public License for more details. |
| 431 |
|
| 432 |
You should have received a copy of the GNU General Public License |
| 433 |
along with guile-json. If not, see https://www.gnu.org/licenses/. |