View Source nm (nm v0.0.1)
nm
is tool to help handling deeply nested structure.
It works by unnesting your data into a ets table, allowing you to handle transformations in a simple
and easy way.
Once you finished manipulating your data in the way you want, it allows you to nest the data back
with all the applied changes.
It provides simple operations to get, update and delete values in a meaninful way.
To keep it as simple as possible, initially we're considering only maps and simple lists as
nesteable structures.
When unnesting, everytime nm
finds a nesteable structure, it gonna replace it by nm_ref/0
and also unnest it recursevely.
So for exemple a list of maps like [#{}, #{}]
, would be unnested to
[{'$nm_ref', Id1}, {'$nm_ref', Id2}]
.
This can help handling deeply nested structures because when transforming some data referencing
it by it's nested_id/0
, you don't need to update all the parent structures for this change
to take efffect.
After all transformations you can nest the structure again and use it externaly to your system.
Keep in mind that proplists and tuples won't be unnested, so if nm
finds a tuple while unnesting
it gonna consider it a literal value for a thing.
For exemlo, now let's think of a list with a map and a tuple [#{}, {1, 2 , 3}]
, after unnesting it
you gonna have [{'$nm_ref', Id}, {1, 2, 3}]
.
Summary
Types
Identifiers for nested structure.
root
is the begining of the nested structure, all other inner structures are binaries.
null
is used only as parent for root
.
A nested structure of maps
and lists
.
An ETS table configured as set
and protected
with the unnested structure.
A map with the value of an unnested_structure/0
and it's metadata.
A tag to reference a value that was unnested
A unnested strucutre, any value that was another nested_structure is replaced by nm_ref/0
.
Functions
Removes the node identified by the id. Also remove the reference to the node in the parent and all the subtrees of children of the node.
Update a node without removing children nodes or unnesting all it's values. Useful when you want to do simple updates that doesn't change relation with children nodes. For example, adding a new field to a map that is a literal or changing the order of a list.
Returns a node of the table. The node contains the actual value and metadata as the current node id and the parent node id.
Get the actual value of the node.
It nests the entire table back into a nested structure. Re-nesting the table won't remove anything from the table.
It nests just a subtree of the table, starting from the id provided.
Just as nm:nest/1
, re-nesting the information won't remove it from the table.
This is useful when you want to modify an entire subtreee of the data.
Take a nested data structure and unnest it into a ets table.
Update a node of the table with a new value.
This operation will discard all children of the node and recursevely unnest all it's values.
Can be used in conjunction with nm:partial_nest/2
to change entire subtrees.
In case you're changing just literals and not adding or removing a nested data structure,
you might want to sue nm:fast_update/3
.
Types
-type nested_id() :: root | null | binary().
Identifiers for nested structure.
root
is the begining of the nested structure, all other inner structures are binaries.
null
is used only as parent for root
.
A nested structure of maps
and lists
.
-type nested_table() :: ets:table().
An ETS table configured as set
and protected
with the unnested structure.
-type nm_node() :: #{ref => nested_id(), parent => nested_id(), value => unnested_structure()}.
A map with the value of an unnested_structure/0
and it's metadata.
ref
: thenested_id/0
of the structure.parent
: thenested_id/0
of the parent structure.value
: the actualunnested_structure/0
value.
-type nm_ref() :: {'$nm_ref', nested_id()}.
A tag to reference a value that was unnested
A unnested strucutre, any value that was another nested_structure is replaced by nm_ref/0
.
Functions
-spec delete(nested_table(), nested_id()) -> ok | {error, atom()}.
Removes the node identified by the id. Also remove the reference to the node in the parent and all the subtrees of children of the node.
-spec fast_delete(nested_table(), nested_id()) -> ok | {error, atom()}.
-spec fast_update(nested_table(), nested_id(), unnested_structure()) -> ok | {error, atom()}.
Update a node without removing children nodes or unnesting all it's values. Useful when you want to do simple updates that doesn't change relation with children nodes. For example, adding a new field to a map that is a literal or changing the order of a list.
-spec get_node(nested_table(), nested_id()) -> {ok, nm_node()} | {error, atom()}.
Returns a node of the table. The node contains the actual value and metadata as the current node id and the parent node id.
-spec get_value(nested_table(), nested_id()) -> {ok, unnested_structure()} | {error, atom()}.
Get the actual value of the node.
-spec nest(nested_table()) -> {ok, nested_structure()} | {error, atom()}.
It nests the entire table back into a nested structure. Re-nesting the table won't remove anything from the table.
-spec partial_nest(nested_table(), nested_id()) -> {ok, nested_structure()} | {error, atom()}.
It nests just a subtree of the table, starting from the id provided.
Just as nm:nest/1
, re-nesting the information won't remove it from the table.
This is useful when you want to modify an entire subtreee of the data.
-spec unnest(nested_structure()) -> {ok, nested_table()} | {error, atom()}.
Take a nested data structure and unnest it into a ets table.
-spec update(nested_table(), nested_id(), nested_structure()) -> ok | {error, atom()}.
Update a node of the table with a new value.
This operation will discard all children of the node and recursevely unnest all it's values.
Can be used in conjunction with nm:partial_nest/2
to change entire subtrees.
In case you're changing just literals and not adding or removing a nested data structure,
you might want to sue nm:fast_update/3
.