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
|
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<link rel="stylesheet" href="style.css" type="text/css" />
<title>JSON implementation for Ruby</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
</head>
<body>
<ul id="linkbox">
<li><a href="http://flori.github.com/json/index.html">Homepage</a></li>
<li><a href="http://github.com/flori/json/tree/master">Github Repository</a></li>
<li><a href="http://www.ping.de/~flori">Download</a></li>
<li><a href="doc/index.html">Documentation</a></li>
<li><a href="screenshots.html">Screenshots</a></li>
</ul>
<div id="content">
<h1>
<img style="float: left; margin-right: 32px;" id="logo" src="json_logo.png" alt="JSON Logo" title="JSON Logo" />
<span style="float: left; margin-top: 16px;">JSON implementation for Ruby</span>
</h1>
<div style="clear: both;"></div>
<h2>Description</h2>
<p>
This is a implementation of the JSON specification according to
<a href="http://www.ietf.org/rfc/rfc4627.txt">RFC 4627</a>. You can think of it as a low fat
alternative to XML, if you want to store data to disk or transmit it over a
network rather than use a verbose markup language.
</p>
<p>
Starting from version 1.0.0 on there
will be two variants available:
</p>
<ul>
<li>A pure ruby variant, that relies on the iconv and the stringscan
extensions, which are both part of the ruby standard library.</li>
<li> The quite a bit faster (see the <a href="doc/index.html">documentation</a>) C
extension variant, which is in parts implemented in C and comes with its own
unicode conversion functions and a parser
generated by the <a href="http://www.cs.queensu.ca/~thurston/ragel">Ragel
State Machine Compiler</a>.</li>
</ul>
<p>
Both variants of the JSON generator escape all non-ASCII an control
characters with \uXXXX escape sequences, and support UTF-16 surrogate pairs
in order to be able to generate the whole range of unicode code points. This
means that generated JSON text is encoded as UTF-8 (because ASCII is a subset
of UTF-8) and at the same time avoids decoding problems for receiving
endpoints, that don't expect UTF-8 encoded texts. On the negative side this
may lead to a bit longer strings than necessarry.
</p>
<p>
It's also easy to extend JSON data types for arbitrary Ruby classes (including
your own) like this:
</p>
<pre>
class Range
def to_json(*a)
{
'json_class' => self.class.name,
'data' => [ first, last, exclude_end? ]
}.to_json(*a)
end
def self.json_create(o)
new(*o['data'])
end
end
</pre>
<p>
Now Range instances can be serialized/deserialized:
</p>
<pre>
JSON.parse((1..10).to_json) == (1..10)
</pre>
<p>
A lot of additional information about JSON can be found <a
href="http://www.json.org/">Douglas Crockford's JSON
site</a>.
</p>
<h2>Installation</h2>
<p>
The library can be installed via rubygems:
</p>
<pre>
# gem install json
</pre>
<p>
If you have to use the pure variant, you can use:
</p>
<pre>
# gem install json_pure
</pre>
<p>
The gem and the source archive can also be <a
href="http://www.ping.de/~flori">downloaded</a> directly from rubyforge.org.
</p>
<h2>Usage</h2>
<p>
If you require JSON like this:
</p>
<pre>
require 'json'
</pre>
<p>
JSON first tries to load the extension variant. If this fails, the pure variant
is loaded and used.
</p>
<p>
To determine, which variant is active you can use the follwing methods:
</p>
<ul>
<li>Ext variant:
<pre>
[ JSON.parser, JSON.generator ] # => [JSON::Ext::Parser, JSON::Ext::Generator]
</pre>
</li>
<li>Pure variant:
<pre>
[ JSON.parser, JSON.generator ] # => [JSON::Pure::Parser, JSON::Pure::Generator]
</pre>
</li>
</ul>
<p>
If you want to enforce loading of a special variant, use
</p>
<pre>
require 'json/ext'
</pre>
<p>
to load the extension variant. Or use
</p>
<pre>
require 'json/pure'
</pre>
<p>
to use the pure variant.
</p>
<p>
You can choose to load a set of common additions to ruby core's objects if you
</p>
<pre>
require 'json/add/core'
</pre>
<p>
To get the best compatibility to rails' JSON implementation, you can
</p>
<pre>
require 'json/add/rails'
</pre>
<p>
Both of the additions attempt to require 'json' (like above) first, if it has not been required yet.
</p>
<h2>Author</h2>
Florian Frank <<a href="mailto:flori@ping.de">flori@ping.de</a>>
<h2>License</h2>
<p>
This is software is distributed under the same license as Ruby itself. See <a
href="http://www.ruby-lang.org/en/LICENSE.txt">http://www.ruby-lang.org/en/LICENSE.txt</a>.
</p>
</div>
<p class="valid">
<a href="http://validator.w3.org/check?uri=referer"><img
src="http://www.w3.org/Icons/valid-xhtml10"
alt="Valid XHTML 1.0 Transitional" height="31" width="88" /></a>
</p>
</body>
</html>
|
