diff --git a/doc/overview.edoc b/doc/overview.edoc deleted file mode 100644 index ab7c842..0000000 --- a/doc/overview.edoc +++ /dev/null @@ -1,138 +0,0 @@ -@author Alisdair Sullivan -@copyright 2010 Alisdair Sullivan -@version 0.9.0 -@title jsx -@doc jsx is a json parser with an easily transformable representation, the ability to parse streams incrementally, low memory overhead and a clean generator based interface. it also includes an implementation of eep0018, a json reformatter and a json verifier - - -== contents == - -
    -
  1. {@section introduction}
    2. -
  2. {@section features}
    3. -
  3. {@section usage}
    4. -
  4. {@section contributing}
    5. -
  5. {@section acknowledgements}
    6. -
- - -== introduction == - -what's a language without strong json integration? one that no one is gonna use for much of anything that requires integration with other systems - -erlang has a number of json libraries, some of them very good, but all of them tied to fairly specific representations and usage scenarios. working with json in erlang, outside of simple decoding into terms that probably aren't ideal, is laborious and clumsy. jsx seeks to correct this unfortunate state - - -== features == - -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 - -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) - -jsx attempts to follow the json specification as closely as possible but is realistic about actual usage of json and provides optional support for comments, json values not wrapped in a json object or array and streams containing multiple json documents - -jsx is wicked fast. sort of. it's as fast as possible without sacrificing a useable interface, at least. things like efficiency of binary matching, elimination of unused intermediate states, the relative costs of using lists or binaries and even garbage collection were tested and taken into consideration during development - - -== usage == - -`jsx:parser()' is the entry point for a jsx parser. it returns a function that takes a binary and attempts to parse it as if it were a chunk of valid (or not so valid, depending on the options passed to `jsx:parser/1') json encoded in utf8, utf16 (big or little endian) or utf32 (big or little endian). it's an incremental parser, it's parsed on demand; an 'event' at a time. events are tuples of the form: - -``` - {event, Event, Next} - Event = start_object - | start_array - | end_object - | end_array - | {string, [Character]} - | {integer, [Character]} - | {float, [Character]} - | {literal, true} - | {literal, false} - | {literal, null} - | end_json - Character -- a unicode codepoint represented by an erlang integer - Next -- a function of arity zero that, when invoked, returns the next event -''' - -the decoder can also return two other tuples: - -``` - {incomplete, More} - More -- a function of arity 1 that accepts additional input for - the parser and resumes parsing as if never interrupted. the semantics - are as if the new binary were appended to the already parsed binary - - {error, {badjson, Bin}} - Bin -- the remainder of the input at the point of the error. the first - byte of the binary is the byte that failed to match -''' - -`incomplete' is returned when input is exhausted. `error' is returned when invalid json input is detected. how obvious - -putting all of this together, the following short module: - -``` - -module(jsx_ex). - - -export([simple_decode/1]). - - simple_decode(JSON) when is_binary(JSON) -> - P = jsx:parser(), - decode(P(JSON), []). - - decode({event, end_json, _Next}, Acc) -> - lists:reverse(Acc); - decode({event, Event, Next}, Acc) -> - decode(Next(), [Event] ++ Acc). -''' - -does this when called from the shell with suitable input: - -``` - 1> jsx_ex:simple_decode( - <<"{ - \"dead rock stars\": [\"kurt cobain\", \"elliott smith\", \"nicky wire\"], - \"total\": 3.0, - \"courtney killed kurt\": true - }">> - ). - [start_object, - {key,"dead rock stars"}, - start_array, - {string,"kurt cobain"}, - {string,"elliott smith"}, - {string,"nicky wire"}, - end_array, - {key,"total"}, - {float,"3.0"}, - {key,"courtney killed kurt"}, - {literal,true}, - end_object] -''' - - -jsx also has an eep0018 decoder and encoder, a json pretty printer and a json verifier: - -``` - 1> jsx:json_to_term(<<"[1, true, \"hi\"]">>). - [1,true,<<"hi">>] - 2> jsx:term_to_json([{name, <<"alisdair">>}, {balance, -3742.35}, {employed, false}]). - <<"{\"name\":\"alisdair\",\"balance\":-3742.35,\"employed\":false}">> - 3> jsx:is_json(<<"{}">>). - true - 4> jsx:format(<<" \t\t [\n \"i love whitespace\"\n ]\n ">>). - <<"[\"i love whitespace\"]">> -''' - - -== contributing == - -jsx is available on github. users are encouraged to fork, edit and make pull requests - - -== acknowledgments == - -jsx wouldn't be possible without Lloyd Hilaiel's yajl and the encouragement of the erlang community. thanks also must be given to the es-discuss mailing list and Douglas Crockford for insight into the intricacies of json \ No newline at end of file diff --git a/src/jsx.erl b/src/jsx.erl index 8df7696..76a6592 100644 --- a/src/jsx.erl +++ b/src/jsx.erl @@ -21,11 +21,6 @@ %% THE SOFTWARE. -%% @author Alisdair Sullivan -%% @copyright 2010 Alisdair Sullivan -%% @version 0.9.0 -%% @doc this module defines the interface to the jsx json parsing library - -module(jsx). @@ -46,142 +41,11 @@ -endif. -%% @type jsx_parser() = (binary()) -> jsx_parser_result(). - -%% @type jsx_parser_result() = {event, jsx_event(), (() -> jsx_parser_result())} -%% | {incomplete, jsx_parser()} -%% | {error, {badjson, binary()}} -%% | {error, badarg}. - -%% @type jsx_event() = start_object -%% | end_object -%% | start_array -%% | end_array -%% | end_json -%% | {key, unicode_string()} -%% | {string, unicode_string()} -%% | {integer, unicode_string()} -%% | {float, unicode_string()} -%% | {literal, true} -%% | {literal, false} -%% | {literal, null}. - -%% @type unicode_string() = [integer()]. - -%% @type jsx_opts() = [jsx_opt()]. -%% @type jsx_opt() = {comments, true | false} -%% | {escaped_unicode, ascii | codepoint | none} -%% | {multi_term, true | false} -%% | {unquoted_keys, true | false} -%% | {encoding, auto | supported_utf()}. - -%% @type supported_utf() = utf8 -%% | utf16 -%% | {utf16, little} -%% | utf32 -%% | {utf32, little}. - -%% @type eep0018() = eep0018_object() | eep0018_array(). - -%% @type eep0018_array() = [eep0018_term()]. -%% @type eep0018_object() = [{eep0018_key(), eep0018_term()}]. - -%% @type eep0018_key() = binary() | atom(). - -%% @type eep0018_term() = eep0018_array() -%% | eep0018_object() -%% | eep0018_string() -%% | eep0018_number() -%% | true -%% | false -%% | null. - -%% @type eep0018_string() = binary(). - -%% @type eep0018_number() = float() | integer(). - -%% @type encoder_opts() = [encoder_opt()]. -%% @type encoder_opt() = {strict, true | false} -%% | {encoding, supported_utf()} -%% | {space, integer()} -%% | space -%% | {indent, integer()} -%% | indent. - - -%% @type decoder_opts() = [decoder_opt()]. -%% @type decoder_opt() = {strict, true | false} -%% | {comments, true | false} -%% | {encoding, supported_utf()} -%% | {label, atom | binary | existing_atom} -%% | {float, true | false}. - - -%% @type verify_opts() = [verify_opt()]. -%% @type verify_opt() = {strict, true | false} -%% | {encoding, auto | supported_utf()} -%% | {comments, true | false}. - - -%% @type format_opts() = [format_opt()]. -%% @type format_opt() = {strict, true | false} -%% | {encoding, auto | supported_utf()} -%% | {comments, true | false} -%% | {space, integer()} -%% | space -%% | {indent, integer()} -%% | indent -%% | {output_encoding, supported_utf()}. - - -%% @spec parser() -> jsx_parser() -%% @equiv parser([]) - -spec parser() -> jsx_parser(). parser() -> parser([]). -%% @spec parser(Opts::jsx_opts()) -> jsx_parser() -%% @doc -%% produces a function which takes a binary which may or may not represent an -%% encoded json document and returns a generator -%% -%% options: -%% -%% @end -spec parser(OptsList::jsx_opts()) -> jsx_parser(). @@ -194,10 +58,7 @@ parser(OptsList) -> ; {utf32, little} -> jsx_utf32le:parser(OptsList) ; auto -> detect_encoding(OptsList) end. - -%% @spec json_to_term(JSON::binary()) -> eep0018() -%% @equiv json_to_term(JSON, []) -spec json_to_term(JSON::binary()) -> eep0018(). @@ -207,70 +68,13 @@ json_to_term(JSON) -> catch error:badarg -> erlang:error(badarg) end. -%% @spec json_to_term(JSON::binary(), Opts::decoder_opts()) -> eep0018() -%% @doc -%% produces an eep0018 representation of a binary encoded json document -%% -%% options: -%% -%% @end -spec json_to_term(JSON::binary(), Opts::decoder_opts()) -> eep0018(). - -%json_to_term(JSON, Opts) -> -% try jsx_eep0018:json_to_term(JSON, Opts) -% %% rethrow exception so internals aren't confusingly exposed to users -% catch error:badarg -> erlang:error(badarg) -% end. json_to_term(JSON, Opts) -> jsx_eep0018:json_to_term(JSON, Opts). -%% @spec term_to_json(JSON::eep0018()) -> binary() -%% @equiv term_to_json(JSON, []) - -spec term_to_json(JSON::eep0018()) -> binary(). term_to_json(JSON) -> @@ -278,43 +82,7 @@ term_to_json(JSON) -> %% rethrow exception so internals aren't confusingly exposed to users catch error:badarg -> erlang:error(badarg) end. - -%% @spec term_to_json(JSON::eep0018(), Opts::encoder_opts()) -> binary() -%% @doc -%% takes the erlang representation of a json object (as defined in eep0018) and -%% returns a (binary encoded) json string -%% -%% options: -%% -%% @end + -spec term_to_json(JSON::eep0018(), Opts::encoder_opts()) -> binary(). @@ -325,41 +93,11 @@ term_to_json(JSON, Opts) -> end. -%% @spec is_json(JSON::binary()) -> true | false -%% @equiv is_json(JSON, []) - -spec is_json(JSON::binary()) -> true | false. is_json(JSON) -> is_json(JSON, []). -%% @spec is_json(JSON::binary(), verify_opts()) -> true | false -%% @doc -%% returns true if the binary is an encoded json document, false otherwise -%% -%% options: -%% -%% @end -spec is_json(JSON::binary(), Opts::verify_opts()) -> true | false. @@ -367,75 +105,17 @@ is_json(JSON, Opts) -> jsx_verify:is_json(JSON, Opts). -%% @spec format(JSON::binary()) -> binary() -%% @equiv format(JSON, []) - -spec format(JSON::binary()) -> binary() | iolist(). format(JSON) -> format(JSON, []). - -%% @spec format(JSON::binary(), Opts::format_opts()) -> binary() -%% @doc -%% formats a binary encoded json string according to the options chose. the -%% defaults will produced a string stripped of all whitespace -%% -%% options: -%% -%% @end + -spec format(JSON::binary(), Opts::format_opts()) -> binary() | iolist(). format(JSON, Opts) -> jsx_format:format(JSON, Opts). - -%% @spec eventify(List::list()) -> jsx_parser_result() -%% @doc fake the jsx api for any list. useful if you want to serialize a -%% structure to json using the pretty printer, or verify a sequence could be -%% valid json -spec eventify(List::list()) -> jsx_parser_result(). diff --git a/src/jsx_eep0018.erl b/src/jsx_eep0018.erl index ee6e494..db7b093 100644 --- a/src/jsx_eep0018.erl +++ b/src/jsx_eep0018.erl @@ -21,9 +21,6 @@ %% THE SOFTWARE. -%% @hidden hide this module from edoc, exported functions are internal to jsx -%% and may be altered or removed without notice - -module(jsx_eep0018). diff --git a/src/jsx_format.erl b/src/jsx_format.erl index 4bd3cd3..32f0093 100644 --- a/src/jsx_format.erl +++ b/src/jsx_format.erl @@ -21,9 +21,6 @@ %% THE SOFTWARE. -%% @hidden hide this module from edoc, exported functions are internal to jsx -%% and may be altered or removed without notice - -module(jsx_format). diff --git a/src/jsx_utf16.erl b/src/jsx_utf16.erl index bb6ec8e..7c84293 100644 --- a/src/jsx_utf16.erl +++ b/src/jsx_utf16.erl @@ -21,9 +21,6 @@ %% THE SOFTWARE. -%% @hidden hide this module from edoc, exported functions are internal to jsx -%% and may be altered or removed without notice - -module(jsx_utf16). diff --git a/src/jsx_utf16le.erl b/src/jsx_utf16le.erl index bdcf16b..2133c86 100644 --- a/src/jsx_utf16le.erl +++ b/src/jsx_utf16le.erl @@ -21,9 +21,6 @@ %% THE SOFTWARE. -%% @hidden hide this module from edoc, exported functions are internal to jsx -%% and may be altered or removed without notice - -module(jsx_utf16le). diff --git a/src/jsx_utf32.erl b/src/jsx_utf32.erl index 230b301..87c7337 100644 --- a/src/jsx_utf32.erl +++ b/src/jsx_utf32.erl @@ -21,9 +21,6 @@ %% THE SOFTWARE. -%% @hidden hide this module from edoc, exported functions are internal to jsx -%% and may be altered or removed without notice - -module(jsx_utf32). diff --git a/src/jsx_utf32le.erl b/src/jsx_utf32le.erl index 7c14fae..fd85926 100644 --- a/src/jsx_utf32le.erl +++ b/src/jsx_utf32le.erl @@ -21,9 +21,6 @@ %% THE SOFTWARE. -%% @hidden hide this module from edoc, exported functions are internal to jsx -%% and may be altered or removed without notice - -module(jsx_utf32le). diff --git a/src/jsx_utf8.erl b/src/jsx_utf8.erl index 00052fa..dbe844f 100644 --- a/src/jsx_utf8.erl +++ b/src/jsx_utf8.erl @@ -21,9 +21,6 @@ %% THE SOFTWARE. -%% @hidden hide this module from edoc, exported functions are internal to jsx -%% and may be altered or removed without notice - -module(jsx_utf8). diff --git a/src/jsx_verify.erl b/src/jsx_verify.erl index 890d7ac..a23d6c0 100644 --- a/src/jsx_verify.erl +++ b/src/jsx_verify.erl @@ -21,9 +21,6 @@ %% THE SOFTWARE. -%% @hidden hide this module from edoc, exported functions are internal to jsx -%% and may be altered or removed without notice - -module(jsx_verify).