bknr-cvs

bknr-cvs@common-lisp.net

1964 discussions

[bknr-cvs] hans changed trunk/libraries/yason/index.html
by BKNR Commits 15 Nov '08

15 Nov '08

Revision: 4056 Author: hans URL: http://bknr.net/trac/changeset/4056 regenerated HTML documentation U trunk/libraries/yason/index.html Modified: trunk/libraries/yason/index.html =================================================================== --- trunk/libraries/yason/index.html 2008-11-15 10:40:14 UTC (rev 4055) +++ trunk/libraries/yason/index.html 2008-11-15 10:42:29 UTC (rev 4056) @@ -71,14 +71,16 @@ <p> YASON has its permanent home at <a href="http://common-lisp.net/project/yason/">common-lisp.net</a>. - It can be obtained either by downloading + It can be obtained by downloading the <a href="http://common-lisp.net/project/yason/files/yason.tar.gz">release - tarball</a>. The current release is 0.1. + tarball</a>. The current release is 0.1. </p> <p> You may also check out the current development version from its subversion repository: - <pre>svn co svn://bknr.net/svn/trunk/libraries/yason/</pre> + <pre>svn co svn://bknr.net/svn/trunk/libraries/yason/</pre> If + you have suggestions regarding YASON, please email me + at <i>hans.huebner(a)gmail.com</i>. </p> <p> YASON is written in ANSI Common Lisp and does not depend on

1 0

[bknr-cvs] hans changed trunk/libraries/yason/doc.xml
by BKNR Commits 15 Nov '08

15 Nov '08

Revision: 4055 Author: hans URL: http://bknr.net/trac/changeset/4055 add author email address U trunk/libraries/yason/doc.xml Modified: trunk/libraries/yason/doc.xml =================================================================== --- trunk/libraries/yason/doc.xml 2008-11-15 10:37:50 UTC (rev 4054) +++ trunk/libraries/yason/doc.xml 2008-11-15 10:40:14 UTC (rev 4055) @@ -43,7 +43,9 @@ <p> You may also check out the current development version from its subversion repository: - <pre>svn co svn://bknr.net/svn/trunk/libraries/yason/</pre> + <pre>svn co svn://bknr.net/svn/trunk/libraries/yason/</pre> If + you have suggestions regarding YASON, please email me + at <i>hans.huebner(a)gmail.com</i>. </p> <p> YASON is written in ANSI Common Lisp and does not depend on

1 0

[bknr-cvs] hans changed trunk/libraries/yason/
by BKNR Commits 15 Nov '08

15 Nov '08

Revision: 4054 Author: hans URL: http://bknr.net/trac/changeset/4054 fix documentation glitches U trunk/libraries/yason/doc.xml U trunk/libraries/yason/index.html Modified: trunk/libraries/yason/doc.xml =================================================================== --- trunk/libraries/yason/doc.xml 2008-11-15 10:18:57 UTC (rev 4053) +++ trunk/libraries/yason/doc.xml 2008-11-15 10:37:50 UTC (rev 4054) @@ -36,9 +36,9 @@ <p> YASON has its permanent home at <a href="http://common-lisp.net/project/yason/">common-lisp.net</a>. - It can be obtained either by downloading + It can be obtained by downloading the <a href="http://common-lisp.net/project/yason/files/yason.tar.gz">release - tarball</a>. The current release is 0.1. + tarball</a>. The current release is 0.1. </p> <p> You may also check out the current development version from its @@ -447,7 +447,7 @@ Thanks go to Edi Weitz for being a great inspiration. This documentation as been generated with a hacked-up version of his <a href="http://weitz.de/documentation-template/">DOCUMENTATION-TEMPLATE</a> - software. + software. Thanks to David Lichteblau for coining YASON's name. </clix:chapter> </clix:documentation> Modified: trunk/libraries/yason/index.html =================================================================== --- trunk/libraries/yason/index.html 2008-11-15 10:18:57 UTC (rev 4053) +++ trunk/libraries/yason/index.html 2008-11-15 10:37:50 UTC (rev 4054) @@ -474,7 +474,7 @@ Thanks go to Edi Weitz for being a great inspiration. This documentation as been generated with a hacked-up version of his <a href="http://weitz.de/documentation-template/">DOCUMENTATION-TEMPLATE</a> - software. + software. Thanks to David Lichteblau for coining YASON's name. </body></html>

1 0

[bknr-cvs] hans changed trunk/libraries/yason/
by BKNR Commits 15 Nov '08

15 Nov '08

Revision: 4053 Author: hans URL: http://bknr.net/trac/changeset/4053 doc updates for release U trunk/libraries/yason/doc.xml U trunk/libraries/yason/index.html Modified: trunk/libraries/yason/doc.xml =================================================================== --- trunk/libraries/yason/doc.xml 2008-11-15 10:14:36 UTC (rev 4052) +++ trunk/libraries/yason/doc.xml 2008-11-15 10:18:57 UTC (rev 4053) @@ -32,14 +32,17 @@ objects and YASON, but can be used to implement such mappings. </clix:chapter> - <clix:chapter name="install" title="Installation"> + <clix:chapter name="install" title="Download and Installation"> <p> YASON has its permanent home at <a href="http://common-lisp.net/project/yason/">common-lisp.net</a>. It can be obtained either by downloading the <a href="http://common-lisp.net/project/yason/files/yason.tar.gz">release - tarball</a> or by checking out the current development version - from its subversion repository: + tarball</a>. The current release is 0.1. + </p> + <p> + You may also check out the current development version from its + subversion repository: <pre>svn co svn://bknr.net/svn/trunk/libraries/yason/</pre> </p> <p> Modified: trunk/libraries/yason/index.html =================================================================== --- trunk/libraries/yason/index.html 2008-11-15 10:14:36 UTC (rev 4052) +++ trunk/libraries/yason/index.html 2008-11-15 10:18:57 UTC (rev 4053) @@ -42,7 +42,7 @@ <h3 xmlns="">Contents</h3> <ol xmlns=""> <li><a href="#intro">Introduction</a></li> -<li><a href="#install">Installation</a></li> +<li><a href="#install">Download and Installation</a></li> <li><a href="#mapping">Mapping between JSON and CL datatypes</a></li> <li> <a href="#parsing">Parsing JSON data</a><ol><li><a href="#parser-dict">Parser dictionary</a></li></ol> @@ -67,14 +67,17 @@ objects and YASON, but can be used to implement such mappings. - <h3 xmlns=""><a class="none" name="install">Installation</a></h3> + <h3 xmlns=""><a class="none" name="install">Download and Installation</a></h3> <p> YASON has its permanent home at <a href="http://common-lisp.net/project/yason/">common-lisp.net</a>. It can be obtained either by downloading the <a href="http://common-lisp.net/project/yason/files/yason.tar.gz">release - tarball</a> or by checking out the current development version - from its subversion repository: + tarball</a>. The current release is 0.1. + </p> + <p> + You may also check out the current development version from its + subversion repository: <pre>svn co svn://bknr.net/svn/trunk/libraries/yason/</pre> </p> <p>

1 0

[bknr-cvs] hans changed releases/yason/
by BKNR Commits 15 Nov '08

15 Nov '08

Revision: 4052 Author: hans URL: http://bknr.net/trac/changeset/4052 create releases dir A releases/yason/

1 0

[bknr-cvs] hans changed releases/
by BKNR Commits 15 Nov '08

15 Nov '08

Revision: 4051 Author: hans URL: http://bknr.net/trac/changeset/4051 create releases dir A releases/

1 0

[bknr-cvs] hans changed trunk/libraries/yason/index.html
by BKNR Commits 15 Nov '08

15 Nov '08

Revision: 4050 Author: hans URL: http://bknr.net/trac/changeset/4050 Add HTML rendered version of the documentation. A trunk/libraries/yason/index.html Added: trunk/libraries/yason/index.html =================================================================== --- trunk/libraries/yason/index.html (rev 0) +++ trunk/libraries/yason/index.html 2008-11-15 10:12:08 UTC (rev 4050) @@ -0,0 +1,477 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Strict//EN"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>YASON - A JSON encoder/decoder for Common Lisp</title><meta name="description" content=" + YASON is a JSON encoding and decoding library for Common Lisp. + It provides for functions to read JSON strings into Lisp data + structures and for serializing Lisp data structures as JSON + strings. + "></meta><style type="text/css"> + body { background-color: #ffffff; max-width: 50em; margin-left: 2em; font-family: Georgia, 'Times New Roman', serif; } + pre { padding:5px; background-color:#e0e0e0; margin: 1em 2em 1em 2em; } + pre.none { padding:5px; background-color:#ffffff; } + h3, h4, h5 { text-decoration: underline; } + a { text-decoration: none; padding: 1px 2px 1px 2px; } + a:visited { text-decoration: none; padding: 1px 2px 1px 2px; } + a:hover { text-decoration: none; padding: 1px 1px 1px 1px; border: 1px solid #000000; } + a:focus { text-decoration: none; padding: 1px 2px 1px 2px; border: none; } + a.none { text-decoration: none; padding: 0; } + a.none:visited { text-decoration: none; padding: 0; } + a.none:hover { text-decoration: none; border: none; padding: 0; } + a.none:focus { text-decoration: none; border: none; padding: 0; } + a.noborder { text-decoration: none; padding: 0; } + a.noborder:visited { text-decoration: none; padding: 0; } + a.noborder:hover { text-decoration: none; border: none; padding: 0; } + a.noborder:focus { text-decoration: none; border: none; padding: 0; } + table { margin: 1em; } + </style></head><body> + + <h2 xmlns="">YASON - A JSON encoder/decoder for Common Lisp</h2> + + + + <h3 xmlns="">Abstract</h3> +<blockquote xmlns=""> + YASON is a Common Lisp library for encoding and decoding data in + the <a xmlns="http://www.w3.org/1999/xhtml" href="http://json.org/">JSON</a> interchange format. + JSON is used in AJAX applications as a lightweight alternative + to XML. YASON has the sole purpose of encoding and decoding + data and does not impose any object model on the Common Lisp + application that uses it. + </blockquote> + + <h3 xmlns="">Contents</h3> +<ol xmlns=""> +<li><a href="#intro">Introduction</a></li> +<li><a href="#install">Installation</a></li> +<li><a href="#mapping">Mapping between JSON and CL datatypes</a></li> +<li> +<a href="#parsing">Parsing JSON data</a><ol><li><a href="#parser-dict">Parser dictionary</a></li></ol> +</li> +<li> +<a href="#encoding">Encoding JSON data</a><ol> +<li><a href="#dom-encoder">Encoding a JSON DOM</a></li> +<li><a href="#stream-encoder">Encoding JSON in streaming mode</a></li> +<li><a href="#app-encoders">Application specific encoders</a></li> +</ol> +</li> +<li><a href="#index">Symbol index</a></li> +<li><a href="#license">License</a></li> +<li><a href="#ack">Acknowledgements</a></li> +</ol> + + <h3 xmlns=""><a class="none" name="intro">Introduction</a></h3> + <a href="http://json.org/">JSON</a> is an established alternative + to XML as a data interchange format for web applications. YASON + implements reading and writing of JSON formatted data in Common + Lisp. It does not attempt to provide a mapping between CLOS + objects and YASON, but can be used to implement such mappings. + + + <h3 xmlns=""><a class="none" name="install">Installation</a></h3> + <p> + YASON has its permanent home + at <a href="http://common-lisp.net/project/yason/">common-lisp.net</a>. + It can be obtained either by downloading + the <a href="http://common-lisp.net/project/yason/files/yason.tar.gz">release + tarball</a> or by checking out the current development version + from its subversion repository: + <pre>svn co svn://bknr.net/svn/trunk/libraries/yason/</pre> + </p> + <p> + YASON is written in ANSI Common Lisp and does not depend on + other libraries. + </p> + <p> + YASON lives in the <b>:yason</b> package and creates a package nickname + <b>:json</b>. Applications will not normally <b>:use</b> this + package, but rather use qualified names to access YASON's + symbols. For that reason, YASON's symbols do not contain the + string "JSON" themselves. See below for usage samples. + </p> + + + <h3 xmlns=""><a class="none" name="mapping">Mapping between JSON and CL datatypes</a></h3> + By default, YASON performs the following mappings between JSON and + CL datatypes: + <table border="1"> + <thead> + <tr> + <th>JSON<br></br>datatype</th> + <th>CL<br></br>datatype</th> + <th>Notes</th> + </tr> + </thead> + <tbody> + <tr> + <td>object</td> + <td>hash-table<br></br>:test #'equal</td> + <td> + Keys are strings by default, + see <code xmlns=""><a href="#*parse-object-key-fn*">*parse-object-key-fn*</a></code> + </td> + </tr> + <tr> + <td>array</td> + <td>list</td> + <td> + Can be changed to read to vectors, + see <code xmlns=""><a href="#*parse-json-arrays-as-vectors*">*parse-json-arrays-as-vectors*</a></code> + </td> + </tr> + <tr> + <td>string</td> + <td>string</td> + <td> + JSON escape characters are recognized upon reading. + Upon writing, known escape characters are used, but + non-ASCII Unicode characters are written as is. + </td> + </tr> + <tr> + <td>number</td> + <td>number</td> + <td> + Parsed with READ, printed with PRINC. This is not a + faithful implementation of the specification. + </td> + </tr> + <tr> + <td>true</td> + <td>t</td> + <td>Can be changed to read as TRUE, see <code xmlns=""><a href="#*parse-json-booleans-as-symbols*">*parse-json-booleans-as-symbols*</a></code></td> + </tr> + <tr> + <td>false</td> + <td>nil</td> + <td>Can be changed to read as FALSE, see <code xmlns=""><a href="#*parse-json-booleans-as-symbols*">*parse-json-booleans-as-symbols*</a></code></td> + </tr> + <tr> + <td>null</td> + <td>nil</td> + <td></td> + </tr> + </tbody> + </table> + + + <h3 xmlns=""><a class="none" name="parsing">Parsing JSON data</a></h3> + <p> + JSON data is always completely parsed into an equivalent + in-memory representation. Upon reading, some translations are + performed by default to make it easier for the Common Lisp + program to work with the data; see <code xmlns=""><a href="#mapping">mapping</a></code> + for details. If desired, the parser can be configured to + preserve the full semantics of the JSON data read. + </p> + + For example + + <pre>CL-USER> (defvar *json-string* "[{\"foo\":1,\"bar\":[7,8,9]},2,3,4,[5,6,7],true,null]") +*JSON-STRING* +CL-USER> (let* ((result (json:parse *json-string*))) + (print result) + (alexandria:hash-table-plist (first result))) + +(#<HASH-TABLE :TEST EQUAL :COUNT 2 {5A4420F1}> 2 3 4 (5 6 7) T NIL) +("bar" (7 8 9) "foo" 1) +CL-USER> (defun maybe-convert-to-keyword (js-name) + (or (find-symbol (string-upcase js-name) :keyword) + js-name)) +MAYBE-CONVERT-TO-KEYWORD +CL-USER> :FOO ; intern the :FOO keyword +:FOO +CL-USER> (let* ((json:*parse-json-arrays-as-vectors* t) + (json:*parse-json-booleans-as-symbols* t) + (json:*parse-object-key-fn* #'maybe-convert-to-string) + (result (json:parse *json-string*))) + (print result) + (alexandria:hash-table-plist (aref result 0))) + +#(#<HASH-TABLE :TEST EQUAL :COUNT 2 {59B4EAD1}> 2 3 4 #(5 6 7) YASON:TRUE NIL) +("bar" #(7 8 9) :FOO 1)</pre> + + <p> + The second example modifies the parser's behaviour so that JSON + arrays are read as CL vectors, JSON booleans will be read as the + symbols TRUE and FALSE and JSON object keys will be looked up in + the <b>:keyword</b> package. Interning strings coming from an + external source is not recommended practice. + </p> + + <h4 xmlns=""><a name="parser-dict">Parser dictionary</a></h4> + <p xmlns="">[Generic function]<br><a class="none" name="parse"><b>parse</b> <i><clix:lambda-list xmlns:clix="http://bknr.net/clixdoc">input</clix:lambda-list></i> + => + <i>object</i></a><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc"> + Parse <code><i>input</i></code>, which needs to be a string + or a stream, as JSON. Returns the lisp representation of the + JSON structure parsed. + </clix:description></blockquote></p> + + <p xmlns=""> + [Special variable]<br><a class="none" name="*parse-json-arrays-as-vectors*"><b>*parse-json-arrays-as-vectors*</b></a><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc"> + If set to a true value, JSON arrays will be parsed as vectors, + not as lists. + </clix:description></blockquote></p> + + <p xmlns=""> + [Special variable]<br><a class="none" name="*parse-json-booleans-as-symbols*"><b>*parse-json-booleans-as-symbols*</b></a><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc"> + If set to a true value, JSON booleans will be read as the + symbols TRUE and FALSE, not as T and NIL, respectively. + </clix:description></blockquote></p> + + <p xmlns=""> + [Special variable]<br><a class="none" name="*parse-object-key-fn*"><b>*parse-object-key-fn*</b></a><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc"> + Function to call to convert a key string in a JSON array to a + key in the CL hash produced. + </clix:description></blockquote></p> + + + + <h3 xmlns=""><a class="none" name="encoding">Encoding JSON data</a></h3> + YASON provides for two distinct modes to encode JSON data: + Applications can either create an in memory representation of the + data to be serialized, then have YASON convert it to JSON in one + go, or they can use a set of macros to serialze the JSON data + element-by-element, thereby having fine grained control over the + layout of the generated data. + + <h4 xmlns=""><a name="dom-encoder">Encoding a JSON DOM</a></h4> + <p> + In this mode, an in-memory structure is encoded in JSON format. + The structure must consist of objects that are serializable + using the <code xmlns=""><a href="#encode">ENCODE</a></code> function. YASON defines a + number of encoders for standard data types + (see <code xmlns=""><a href="#mapping">MAPPING</a></code>), but the application can + define additional methods, e.g. for encoding CLOS objects. + </p> + For example: + <pre>CL-USER> (json:encode + (list (alexandria:plist-hash-table + '("foo" 1 "bar" (7 8 9)) + :test #'equal) + 2 3 4 + '(5 6 7) + t nil) + *standard-output*) +[{"foo":1,"bar":[7,8,9]},2,3,4,[5,6,7],true,null] +(#<HASH-TABLE :TEST EQUAL :COUNT 2 {59942D21}> 2 3 4 (5 6 7) T NIL)</pre> + + <h4 xmlns=""><a name="dom-encoder-dict">DOM encoder dictionary</a></h4> + <p xmlns="">[Generic function]<br><a class="none" name="encode"><b>encode</b> <i><clix:lambda-list xmlns:clix="http://bknr.net/clixdoc">object &optional stream</clix:lambda-list></i> + => + <i>object</i></a><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc"> + Encode <code><i>object</i></code> + to <code><i>stream</i></code> in JSON format. May be + specialized by applications to perform specific + rendering. <code><i>stream</i></code> defaults to + *STANDARD-OUTPUT*. + </clix:description></blockquote></p> + + + + <h4 xmlns=""><a name="stream-encoder">Encoding JSON in streaming mode</a></h4> + <p> + In this mode, the JSON structure is generated in a stream. + The application makes explicit calls to the encoding library + in order to generate the JSON structure. It provides for more + control over the generated output, and can be used to generate + arbitary JSON without requiring that there exists a directly + matching Lisp datastructure. The streaming API uses + the <code xmlns=""><a href="#encode">encode</a></code> function, so it is possible to + intermix the two. See <code xmlns=""><a href="#app-encoders">app-encoders</a></code> for + an example. + </p> + For example: + <pre>CL-USER> (json:with-output (*standard-output*) + (json:with-array () + (dotimes (i 3) + (json:encode-array-element i)))) +[0,1,2] +NIL +CL-USER> (json:with-output (*standard-output*) + (json:with-object () + (json:encode-object-element "hello" "hu hu") + (json:with-object-element ("harr") + (json:with-array () + (dotimes (i 3) + (json:encode-array-element i)))))) +{"hello":"hu hu","harr":[0,1,2]} +NIL</pre> + + <h4 xmlns=""><a name="stream-encoder-dict">Streaming encoder dictionary</a></h4> + <p xmlns="">[Macro]<br><a class="none" name="with-output"><b>with-output</b> <i><clix:lambda-list xmlns:clix="http://bknr.net/clixdoc">(stream) &body body</clix:lambda-list></i> + => + <i>result*</i></a><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc"> + Set up a JSON streaming encoder context + on <code><i>stream</i></code>, then + evaluate <code><i>body</i></code>. + </clix:description></blockquote></p> + + <p xmlns="">[Macro]<br><a class="none" name="with-output-to-string*"><b>with-output-to-string*</b> <i><clix:lambda-list xmlns:clix="http://bknr.net/clixdoc">() &body body</clix:lambda-list></i> + => + <i>result*</i></a><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc"> + Set up a JSON streaming encoder context, then + evaluate <code><i>body</i></code>. Return a string with the + generated JSON output. + </clix:description></blockquote></p> + + <p xmlns=""> + [Condition type]<br><a class="none" name="no-json-output-context"><b>no-json-output-context</b></a><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc"> + This condition is signalled when one of the stream encoding + function is used outside the dynamic context of a + <code><a href="#with-output">WITH-OUTPUT</a></code> or + <code><a href="#with-output-to-string*">WITH-OUTPUT-TO-STRING*</a></code> body. + </clix:description></blockquote></p> + + <p xmlns="">[Macro]<br><a class="none" name="with-array"><b>with-array</b> <i><clix:lambda-list xmlns:clix="http://bknr.net/clixdoc">() &body body</clix:lambda-list></i> + => + <i>result*</i></a><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc"> + Open a JSON array, then run <code><i>body</i></code>. Inside + the body, <code><a href="#encode-array-element">ENCODE-ARRAY-ELEMENT</a></code> must be + called to encode elements to the opened array. Must be called + within an existing JSON encoder context, see + <code><a href="#with-output">WITH-OUTPUT</a></code> and + <code><a href="#with-output-to-string*">WITH-OUTPUT-TO-STRING*</a></code>. + </clix:description></blockquote></p> + + <p xmlns="">[Function]<br><a class="none" name="encode-array-element"><b>encode-array-element</b> <i><clix:lambda-list xmlns:clix="http://bknr.net/clixdoc">object</clix:lambda-list></i> + => + <i>object</i></a><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc"> + Encode <code><i>object</i></code> as next array element to + the last JSON array opened + with <code><a href="#with-array">WITH-ARRAY</a></code> in the dynamic + context. <code><i>object</i></code> is encoded using the + <code><a href="#encode">ENCODE</a></code> generic function, so it must be of + a type for which an <code><a href="#encode">ENCODE</a></code> method is + defined. + </clix:description></blockquote></p> + + <p xmlns="">[Macro]<br><a class="none" name="with-object"><b>with-object</b> <i><clix:lambda-list xmlns:clix="http://bknr.net/clixdoc">() &body body</clix:lambda-list></i> + => + <i>result*</i></a><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc"> + Open a JSON object, then run <code><i>body</i></code>. Inside the body, + <code><a href="#encode-object-element">ENCODE-OBJECT-ELEMENT</a></code> + or <code><a href="#with-object-element">WITH-OBJECT-ELEMENT</a></code> must be called to + encode elements to the object. Must be called within an + existing JSON encoder context, + see <code><a href="#with-output">WITH-OUTPUT</a></code> + and <code><a href="#with-output-to-string*">WITH-OUTPUT-TO-STRING*</a></code>. + </clix:description></blockquote></p> + + <p xmlns="">[Macro]<br><a class="none" name="with-object-element"><b>with-object-element</b> <i><clix:lambda-list xmlns:clix="http://bknr.net/clixdoc">(key) &body body</clix:lambda-list></i> + => + <i>result*</i></a><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc"> + Open a new encoding context to encode a JSON object + element. <code><i>key</i></code> is the key of the element. + The value will be whatever <code><i>body</i></code> + serializes to the current JSON output context using one of the + stream encoding functions. This can be used to stream out + nested object structures. + </clix:description></blockquote></p> + + <p xmlns="">[Function]<br><a class="none" name="encode-object-element"><b>encode-object-element</b> <i><clix:lambda-list xmlns:clix="http://bknr.net/clixdoc">key value</clix:lambda-list></i> + => + <i>value</i></a><blockquote><clix:description xmlns:clix="http://bknr.net/clixdoc"> + Encode <code><i>key</i></code> and <code><i>value</i></code> + as object element to the last JSON object opened + with <code><a href="#with-object">WITH-OBJECT</a></code> in the dynamic + context. <code><i>key</i></code> + and <code><i>value</i></code> are encoded using + the <code><a href="#encode">ENCODE</a></code> generic function, so they both + must be of a type for which an <code><a href="#encode">ENCODE</a></code> + method is defined. + </clix:description></blockquote></p> + + + + <h4 xmlns=""><a name="app-encoders">Application specific encoders</a></h4> + + Suppose your application uses structs to represent its data, and + you want to encode such structs using JSON in order to send it + to a client application. Suppose further that your structs also + include internal information that you do not want to send. Here + is some code that illustrates how one could implement a + serialization function: + + <pre>CL-USER> (defstruct user name age password) +USER +CL-USER> (defmethod json:encode ((user user) &optional (stream *standard-output*)) + (json:with-output (stream) + (json:with-object () + (json:encode-object-element "name" (user-name user)) + (json:encode-object-element "age" (user-age user))))) +#<STANDARD-METHOD YASON:ENCODE (USER) {5B40A591}> +CL-USER> (json:encode (list (make-user :name "horst" :age 27 :password "puppy") + (make-user :name "uschi" :age 28 :password "kitten"))) +[{"name":"horst","age":27},{"name":"uschi","age":28}] +(#S(USER :NAME "horst" :AGE 27 :PASSWORD "puppy") + #S(USER :NAME "uschi" :AGE 28 :PASSWORD "kitten"))</pre> + + As you can see, the streaming API and the DOM encoder can be + used together. <code xmlns=""><a href="#encode">ENCODE</a></code> invokes itself + recursively, so any application defined method will be called + while encoding in-memory objects as appropriate. + + + + + <h3 xmlns=""><a class="none" name="index">Symbol index</a></h3> + <ul xmlns=""> +<li><code><a href="#*parse-json-arrays-as-vectors*">*parse-json-arrays-as-vectors*</a></code></li> +<li><code><a href="#*parse-json-booleans-as-symbols*">*parse-json-booleans-as-symbols*</a></code></li> +<li><code><a href="#*parse-object-key-fn*">*parse-object-key-fn*</a></code></li> +<li><code><a href="#encode">encode</a></code></li> +<li><code><a href="#encode-array-element">encode-array-element</a></code></li> +<li><code><a href="#encode-object-element">encode-object-element</a></code></li> +<li><code><a href="#no-json-output-context">no-json-output-context</a></code></li> +<li><code><a href="#parse">parse</a></code></li> +<li><code><a href="#with-array">with-array</a></code></li> +<li><code><a href="#with-object">with-object</a></code></li> +<li><code><a href="#with-object-element">with-object-element</a></code></li> +<li><code><a href="#with-output">with-output</a></code></li> +<li><code><a href="#with-output-to-string*">with-output-to-string*</a></code></li> +</ul> + + + <h3 xmlns=""><a class="none" name="license">License</a></h3> + <pre class="none">Copyright (c) 2008 Hans Hübner +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + + - Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + + - Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in + the documentation and/or other materials provided with the + distribution. + + - Neither the name BKNR nor the names of its contributors may be + used to endorse or promote products derived from this software + without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> + + + <h3 xmlns=""><a class="none" name="ack">Acknowledgements</a></h3> + Thanks go to Edi Weitz for being a great inspiration. This + documentation as been generated with a hacked-up version of + his <a href="http://weitz.de/documentation-template/">DOCUMENTATION-TEMPLATE</a> + software. + + +</body></html>

1 0

[bknr-cvs] hans changed trunk/libraries/yason/
by BKNR Commits 15 Nov '08

15 Nov '08

Revision: 4049 Author: hans URL: http://bknr.net/trac/changeset/4049 release 0.1 U trunk/libraries/yason/doc.xml U trunk/libraries/yason/encode.lisp U trunk/libraries/yason/package.lisp U trunk/libraries/yason/parse.lisp Change set too large, please see URL above

1 0

[bknr-cvs] hans changed trunk/libraries/
by BKNR Commits 14 Nov '08

14 Nov '08

Revision: 4048 Author: hans URL: http://bknr.net/trac/changeset/4048 Documentation updates. U trunk/libraries/clixdoc/clixdoc.xsl U trunk/libraries/yason/doc.xml Modified: trunk/libraries/clixdoc/clixdoc.xsl =================================================================== --- trunk/libraries/clixdoc/clixdoc.xsl 2008-11-14 12:37:03 UTC (rev 4047) +++ trunk/libraries/clixdoc/clixdoc.xsl 2008-11-14 13:05:00 UTC (rev 4048) @@ -45,7 +45,7 @@ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> <title><xsl:value-of select="clix:title"/></title> <meta name="description"><xsl:attribute name="content"><xsl:value-of select="clix:short-description"/></xsl:attribute></meta> - <style type="text/css"> + <style type="text/css"> body { background-color: #ffffff; max-width: 50em } pre { padding:5px; background-color:#e0e0e0 } pre.none { padding:5px; background-color:#ffffff } Modified: trunk/libraries/yason/doc.xml =================================================================== --- trunk/libraries/yason/doc.xml 2008-11-14 12:37:03 UTC (rev 4047) +++ trunk/libraries/yason/doc.xml 2008-11-14 13:05:00 UTC (rev 4048) @@ -96,29 +96,36 @@ </clix:chapter> <clix:chapter name="parsing" title="Parsing JSON data"> - JSON data is always completely parsed into an equivalent - in-memory representation. Upon reading, some translations are - performed by default to make it easier for the Common Lisp - program to work with the data; see <clix:ref>mapping</clix:ref> - for details. If desired, the parser can be configured to - preserve the full semantics of the JSON data read. - </clix:chapter> + <p> + JSON data is always completely parsed into an equivalent + in-memory representation. Upon reading, some translations are + performed by default to make it easier for the Common Lisp + program to work with the data; see <clix:ref>mapping</clix:ref> + for details. If desired, the parser can be configured to + preserve the full semantics of the JSON data read. + </p> - <clix:chapter name="encoding" title="Encoding JSON data"> - YASON provides for two distinct modes to encode JSON data: - Applications can either create an in memory representation of - the data to be serialized, then have YASON convert it to JSON in - one go, or they can use a set of macros to serialze the JSON - data element-by-element, thereby having fine grained control - over the layout of the generated data. - </clix:chapter> + <clix:function name="parse" generic="true"> + <clix:lambda-list>input</clix:lambda-list> + <clix:returns>object</clix:returns> + <clix:description> + Parse <clix:arg>input</clix:arg>, which needs to be a string + or a stream, as JSON. Returns the lisp representation of the + JSON structure parsed. + </clix:description> + </clix:function> - <clix:chapter name="reference" title="Reference"> + <clix:special-variable name="*parse-json-arrays-as-vectors*"> + <clix:description> + If set to a true value, JSON arrays will be parsed as vectors, + not as lists. + </clix:description> + </clix:special-variable> - <clix:special-variable name="*parse-json-array-as-list*"> + <clix:special-variable name="*parse-json-booleans-as-symbols*"> <clix:description> - If set to a true value, JSON arrays will be parsed as lists, - not as vectors. + If set to a true value, JSON booleans will be read as the + symbols TRUE and FALSE, not as T and NIL, respectively. </clix:description> </clix:special-variable> @@ -129,125 +136,155 @@ </clix:description> </clix:special-variable> - <clix:function name="encode" generic="true"> - <clix:lambda-list>object stream</clix:lambda-list> - <clix:returns>**RETURN-TYPE**</clix:returns> - <clix:description> - Encode <clix:arg>object</clix:arg> - to <clix:arg>stream</clix:arg> in JSON format - </clix:description> - </clix:function> + </clix:chapter> - <clix:function name="encode-array-element"> - <clix:lambda-list>object</clix:lambda-list> - <clix:returns>**RETURN-TYPE**</clix:returns> - <clix:description> - Encode <clix:arg>object</clix:arg> as next array element to - the last JSON array opened - with <clix:ref>WITH-ARRAY</clix:ref> in the dynamic - context. <clix:arg>object</clix:arg> is encoded using the - <clix:ref>ENCODE</clix:ref> generic function, so it must be of - a type for which an <clix:ref>ENCODE</clix:ref> method is - defined. - </clix:description> - </clix:function> + <clix:chapter name="encoding" title="Encoding JSON data"> + YASON provides for two distinct modes to encode JSON data: + Applications can either create an in memory representation of the + data to be serialized, then have YASON convert it to JSON in one + go, or they can use a set of macros to serialze the JSON data + element-by-element, thereby having fine grained control over the + layout of the generated data. - <clix:function name="encode-object-element"> - <clix:lambda-list>key value</clix:lambda-list> - <clix:returns>**RETURN-TYPE**</clix:returns> - <clix:description> - Encode <clix:arg>key</clix:arg> and <clix:arg>value</clix:arg> - as object element to the last JSON object opened - with <clix:ref>WITH-OBJECT</clix:ref> in the dynamic - context. <clix:arg>key</clix:arg> - and <clix:arg>value</clix:arg> are encoded using - the <clix:ref>ENCODE</clix:ref> generic function, so they both - must be of a type for which an <clix:ref>ENCODE</clix:ref> - method is defined. - </clix:description> - </clix:function> + <clix:subchapter name="dom-encoder" title="Encoding a JSON DOM"> + In this mode, a in-memory structure is ancoded in JSON format. + The structure must consist of objects that are serializable + using the <clix:ref>ENCODE</clix:ref> function. YASON defines a + number of encoders for standard data types + (see <clix:ref>MAPPING</clix:ref>), but the application can + define additional methods, e.g. for encoding CLOS objects. - <clix:condition name="no-json-output-context"> - <clix:description>**DOCSTRING-MISSING**</clix:description> - </clix:condition> + <clix:function name="encode" generic="true"> + <clix:lambda-list>object stream</clix:lambda-list> + <clix:returns>|</clix:returns> + <clix:description> + Encode <clix:arg>object</clix:arg> + to <clix:arg>stream</clix:arg> in JSON format + </clix:description> + </clix:function> - <clix:function name="null"> - <clix:lambda-list>object</clix:lambda-list> - <clix:returns>**RETURN-TYPE**</clix:returns> - <clix:description> - Return true if <clix:arg>object</clix:arg> is a <clix:ref>NULL</clix:ref>, and NIL otherwise. - </clix:description> - </clix:function> + </clix:subchapter> - <clix:function name="parse" generic="true"> - <clix:lambda-list>input</clix:lambda-list> - <clix:returns>**RETURN-TYPE**</clix:returns> - <clix:description> - Parse <clix:arg>input</clix:arg>, which needs to be a string or a - stream, as JSON. Returns the lisp representation of the JSON - structure parsed. - </clix:description> - </clix:function> + <clix:subchapter name="stream-encoder" title="Encoding JSON in streaming mode"> + <p> + In this mode, the JSON structure is generated in a stream. The + application makes explicit calls to the encoding library in + order to generate the JSON structure. It provides for more + control over the generated output, and can be used to generate + arbitary JSON without requiring that there exists a matching + Lisp datastructure. + </p> + For example: + <pre>CL-USER> (json:with-output (*standard-output*) + (json:with-array () + (dotimes (i 3) + (json:encode-array-element i)))) +[0,1,2] +NIL +CL-USER> (json:with-output (*standard-output*) + (json:with-object () + (json:encode-object-element "hello" "hu hu") + (json:with-object-element ("harr") + (json:with-array () + (dotimes (i 3) + (json:encode-array-element i)))))) +{"hello":"hu hu","harr":[0,1,2]} +NIL</pre> - <clix:function name="with-array" macro="true"> - <clix:lambda-list>() &body body</clix:lambda-list> - <clix:returns>**RETURN-TYPE**</clix:returns> - <clix:description> - Open a JSON array, then run <clix:arg>body</clix:arg>. Inside the body, - <clix:ref>ENCODE-ARRAY-ELEMENT</clix:ref> must be called to - encode elements to the opened array. Must be called within an - existing JSON encoder context, see - <clix:ref>WITH-OUTPUT</clix:ref> and - <clix:ref>WITH-OUTPUT-TO-STRING*</clix:ref>. - </clix:description> - </clix:function> + <clix:function name="with-output" macro="true"> + <clix:lambda-list>(stream) &body body</clix:lambda-list> + <clix:returns>**RETURN-TYPE**</clix:returns> + <clix:description> + Set up a JSON streaming encoder context + on <clix:arg>stream</clix:arg>, then + evaluate <clix:arg>body</clix:arg>. + </clix:description> + </clix:function> - <clix:function name="with-object" macro="true"> - <clix:lambda-list>() &body body</clix:lambda-list> - <clix:returns>**RETURN-TYPE**</clix:returns> - <clix:description> - Open a JSON object, then run <clix:arg>body</clix:arg>. Inside the body, - <clix:ref>ENCODE-OBJECT-ELEMENT</clix:ref> - or <clix:ref>WITH-OBJECT-ELEMENT</clix:ref> must be called to - encode elements to the object. Must be called within an - existing JSON encoder context, - see <clix:ref>WITH-OUTPUT</clix:ref> - and <clix:ref>WITH-OUTPUT-TO-STRING*</clix:ref>. - </clix:description> - </clix:function> + <clix:function name="with-output-to-string*" macro="true"> + <clix:lambda-list>() &body body</clix:lambda-list> + <clix:returns>**RETURN-TYPE**</clix:returns> + <clix:description> + Set up a JSON streaming encoder context, then + evaluate <clix:arg>body</clix:arg>. Return a string with the + generated JSON output. + </clix:description> + </clix:function> - <clix:function name="with-object-element" macro="true"> - <clix:lambda-list>(key) &body body</clix:lambda-list> - <clix:returns>**RETURN-TYPE**</clix:returns> - <clix:description> - Open a new encoding context to encode a JSON object - element. <clix:arg>key</clix:arg> is the key of the element. - The value will be whatever <clix:arg>body</clix:arg> - serializes to the current JSON output context using one of the - stream encoding functions. This can be used to stream out - nested object structures. - </clix:description> - </clix:function> + <clix:condition name="no-json-output-context"> + <clix:description>**DOCSTRING-MISSING**</clix:description> + </clix:condition> - <clix:function name="with-output" macro="true"> - <clix:lambda-list>(stream) &body body</clix:lambda-list> - <clix:returns>**RETURN-TYPE**</clix:returns> - <clix:description> - Set up a JSON streaming encoder context - on <clix:arg>stream</clix:arg>, then - evaluate <clix:arg>body</clix:arg>. - </clix:description> - </clix:function> + <clix:function name="with-array" macro="true"> + <clix:lambda-list>() &body body</clix:lambda-list> + <clix:returns>**RETURN-TYPE**</clix:returns> + <clix:description> + Open a JSON array, then run <clix:arg>body</clix:arg>. Inside + the body, <clix:ref>ENCODE-ARRAY-ELEMENT</clix:ref> must be + called to encode elements to the opened array. Must be called + within an existing JSON encoder context, see + <clix:ref>WITH-OUTPUT</clix:ref> and + <clix:ref>WITH-OUTPUT-TO-STRING*</clix:ref>. + </clix:description> + </clix:function> - <clix:function name="with-output-to-string*" macro="true"> - <clix:lambda-list>() &body body</clix:lambda-list> - <clix:returns>**RETURN-TYPE**</clix:returns> - <clix:description> - Set up a JSON streaming encoder context, then - evaluate <clix:arg>body</clix:arg>. Return a string with the - generated JSON output. - </clix:description> - </clix:function> + <clix:function name="encode-array-element"> + <clix:lambda-list>object</clix:lambda-list> + <clix:returns>**RETURN-TYPE**</clix:returns> + <clix:description> + Encode <clix:arg>object</clix:arg> as next array element to + the last JSON array opened + with <clix:ref>WITH-ARRAY</clix:ref> in the dynamic + context. <clix:arg>object</clix:arg> is encoded using the + <clix:ref>ENCODE</clix:ref> generic function, so it must be of + a type for which an <clix:ref>ENCODE</clix:ref> method is + defined. + </clix:description> + </clix:function> + + <clix:function name="with-object" macro="true"> + <clix:lambda-list>() &body body</clix:lambda-list> + <clix:returns>**RETURN-TYPE**</clix:returns> + <clix:description> + Open a JSON object, then run <clix:arg>body</clix:arg>. Inside the body, + <clix:ref>ENCODE-OBJECT-ELEMENT</clix:ref> + or <clix:ref>WITH-OBJECT-ELEMENT</clix:ref> must be called to + encode elements to the object. Must be called within an + existing JSON encoder context, + see <clix:ref>WITH-OUTPUT</clix:ref> + and <clix:ref>WITH-OUTPUT-TO-STRING*</clix:ref>. + </clix:description> + </clix:function> + + <clix:function name="with-object-element" macro="true"> + <clix:lambda-list>(key) &body body</clix:lambda-list> + <clix:returns>**RETURN-TYPE**</clix:returns> + <clix:description> + Open a new encoding context to encode a JSON object + element. <clix:arg>key</clix:arg> is the key of the element. + The value will be whatever <clix:arg>body</clix:arg> + serializes to the current JSON output context using one of the + stream encoding functions. This can be used to stream out + nested object structures. + </clix:description> + </clix:function> + + <clix:function name="encode-object-element"> + <clix:lambda-list>key value</clix:lambda-list> + <clix:returns>**RETURN-TYPE**</clix:returns> + <clix:description> + Encode <clix:arg>key</clix:arg> and <clix:arg>value</clix:arg> + as object element to the last JSON object opened + with <clix:ref>WITH-OBJECT</clix:ref> in the dynamic + context. <clix:arg>key</clix:arg> + and <clix:arg>value</clix:arg> are encoded using + the <clix:ref>ENCODE</clix:ref> generic function, so they both + must be of a type for which an <clix:ref>ENCODE</clix:ref> + method is defined. + </clix:description> + </clix:function> + + </clix:subchapter> </clix:chapter> <clix:chapter name="index" title="Symbol index">

1 0

[bknr-cvs] hans changed trunk/libraries/
by BKNR Commits 14 Nov '08

14 Nov '08

Revision: 4047 Author: hans URL: http://bknr.net/trac/changeset/4047 checkpoint work U trunk/libraries/clixdoc/clixdoc.asd U trunk/libraries/clixdoc/clixdoc.xsl U trunk/libraries/clixdoc/edi-docutil.lisp U trunk/libraries/clixdoc/make-doc.lisp A trunk/libraries/yason/doc.xml U trunk/libraries/yason/encode.lisp U trunk/libraries/yason/package.lisp U trunk/libraries/yason/parse.lisp Change set too large, please see URL above

1 0

Jump to page:

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

2010

2009

2008

2007

2006

bknr-cvs