Debian Codegraph @

README

raw
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/.