forked from bestiejs/json3
-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
137 lines (134 loc) · 13.3 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
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>JSON 3</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="page/style.css" media="screen">
</head>
<body>
<ul id="navigation">
<li><a href="#section_1">JSON 3</a></li>
<li><a href="#section_1.1">About</a></li>
<li><a href="#section_2">Usage</a></li>
<li><a href="#section_3">Compatibility</a></li>
<li><a href="#section_4">Contribute</a></li>
</ul>
<div id="content">
<h1 id="json-3-a-name-section_1-a-">JSON 3<a name="section_1"></a></h1>
<p><img src="https://bestiejs.github.io/json3/page/logo.png" alt="JSON 3 Logo" class="logo"></p>
<p><a href="https://travis-ci.org/bestiejs/json3" class="travis-ci"><img src="https://api.travis-ci.org/bestiejs/json3.png?branch=gh-pages" alt="Build Status"></a></p>
<p><strong>JSON 3</strong> is a JSON polyfill for older JavaScript platforms. The current version is <strong>3.3.2</strong>.</p>
<ul>
<li><a href="http://cdnjs.cloudflare.com/ajax/libs/json3/3.3.2/json3.js">Development Version</a> <em>(43 KB; uncompressed with comments)</em></li>
<li><a href="http://cdnjs.cloudflare.com/ajax/libs/json3/3.3.2/json3.min.js">Production Version</a> <em>(3.5 KB; compressed and <code>gzip</code>-ped)</em></li>
<li><a href="https://bestiejs.github.io/json3/changes.html">Change Log</a></li>
</ul>
<p>Special thanks to <a href="http://cdnjs.com/libraries/json3/">cdnjs</a> and <a href="http://www.jsdelivr.com/#!json3">jsDelivr</a> for hosting CDN copies of JSON 3.</p>
<h2 id="call-for-maintainers">Call for Maintainers</h2>
<p class="banner">If you’d like to maintain JSON 3, please reply to the <a href="https://github.com/bestiejs/json3/issues/90">GitHub issue</a>.</p>
<h2 id="about-a-name-section_1-1-a-">About<a name="section_1.1"></a></h2>
<p><a href="http://json.org/">JSON</a> is a language-independent data interchange format based on a loose subset of the JavaScript grammar. Originally popularized by <a href="http://www.crockford.com/">Douglas Crockford</a>, the format was standardized in the <a href="http://es5.github.io/">fifth edition</a> of the ECMAScript specification. The 5.1 edition, ratified in June 2011, incorporates several modifications to the grammar pertaining to the serialization of dates.</p>
<p>JSON 3 exposes two functions: <code>stringify()</code> for <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/JSON/stringify">serializing</a> a JavaScript value to JSON, and <code>parse()</code> for <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/JSON/parse">producing</a> a JavaScript value from a JSON source string. The JSON 3 parser uses recursive descent instead of <code>eval</code> and regular expressions, which makes it slower on older platforms compared to <a href="http://json.org/js">JSON 2</a>. The functions behave exactly as described in the ECMAScript spec, <strong>except</strong> for the date serialization discrepancy noted below.</p>
<p>The project is <a href="http://git.io/json3">hosted on GitHub</a>, along with the <a href="http://bestiejs.github.io/json3/test/test_browser.html">unit tests</a>. It is part of the <a href="https://github.com/bestiejs">BestieJS</a> family, a collection of best-in-class JavaScript libraries that promote cross-platform support, specification precedents, unit testing, and plenty of documentation.</p>
<h2 id="date-serialization">Date Serialization</h2>
<p><strong>JSON 3 deviates from the specification in one important way</strong>: it does not define <code>Date#toISOString()</code> or <code>Date#toJSON()</code>. This preserves CommonJS compatibility and avoids polluting native prototypes. Instead, date serialization is performed internally by the <code>stringify()</code> implementation: if a date object does not define a custom <code>toJSON()</code> method, it is serialized as a <a href="http://es5.github.com/#x15.9.1.15">simplified ISO 8601 date-time string</a>.</p>
<p><strong>Several native <code>Date#toJSON()</code> implementations produce date time strings that do <em>not</em> conform to the grammar outlined in the spec</strong>. In these environments, JSON 3 will override the native <code>stringify()</code> implementation. There is an <a href="https://github.com/bestiejs/json3/issues/73">issue</a> on file to make these tests less strict.</p>
<p>Portions of the date serialization code are adapted from the <a href="https://github.com/Yaffle/date-shim"><code>date-shim</code></a> project.</p>
<h1 id="usage-a-name-section_2-a-">Usage<a name="section_2"></a></h1>
<h2 id="web-browsers">Web Browsers</h2>
<pre><code><span class="hljs-tag"><<span class="hljs-title">script</span> <span class="hljs-attribute">src</span>=<span class="hljs-value">"//cdnjs.cloudflare.com/ajax/libs/json3/3.3.2/json3.min.js"</span>></span><span class="javascript"></span><span class="hljs-tag"></<span class="hljs-title">script</span>></span>
<span class="hljs-tag"><<span class="hljs-title">script</span>></span><span class="javascript">
<span class="hljs-built_in">JSON</span>.stringify({<span class="hljs-string">"Hello"</span>: <span class="hljs-number">123</span>});
<span class="hljs-comment">// => '{"Hello":123}'</span>
<span class="hljs-built_in">JSON</span>.parse(<span class="hljs-string">"[[1, 2, 3], 1, 2, 3, 4]"</span>, <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-params">(key, value)</span> </span>{
<span class="hljs-keyword">if</span> (<span class="hljs-keyword">typeof</span> value == <span class="hljs-string">"number"</span>) {
value = value % <span class="hljs-number">2</span> ? <span class="hljs-string">"Odd"</span> : <span class="hljs-string">"Even"</span>;
}
<span class="hljs-keyword">return</span> value;
});
<span class="hljs-comment">// => [["Odd", "Even", "Odd"], "Odd", "Even", "Odd", "Even"]</span>
</span><span class="hljs-tag"></<span class="hljs-title">script</span>></span>
</code></pre><p><strong>When used in a web browser</strong>, JSON 3 exposes an additional <code>JSON3</code> object containing the <code>noConflict()</code> and <code>runInContext()</code> functions, as well as aliases to the <code>stringify()</code> and <code>parse()</code> functions.</p>
<h3 id="-noconflict-and-runincontext-"><code>noConflict</code> and <code>runInContext</code></h3>
<ul>
<li><code>JSON3.noConflict()</code> restores the original value of the global <code>JSON</code> object and returns a reference to the <code>JSON3</code> object.</li>
<li><code>JSON3.runInContext([context, exports])</code> initializes JSON 3 using the given <code>context</code> object (e.g., <code>window</code>, <code>global</code>, etc.), or the global object if omitted. If an <code>exports</code> object is specified, the <code>stringify()</code>, <code>parse()</code>, and <code>runInContext()</code> functions will be attached to it instead of a new object.</li>
</ul>
<h3 id="asynchronous-module-loaders">Asynchronous Module Loaders</h3>
<p>JSON 3 is defined as an <a href="https://github.com/amdjs/amdjs-api/wiki/AMD#define-function-">anonymous module</a> for compatibility with <a href="http://requirejs.org/">RequireJS</a>, <a href="https://github.com/cujojs/curl"><code>curl.js</code></a>, and other asynchronous module loaders.</p>
<pre><code><span class="hljs-tag"><<span class="hljs-title">script</span> <span class="hljs-attribute">src</span>=<span class="hljs-value">"//cdnjs.cloudflare.com/ajax/libs/require.js/2.1.10/require.js"</span>></span><span class="javascript"></span><span class="hljs-tag"></<span class="hljs-title">script</span>></span>
<span class="hljs-tag"><<span class="hljs-title">script</span>></span><span class="javascript">
<span class="hljs-built_in">require</span>({
<span class="hljs-string">"paths"</span>: {
<span class="hljs-string">"json3"</span>: <span class="hljs-string">"./path/to/json3"</span>
}
}, [<span class="hljs-string">"json3"</span>], <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-params">(JSON)</span> </span>{
<span class="hljs-built_in">JSON</span>.parse(<span class="hljs-string">"[1, 2, 3]"</span>);
<span class="hljs-comment">// => [1, 2, 3]</span>
});
</span><span class="hljs-tag"></<span class="hljs-title">script</span>></span>
</code></pre><p>To avoid issues with third-party scripts, <strong>JSON 3 is exported to the global scope even when used with a module loader</strong>. If this behavior is undesired, <code>JSON3.noConflict()</code> can be used to restore the global <code>JSON</code> object to its original value.</p>
<p><strong>Note:</strong> If you intend to use JSON3 alongside another module, <strong>please do not simply concatenate these modules together</strong>, as that would cause multiple <code>define</code> calls in one script, resulting in errors in AMD loaders. The <code>r.js</code> build optimizer can be used instead if you need a single compressed file for production.</p>
<h2 id="commonjs-environments">CommonJS Environments</h2>
<pre><code>var JSO<span class="hljs-label">N3</span> = require<span class="hljs-comment">("./path/to/json3")</span>;
JSO<span class="hljs-label">N3</span>.parse<span class="hljs-comment">("[1, 2, 3]")</span>;
<span class="hljs-comment">// => [1, 2, 3]</span>
</code></pre><h2 id="javascript-engines">JavaScript Engines</h2>
<pre><code>load(<span class="hljs-string">"path/to/json3.js"</span>);
<span class="hljs-constant">JSON.</span>stringify({<span class="hljs-string">"Hello"</span><span class="hljs-symbol">:</span> <span class="hljs-number">123</span>, <span class="hljs-string">"Good-bye"</span><span class="hljs-symbol">:</span> <span class="hljs-number">456</span>}, [<span class="hljs-string">"Hello"</span>], <span class="hljs-string">"\t"</span>);
<span class="hljs-regexp">//</span> => <span class="hljs-string">'{\n\t"Hello": 123\n}'</span>
</code></pre><h1 id="compatibility-a-name-section_3-a-">Compatibility<a name="section_3"></a></h1>
<p>JSON 3 has been <strong>tested</strong> with the following web browsers, CommonJS environments, and JavaScript engines.</p>
<h2 id="web-browsers">Web Browsers</h2>
<ul>
<li>Windows <a href="http://windows.microsoft.com/en-us/internet-explorer/download-ie">Internet Explorer</a>, version 6.0 and higher</li>
<li>Google <a href="http://www.google.com/chrome">Chrome</a>, version 19.0 and higher</li>
<li>Mozilla <a href="https://www.mozilla.org/en-US/firefox/new/">Firefox</a>, version 2.0 and higher</li>
<li>Apple <a href="http://www.apple.com/safari/">Safari</a>, version 3.0 and higher</li>
<li><a href="http://www.opera.com/">Opera</a> 8.54 and higher</li>
<li><a href="http://www.seamonkey-project.org/">SeaMonkey</a> 1.0 and higher</li>
</ul>
<h2 id="commonjs-environments">CommonJS Environments</h2>
<ul>
<li><a href="http://nodejs.org/">Node</a> 0.6.21 and higher</li>
<li><a href="https://iojs.org/">io.js</a> 1.0.3 and higher</li>
<li><a href="http://ringojs.org/">RingoJS</a> 0.9 and higher</li>
<li><a href="https://github.com/280north/narwhal">Narwhal</a> 0.3.2</li>
</ul>
<h2 id="javascript-engines">JavaScript Engines</h2>
<ul>
<li>Mozilla <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Projects/Rhino">Rhino</a> 1.7R3 and higher</li>
<li>WebKit <a href="https://trac.webkit.org/wiki/JSC">JSC</a></li>
<li>Google <a href="http://code.google.com/p/v8/">V8</a></li>
</ul>
<h2 id="known-incompatibilities">Known Incompatibilities</h2>
<ul>
<li>Attempting to serialize the <code>arguments</code> object may produce inconsistent results across environments due to specification version differences. As a workaround, please convert the <code>arguments</code> object to an array first: <code>JSON.stringify([].slice.call(arguments, 0))</code>.</li>
</ul>
<h2 id="required-native-methods">Required Native Methods</h2>
<p>JSON 3 assumes that the following methods exist and function as described in the ECMAScript specification:</p>
<ul>
<li>The <code>Number</code>, <code>String</code>, <code>Array</code>, <code>Object</code>, <code>Date</code>, <code>SyntaxError</code>, and <code>TypeError</code> constructors.</li>
<li><code>String.fromCharCode</code></li>
<li><code>Object#toString</code></li>
<li><code>Object#hasOwnProperty</code></li>
<li><code>Function#call</code></li>
<li><code>Math.floor</code></li>
<li><code>Number#toString</code></li>
<li><code>Date#valueOf</code></li>
<li><code>String.prototype</code>: <code>indexOf</code>, <code>charCodeAt</code>, <code>charAt</code>, <code>slice</code>, <code>replace</code>.</li>
<li><code>Array.prototype</code>: <code>push</code>, <code>pop</code>, <code>join</code>.</li>
</ul>
<h1 id="contribute-a-name-section_4-a-">Contribute<a name="section_4"></a></h1>
<p>Check out a working copy of the JSON 3 source code with <a href="http://git-scm.com/">Git</a>:</p>
<pre><code>$ git clone gi<span class="hljs-variable">t:</span>//github.<span class="hljs-keyword">com</span>/bestiejs/json3.git
$ <span class="hljs-keyword">cd</span> json3
</code></pre><p>We ♥ bug reports, suggestions, questions, and pull requests! Please see our <a href="https://bestiejs.github.io/json3/contribute.html">contribution guidelines</a> if you’d like to contribute.</p>
<p>JSON 3 is released under the <a href="http://kit.mit-license.org/">MIT License</a>.</p>
</div>
<div id="footer">
<p>© 2012-2015 <a href="http://kitcambridge.be/">Kit Cambridge</a>, <a href="https://d10.github.io/">Benjamin Tan</a>.</p>
</div>
</body>
</html>