View Source jsonpull_construct (jsonpull v0.1.1)

These functions are helpers to construct a proper Erlang list or map from JSON equivalents.

They can be used with the main functions that return {ok, {Value, Rest}} or {error, Atom} and also have the same signature themselves.

However, you can also substitute your own function to construct whatever you'd like.

Summary

Functions

Tries to read an object from the JSON and constructs a value using Conditions.

Tries to read an array from the JSON and constructs a list using Fun.

Helper function for pulling a single value out of an object.

Functions

Link to this function

fold(JSON, Acc0, Conditions)

View Source
-spec fold(JSON :: binary(), Acc0, Conditions) ->
        {ok, {Acc1, Rest :: binary()}} | {error, Error | not_object | failed_condition}
        when
            Conditions :: [Condition],
            Condition :: {required | optional, [KeyFun]},
            KeyFun :: {Key :: binary(), Fun | Shortcut},
            Fun ::
                fun((JSON :: binary(), AccIn) ->
                        {ok, {AccOut, FunRest :: binary}} | {error, Error}),
            Shortcut :: {set, term(), Mainish | atom()},
            Mainish ::
                fun((JSON :: binary()) -> {ok, {term(), FunRest :: binary}} | {error, Error}),
            Acc0 :: term(),
            Acc1 :: term(),
            AccIn :: term(),
            AccOut :: term().

Tries to read an object from the JSON and constructs a value using Conditions.

The conditions can be seen as a list of items to check. Each condition will only apply once. It works like this:
  1. A new key is pulled from the object
  2. The key is checked to find any condition that matches it. If no condition is found, the value is skipped.
  3. When a key has a matching condition, the Fun for that condition is called to read the value.
  4. If it's a required condition, the constructor will make sure it only gets called once by erroring out if the condition matches any key again.
  5. If it's an optional condition, the constructor will make sure it only gets called once by silently ignoring any further mathces.
  6. When the object runs out of keys, if there are any required conditions left, an error will be returned.

A single condition can have any number of Key-Fun pairs. Each pair contains the Key to check, and the Fun to be called if found.

The Fun receives the JSON to read and the current accumulator. You may modify the accumulator in any way you'd like. There are some shortcut tuples you can use instead of supplying a Fun yourself, such as
 {set, name, string} % the third element can be a main-ish fun or an atom that refers to one
 
instead of
 fun (Bin, Acc) ->
     {ok, {Name, Rest}} = jsonpull:string(Bin),
     {ok, {Acc#{name => Name}, Rest}}
 end
 
{set, Key, ...} will behave differently depending on the type of your accumulator.
  • If it is a map, it will set the Key in the accumulator to the value.
  • If it is a tuple, it will use setelement to set the corresponding Nth element to the value.
  • If it is a list, it will be added to the list as {Key, Value} - like a proplist.
This is still pretty complicated. Please look at some of the examples if you need more info.
-spec list(JSON :: binary(), Fun) -> {ok, {List, Rest :: binary()}} | {error, Error | not_array}
        when
            Fun ::
                fun((JSON :: binary()) -> {ok, {Value, FunRest :: binary}} | {error, Error}) |
                atom(),
            List :: [Value].

Tries to read an array from the JSON and constructs a list using Fun.

The Fun should have the same signature as one of the main reading functions. You can also use an atom as a shorthand for the main functions, e.g. string instead of 'fun jsonpull:string/1'.
-spec map(JSON :: binary(), Conditions) ->
       {ok, {Map, Rest :: binary()}} | {error, Error | not_object | failed_condition}
       when
           Conditions :: [Condition],
           Condition :: {required | optional, [KeyFun]},
           KeyFun :: {Key :: binary(), Fun | Shortcut},
           Fun ::
               fun((JSON :: binary(), AccIn) -> {ok, {AccOut, FunRest :: binary}} | {error, Error}),
           Shortcut :: {set, term(), Mainish | atom()},
           Mainish ::
               fun((JSON :: binary()) -> {ok, {term(), FunRest :: binary}} | {error, Error}),
           Map :: map(),
           AccIn :: map(),
           AccOut :: map().
Equivalent to jsonpull_construct:fold(JSON, #{}, Conditions).
Link to this function

single_value(JSON, Key, Fun)

View Source
-spec single_value(JSON :: binary(), Key, Fun) ->
                {ok, {Value, Rest :: binary()}} | {error, Error | not_object | failed_condition}
                when
                    Key :: binary(),
                    Fun :: Mainish | atom(),
                    Mainish ::
                        fun((JSON :: binary()) ->
                                {ok, {Value, FunRest :: binary}} | {error, Error}).

Helper function for pulling a single value out of an object.

Equivalent to jsonpull_construct:fold(JSON, unreachable, [{required, [{Key, Fun}]}]).