umgeher/jsx
0
Fork 0
Code Issues Pull requests Activity

minor updates to edocs

Browse source
This commit is contained in:
alisdair sullivan 2010-08-20 18:25:06 -07:00
parent 6ff74e6d59
commit 24af6c36cb
2 changed files with 96 additions and 89 deletions
Download patch file Download diff file Expand all files Collapse all files

4
doc/overview.edoc
View file

@ -27,7 +27,7 @@ erlang has a number of json libraries, some of them very good, but all of them t
jsx is not an end to end json parser. jsx takes a json document and produces a generator that returns a jsx event and a new generator. a jsx event is an atom or tuple that represents a json structural element (like the start or end of an object or array) or a json value (like a string or a number). this provides a simple, easy to consume, iterative api that makes it easy to produce arbitrarily complex representations of the json document jsx is not an end to end json parser. jsx takes a json document and produces a generator that returns a jsx event and a new generator. a jsx event is an atom or tuple that represents a json structural element (like the start or end of an object or array) or a json value (like a string or a number). this provides a simple, easy to consume, iterative api that makes it easy to produce arbitrarily complex representations of the json document
the representation of jsx events was chosen for pragmatic reasons. strings, integers and floats are encoded in json as strings of unicode characters and many erlang functions operate on lists so returning them as lists of unicode codepoints is both efficient and convenient. structural elements are converted to descriptive atoms for ease of matching and clarity. json literals (`true`, `false` and `null`) are encoded as atoms for ease of matching and wrapped in a tagged tuple to differentiate them from structural elements the representation of jsx events was chosen for pragmatic reasons. strings, integers and floats are encoded in json as strings of unicode characters and many erlang functions operate on lists so returning them as lists of unicode codepoints is both efficient and convenient. structural elements are converted to descriptive atoms for ease of matching and clarity. json literals (`true', `false' and `null') are encoded as atoms for ease of matching and wrapped in a tagged tuple to differentiate them from structural elements
in cases where an incomplete json document is supplied to the parser, upon reaching the end of the document the generator may also return a new function that allows another chunk of the json document to be parsed as if parsing were never interrupted. this is useful for parsing very large json documents (to avoid holding the entire document in memory) or for parsing as data is made available (like over a network or from storage) in cases where an incomplete json document is supplied to the parser, upon reaching the end of the document the generator may also return a new function that allows another chunk of the json document to be parsed as if parsing were never interrupted. this is useful for parsing very large json documents (to avoid holding the entire document in memory) or for parsing as data is made available (like over a network or from storage)
@ -53,7 +53,7 @@ jsx is wicked fast. sort of. it's as fast as possible without sacrificing a usea
| {literal, false} | {literal, false}
| {literal, null} | {literal, null}
| end_json | end_json
Character -- a unicode codepoint represented by an erlang integer Character -- a unicode codepoint represented by an erlang integer
Next -- a function of arity zero that, when invoked, returns the next event Next -- a function of arity zero that, when invoked, returns the next event
''' '''

181
src/jsx.erl
View file

@ -130,35 +130,34 @@ parser() ->
%% @doc %% @doc
%% produces a function which takes a binary which may or may not represent an encoded json document and returns a generator %% produces a function which takes a binary which may or may not represent an encoded json document and returns a generator
%% %%
%% ```
%% options: %% options:
%% %% <ul>
%% {comments, true | false} %% <li>{comments, true | false}
%% if true, json documents that contain c style (/* ... */) comments %% <p>if true, json documents that contain c style (/* ... */) comments
%% will be parsed as if they did not contain any comments. default is %% will be parsed as if they did not contain any comments. default is
%% false %% false</p></li>
%% %%
%% {encoded_unicode, ascii | codepoint | none} %% <li>{encoded_unicode, ascii | codepoint | none}
%% if a \uXXXX escape sequence is encountered within a key or string, %% <p>if a \uXXXX escape sequence is encountered within a key or string,
%% this option controls how it is interpreted. none makes no attempt %% this option controls how it is interpreted. none makes no attempt
%% to interpret the value, leaving it unconverted. ascii will convert %% to interpret the value, leaving it unconverted. ascii will convert
%% any value that falls within the ascii range. codepoint will convert %% any value that falls within the ascii range. codepoint will convert
%% any value that is a valid unicode codepoint. note that unicode %% any value that is a valid unicode codepoint. note that unicode
%% non-characters (including badly formed surrogates) will never be %% non-characters (including badly formed surrogates) will never be
%% converted. codepoint is the default %% converted. codepoint is the default</p></li>
%% %%
%% {encoding, auto | utf8 | utf16 | {utf16, little} | utf32 | {utf32, little} } %% <li>{encoding, auto | utf8 | utf16 | {utf16, little} | utf32 | {utf32, little} }
%% attempt to parse the binary using the specified encoding. auto will %% <p>attempt to parse the binary using the specified encoding. auto will
%% auto detect any supported encoding and is the default %% auto detect any supported encoding and is the default</p></li>
%% %%
%% {multi_term, true | false} %% <li>{multi_term, true | false}
%% usually, documents will be parsed in full before the end_json %% <p>usually, documents will be parsed in full before the end_json
%% event is emitted. setting this option to true will instead emit %% event is emitted. setting this option to true will instead emit
%% the end_json event as soon as a valid document is parsed and then %% the end_json event as soon as a valid document is parsed and then
%% reset the parser to it's initial state and attempt to parse the %% reset the parser to it's initial state and attempt to parse the
%% remainder as a new json document. this allows streams containing %% remainder as a new json document. this allows streams containing
%% multiple documents to be parsed correctly %% multiple documents to be parsed correctly</p></li>
%% ''' %% </ul>
%% @end %% @end
parser(OptsList) -> parser(OptsList) ->
@ -186,32 +185,42 @@ json_to_term(JSON) ->
%% @doc %% @doc
%% produces an eep0018 representation of a binary encoded json document %% produces an eep0018 representation of a binary encoded json document
%% %%
%% ```
%% options: %% options:
%% %% <ul>
%% {strict, true | false} %% <li>{strict, true | false}
%% by default, attempting to convert unwrapped json values (numbers, strings and %% <p>by default, attempting to convert unwrapped json values (numbers, strings and
%% the atoms true, false and null) result in a badarg exception. if strict equals %% the atoms true, false and null) result in a badarg exception. if strict equals
%% false, these are instead decoded to their equivalent eep0018 value. default is %% false, these are instead decoded to their equivalent eep0018 value. default is
%% false %% false</p>
%%
%% <p>note that there is a problem of ambiguity when parsing unwrapped json
%% numbers that requires special handling</p>
%%
%% <p>an unwrapped json number has no unambiguous end marker like a json object,
%% array or string. `1', `12' and `123' may all represent either a complete json
%% number or just the beginning of one. in this case, the parser will always
%% return `{incomplete, More}' rather than potentially terminate before input
%% is exhausted. to force termination, `More/1' may be called with the atom
%% `end_stream' as it's argument. note also that numbers followed by whitespace
%% will be parsed correctly</p></li>
%% %%
%% {encoding, auto | utf8 | utf16 | {utf16, little} | utf32 | {utf32, little} } %% <li>{encoding, auto | utf8 | utf16 | {utf16, little} | utf32 | {utf32, little} }
%% assume the binary is encoded using the specified binary. default is auto, which %% <p>assume the binary is encoded using the specified binary. default is auto, which
%% attempts to autodetect the encoding %% attempts to autodetect the encoding</p></li>
%% %%
%% {comments, true | false} %% <li>{comments, true | false}
%% if true, json documents that contain c style (/* ... */) comments %% <p>if true, json documents that contain c style (/* ... */) comments
%% will be parsed as if they did not contain any comments. default is %% will be parsed as if they did not contain any comments. default is
%% false %% false</p></li>
%% %%
%% {label, atom | existing_atom | binary} %% <li>{label, atom | existing_atom | binary}
%% json keys (labels) are decoded to utf8 encoded binaries, atoms or %% <p>json keys (labels) are decoded to utf8 encoded binaries, atoms or
%% existing_atoms (atom if it exists, binary otherwise) as specified by %% existing_atoms (atom if it exists, binary otherwise) as specified by
%% this option. default is binary %% this option. default is binary</p></li>
%% %%
%% {float, true | false} %% <li>{float, true | false}
%% return all numbers as floats. default is false %% <p>return all numbers as floats. default is false</p></li>
%% ''' %% </ul>
%% @end %% @end
json_to_term(JSON, Opts) -> json_to_term(JSON, Opts) ->
@ -227,31 +236,29 @@ term_to_json(JSON) ->
%% @spec term_to_json(JSON::eep0018(), Opts::encoder_opts()) -> binary() %% @spec term_to_json(JSON::eep0018(), Opts::encoder_opts()) -> binary()
%% @doc %% @doc
%% takes the erlang representation of a json object (as defined in eep0018) and returns a (binary encoded) json string %% takes the erlang representation of a json object (as defined in eep0018) and returns a (binary encoded) json string
%% %%
%% ```
%% options: %% options:
%% %% <ul>
%% {strict, true | false} %% <li>{strict, true | false}
%% by default, attempting to convert unwrapped json values (numbers, %% <p>by default, attempting to convert unwrapped json values (numbers,
%% strings and the atoms true, false and null) result in a badarg exception. %% strings and the atoms true, false and null) result in a badarg exception.
%% if strict equals false, these are instead json encoded. default is false %% if strict equals false, these are instead json encoded. default is false</p></li>
%% %%
%% note that there is a problem of ambiguity when parsing unwrapped json %% <li>{encoding, utf8 | utf16 | {utf16, little} | utf32 | {utf32, little} }
%% numbers that requires special handling, see the [[notes|technotes]] %% <p>the encoding of the resulting binary. default is utf8</p></li>
%% %%
%% {encoding, utf8 | utf16 | {utf16, little} | utf32 | {utf32, little} } %% <li>space
%% the encoding of the resulting binary. default is utf8 %% <p>space is equivalent to {space, 1}</p></li>
%% %%
%% space %% <li>{space, N}
%% {space, N} %% <p>place N spaces after each colon and comma in the resulting binary. default is zero</p></li>
%% place N spaces after each colon and comma in the resulting binary. space
%% implies {space, 1}. default is zero
%% %%
%% indent %% <li>indent
%% {indent, N} %% <p>indent is equivalent to {indent, 1}</p></li>
%% indent each 'level' of the json structure by N spaces. indent implies %%
%% {indent, 1}. default is zero %% <li>{indent, N}
%% ''' %% <p>indent each 'level' of the json structure by N spaces. default is zero</p></li>
%% </ul>
%% @end %% @end
term_to_json(JSON, Opts) -> term_to_json(JSON, Opts) ->
@ -268,23 +275,22 @@ is_json(JSON) ->
%% @doc %% @doc
%% returns true if the binary is an encoded json document, false otherwise %% returns true if the binary is an encoded json document, false otherwise
%% %%
%% ```
%% options: %% options:
%% %% <ul>
%% {strict, true | false} %% <li>{strict, true | false}
%% by default, unwrapped json values (numbers, strings and the atoms %% <p>by default, unwrapped json values (numbers, strings and the atoms
%% true, false and null) return false. if strict equals true, is_json %% true, false and null) return false. if strict equals true, is_json
%% returns true. default is false %% returns true. default is false</p></li>
%% %%
%% {encoding, auto | utf8 | utf16 | {utf16, little} | utf32 | {utf32, little} } %% <li>{encoding, auto | utf8 | utf16 | {utf16, little} | utf32 | {utf32, little} }
%% assume the binary is encoded using the specified binary. default is auto, %% <p>assume the binary is encoded using the specified binary. default is auto,
%% which attempts to autodetect the encoding %% which attempts to autodetect the encoding</p></li>
%% %%
%% {comments, true | false} %% <li>{comments, true | false}
%% if true, json documents that contain c style (/* ... */) comments %% <p>if true, json documents that contain c style (/* ... */) comments
%% will be parsed as if they did not contain any comments. default is %% will be parsed as if they did not contain any comments. default is
%% false %% false</p></li>
%% ''' %% </ul>
%% @end %% @end
is_json(JSON, Opts) -> is_json(JSON, Opts) ->
@ -301,36 +307,37 @@ format(JSON) ->
%% @doc %% @doc
%% formats a binary encoded json string according to the options chose. the defaults will produced a string stripped of all whitespace %% formats a binary encoded json string according to the options chose. the defaults will produced a string stripped of all whitespace
%% %%
%% ```
%% options: %% options:
%% %% <ul>
%% {strict, true | false} %% <li>{strict, true | false}
%% by default, unwrapped json values (numbers, strings and the atoms %% <p>by default, unwrapped json values (numbers, strings and the atoms
%% true, false and null) result in an error. if strict equals true, they %% true, false and null) result in an error. if strict equals true, they
%% are treated as valid json. default is false %% are treated as valid json. default is false</p></li>
%% %%
%% {encoding, auto | utf8 | utf16 | {utf16, little} | utf32 | {utf32, little} } %% <li>{encoding, auto | utf8 | utf16 | {utf16, little} | utf32 | {utf32, little} }
%% assume the binary is encoded using the specified binary. default is auto, %% <p>assume the binary is encoded using the specified binary. default is auto,
%% which attempts to autodetect the encoding %% which attempts to autodetect the encoding</p></li>
%% %%
%% {output_encoding, utf8 | utf16 | {utf16, little} | utf32 | {utf32, little} } %% <li>{output_encoding, utf8 | utf16 | {utf16, little} | utf32 | {utf32, little} }
%% the encoding of the resulting binary. default is utf8 %% <p>the encoding of the resulting binary. default is utf8</p></li>
%% %%
%% {comments, true | false} %% <li>{comments, true | false}
%% if true, json documents that contain c style (/* ... */) comments %% <p>if true, json documents that contain c style (/* ... */) comments
%% will be parsed as if they did not contain any comments. default is %% will be parsed as if they did not contain any comments. default is
%% false %% false</p></li>
%%
%% space
%% {space, N}
%% place N spaces after each colon and comma in the resulting binary. space
%% implies {space, 1}. default is zero
%% %%
%% indent %% <li>space
%% {indent, N} %% <p>space is equivalent to {space, 1}</p></li>
%% indent each 'level' of the json structure by N spaces. indent implies %%
%% {indent, 1}. default is zero %% <li>{space, N}
%% ''' %% <p>place N spaces after each colon and comma in the resulting binary. default is zero</p></li>
%%
%% <li>indent
%% <p>indent is equivalent to {indent, 1}</p></li>
%%
%% <li>{indent, N}
%% <p>indent each 'level' of the json structure by N spaces. default is zero</p></li>
%% </ul>
%% @end %% @end
format(JSON, Opts) -> format(JSON, Opts) ->