jyson

h1. Options for controlling the jyson decoding process.

{{toc}}

h2. Default mode is strict compliance.

If you use jyson in it's default mode, which is *strict* mode, then parsing will be performed strictly according to the original "JSON":http://json.org specification. If an error is found, a *JSONDecodeError* exception is raised, giving the location of the offending construct in the document, as described on the [[JysonErrorReporting|jyson error reporting]] page.

For a discussion of compliance with "RFC 4627":http://www.ietf.org/rfc/rfc4627.txt?number=4627 , see the [[JysonDifferences|jyson comparison]] page.

h2. Why have options?

One nice feature of JSON is that it's syntax is valid in more than one language. As well being valid "javascript":http://en.wikipedia.org/wiki/JavaScript (and thus also "ECMAScript":http://en.wikipedia.org/wiki/ECMAScript ) , JSON documents are also valid "python":http://python.org .

Python permits the user to represent data in different ways. For example, the integer constant *42* could be represented in hexadecimal as *0x2a*, an also as the octal constant *052*. When representing characters in strings, the letter *a* can be represented as *\x61* (hexadecimal escape), or as *\u0061* (unicode escape). This capability allows the user to directly bypass the character encodings of their terminals and viewing programs, and represent unambiguously what they mean.

Another important issue is that of "dangling commas":http://mail.python.org/pipermail/web-sig/2008-April/003385.html in JSON documents. It is often the case that JSON documents are written by hand (when they are template documents, for example), and contain hard to spot mistakes. It is "arguable whether JSON parsers should accept such (strictly invalid) documents":http://mail.python.org/pipermail/web-sig/2008-April/003386.html : I wrote jyson to accept dangling commas, at user option.

These are the options you can use to control parsing with jyson.

h2. How to use these options

All decode options are passed to the *loads* method as keyword arguments with boolean values *True* or *false*., like this

<pre>

>>> from com.xhaus.jyson import JysonCodec as json

>>> json.loads("42.0", accept_any_primary_datum=True)

42.0

>>>

</pre>

Which instructs jyson to accept any top level datum in the document, as described below.

h2. Option: strict_mode

This option controls all of the options listed below. If you set this option to *true*, then jyson is set into strict JSON compliance mode, and all of the options below are set to *false*.

If you set this option to *false*., then all non-JSON-conformant options listed below will be set to *true*.

The default value for the *strict_mode* option is *true*.

h2. Option: accept_any_primary_datum

This option controls whether or not jyson will accept documents that contain something other than a JSON object or array as the top level object. For example, this document is strictly invalid

<pre>

42.0

</pre>

because the top level object is a number, which is a breach of "RFC 4627":http://www.ietf.org/rfc/rfc4627.txt?number=4627 . 

If you parse with this option set to *true*, then the above document would be accepted, as follows

<pre>

>>> from com.xhaus.jyson import JysonCodec as json

>>> json.loads("42.0")

com.xhaus.jyson.JSONDecodeError: JSON expressions must strictly be either objects or lists: position=4

>>> json.loads("42.0", accept_any_primary_datum=True)

42.0

>>>

</pre>

The default value for *accept_any_primary_datum* is *false*.

h2. Option: accept_dangling_commas

If this is option is *true*, then dangling commas in a JSON document will be accepted.

<pre>

>>> from com.xhaus.jyson import JysonCodec as json

>>> json.loads("[1,]")

com.xhaus.jyson.JSONDecodeError: Commas after last element of array not accepted: position=4

>>> json.loads("[1,]", accept_dangling_commas=True)

[1]

>>> json.loads('{"hello":"world",}')

com.xhaus.jyson.JSONDecodeError: Commas after last entry of object not accepted: position=18

>>> json.loads('{"hello":"world",}', accept_dangling_commas=True)

{'hello': 'world'}

>>>

</pre>

The default value for *accept_dangling_commas* is *false*.

h2. Option: accept_shell_style_comments  

This option controls whether jyson accepts shell style comments, as would be seen in a python program

<pre>

>>> from com.xhaus.jyson import JysonCodec as json

>>> json.loads("""# my json document

... [1]

... # end of my json document""")

com.xhaus.jyson.JSONDecodeError: Shell style comments are not accepted: position=1

>>> json.loads("""# my json document

... [1]

... # end of my json document""", accept_shell_style_comments=True)

[1]

>>>

</pre>

The default value for *accept_shell_style_comments* is *false*.

h2. Option: accept_single_quoted_strings

This option controls whether jyson accepts quotes delimited with single quote characters ('is this a string?'). Such string delimiters are valid in both python and javascript, but not in JSON.

<pre>

>>> from com.xhaus.jyson import JysonCodec as json

>>> json.loads("['Hello World!']")

com.xhaus.jyson.JSONDecodeError: Single quoted strings are not accepted: position=2

>>> json.loads("['Hello World!']", accept_single_quoted_strings=True)

['Hello World!']

>>>

</pre>

The default value for *accept_single_quoted_strings* is *false*.

h2. Option: accept_hex_char_escapes

This option controls whether jyson accepts hexadecimal character escapes, as are commonly used in python strings ("A" == "\x41")

<pre>

>>> from com.xhaus.jyson import JysonCodec as json

>>> json.loads('["This is a capital \\x41"]')

com.xhaus.jyson.JSONDecodeError: Hexadecimal escapes for characters are not accepted: position=22

>>> json.loads('["This is a capital \\x41"]', accept_hex_char_escapes=True)

['This is a capital A']

>>>

</pre>

The default value for *accept_hex_char_escapes* is *false*.

h2. Option: accept_hexadecimal_integers

This option ontrols whether jyson accepts hexadecimal integer constants, which are indicated with a leading *0x* and are case insensitive: e.g. 255=0xFF=0xff.

<pre>

>>> from com.xhaus.jyson import JysonCodec as json

>>> json.loads('[255,0xFF,0xff]')

com.xhaus.jyson.JSONDecodeError: Hexadecimal integers are not accepted.: position=9

>>> json.loads('[255,0xFF,0xff]', accept_hexadecimal_integers=True)

[255, 255, 255]

>>>

</pre>

The default value for *accept_hexadecimal_integers* is *false*.

h2. Option: accept_octal_integers

This option controls whether jyson accepts octal integer constants, which are indicated with a leading *0*: e.g. 0100=64=0x40.

<pre>

>>> from com.xhaus.jyson import JysonCodec as json

>>> json.loads('[0100,64]')

com.xhaus.jyson.JSONDecodeError: Octal integers are not accepted.:position=5

>>> json.loads('[0100,64]', accept_octal_integers=True)

[64, 64]

>>>

</pre>

The default value for *accept_octal_integers* is *false*.

h2. Option: accept_junk_after_data

This option controls whether jyson accepts extraneous data after the primary object

<pre>

>>> json.loads('{"an": "object"} ["and some more stuff"]')

com.xhaus.jyson.JSONDecodeError: Only whitespace is permitted after the primary datum: not '[': position=18

>>> json.loads('{"an": "object"} ["and some more stuff"]', accept_junk_after_data=True)

{'an': 'object'}

>>>

</pre>

The default value for *accept_junk_after_data* is *false*.