Module jwalk

Description
Data Types
Function Index
Function Details

The jwalk module is intended to make it easier to work with Erlang encodings of JSON, specifically: eep 18, maps, mochijson-style and proplists representations.

Authors: Jim Rosenblum (jrosenblum@prodigy.net).

Description

The jwalk module is intended to make it easier to work with Erlang encodings of JSON, specifically: eep 18, maps, mochijson-style and proplists representations.

This work is inspired by https://github.com/seth/ej, but handles additional representation types, including maps.

Functions always take at least two parameters: a first parameter which is a tuple of elements representing a Path into a JSON Object, and a second parameter which is expected to be a valid representation of a JSON structure.

The Path components of the first parameter are a tuple representation of a javascript-like, dot-path notation: i.e.,

Obj.cars.make.model would be expressed as {"cars","make","model"}

Path components may also contain:

The atoms 'first' and 'last' or an integer index indicating an element from a JSON Array; or,

{select, {"name","value"}} which will return the subset of JSON objects in an Array that has a {"name":"value"} Member.

{select, 'all'} which will return all Objects in an array.

new: for set/2 and set_p/2, when the final element of a path is the atom new, the supplied value is added to the stucture as the first element of an array, the array is created if necessary.

Path, string elements can be binary or not

   Cars = {[{<<"cars">>, [ {[{<<"color">>, <<"white">>}, {<<"age">>, <<"old">>}]},
                           {[{<<"color">>, <<"red">>},  {<<"age">>, <<"old">>}]},
                           {[{<<"color">>, <<"blue">>}, {<<"age">>, <<"new">>}]}
                         ] }]}.

Then

   jwalk:get({"cars", {select, {"age", "old"}}}, Cars).
  
   [ {[{<<"color">>,<<"white">>},{<<"age">>,<<"old">>}]},
     {[{<<"color">>,<<"red">>},{<<"age">>,<<"old">>}]} ]
  
   jwalk:get({"cars", {select, {"age", "old"}}, 1}, Cars).
   {[{<<"color">>,<<"white">>},{<<"age">>,<<"old">>}]}
  
   jwalk:get({"cars", {select, {"age", "old"}},first,"color"}, Cars).
   <<"white">>

Data Types

eep()

eep() = {[{name(), eep_value()}, ...]}

eep_value()

eep_value() = value() | eep() | [eep_value(), ...]

j_obj()

j_obj() = [{}] | {[]} | {struct, []} | map() | pl() | eep() | mochi()

jwalk_return()

jwalk_return() = undefined | j_obj() | value() | [] | [jwalk_return(), ...]

mochi()

mochi() = {struct, [{name(), mochi_value()}, ...]}

mochi_value()

mochi_value() = value() | mochi() | [mochi_value(), ...]

name()

name() = binary()

p_elt()

p_elt() = name() | select() | p_index() | new

p_index()

p_index() = first | last | non_neg_integer()

path()

path() = {p_elt()} | [p_elt(), ...]

pl()

pl() = [{name(), pl_value()}, ...]

pl_value()

pl_value() = value() | pl() | [pl_value(), ...]

select()

select() = {select, {name(), value()} | all}

value()

Function Index

delete/2	Remove the value at the location specified by `Path` and return the new representation.
get/2	Return a value from an `Obj`.
get/3	Return a value from an `Obj` or Default if value not found.
set/3	Set a value in `Obj`.
set_p/3	Same as set/3 but creates intermediary elements as necessary.

Function Details

delete/2

delete(Path, Object) -> NewObject | no_return()

Path = path()
Object = j_obj()
NewObject = j_obj()

Remove the value at the location specified by Path and return the new representation.

Path elements that are strings can be binary or not - they are converted to binary if not.

Throws
{no_path, _}
{selector_used_on_object, _}
{selector_used_on_non_list, _, _}
{index_for_non_list, _}
{replacing_object_with_value, _}
{index_out_of_bounds, _, _}.

get/2

get(Path, Object) -> Result | no_return()

Path = path()
Object = j_obj()
Result = jwalk_return()

Return a value from an Obj.

Path elements that are strings can be binary or not - they are converted to binary if not.

Throws
{no_path, _}
{selector_used_on_object, _}
{selector_used_on_non_list, _, _}
{index_for_non_list, _}
{replacing_object_with_value, _}
{index_out_of_bounds, _, _}.

get/3

get(Path, Object, Default) -> Result

Path = path()
Object = j_obj()
Default = any()
Result = jwalk_return()

Return a value from an Obj or Default if value not found.

Path elements that are strings can be binary or not - they are converted to binary if not.

See get/2.

set/3

set(Path, Object, Value) -> NewObject | no_return()

Path = path()
Object = j_obj()
Value = value() | j_obj() | [value() | j_obj(), ...]
NewObject = j_obj()

Set a value in Obj.

Replace the value at the specified Path with Value and return the new structure. If the final element of the Path does not exist, create it. The atom, new, applied to an ARRAY, will make the Value the first Element in an Array, creating that Array if necessary.

Path elements that are strings can be binary or not - they are converted to binary if not.

Throws
{no_path, _}
{selector_used_on_object, _}
{selector_used_on_non_list, _, _}
{index_for_non_list, _}
{replacing_object_with_value, _}
{index_out_of_bounds, _, _}.

set_p/3

set_p(Path, Object, Value) -> NewObject

Path = path()
Object = j_obj()
Value = value() | j_obj() | [value() | j_obj(), ...]
NewObject = j_obj()

Same as set/3 but creates intermediary elements as necessary.

Generated by EDoc