Add README

LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Anton Lavrik, http://github.com/alavrik
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README

@@ -0,0 +1,104 @@
+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().
+