Minor 'README.md' update -- way to many features, way to many

README.md

@@ -42,19 +42,98 @@ configured application can have one or more sections, for example:
 
 ```yaml
 example:
+  srv_conf:
+    conn_type: http
+
   log_conf:
     log: "priv/log.txt"
     severity: debug
+
 ```
 
-Here, [example] [3] application defines a single section, named
-`log_conf`. As you might have noticed, applications are defined
-on the **top level** of the configuration file, with sections,
-residing on the **second level**.
+Here, [example] [3] application defines a two sections, named
+`log_conf` and `srv_conf`. So, as you might have noticed, the
+expected structure is simple:
+
+* applications are defined on the **top level** of the configuration file,
+* with sections, residing on the **second level**.
+
+> "Enough YAML, show me some Erlang code, dude?!"
+
+### Configuration path
+
+For flexibility reasons `nakaz` doesn't allow you to actually **read**
+configuration file from the code, instead, it handles reading and
+parsing internally, and all **you** have to do is pass path to the
+configuration file via command line:
+
+```bash
+$ erl -nakaz path/to/config.yaml
+```
+
+**Note**: the current implementation doesn't allow using multiple
+configuration files, but this might change in the future versions.
+
+### Applications
+
+As we've already mentioned, `nakaz` represents your application
+configuration as sections; what we haven't mentioned is that **every**
+section will be parsed into a **typed** Erlang record! Here's an
+[example] [4]:
+
+```erlang
+-module(my_awesome_app).
+-behaviour(application).
+-compile({parse_transform, nakaz_pt}).
+
+-include_lib("nakaz/include/nakaz.hrl").
+
+-type filename() :: string().
+
+-record(srv_conf, {conn_type :: http | ssl}).
+-record(log_conf, {log :: filename(),
+                   severity :: debug | info | error}).
+
+%% Application callbacks
+
+-export([start/2, stop/1]).
+
+%% Application callbacks
+
+start(_StartType, _StartArgs) ->
+    case ?NAKAZ_ENSURE([#srv_conf{}, #log_conf{}]) of
+        ok -> example_sup:start_link();
+        {error, Msg} -> io:format(Msg)
+    end.
+
+stop(_State) ->
+    ok.
+```
+
+What happens here? First thing to notice is `{parse_transform, nakaz_pt}`,
+this is **required** for all the record-related magic to happen. Second,
+`?NAKAZ_ENSURE()` macro -- as the name suggests, this macro *ensures*
+that the configration file actually contains all of the sections, required
+by your application. Moreover, `?NAKAZ_ENSURE()` also checks that the
+values in those sections **exactly** match the types you've declared in
+the record specs!
+
+If anything goes wrong, the `Msg` term will contain an understable
+description of the error.
+
+#### Why records?
+
+Probably, the use of records in `?NAKAZ_ENSURE()` call looks a little
+supprising, and you might be thinking
+`"wtf is wrong with those crazy russians?!"`. Here's the deal, forcing
+arguments to be records we actually make sure that each of them is
+a valid record and is available in the module scope (which is just what
+`nakaz_pt` needs!).
 
 [1]: http://www.yaml.org
 [2]: http://en.wikipedia.org/wiki/YAML#Associative_arrays
 [3]: https://github.com/Spawnfest2012/holybrolly-nakaz/blob/master/example/priv/conf.yaml
+[4]: https://github.com/Spawnfest2012/holybrolly-nakaz/blob/master/example/src/example_app.erl
 
 Why the name?
 -------------

example/src/example_app.erl

@@ -1,13 +1,15 @@
 -module(example_app).
 -behaviour(application).
 -compile({parse_transform, nakaz_pt}).
+
 -include_lib("nakaz/include/nakaz.hrl").
 -include("example.hrl").
 
 %% API
 -export([start/0, stop/0]).
 
 %% Application callbacks
+
 -export([start/2, stop/1]).
 
 %% API