Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Erlang Simple Object Notation - dynamic name-value dictionary data type and syntax for Erlang
Erlang Shell
tree: 6d56d16101

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
include
shell/src
src
test
.gitignore
LICENSE
Makefile
README
rebar
rebar.config

README

Erlson - Erlang Simple Object Notation
======================================

Erlson is a dynamic name-value dictionary data type for Erlang.

Erlson dictionaries come with a convenient syntax and can be directly converted
to and from JSON.

Examples:
```
    % creating an empty dictionary
    X = #{},

    % associating field 'foo' with 1 and 'bar' with "abc"
    D = #{foo = 1, bar = "abc"},

    % accessing dictionary element
    1 = D.foo,

    % adding nested dictionaries to dictionary D
    D1 = D#{baz = #{fum = #{i = 0}}},

    % accessing elements of the nested dictionary
    0 = D1.baz.fum.i,

    % modifying elements of the nested dictionary
    D2 = D1#{baz.fum.i = 100, baz.fum.j = "new nested value"}.

    ...

    % converting Erlson dictionary to JSON iolist()
    erlson:to_json(D2).

    % creating Erlson dictionary from JSON iolist()
    D = erlson:from_json(Json).
'''

General properties
------------------

    * Erlson dictionaries contain zero or more Name->Value associations
      (fields), where each Name is `atom()` or `binary()` and Value can be of
      `any()` type.

    * Name->Value associations are unique. If a new association is created for the
      existing Name, the old value will be replaced by the new value.

    * Erlson dictionaries can be nested.


Runtime properties
------------------

    * Only fields with `atom()` names can be accessed using the Erlson
      dictionary syntax.

    * Unlike Erlang records, Erlson dictionaries can be dynamically constructed
      without any static type declarations.

    * At runtime, Erlson dictionaries are represented as a list of {Name, Value}
      tuples ordered by Name. This way, each Erlson dictionary is a valid
      `proplist` and `orddict` in terms of the correspondent stdlib modules.

    * Erlson dictionaries (dictionary syntax) can't be used as patterns and in
      guard expressions.

    * Erlson dicts can be used in both compiled modules and Erlang interactive
      shell.


Properties related to JSON
--------------------------

    * Each valid JSON object can be converted to correspondent Erlson
      dictionary.

    * An Erlson dictionary can be converted to JSON if it follows JSON data
      model.

    * JSON->Erlson->JSON conversion should produces an equivalent JSON object
      (fields will be reordered).


Usage instructions
-----------------

For compiled modules that use Erlson syntax, the Erlson library header must be
included:

    -include_lib("erlson/include/erlson.hrl").


When rebar is used as a build tool, it should be configured to use
"erlson_rebar_plugin". In order to do that, add the following line to the
project's "rebar.config" file:

    {rebar_plugins, [erlson_rebar_plugin]}.


In order to use Erlson syntax from Erlang shell, run the following command (e.g.
include it in `.erlang` file):
    
    erlson:init().

Something went wrong with that request. Please try again.