/usr/share/doc/racket/json/index.html is in racket-doc 6.1-4.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html><head><meta http-equiv="content-type" content="text/html; charset=utf-8"/><title>JSON</title><link rel="stylesheet" type="text/css" href="../scribble.css" title="default"/><link rel="stylesheet" type="text/css" href="../racket.css" title="default"/><link rel="stylesheet" type="text/css" href="../manual-style.css" title="default"/><link rel="stylesheet" type="text/css" href="../manual-racket.css" title="default"/><link rel="stylesheet" type="text/css" href="../manual-racket.css" title="default"/><link rel="stylesheet" type="text/css" href="../doc-site.css" title="default"/><script type="text/javascript" src="../scribble-common.js"></script><script type="text/javascript" src="../manual-racket.js"></script><script type="text/javascript" src="../manual-racket.js"></script><script type="text/javascript" src="../doc-site.js"></script><script type="text/javascript" src="../local-redirect/local-redirect.js"></script><script type="text/javascript" src="../local-redirect/local-user-redirect.js"></script><!--[if IE 6]><style type="text/css">.SIEHidden { overflow: hidden; }</style><![endif]--></head><body id="doc-racket-lang-org"><div class="tocset"><div class="tocview"><div class="tocviewlist tocviewlisttopspace"><div class="tocviewtitle"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,"tocview_0");">►</a></td><td></td><td><a href="" class="tocviewselflink" data-pltdoc="x">JSON</a></td></tr></table></div><div class="tocviewsublistonly" style="display: none;" id="tocview_0"><table cellspacing="0" cellpadding="0"><tr><td align="right">1 </td><td><a href="#%28part._.J.S-.Expressions%29" class="tocviewlink" data-pltdoc="x">JS-<wbr></wbr>Expressions</a></td></tr><tr><td align="right">2 </td><td><a href="#%28part._.Generating_.J.S.O.N_.Text_from_.J.S-.Expressions%29" class="tocviewlink" data-pltdoc="x">Generating JSON Text from JS-<wbr></wbr>Expressions</a></td></tr><tr><td align="right">3 </td><td><a href="#%28part._.Parsing_.J.S.O.N_.Text_into_.J.S-.Expressions%29" class="tocviewlink" data-pltdoc="x">Parsing JSON Text into JS-<wbr></wbr>Expressions</a></td></tr><tr><td align="right">4 </td><td><a href="#%28part._.A_.Word_.About_.Design%29" class="tocviewlink" data-pltdoc="x">A Word About Design</a></td></tr></table></div></div></div><div class="tocsub"><table class="tocsublist" cellspacing="0"><tr><td><span class="tocsublinknumber"></span><a href="#%28part._top%29" class="tocsubseclink" data-pltdoc="x">JSON</a></td></tr><tr><td><span class="tocsublinknumber">1<tt> </tt></span><a href="#%28part._.J.S-.Expressions%29" class="tocsubseclink" data-pltdoc="x">JS-<wbr></wbr>Expressions</a></td></tr><tr><td><a href="#%28def._%28%28lib._json%2Fmain..rkt%29._jsexpr~3f%29%29" class="tocsubnonseclink" data-pltdoc="x"><span class="RktSym"><span class="RktValLink">jsexpr?</span></span></a></td></tr><tr><td><a href="#%28def._%28%28lib._json%2Fmain..rkt%29._json-null%29%29" class="tocsubnonseclink" data-pltdoc="x"><span class="RktSym"><span class="RktValLink">json-<wbr></wbr>null</span></span></a></td></tr><tr><td><span class="tocsublinknumber">2<tt> </tt></span><a href="#%28part._.Generating_.J.S.O.N_.Text_from_.J.S-.Expressions%29" class="tocsubseclink" data-pltdoc="x">Generating JSON Text from JS-<wbr></wbr>Expressions</a></td></tr><tr><td><a href="#%28def._%28%28lib._json%2Fmain..rkt%29._write-json%29%29" class="tocsubnonseclink" data-pltdoc="x"><span class="RktSym"><span class="RktValLink">write-<wbr></wbr>json</span></span></a></td></tr><tr><td><a href="#%28def._%28%28lib._json%2Fmain..rkt%29._jsexpr-~3estring%29%29" class="tocsubnonseclink" data-pltdoc="x"><span class="RktSym"><span class="RktValLink">jsexpr-<wbr></wbr>>string</span></span></a></td></tr><tr><td><a href="#%28def._%28%28lib._json%2Fmain..rkt%29._jsexpr-~3ebytes%29%29" class="tocsubnonseclink" data-pltdoc="x"><span class="RktSym"><span class="RktValLink">jsexpr-<wbr></wbr>>bytes</span></span></a></td></tr><tr><td><span class="tocsublinknumber">3<tt> </tt></span><a href="#%28part._.Parsing_.J.S.O.N_.Text_into_.J.S-.Expressions%29" class="tocsubseclink" data-pltdoc="x">Parsing JSON Text into JS-<wbr></wbr>Expressions</a></td></tr><tr><td><a href="#%28def._%28%28lib._json%2Fmain..rkt%29._read-json%29%29" class="tocsubnonseclink" data-pltdoc="x"><span class="RktSym"><span class="RktValLink">read-<wbr></wbr>json</span></span></a></td></tr><tr><td><a href="#%28def._%28%28lib._json%2Fmain..rkt%29._string-~3ejsexpr%29%29" class="tocsubnonseclink" data-pltdoc="x"><span class="RktSym"><span class="RktValLink">string-<wbr></wbr>>jsexpr</span></span></a></td></tr><tr><td><a href="#%28def._%28%28lib._json%2Fmain..rkt%29._bytes-~3ejsexpr%29%29" class="tocsubnonseclink" data-pltdoc="x"><span class="RktSym"><span class="RktValLink">bytes-<wbr></wbr>>jsexpr</span></span></a></td></tr><tr><td><span class="tocsublinknumber">4<tt> </tt></span><a href="#%28part._.A_.Word_.About_.Design%29" class="tocsubseclink" data-pltdoc="x">A Word About Design</a></td></tr><tr><td><span class="tocsublinknumber">4.1<tt> </tt></span><a href="#%28part._.The_.J.S-.Expression_.Data_.Type%29" class="tocsubseclink" data-pltdoc="x">The JS-<wbr></wbr>Expression Data Type</a></td></tr><tr><td><span class="tocsublinknumber">4.2<tt> </tt></span><a href="#%28part._.Naming_.Conventions%29" class="tocsubseclink" data-pltdoc="x">Naming Conventions</a></td></tr></table></div></div><div class="maincolumn"><div class="main"><div class="versionbox"><span class="version">6.1</span></div><div class="navsettop"><span class="navleft"><form class="searchform"><input class="searchbox" style="color: #888;" type="text" value="...search manuals..." title="Enter a search string to search the manuals" onkeypress="return DoSearchKey(event, this, "6.1", "../");" onfocus="this.style.color="black"; this.style.textAlign="left"; if (this.value == "...search manuals...") this.value="";" onblur="if (this.value.match(/^ *$/)) { this.style.color="#888"; this.style.textAlign="center"; this.value="...search manuals..."; }"/></form> <a href="../index.html" title="up to the documentation top" data-pltdoc="x" onclick="return GotoPLTRoot("6.1");">top</a></span><span class="navright"> <span class="nonavigation">← prev</span> <a href="../index.html" title="up to the documentation top" data-pltdoc="x" onclick="return GotoPLTRoot("6.1");">up</a> <span class="nonavigation">next →</span></span> </div><h2 x-source-module="(lib "json/json.scrbl")" x-part-tag=""top""><a name="(part._top)"></a><a name="(part._.J.S.O.N)"></a><a name="(mod-path._json)"></a>JSON</h2><div class="SAuthorListBox"><span class="SAuthorList"><p class="author">Eli Barzilay<br/>and Dave Herman</p></span></div><p><table cellspacing="0" cellpadding="0" class="defmodule"><tr><td align="left"><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=6.1" class="RktStxLink Sq" data-pltdoc="x">require</a></span><span class="stt"> </span><a href="" class="RktModLink" data-pltdoc="x"><span class="RktSym">json</span></a><span class="RktPn">)</span></td><td align="right"><span class="RpackageSpec"><span class="Smaller"> package:</span> <span class="stt">base</span></span></td></tr></table></p><p>This library provides utilities for parsing and producing data in the
JSON data exchange format to/from Racket values. See the <a href="http://json.org">JSON web site</a> and
the <a href="http://www.ietf.org/rfc/rfc4627.txt">JSON RFC</a> for more information about JSON.</p><h3 x-source-module="(lib "json/json.scrbl")" x-part-tag=""JS-Expressions"">1<tt> </tt><a name="(part._.J.S-.Expressions)"></a>JS-Expressions</h3><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._json/main..rkt)._jsexpr~3f))"></a><span title="Provided from: json | Package: base"><span class="RktSym"><a href="#%28def._%28%28lib._json%2Fmain..rkt%29._jsexpr~3f%29%29" class="RktValDef RktValLink" data-pltdoc="x">jsexpr?</a></span></span><span class="hspace"> </span><span class="RktVar">x</span><span class="hspace"> </span>[<span class="RktPn">#:null</span><span class="hspace"> </span><span class="RktVar">jsnull</span>]<span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=booleans.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._boolean%7E3f%2529%2529&version=6.1" class="RktValLink Sq" data-pltdoc="x">boolean?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">x</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym">any</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">jsnull</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym">any?</span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="#%28def._%28%28lib._json%2Fmain..rkt%29._json-null%29%29" class="RktValLink" data-pltdoc="x">json-null</a></span><span class="RktPn">)</span></td></tr></table></blockquote></div><div class="SIntrapara">Performs a deep check to determine whether <span class="RktVar">x</span> is a <a href="#%28tech._jsexpr%29" class="techoutside" data-pltdoc="x"><span class="techinside">jsexpr</span></a>.</div></p><p>This library defines a subset of Racket values that can be represented
as JSON strings, and this predicates checks for such values. A
<a name="(tech._js._expression)"></a><span style="font-style: italic">JS-Expression</span>, or <a name="(tech._jsexpr)"></a><span style="font-style: italic">jsexpr</span>, is one of:</p><ul><li><p>the value of <span class="RktVar">jsnull</span>, <span class="RktVal">'</span><span class="RktVal">null</span> by default</p></li><li><p><span class="RktSym"><a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=booleans.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._boolean%7E3f%2529%2529&version=6.1" class="RktValLink Sq" data-pltdoc="x">boolean?</a></span></p></li><li><p><span class="RktSym"><a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=strings.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._string%7E3f%2529%2529&version=6.1" class="RktValLink Sq" data-pltdoc="x">string?</a></span></p></li><li><p><span class="RktPn">(</span><span class="RktSym"><a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=if.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fletstx-scheme..rkt%2529._or%2529%2529&version=6.1" class="RktStxLink Sq" data-pltdoc="x">or</a></span><span class="stt"> </span><span class="RktSym"><a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=number-types.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._exact-integer%7E3f%2529%2529&version=6.1" class="RktValLink Sq" data-pltdoc="x">exact-integer?</a></span><span class="stt"> </span><span class="RktSym"><a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=number-types.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._inexact-real%7E3f%2529%2529&version=6.1" class="RktValLink Sq" data-pltdoc="x">inexact-real?</a></span><span class="RktPn">)</span></p></li><li><p><span class="RktPn">(</span><span class="RktSym">listof</span><span class="stt"> </span><span class="RktSym"><a href="#%28def._%28%28lib._json%2Fmain..rkt%29._jsexpr~3f%29%29" class="RktValLink" data-pltdoc="x">jsexpr?</a></span><span class="RktPn">)</span></p></li><li><p><span class="RktPn">(</span><span class="RktSym">hasheqof</span><span class="stt"> </span><span class="RktSym"><a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=symbols.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._symbol%7E3f%2529%2529&version=6.1" class="RktValLink Sq" data-pltdoc="x">symbol?</a></span><span class="stt"> </span><span class="RktSym"><a href="#%28def._%28%28lib._json%2Fmain..rkt%29._jsexpr~3f%29%29" class="RktValLink" data-pltdoc="x">jsexpr?</a></span><span class="RktPn">)</span></p></li></ul><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>parameter</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._json/main..rkt)._json-null))"></a><span title="Provided from: json | Package: base"><span class="RktSym"><a href="#%28def._%28%28lib._json%2Fmain..rkt%29._json-null%29%29" class="RktValDef RktValLink" data-pltdoc="x">json-null</a></span></span><span class="RktPn"></span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym">any?</span></p></blockquote></td></tr><tr><td><span class="RktPn">(</span><span title="Provided from: json | Package: base"><span class="RktSym"><a href="#%28def._%28%28lib._json%2Fmain..rkt%29._json-null%29%29" class="RktValDef RktValLink" data-pltdoc="x">json-null</a></span></span><span class="hspace"> </span><span class="RktVar">jsnull</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=void.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._void%7E3f%2529%2529&version=6.1" class="RktValLink Sq" data-pltdoc="x">void?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">jsnull</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym">any?</span></td></tr></table></blockquote></div><div class="SIntrapara">This parameter determines the default Racket value that corresponds to
a JSON “<span class="stt">null</span>”. By default, it is the <span class="RktVal">'</span><span class="RktVal">null</span> symbol.
In some cases a different value may better fit your needs, therefore
all functions in this library accept a <span class="RktPn">#:null</span> keyword
argument for the value that is used to represent a JSON “<span class="stt">null</span>”,
and this argument defaults to <span class="RktPn">(</span><span class="RktSym"><a href="#%28def._%28%28lib._json%2Fmain..rkt%29._json-null%29%29" class="RktValLink" data-pltdoc="x">json-null</a></span><span class="RktPn">)</span>.</div></p><h3 x-source-module="(lib "json/json.scrbl")" x-part-tag=""Generating_JSON_Text_from_JS-Expressions"">2<tt> </tt><a name="(part._.Generating_.J.S.O.N_.Text_from_.J.S-.Expressions)"></a>Generating JSON Text from JS-Expressions</h3><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><table cellspacing="0" cellpadding="0" class="prototype RForeground"><tr><td><span class="RktPn">(</span><a name="(def._((lib._json/main..rkt)._write-json))"></a><span title="Provided from: json | Package: base"><span class="RktSym"><a href="#%28def._%28%28lib._json%2Fmain..rkt%29._write-json%29%29" class="RktValDef RktValLink" data-pltdoc="x">write-json</a></span></span></td><td><span class="hspace"> </span></td><td><span class="RktVar">x</span></td><td><span class="hspace"> </span></td><td><span class="hspace"> </span></td><td><span class="hspace"> </span></td><td><span class="hspace"> </span></td></tr><tr><td><span class="hspace"> </span></td><td><span class="hspace"> </span>[</td><td><span class="RktVar">out</span></td><td><span class="hspace"> </span></td><td><span class="hspace"> </span></td><td><span class="hspace"> </span></td><td><span class="hspace"> </span></td></tr><tr><td><span class="hspace"> </span></td><td><span class="hspace"> </span></td><td><span class="RktPn">#:null</span><span class="hspace"> </span><span class="RktVar">jsnull</span></td><td><span class="hspace"> </span></td><td><span class="hspace"> </span></td><td><span class="hspace"> </span></td><td><span class="hspace"> </span></td></tr><tr><td><span class="hspace"> </span></td><td><span class="hspace"> </span></td><td><span class="RktPn">#:encode</span><span class="hspace"> </span><span class="RktVar">encode</span>]<span class="RktPn">)</span></td><td><span class="hspace"> </span></td><td>→</td><td><span class="hspace"> </span></td><td><span class="RktSym">any</span></td></tr></table></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">x</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="#%28def._%28%28lib._json%2Fmain..rkt%29._jsexpr~3f%29%29" class="RktValLink" data-pltdoc="x">jsexpr?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">out</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=port-ops.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._output-port%7E3f%2529%2529&version=6.1" class="RktValLink Sq" data-pltdoc="x">output-port?</a></span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=port-ops.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._current-output-port%2529%2529&version=6.1" class="RktValLink Sq" data-pltdoc="x">current-output-port</a></span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">jsnull</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym">any?</span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="#%28def._%28%28lib._json%2Fmain..rkt%29._json-null%29%29" class="RktValLink" data-pltdoc="x">json-null</a></span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">encode</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">or/c</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">control</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">all</span><span class="RktPn">)</span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">control</span></td></tr></table></blockquote></div><div class="SIntrapara">Writes the <span class="RktVar">x</span> <a href="#%28tech._jsexpr%29" class="techoutside" data-pltdoc="x"><span class="techinside">jsexpr</span></a>, encoded as JSON, to the
<span class="RktSym">outp</span> output port.</div></p><p>By default, only ASCII control characters are encoded as
“<span class="stt">\uHHHH</span>”. If <span class="RktVar">encode</span> is given as <span class="RktVal">'</span><span class="RktVal">all</span>, then
in addition to ASCII control characters, non-ASCII characters are
encoded as well. This can be useful if you need to transport the text
via channels that might not support UTF-8. Note that characters in
the range of <span class="stt">U+10000</span> and above are encoded as two <span class="stt">\uHHHH</span>
escapes, see Section 2.5 of the <a href="http://www.ietf.org/rfc/rfc4627.txt">JSON RFC</a>.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><table cellspacing="0" cellpadding="0" class="prototype RForeground"><tr><td><span class="RktPn">(</span><a name="(def._((lib._json/main..rkt)._jsexpr-~3estring))"></a><span title="Provided from: json | Package: base"><span class="RktSym"><a href="#%28def._%28%28lib._json%2Fmain..rkt%29._jsexpr-~3estring%29%29" class="RktValDef RktValLink" data-pltdoc="x">jsexpr->string</a></span></span></td><td><span class="hspace"> </span></td><td><span class="RktVar">x</span></td><td><span class="hspace"> </span></td><td><span class="hspace"> </span></td><td><span class="hspace"> </span></td><td><span class="hspace"> </span></td></tr><tr><td><span class="hspace"> </span></td><td><span class="hspace"> </span>[</td><td><span class="RktPn">#:null</span><span class="hspace"> </span><span class="RktVar">jsnull</span></td><td><span class="hspace"> </span></td><td><span class="hspace"> </span></td><td><span class="hspace"> </span></td><td><span class="hspace"> </span></td></tr><tr><td><span class="hspace"> </span></td><td><span class="hspace"> </span></td><td><span class="RktPn">#:encode</span><span class="hspace"> </span><span class="RktVar">encode</span>]<span class="RktPn">)</span></td><td><span class="hspace"> </span></td><td>→</td><td><span class="hspace"> </span></td><td><span class="RktSym"><a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=strings.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._string%7E3f%2529%2529&version=6.1" class="RktValLink Sq" data-pltdoc="x">string?</a></span></td></tr></table></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">x</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="#%28def._%28%28lib._json%2Fmain..rkt%29._jsexpr~3f%29%29" class="RktValLink" data-pltdoc="x">jsexpr?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">jsnull</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym">any?</span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="#%28def._%28%28lib._json%2Fmain..rkt%29._json-null%29%29" class="RktValLink" data-pltdoc="x">json-null</a></span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">encode</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">or/c</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">control</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">all</span><span class="RktPn">)</span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">control</span></td></tr></table></blockquote></div><div class="SIntrapara">Generates a JSON source string for the <a href="#%28tech._jsexpr%29" class="techoutside" data-pltdoc="x"><span class="techinside">jsexpr</span></a> <span class="RktVar">x</span>.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><table cellspacing="0" cellpadding="0" class="prototype RForeground"><tr><td><span class="RktPn">(</span><a name="(def._((lib._json/main..rkt)._jsexpr-~3ebytes))"></a><span title="Provided from: json | Package: base"><span class="RktSym"><a href="#%28def._%28%28lib._json%2Fmain..rkt%29._jsexpr-~3ebytes%29%29" class="RktValDef RktValLink" data-pltdoc="x">jsexpr->bytes</a></span></span></td><td><span class="hspace"> </span></td><td><span class="RktVar">x</span></td><td><span class="hspace"> </span></td><td><span class="hspace"> </span></td><td><span class="hspace"> </span></td><td><span class="hspace"> </span></td></tr><tr><td><span class="hspace"> </span></td><td><span class="hspace"> </span>[</td><td><span class="RktPn">#:null</span><span class="hspace"> </span><span class="RktVar">jsnull</span></td><td><span class="hspace"> </span></td><td><span class="hspace"> </span></td><td><span class="hspace"> </span></td><td><span class="hspace"> </span></td></tr><tr><td><span class="hspace"> </span></td><td><span class="hspace"> </span></td><td><span class="RktPn">#:encode</span><span class="hspace"> </span><span class="RktVar">encode</span>]<span class="RktPn">)</span></td><td><span class="hspace"> </span></td><td>→</td><td><span class="hspace"> </span></td><td><span class="RktSym"><a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=bytestrings.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._bytes%7E3f%2529%2529&version=6.1" class="RktValLink Sq" data-pltdoc="x">bytes?</a></span></td></tr></table></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">x</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="#%28def._%28%28lib._json%2Fmain..rkt%29._jsexpr~3f%29%29" class="RktValLink" data-pltdoc="x">jsexpr?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">jsnull</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym">any?</span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="#%28def._%28%28lib._json%2Fmain..rkt%29._json-null%29%29" class="RktValLink" data-pltdoc="x">json-null</a></span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">encode</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">or/c</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">control</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">all</span><span class="RktPn">)</span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">control</span></td></tr></table></blockquote></div><div class="SIntrapara">Generates a JSON source byte string for the <a href="#%28tech._jsexpr%29" class="techoutside" data-pltdoc="x"><span class="techinside">jsexpr</span></a> <span class="RktVar">x</span>.
(The byte string is encoded in UTF-8.)</div></p><h3 x-source-module="(lib "json/json.scrbl")" x-part-tag=""Parsing_JSON_Text_into_JS-Expressions"">3<tt> </tt><a name="(part._.Parsing_.J.S.O.N_.Text_into_.J.S-.Expressions)"></a>Parsing JSON Text into JS-Expressions</h3><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._json/main..rkt)._read-json))"></a><span title="Provided from: json | Package: base"><span class="RktSym"><a href="#%28def._%28%28lib._json%2Fmain..rkt%29._read-json%29%29" class="RktValDef RktValLink" data-pltdoc="x">read-json</a></span></span><span class="hspace"> </span>[<span class="RktVar">in</span><span class="hspace"> </span><span class="RktPn">#:null</span><span class="hspace"> </span><span class="RktVar">jsnull</span>]<span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">or/c</span><span class="hspace"> </span><span class="RktSym"><a href="#%28def._%28%28lib._json%2Fmain..rkt%29._jsexpr~3f%29%29" class="RktValLink" data-pltdoc="x">jsexpr?</a></span><span class="hspace"> </span><span class="RktSym"><a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=port-ops.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._eof-object%7E3f%2529%2529&version=6.1" class="RktValLink Sq" data-pltdoc="x">eof-object?</a></span><span class="RktPn">)</span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">in</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=port-ops.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._input-port%7E3f%2529%2529&version=6.1" class="RktValLink Sq" data-pltdoc="x">input-port?</a></span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=port-ops.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._current-input-port%2529%2529&version=6.1" class="RktValLink Sq" data-pltdoc="x">current-input-port</a></span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">jsnull</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym">any?</span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="#%28def._%28%28lib._json%2Fmain..rkt%29._json-null%29%29" class="RktValLink" data-pltdoc="x">json-null</a></span><span class="RktPn">)</span></td></tr></table></blockquote></div><div class="SIntrapara">Reads a <a href="#%28tech._jsexpr%29" class="techoutside" data-pltdoc="x"><span class="techinside">jsexpr</span></a> from a JSON-encoded input port <span class="RktVar">in</span> as a
Racket (immutable) value, or produces <span class="RktSym"><a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=port-ops.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._eof%2529%2529&version=6.1" class="RktValLink Sq" data-pltdoc="x">eof</a></span> if only whitespace
remains.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._json/main..rkt)._string-~3ejsexpr))"></a><span title="Provided from: json | Package: base"><span class="RktSym"><a href="#%28def._%28%28lib._json%2Fmain..rkt%29._string-~3ejsexpr%29%29" class="RktValDef RktValLink" data-pltdoc="x">string->jsexpr</a></span></span><span class="hspace"> </span><span class="RktVar">str</span><span class="hspace"> </span>[<span class="RktPn">#:null</span><span class="hspace"> </span><span class="RktVar">jsnull</span>]<span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="#%28def._%28%28lib._json%2Fmain..rkt%29._jsexpr~3f%29%29" class="RktValLink" data-pltdoc="x">jsexpr?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">str</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=strings.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._string%7E3f%2529%2529&version=6.1" class="RktValLink Sq" data-pltdoc="x">string?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">jsnull</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym">any?</span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="#%28def._%28%28lib._json%2Fmain..rkt%29._json-null%29%29" class="RktValLink" data-pltdoc="x">json-null</a></span><span class="RktPn">)</span></td></tr></table></blockquote></div><div class="SIntrapara">Parses the JSON string <span class="RktVar">str</span> as an immutable <a href="#%28tech._jsexpr%29" class="techoutside" data-pltdoc="x"><span class="techinside">jsexpr</span></a>.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._json/main..rkt)._bytes-~3ejsexpr))"></a><span title="Provided from: json | Package: base"><span class="RktSym"><a href="#%28def._%28%28lib._json%2Fmain..rkt%29._bytes-~3ejsexpr%29%29" class="RktValDef RktValLink" data-pltdoc="x">bytes->jsexpr</a></span></span><span class="hspace"> </span><span class="RktVar">str</span><span class="hspace"> </span>[<span class="RktPn">#:null</span><span class="hspace"> </span><span class="RktVar">jsnull</span>]<span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="#%28def._%28%28lib._json%2Fmain..rkt%29._jsexpr~3f%29%29" class="RktValLink" data-pltdoc="x">jsexpr?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">str</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=bytestrings.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._bytes%7E3f%2529%2529&version=6.1" class="RktValLink Sq" data-pltdoc="x">bytes?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">jsnull</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym">any?</span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="#%28def._%28%28lib._json%2Fmain..rkt%29._json-null%29%29" class="RktValLink" data-pltdoc="x">json-null</a></span><span class="RktPn">)</span></td></tr></table></blockquote></div><div class="SIntrapara">Parses the JSON bytes string <span class="RktVar">str</span> as an immutable <a href="#%28tech._jsexpr%29" class="techoutside" data-pltdoc="x"><span class="techinside">jsexpr</span></a>.</div></p><h3 x-source-module="(lib "json/json.scrbl")" x-part-tag=""A_Word_About_Design"">4<tt> </tt><a name="(part._.A_.Word_.About_.Design)"></a>A Word About Design</h3><h4 x-source-module="(lib "json/json.scrbl")" x-part-tag=""The_JS-Expression_Data_Type"">4.1<tt> </tt><a name="(part._.The_.J.S-.Expression_.Data_.Type)"></a>The JS-Expression Data Type</h4><p>JSON syntactically distinguishes “<span class="stt">null</span>”, array literals, and
object literals, and therefore there is a question of what Racket value
should represent a JSON “<span class="stt">null</span>”. This library uses the Racket
<span class="RktVal">'</span><span class="RktVal">null</span> symbol by default. Note that this is unambiguous, since
Racket symbols are used only as object keys, which are required to be
strings in JSON.</p><p>Several other options have been used by various libaries. For example,
Dave Herman’s PLaneT library (which has been the basis for this library)
uses the <span class="RktVal">#\nul</span> character, other libraries for Racket and other
Lisps use <span class="RktPn">(</span><span class="RktSym"><a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=void.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._void%2529%2529&version=6.1" class="RktValLink Sq" data-pltdoc="x">void</a></span><span class="RktPn">)</span>, <span class="stt">NIL</span> (some use it also for JSON
“<span class="stt">false</span>”), and more. The approach taken by this library is to use
a keyword argument for all functions, with a parameter that determines
its default, making it easy to use any value that fits your needs.</p><p>The <a href="http://www.ietf.org/rfc/rfc4627.txt">JSON RFC</a> only states that object literal expressions “SHOULD” contain
unique keys, but does not proscribe them entirely. Looking at existing
practice, it appears that popular JSON libraries parse object literals
with duplicate keys by simply picking one of the key-value pairs and
discarding the others with the same key. This behavior is naturally
paralleled by Racket hash tables, making them a natural analog.</p><p>Finally, the <a href="http://www.ietf.org/rfc/rfc4627.txt">JSON RFC</a> is almost completely silent about the order of
key-value pairs. While the RFC only specifies the syntax of JSON, which
of course always must represent object literals as an ordered
collection, the introduction states:</p><blockquote><p>An object is an unordered collection of zero or more name/value pairs,
where a name is a string and a value is a string, number, boolean,
null, object, or array.</p></blockquote><p>In practice, JSON libraries discard the order of object literals in
parsed JSON text and make no guarantees about the order of generated
object literals, usually using a hash table of some flavor as a natural
choice. We therefore use do so as well.</p><h4 x-source-module="(lib "json/json.scrbl")" x-part-tag=""Naming_Conventions"">4.2<tt> </tt><a name="(part._.Naming_.Conventions)"></a>Naming Conventions</h4><p>Some names in this library use “jsexpr” and some use “json”. The
rationale that the first is used for our representation, and the second
is used as information that is received from or sent to the outside
world.</p><div class="navsetbottom"><span class="navleft"><form class="searchform"><input class="searchbox" style="color: #888;" type="text" value="...search manuals..." title="Enter a search string to search the manuals" onkeypress="return DoSearchKey(event, this, "6.1", "../");" onfocus="this.style.color="black"; this.style.textAlign="left"; if (this.value == "...search manuals...") this.value="";" onblur="if (this.value.match(/^ *$/)) { this.style.color="#888"; this.style.textAlign="center"; this.value="...search manuals..."; }"/></form> <a href="../index.html" title="up to the documentation top" data-pltdoc="x" onclick="return GotoPLTRoot("6.1");">top</a></span><span class="navright"> <span class="nonavigation">← prev</span> <a href="../index.html" title="up to the documentation top" data-pltdoc="x" onclick="return GotoPLTRoot("6.1");">up</a> <span class="nonavigation">next →</span></span> </div></div></div><div id="contextindicator"> </div></body></html>
|