|
| 1 | +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| 2 | +<html xmlns="http://www.w3.org/1999/xhtml"> |
| 3 | +<head> |
| 4 | + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> |
| 5 | + <meta http-equiv="Content-Style-Type" content="text/css" /> |
| 6 | + <meta name="generator" content="pandoc" /> |
| 7 | + <title></title> |
| 8 | + <style type="text/css">code{white-space: pre;}</style> |
| 9 | + <style type="text/css"> |
| 10 | +div.sourceCode { overflow-x: auto; } |
| 11 | +table.sourceCode, tr.sourceCode, td.lineNumbers, td.sourceCode { |
| 12 | + margin: 0; padding: 0; vertical-align: baseline; border: none; } |
| 13 | +table.sourceCode { width: 100%; line-height: 100%; } |
| 14 | +td.lineNumbers { text-align: right; padding-right: 4px; padding-left: 4px; color: #aaaaaa; border-right: 1px solid #aaaaaa; } |
| 15 | +td.sourceCode { padding-left: 5px; } |
| 16 | +code > span.kw { color: #007020; font-weight: bold; } /* Keyword */ |
| 17 | +code > span.dt { color: #902000; } /* DataType */ |
| 18 | +code > span.dv { color: #40a070; } /* DecVal */ |
| 19 | +code > span.bn { color: #40a070; } /* BaseN */ |
| 20 | +code > span.fl { color: #40a070; } /* Float */ |
| 21 | +code > span.ch { color: #4070a0; } /* Char */ |
| 22 | +code > span.st { color: #4070a0; } /* String */ |
| 23 | +code > span.co { color: #60a0b0; font-style: italic; } /* Comment */ |
| 24 | +code > span.ot { color: #007020; } /* Other */ |
| 25 | +code > span.al { color: #ff0000; font-weight: bold; } /* Alert */ |
| 26 | +code > span.fu { color: #06287e; } /* Function */ |
| 27 | +code > span.er { color: #ff0000; font-weight: bold; } /* Error */ |
| 28 | +code > span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */ |
| 29 | +code > span.cn { color: #880000; } /* Constant */ |
| 30 | +code > span.sc { color: #4070a0; } /* SpecialChar */ |
| 31 | +code > span.vs { color: #4070a0; } /* VerbatimString */ |
| 32 | +code > span.ss { color: #bb6688; } /* SpecialString */ |
| 33 | +code > span.im { } /* Import */ |
| 34 | +code > span.va { color: #19177c; } /* Variable */ |
| 35 | +code > span.cf { color: #007020; font-weight: bold; } /* ControlFlow */ |
| 36 | +code > span.op { color: #666666; } /* Operator */ |
| 37 | +code > span.bu { } /* BuiltIn */ |
| 38 | +code > span.ex { } /* Extension */ |
| 39 | +code > span.pp { color: #bc7a00; } /* Preprocessor */ |
| 40 | +code > span.at { color: #7d9029; } /* Attribute */ |
| 41 | +code > span.do { color: #ba2121; font-style: italic; } /* Documentation */ |
| 42 | +code > span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */ |
| 43 | +code > span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */ |
| 44 | +code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */ |
| 45 | + </style> |
| 46 | +</head> |
| 47 | +<body> |
| 48 | +<h1 id="title">Title</h1> |
| 49 | +<p>JSON</p> |
| 50 | +<h2 id="author">Author</h2> |
| 51 | +<p>Amirouche Boubekki</p> |
| 52 | +<h2 id="status">Status</h2> |
| 53 | +<p>Draft</p> |
| 54 | +<h2 id="abstract">Abstract</h2> |
| 55 | +<p>This library describes a JavaScript Object Notation (JSON) parser and printer. It does support to stream parse JSON that is possibly bigger than memory.</p> |
| 56 | +<h2 id="rationale">Rationale</h2> |
| 57 | +<p>JSON is a defacto industry standard to exchange data.</p> |
| 58 | +<p>For best interoperability the sample implementation is based on <a href="https://tools.ietf.org/html/rfc7159">RFC7159</a>, and the tests are based on <a href="https://github.com/nst/JSONTestSuite/">JSONTestSuite</a>.</p> |
| 59 | +<p>The mapping between JSON types and Scheme objects is not trivial because a given mapping might not be the best for every situations. That is one of the reason why this library expose a stream reader, in order to allow users to specify the scheme representation and have efficient code.</p> |
| 60 | +<h2 id="specification">Specification</h2> |
| 61 | +<h3 id="json-error-obj-boolean"><code>(json-error? obj) → boolean</code></h3> |
| 62 | +<p>Returns <code>#t</code> is <code>OBJ</code> is an error object. This exception can be raised during <code>json-stream-read</code>, <code>json-read</code> or <code>json-write</code>.</p> |
| 63 | +<h3 id="json-error-reason-obj-string"><code>(json-error-reason obj) → string</code></h3> |
| 64 | +<p>Return a string explaining the reason of the error. This should be human readable.</p> |
| 65 | +<h3 id="json-null-obj-boolean"><code>(json-null? obj) → boolean</code></h3> |
| 66 | +<p>Return <code>#t</code> if <code>OBJ</code> is the scheme symbol <code>'null</code> representing in Scheme the JSON <code>null</code>. In any other cases, return <code>#f</code>.</p> |
| 67 | +<h3 id="json-stream-read-proc-port-unspecified"><code>(json-stream-read proc [port]) → unspecified</code></h3> |
| 68 | +<p>Streaming event-based JSON reader. <code>PORT</code> must be a textual input port. The default value of <code>PORT</code> is the value returned by the procedure <code>current-input-port</code>. The returned value is unspecified.</p> |
| 69 | +<p><code>json-stream-read</code> should raise an object that satisfy the predicate <code>json-error?</code> in cases where the JSON is invalid.</p> |
| 70 | +<p><code>json-stream-read</code> will call <code>PROC</code> with two arguments. The first argument is the event <code>type</code>, the second argument is the event <code>obj</code>. Since the value that can be taken by <code>obj</code> depends on the value of <code>type</code>, they are presented together in the following paragraph.</p> |
| 71 | +<p>The first arguments is noted <code>type</code>. It is a symbol. It can be the following:</p> |
| 72 | +<ul> |
| 73 | +<li><code>'json-structure</code></li> |
| 74 | +<li><code>'json-value</code></li> |
| 75 | +</ul> |
| 76 | +<p>The <code>obj</code> argument can take the following values dependings on <code>type</code>:</p> |
| 77 | +<ul> |
| 78 | +<li><p>If type is <code>'json-structure</code>, then <code>obj</code> can be:</p> |
| 79 | +<ul> |
| 80 | +<li><p><code>'array-open</code> symbol denoting that an array should be constructed.</p></li> |
| 81 | +<li><p><code>'array-close</code> symbol denoting that the construction of the array for which the last <code>'array-open</code> was emitted and not closed, is finished.</p></li> |
| 82 | +<li><p><code>'object-open'</code> symbol denoting that an object should be constructed. The object's key-value pairs are emitted in sequence like property list (plist). The keys will be produced by <code>(proc 'json-structure some-symbol)</code>, that is, the key is always a symbol. The production of the key is always followed by the production of a value. Otherwise, the JSON would be invalid and <code>json-stream-read</code> would raise error. The production of the value can be a <code>'json-value</code> but can also be <code>'json-structure</code> with <code>obj</code> strictly equivalent <code>'array-open</code> or <code>'object-open</code>. This events will be followed by other events. Eventually, an associated <code>'object-close</code> event is emitted.</p></li> |
| 83 | +<li><p><code>'object-close</code> symbol denoting that the construction of the object for which the last <code>object-open</code> was emitted and not closed, is finished.</p></li> |
| 84 | +</ul></li> |
| 85 | +<li><p>If type is <code>'json-value</code>, then <code>obj</code> is scheme object that can be of the following types:</p> |
| 86 | +<ul> |
| 87 | +<li><p>symbol</p></li> |
| 88 | +<li><p>number</p></li> |
| 89 | +<li><p>string</p></li> |
| 90 | +</ul></li> |
| 91 | +</ul> |
| 92 | +<p><strong>Note:</strong> This document does not prescribes a validating parser. But in cases where the input JSON is valid, <code>json-parse</code> must emit the correct sequence of events.</p> |
| 93 | +<p><strong>Note:</strong> Given <code>type</code> is <code>'json-value</code>, then there is two occasions where <code>obj</code> can be a symbol: 1) the JSON contains a <code>null</code> value, in that case <code>'null</code> symbol is produced; 2) In a JSON object, keys are produced with the type <code>'json-value</code> and the <code>obj</code> as a symbol. In particular the key <code>"null"</code> will be represented with <code>'null</code> symbol and JSON <code>null</code> too: that does not have bad consequences for the user.</p> |
| 94 | +<h4 id="example-one">Example One</h4> |
| 95 | +<p>Take for instance the following JSON text:</p> |
| 96 | +<div class="sourceCode"><pre class="sourceCode javascript"><code class="sourceCode javascript">[<span class="kw">true</span><span class="op">,</span> <span class="kw">false</span><span class="op">,</span> <span class="dv">42</span><span class="op">,</span> <span class="kw">null</span>]</code></pre></div> |
| 97 | +<p>It will produce the following calls to <code>PROC</code>:</p> |
| 98 | +<div class="sourceCode"><pre class="sourceCode scheme"><code class="sourceCode scheme">(proc 'json-structure 'array-open) |
| 99 | +(proc 'json-value <span class="dv">#t</span>) |
| 100 | +(proc 'json-value <span class="dv">#f</span>) |
| 101 | +(proc 'json-value <span class="dv">42</span>) |
| 102 | +(proc 'json-value 'null) |
| 103 | +(proc 'json-structure 'array-close)</code></pre></div> |
| 104 | +<h4 id="example-two">Example Two</h4> |
| 105 | +<p>Take for instance the following JSON text:</p> |
| 106 | +<div class="sourceCode"><pre class="sourceCode javascript"><code class="sourceCode javascript">[<span class="st">"hello"</span><span class="op">,</span> <span class="st">"world"</span><span class="op">,</span> <span class="op">{</span><span class="st">"truth"</span><span class="op">:</span> [<span class="dv">42</span>]<span class="op">}</span>]</code></pre></div> |
| 107 | +<p>It will produce the following calls to <code>PROC</code>:</p> |
| 108 | +<div class="sourceCode"><pre class="sourceCode scheme"><code class="sourceCode scheme">(proc 'json-structure 'array-open) |
| 109 | +(proc 'json-value <span class="st">"hello"</span>) |
| 110 | +(proc 'json-value <span class="st">"world"</span>) |
| 111 | +(proc 'json-structure 'object-open) |
| 112 | +(proc 'json-value 'truth) |
| 113 | +(proc 'json-structure 'array-open) |
| 114 | +(proc 'json-value <span class="dv">42</span>) |
| 115 | +(proc 'json-structure 'array-close) |
| 116 | +(proc 'json-structure 'object-close) |
| 117 | +(proc 'json-structure 'array-close)</code></pre></div> |
| 118 | +<h3 id="json-read-port-object"><code>(json-read [port]) → object</code></h3> |
| 119 | +<p>JSON reader procedure. <code>PORT</code> must be a textual input port. The default value of <code>PORT</code> is the value returned by the procedure <code>current-input-port</code>. The returned value is a scheme object.</p> |
| 120 | +<p>The mapping between JSON types and Scheme objects is the following:</p> |
| 121 | +<ul> |
| 122 | +<li><code>null</code> → the symbol <code>'null</code></li> |
| 123 | +<li><code>true</code> → <code>#t</code></li> |
| 124 | +<li><code>false</code> → <code>#f</code></li> |
| 125 | +<li>number → number</li> |
| 126 | +<li>string → string</li> |
| 127 | +<li>array → vector</li> |
| 128 | +<li>object → association list with keys that are symbols</li> |
| 129 | +</ul> |
| 130 | +<h3 id="json-write-obj-port-unspecified"><code>(json-write obj [port]) → unspecified</code></h3> |
| 131 | +<p>JSON writer procedure. <code>PORT</code> must be a textual output port. The default value of <code>PORT</code> is the value returned by the procedure <code>current-output-port</code>. The returned value is unspecified.</p> |
| 132 | +<p><code>json-write</code> will validate that <code>OBJ</code> can be serialized into JSON before writing to <code>PORT</code>. In the case where <code>OBJ</code> is not an object or composition of the following types, an error that satisfy <code>json-error?</code> is raised:</p> |
| 133 | +<ul> |
| 134 | +<li>symbol <code>'null</code></li> |
| 135 | +<li>boolean</li> |
| 136 | +<li>real number</li> |
| 137 | +<li>string</li> |
| 138 | +<li>vector</li> |
| 139 | +<li>association list</li> |
| 140 | +</ul> |
| 141 | +<h2 id="implementation">Implementation</h2> |
| 142 | +<p>Link to the sample implementation</p> |
| 143 | +<h2 id="acknowledgements">Acknowledgements</h2> |
| 144 | +<p>Give credits where credits is due.</p> |
| 145 | +<h2 id="copyright">Copyright</h2> |
| 146 | +<p>Copyright (C) Amirouche Boubekki (2020).</p> |
| 147 | +<p>Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:</p> |
| 148 | +<p>The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.</p> |
| 149 | +<p>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</p> |
| 150 | +</body> |
| 151 | +</html> |
0 commit comments