delistify README
This commit is contained in:
alisdair sullivan
parent
0e53893fce
commit
56ff3b914e
1 changed files with 284 additions and 288 deletions
|
|
@ -25,7 +25,7 @@ jsx may be built using either [sinan][sinan] or [rebar][rebar]
|
|||
|
||||
## quickstart ##
|
||||
|
||||
* to build the library and run tests
|
||||
#### to build the library and run tests ####
|
||||
|
||||
```bash
|
||||
tanga:jsx alisdair$ sinan build
|
||||
|
|
@ -37,7 +37,7 @@ jsx may be built using either [sinan][sinan] or [rebar][rebar]
|
|||
tanga:jsx alisdair$ rebar eunit
|
||||
```
|
||||
|
||||
* to convert a utf8 binary containing a json string into an erlang term
|
||||
#### to convert a utf8 binary containing a json string into an erlang term ####
|
||||
|
||||
```erlang
|
||||
1> jsx:decode(<<"{\"library\": \"jsx\", \"awesome\": true}">>).
|
||||
|
|
@ -46,7 +46,7 @@ jsx may be built using either [sinan][sinan] or [rebar][rebar]
|
|||
[<<"a">>, <<"list">>, <<"of">>, <<"words">>]
|
||||
```
|
||||
|
||||
* to convert an erlang term into a utf8 binary containing a json string
|
||||
#### to convert an erlang term into a utf8 binary containing a json string ####
|
||||
|
||||
```erlang
|
||||
1> jsx:encode([{<<"library">>,<<"jsx">>},{<<"awesome">>,true}]).
|
||||
|
|
@ -55,7 +55,7 @@ jsx may be built using either [sinan][sinan] or [rebar][rebar]
|
|||
<<"[\"a\",\"list\",\"of\",\"words\"]">>
|
||||
```
|
||||
|
||||
* to check if a binary or a term is valid json
|
||||
#### to check if a binary or a term is valid json ####
|
||||
|
||||
```erlang
|
||||
1> jsx:is_json(<<"[\"this is json\"]">>).
|
||||
|
|
@ -68,7 +68,7 @@ jsx may be built using either [sinan][sinan] or [rebar][rebar]
|
|||
false
|
||||
```
|
||||
|
||||
* to minify some json
|
||||
#### to minify some json ####
|
||||
|
||||
```erlang
|
||||
1> jsx:minify(<<"{
|
||||
|
|
@ -81,7 +81,7 @@ jsx may be built using either [sinan][sinan] or [rebar][rebar]
|
|||
<<"{\"a list\":[1,2,3]}">>
|
||||
```
|
||||
|
||||
* to prettify some json
|
||||
#### to prettify some json ####
|
||||
|
||||
```erlang
|
||||
1> jsx:prettify(<<"{\"a list\":[1,2,3]}">>).
|
||||
|
|
@ -108,7 +108,7 @@ the [spec][rfc4627] thinks json values must be wrapped in a json array or object
|
|||
|
||||
here is a table of how various json values map to erlang:
|
||||
|
||||
#### json <-> erlang mapping ####
|
||||
### json <-> erlang mapping ###
|
||||
|
||||
**json** | **erlang**
|
||||
--------------------------------|--------------------------------
|
||||
|
|
@ -149,7 +149,7 @@ here is a table of how various json values map to erlang:
|
|||
json objects are represented by erlang proplists. the empty object has the special representation `[{}]` to differentiate it from the empty list. ambiguities like `[true, false]` prevent the use of the shorthand form of property lists using atoms as properties so all properties must be tuples. all keys must be encoded as in `string` or as atoms (which will be escaped and converted to binaries for presentation to handlers). values should be valid json values
|
||||
|
||||
|
||||
#### incomplete input ####
|
||||
### incomplete input ###
|
||||
|
||||
jsx handles incomplete json texts. if a partial json text is parsed, rather than returning a term from your callback handler, jsx returns `{incomplete, F}` where `F` is a function with an identical API to the anonymous fun returned from `decoder/3`, `encoder/3` or `parser/3`. it retains the internal state of the parser at the point where input was exhausted. this allows you to parse as you stream json over a socket or file descriptor, or to parse large json texts without needing to keep them entirely in memory
|
||||
|
||||
|
|
@ -158,7 +158,7 @@ however, it is important to recognize that jsx is greedy by default. jsx will co
|
|||
|
||||
## data types ##
|
||||
|
||||
* `json_term()`
|
||||
#### `json_term()` ####
|
||||
|
||||
```erlang
|
||||
json_term() = [json_term()]
|
||||
|
|
@ -173,7 +173,7 @@ however, it is important to recognize that jsx is greedy by default. jsx will co
|
|||
|
||||
the erlang representation of json. binaries should be `utf8` encoded, or close at least
|
||||
|
||||
* `json_text()`
|
||||
#### `json_text()` ####
|
||||
|
||||
```erlang
|
||||
json_text() = binary()
|
||||
|
|
@ -181,11 +181,9 @@ however, it is important to recognize that jsx is greedy by default. jsx will co
|
|||
|
||||
a utf8 encoded binary containing a json string
|
||||
|
||||
* `tokens()` & `token()`
|
||||
#### `token()` ####
|
||||
|
||||
```erlang
|
||||
tokens() = token() | [token()]
|
||||
|
||||
token() = start_object
|
||||
| end_object
|
||||
| start_array
|
||||
|
|
@ -209,7 +207,7 @@ however, it is important to recognize that jsx is greedy by default. jsx will co
|
|||
|
||||
the internal representation used during syntactic analysis
|
||||
|
||||
* `events()` & `event()`
|
||||
#### `event()` ####
|
||||
|
||||
```erlang
|
||||
event() = start_object
|
||||
|
|
@ -228,11 +226,9 @@ however, it is important to recognize that jsx is greedy by default. jsx will co
|
|||
|
||||
the internal representation used during semantic analysis
|
||||
|
||||
* `options()` & `option()`
|
||||
#### `option()` ####
|
||||
|
||||
```erlang
|
||||
options() = [option()]
|
||||
|
||||
option() = replaced_bad_utf8
|
||||
| escaped_forward_slashes
|
||||
| single_quoted_strings
|
||||
|
|
@ -295,7 +291,7 @@ however, it is important to recognize that jsx is greedy by default. jsx will co
|
|||
## exports ##
|
||||
|
||||
|
||||
* `encoder/3`, `decoder/3` & `parser/3`
|
||||
#### `encoder/3`, `decoder/3` & `parser/3` ####
|
||||
|
||||
```erlang
|
||||
decoder(Module, Args, Opts) -> Fun((JSONText) -> any())
|
||||
|
|
@ -304,13 +300,13 @@ however, it is important to recognize that jsx is greedy by default. jsx will co
|
|||
|
||||
Module = atom()
|
||||
Args = any()
|
||||
Opts = options()
|
||||
Opts = [option()]
|
||||
JSONText = json_text()
|
||||
JSONTerm = json_term()
|
||||
Tokens = tokens()
|
||||
Tokens = token() | [token()]
|
||||
```
|
||||
|
||||
jsx is a json compiler with distinct tokenizing, syntactic analysis and semantic analysis stages (actually, semantic analysis takes place during syntactic analysis, for efficiency). included are two tokenizers; one that handles json texts (`decoder/3`) and one that handles erlang terms (`encoder/3`). there is also an entry point to the syntactic analysis stage for use with user-defined tokenizers (`parser/3`)
|
||||
jsx is a json compiler with interleaved tokenizing, syntactic analysis and semantic analysis stages. included are two tokenizers; one that handles json texts (`decoder/3`) and one that handles erlang terms (`encoder/3`). there is also an entry point to the syntactic analysis stage for use with user-defined tokenizers (`parser/3`)
|
||||
|
||||
all three functions return an anonymous function that takes the appropriate type of input and returns the result of performing semantic analysis, the tuple `{incomplete, F}` where `F` is a new anonymous function (see [incomplete input](#incomplete_input)) or a `badarg` error exception if syntactic analysis fails
|
||||
|
||||
|
|
@ -320,9 +316,9 @@ however, it is important to recognize that jsx is greedy by default. jsx will co
|
|||
|
||||
`Opts` are detailed in [data types](#data_types)
|
||||
|
||||
see [callback exports](#callback_exports) for details on the callback module
|
||||
check out [callback module documentation](#callback_exports) for details of the callback module interface
|
||||
|
||||
* `decode/1,2`
|
||||
#### `decode/1,2` ####
|
||||
|
||||
```erlang
|
||||
decode(JSON) -> Term
|
||||
|
|
@ -335,7 +331,7 @@ however, it is important to recognize that jsx is greedy by default. jsx will co
|
|||
F = fun((any()) -> any())
|
||||
```
|
||||
|
||||
`decode` parses a json text (a `utf8` encoded binary) and produces an erlang term (see [json <-> erlang mapping](#json---erlang-mapping))
|
||||
`decode` parses a json text (a `utf8` encoded binary) and produces an erlang term
|
||||
|
||||
the option `labels` controls how keys are converted from json to erlang terms. `binary` does no conversion beyond normal escaping. `atom` converts keys to erlang atoms and results in a badarg error if the keys fall outside the range of erlang atoms. `existing_atom` is identical to `atom` except it will not add new atoms to the atom table
|
||||
|
||||
|
|
@ -352,7 +348,7 @@ however, it is important to recognize that jsx is greedy by default. jsx will co
|
|||
raises a `badarg` error exception if input is not valid json
|
||||
|
||||
|
||||
* `encode/1,2`
|
||||
#### `encode/1,2` ####
|
||||
|
||||
```erlang
|
||||
encode(Term) -> JSON
|
||||
|
|
@ -365,7 +361,7 @@ however, it is important to recognize that jsx is greedy by default. jsx will co
|
|||
N = pos_integer()
|
||||
```
|
||||
|
||||
`encode` parses a json text (a `utf8` encoded binary) and produces an erlang term (see [json <-> erlang mapping](#json---erlang-mapping))
|
||||
`encode` parses a json text (a `utf8` encoded binary) and produces an erlang term
|
||||
|
||||
the option `{space, N}` inserts `N` spaces after every comma and colon in your json output. `space` is an alias for `{space, 1}`. the default is `{space, 0}`
|
||||
|
||||
|
|
@ -381,10 +377,10 @@ however, it is important to recognize that jsx is greedy by default. jsx will co
|
|||
|
||||
declaring more than one pre-encoder will result in a `badarg` error exception
|
||||
|
||||
raises a `badarg` error exception if input is not a valid erlang representation of json
|
||||
raises a `badarg` error exception if input is not a valid [erlang representation of json](#json---erlang-mapping)
|
||||
|
||||
|
||||
* `format/1,2`
|
||||
#### `format/1,2` ####
|
||||
|
||||
```erlang
|
||||
format(JSON) -> JSON
|
||||
|
|
@ -404,7 +400,7 @@ however, it is important to recognize that jsx is greedy by default. jsx will co
|
|||
raises a `badarg` error exception if input is not valid json
|
||||
|
||||
|
||||
* `minify/1`
|
||||
#### `minify/1` ####
|
||||
|
||||
```erlang
|
||||
minify(JSON) -> JSON
|
||||
|
|
@ -417,7 +413,7 @@ however, it is important to recognize that jsx is greedy by default. jsx will co
|
|||
raises a `badarg` error exception if input is not valid json
|
||||
|
||||
|
||||
* `prettify/1`
|
||||
#### `prettify/1` ####
|
||||
|
||||
```erlang
|
||||
prettify(JSON) -> JSON
|
||||
|
|
@ -430,7 +426,7 @@ however, it is important to recognize that jsx is greedy by default. jsx will co
|
|||
raises a `badarg` error exception if input is not valid json
|
||||
|
||||
|
||||
* `is_json/1,2`
|
||||
#### `is_json/1,2` ####
|
||||
|
||||
```erlang
|
||||
is_json(MaybeJSON) -> true | false
|
||||
|
|
@ -445,7 +441,7 @@ however, it is important to recognize that jsx is greedy by default. jsx will co
|
|||
what exactly constitutes valid json may be altered per the options, detailed in [data types](#data_types)
|
||||
|
||||
|
||||
* `is_term/1,2`
|
||||
#### `is_term/1,2` ####
|
||||
|
||||
```erlang
|
||||
is_term(MaybeJSON) -> true | false
|
||||
|
|
@ -464,7 +460,7 @@ however, it is important to recognize that jsx is greedy by default. jsx will co
|
|||
|
||||
the following functions should be exported from a jsx callback module
|
||||
|
||||
* `Module:init/1`
|
||||
#### `Module:init/1` ####
|
||||
|
||||
```erlang
|
||||
Module:init(Args) -> InitialState
|
||||
|
|
@ -475,12 +471,12 @@ the following functions should be exported from a jsx callback module
|
|||
|
||||
whenever any of `encoder/3`, `decoder/3` or `parser/3` are called, this function is called with the `Args` argument provided in the calling function to obtain `InitialState`
|
||||
|
||||
* `Module:handle_event/2`
|
||||
#### `Module:handle_event/2` ####
|
||||
|
||||
```erlang
|
||||
Module:handle_event(Event, State) -> NewState
|
||||
|
||||
Event = events()
|
||||
Event = [event()]
|
||||
State = any()
|
||||
NewState = any()
|
||||
```
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue