|
| 1 | +* chez-json |
| 2 | + |
| 3 | +fork from <https://github.com/aconchillo/guile-json> |
| 4 | + |
| 5 | +-------------------------------------------------------------- |
| 6 | + |
| 7 | +* guile-json |
| 8 | + |
| 9 | +guile-json is a JSON module for Guile. It supports parsing and |
| 10 | +building JSON documents according to the http://json.org |
| 11 | +specification. These are the main features: |
| 12 | + |
| 13 | +- Strictly complies to http://json.org specification. |
| 14 | + |
| 15 | +- Build JSON documents programmatically via macros. |
| 16 | + |
| 17 | +- Basic unicode support for strings. |
| 18 | + |
| 19 | +- Allows JSON pretty printing. |
| 20 | + |
| 21 | + |
| 22 | +* Installation |
| 23 | + |
| 24 | +guile-json is freely available for download under the terms of the GNU |
| 25 | +Lesser General Public License version 3 (LGPLv3+). |
| 26 | + |
| 27 | +Download the latest tarball and untar it: |
| 28 | + |
| 29 | +- [[http://download.savannah.gnu.org/releases/guile-json/guile-json-0.5.0.tar.gz][guile-json-0.5.0.tar.gz]] |
| 30 | + |
| 31 | +Then, run the typical sequence: |
| 32 | + |
| 33 | + : $ ./configure --prefix=<guile-prefix> |
| 34 | + : $ make |
| 35 | + : $ sudo make install |
| 36 | + |
| 37 | +Where <guile-prefix> should preferably be the same as your system Guile |
| 38 | +installation directory (e.g. /usr). |
| 39 | + |
| 40 | +If everything installed successfully you should be up and running: |
| 41 | + |
| 42 | + : $ guile |
| 43 | + : scheme@(guile-user)> (use-modules (json)) |
| 44 | + : scheme@(guile-user)> (scm->json (json (array 1 2 3))) |
| 45 | + : [1, 2, 3] |
| 46 | + |
| 47 | +It might be that you installed guile-json somewhere differently than |
| 48 | +your system's Guile. If so, you need to indicate Guile where to find |
| 49 | +guile-json, for example: |
| 50 | + |
| 51 | + : $ GUILE_LOAD_PATH=/usr/local/share/guile/site guile |
| 52 | + |
| 53 | +A pkg-list.scm file is also provided for users of the |
| 54 | +Guildhall/Dorodango packaging system. |
| 55 | + |
| 56 | + |
| 57 | +* Usage |
| 58 | + |
| 59 | +guile-json provides a few procedures to parse and build a JSON |
| 60 | +document. A JSON document is transformed into or from native Guile |
| 61 | +values according to the following table: |
| 62 | + |
| 63 | +| JSON | Guile | |
| 64 | +|--------+------------| |
| 65 | +| string | string | |
| 66 | +| number | number | |
| 67 | +| object | hash-table | |
| 68 | +| array | list | |
| 69 | +| true | #t | |
| 70 | +| false | #f | |
| 71 | +| null | #nil | |
| 72 | + |
| 73 | +To start using guile-json procedures and macros you first need to load |
| 74 | +the module: |
| 75 | + |
| 76 | + : scheme@(guile-user)> (use-modules (json)) |
| 77 | + |
| 78 | + |
| 79 | +** Procedures |
| 80 | + |
| 81 | +- (*json->scm* #:optional port) : Reads a JSON document from the given |
| 82 | + port, or from the current input port if none is given. |
| 83 | + |
| 84 | + - /port/ : is optional, it defaults to the current input port. |
| 85 | + |
| 86 | +- (*json-string->scm* str) : Reads a JSON document from the given |
| 87 | + string. |
| 88 | + |
| 89 | +- (*scm->json* native #:optional port #:key escape pretty) : Creates a |
| 90 | + JSON document from the given native Guile value. The JSON document is |
| 91 | + written into the given port, or to the current output port if non is |
| 92 | + given. |
| 93 | + |
| 94 | + - /port/ : it defaults to the current output port. |
| 95 | + - /escape/ : if true, the slash (/ solidus) character will be escaped. |
| 96 | + - /pretty/ : if true, the JSON document will be pretty printed. |
| 97 | + |
| 98 | +- (*scm->json-string* native #:key escape pretty) : Creates a JSON |
| 99 | + document from the given native Guile value into a string. |
| 100 | + |
| 101 | + - /escape/ : if true, the slash (/ solidus) character will be escaped. |
| 102 | + - /pretty/ : if true, the JSON document will be pretty printed. |
| 103 | + |
| 104 | + |
| 105 | +** Exceptions |
| 106 | + |
| 107 | +A /json-invalid/ exception is thrown if an error is found during the |
| 108 | +JSON parsing. Since version 0.2.0, the /json-invalid/ exception has a |
| 109 | +single parser argument (see predicate and accessors below). The line or |
| 110 | +column where the error occured can be easily obtained from the parser |
| 111 | +port (calling /port-line/ or /port-column/ on the port). |
| 112 | + |
| 113 | +- (*json-parser?* parser) : Tells whether the given argument is a JSON |
| 114 | + parser record type. |
| 115 | + |
| 116 | +- (*json-parser-port* parser) : Get the port that the parser was reading |
| 117 | + from. |
| 118 | + |
| 119 | + |
| 120 | +** Macros |
| 121 | + |
| 122 | +It is also possible to build JSON documents programmatically using the |
| 123 | +main /json/ macro (and /object/ and /array/). Here are some examples: |
| 124 | + |
| 125 | +- Build the string "hello world": |
| 126 | + |
| 127 | + : scheme@(guile-user)> (scm->json (json "hello world")) |
| 128 | + : "hello world" |
| 129 | + |
| 130 | +- Build the [1, 2, 3] array: |
| 131 | + |
| 132 | + : scheme@(guile-user)> (scm->json (json (array 1 2 3))) |
| 133 | + : [1, 2, 3] |
| 134 | + |
| 135 | +- Build the [1, 2, 3, 4] array using unquote-splicing: |
| 136 | + |
| 137 | + : scheme@(guile-user)> (define values '(2 3)) |
| 138 | + : scheme@(guile-user)> (scm->json (json (array 1 ,@values 4))) |
| 139 | + : [1, 2, 3, 4] |
| 140 | + |
| 141 | +- Build the object { "project" : "foo", "author" : "bar" }: |
| 142 | + |
| 143 | + : scheme@(guile-user)> (scm->json (json (object ("project" "foo") |
| 144 | + : ("author" "bar")))) |
| 145 | + : {"author" : "bar", "project" : "foo"} |
| 146 | + |
| 147 | +- Build the object { "values" : [ 234, 98.56 ] }: |
| 148 | + |
| 149 | + : scheme@(guile-user)> (scm->json (json (object ("values" (array 234 98.56))))) |
| 150 | + : {"values" : [234, 98.56]} |
| 151 | + |
| 152 | +- Build the object { "values" : [ 234, 98.56 ] } again, this time using |
| 153 | + a variable: |
| 154 | + |
| 155 | + : scheme@(guile-user)> (define values '(234 98.56)) |
| 156 | + : scheme@(guile-user)> (scm->json (json (object ("values" ,values)))) |
| 157 | + : {"values" : [1, 2, 3]} |
0 commit comments