forked from marijnh/ST-JSON
-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
186 lines (147 loc) · 6.34 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<style type="text/css">
body { max-width: 50em; font-family: georgia, times, serif; margin: 3em; }
h1, h2 { font-weight: normal; }
p.def { margin-top: 1.5em; font-family: courier; }
p.def span { color: #555555; font-weight: bold; font-family: tahoma, sans-serif; font-size: 80%; }
p.desc { margin-left: 1em; }
pre { margin-left: 1em; }
h1 { color: #2B7; }
h2 { color: #B72; font-size: 130% }
a:link { color: #72B; }
a:visited { color: #548; }
</style>
<title>ST-JSON</title>
</head>
<body>
<h1>ST-JSON</h1>
<p>ST-JSON ('ST' because it originated at <a
href="http://streamtech.nl">Streamtech</a>) is a Common Lisp library
for encoding and decoding JSON values (as specified on <a
href="http://json.org">json.org</a>).</p>
<p>This library does mostly the same thing as <a
href="http://common-lisp.net/project/cl-json/">CL-JSON</a>, but is
simpler and more precise about types (distinguishing boolean false,
the empty array, and the empty object).</p>
<h2>Download and installation</h2>
<p>The library is available under a <a href="LICENSE">zlib-style</a>
license. It can be installed with <a
href="http://www.cliki.net/ASDF-Install">asdf-install</a>, or you
can download the current <a
href="http://marijnhaverbeke.nl/st-json/st-json.tgz">release</a>
manually. The <a href="http://git-scm.com">git</a> repository
can be checked out with:</p>
<pre>git clone http://marijnhaverbeke.nl/git/st-json</pre>
<p>The code is also on <a href="http://github.com/marijnh/ST-JSON">github</a>.</p>
<h2>Support</h2>
<p>Mail <a href="mailto:[email protected]">Marijn Haverbeke</a> with
any questions, bug reports, patches, etcetera. I'll set up some
mailing list when there is a need.</p>
<h2>Documentation</h2>
<p>ST-JSON maps JavaScript numbers to Lisp numbers, strings to
strings, null to the keyword <code>:null</code>, booleans to the
keywords <code>:true</code> and <code>:false</code>, arrays to
lists, and objects to a custom type <code>jso</code> (JavaScript
object). Since in CL boolean false, the empty list, and nullish
stuff is all usually represented by <code>nil</code>, you will
sometimes have to selectively transform your values before writing
or after reading them. (The empty array is a truthy value in
JavaScript, so writing out <code>nil</code> for a boolean is bound
to get you into trouble.)</p>
<p class="def" id="json-bool">
<span>type</span> json-bool
</p>
<p class="desc">A type including only the values <code>:true</code>
and <code>:false</code>. Useful in <a
href="#read-json-as-type"><code>read-json-as-type</code></a> and
similar.</p>
<p class="def" id="as-json-bool">
<span>function</span> as-json-bool (value)
<br/>→ json-bool
</p>
<p class="desc">Convert a generalised boolean to a <a
href="#json-bool"><code>json-bool</code></a>.</p>
<p class="def" id="from-json-bool">
<span>function</span> from-json-bool (value)
<br/>→ bool
</p>
<p class="desc">Convert a <a
href="#json-bool"><code>json-bool</code></a> to a Lisp boolean.</p>
<p class="def" id="json-null">
<span>type</span> json-null
</p>
<p class="desc">A type containing only <code>:null</code>.</p>
<p class="def" id="jso">
<span>function</span> jso (&rest fields)
<br/>→ jso
</p>
<p class="desc"><code>jso</code> names both a function and a type.
This type is used to represent JavaScript objects. It simply wraps
an alist. The function is called with an even number of arguments,
which give the properties of the object and their values.</p>
<p class="def" id="getjso">
<span>function</span> getjso (key jso)
<br/>→ value
</p>
<p class="desc">Looks up a value in a JavaScript object, returns a
second value indicating whether the value was found (like
<code>gethash</code>). Can be used with <code>setf</code>.</p>
<p class="def" id="getjso*">
<span>function</span> getjso* (keys jso)
<br/>→ value
</p>
<p class="desc">Takes a key of the form "a.b.c", generates a series
of getjso calls that descend into the object and returns 'c'.
<p class="def" id="mapjso">
<span>function</span> mapjso (function jso)
</p>
<p class="desc"><code>maphash</code> equivalent for JavaScript
objects.</p>
<p class="def" id="read-json">
<span>method</span> read-json (source &optional junk-allowed-p)
<br/>→ value
</p>
<p class="desc">Reads a JSON value from an input stream or string.
When <code>junk-allowed-p</code> is <code>nil</code>, an error will
be raised if any non-whitespace characters are found after the
value. This error, and any other parsing errors, will have the type
<code>json-parse-error</code>.</p>
<p class="def" id="read-json-as-type">
<span>function</span> read-json-as-type (source type)
<br/>→ value
</p>
<p class="desc">Like <a
href="#read-json"><code>read-json</code></a>, but also asserts that
the resulting value is of a given type, and raises an error of type
<code>json-type-error</code> if not.</p>
<p class="def" id="write-json">
<span>function</span> write-json (element stream)
</p>
<p class="desc">Writes a value to a stream. Raises an error of type
<code>json-write-error</code> if a value for which no <a
href="#write-json-element"><code>write-json-element</code></a>
method is defined is encountered.</p>
<p class="def" id="write-json-to-string">
<span>function</span> write-json-to-string (element)
<br/>→ string
</p>
<p class="desc">Like <a
href="#write-json"><code>write-json</code></a>, but produces a
string.</p>
<p class="def" id="write-json-element">
<span>method</span> write-json-element (element stream)
</p>
<p class="desc">Generic function used to serialise values as JSON.
You can specialise it for your own types, if needed.</p>
<p class="def" id="script-tag-hack">
<span>variable</span> *script-tag-hack*
</p>
<p class="desc">Bind this to <code>t</code> when writing JSON that
will end up in an HTML document. It prevents
<code>'</script>'</code> from occurring in strings by escaping
any slash following a '<code><</code>' character. Default value
is <code>nil</code>.</p>
</body>
</html>