Documentation update for 2.0.0.

psfblair · Jan 22, 2016 · edd8724 · edd8724
1 parent 95fba71
commit edd8724
Show file tree

Hide file tree

Showing 6 changed files with 90 additions and 39 deletions.
diff --git a/doc/404.html b/doc/404.html
@@ -5,7 +5,7 @@
     <meta http-equiv="x-ua-compatible" content="ie=edge">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <meta name="generator" content="ExDoc v0.11.3">
-    <title>404 – exdn v1.0.1</title>
+    <title>404 – exdn v2.0.0</title>
     <link rel="stylesheet" href="dist/app-ddd9717ad9.css" />
     <script src="dist/sidebar_items.js"></script>
   </head>
@@ -27,7 +27,7 @@ <h1 class="sidebar-projectName">
         exdn
       </h1>
       <h2 class="sidebar-projectVersion">
-        v1.0.1
+        v2.0.0
       </h2>
     </div>
 

diff --git a/doc/Exdn.html b/doc/Exdn.html
@@ -5,7 +5,7 @@
     <meta http-equiv="x-ua-compatible" content="ie=edge">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <meta name="generator" content="ExDoc v0.11.3">
-    <title>Exdn – exdn v1.0.1</title>
+    <title>Exdn – exdn v2.0.0</title>
     <link rel="stylesheet" href="dist/app-ddd9717ad9.css" />
     <script src="dist/sidebar_items.js"></script>
   </head>
@@ -27,7 +27,7 @@ <h1 class="sidebar-projectName">
         exdn
       </h1>
       <h2 class="sidebar-projectVersion">
-        v1.0.1
+        v2.0.0
       </h2>
     </div>
 
@@ -59,7 +59,7 @@ <h2 class="sidebar-projectVersion">
 
 
       <h1>
-        <small class="visible-xs">exdn v1.0.1</small>
+        <small class="visible-xs">exdn v2.0.0</small>
         Exdn
 
 
@@ -91,7 +91,7 @@ <h2>Type mappings:</h2>
 </colgroup>
 <thead>
 <tr>
-<th style="text-align: left">edn</th><th style="text-align: left">Elixir generated by <code class="inline">to_elixir</code> functions</th>
+<th style="text-align: left">edn</th><th style="text-align: left">Elixir generated by <code class="inline">to_elixir</code> functions (when no custom converter is provided)</th>
 </tr>
 </thead>
 <tr>
@@ -169,6 +169,9 @@ <h2>Type mappings:</h2>
 <td style="text-align: left">map</td><td style="text-align: left">map</td>
 </tr>
 <tr>
+<td style="text-align: left">struct</td><td style="text-align: left">map</td>
+</tr>
+<tr>
 <td style="text-align: left">mapset</td><td style="text-align: left">set</td>
 </tr>
 <tr>
@@ -199,12 +202,11 @@ <h2>
     </h2>
     <div class="summary-row">
   <div class="summary-signature">
-    <a href="#evaluate_tagged_expr/2">evaluate_tagged_expr(arg, handlers)</a>
+    <a href="#evaluate_tagged_expr/3">evaluate_tagged_expr(arg, converter, handlers)</a>
   </div>
 
     <div class="summary-synopsis"><p>interprets a tagged expression using the tagged reversible representation and
-  handlers passed in as a keyword list. Does not operate at all
-  on the contents of the extracted list</p>
+  handlers passed in as a keyword list</p>
 </div>
 
 </div>
@@ -228,6 +230,17 @@ <h2>
   an edn string. Will raise exceptions if the data structure cannot be converted</p>
 </div>
 
+</div>
+<div class="summary-row">
+  <div class="summary-signature">
+    <a href="#standard_handlers/0">standard_handlers()</a>
+  </div>
+
+    <div class="summary-synopsis"><p>handlers for standard edn tagged expressions #inst and #uuid. If you need to supply
+   your own custom handlers for other tags, you may wish to append them to this list of
+   handlers</p>
+</div>
+
 </div>
 <div class="summary-row">
   <div class="summary-signature">
@@ -250,7 +263,7 @@ <h2>
 </div>
 <div class="summary-row">
   <div class="summary-signature">
-    <a href="#to_elixir/2">to_elixir(val, handlers \\ standard_handlers)</a>
+    <a href="#to_elixir/3">to_elixir(val, converter \\ fn x -&gt; x end, handlers \\ standard_handlers)</a>
   </div>
 
     <div class="summary-synopsis"><p>parses an edn string into an Elixir data structure, but does not throw
@@ -262,7 +275,7 @@ <h2>
 </div>
 <div class="summary-row">
   <div class="summary-signature">
-    <a href="#to_elixir!/2">to_elixir!(edn, handlers \\ standard_handlers)</a>
+    <a href="#to_elixir!/3">to_elixir!(edn, converter \\ fn x -&gt; x end, handlers \\ standard_handlers)</a>
   </div>
 
     <div class="summary-synopsis"><p>parses an edn string into an Elixir data structure; this is not a reversible
@@ -304,22 +317,21 @@ <h1 class="section-heading">
             </a>
             Functions
           </h1>
-          <div class="detail" id="evaluate_tagged_expr/2">
+          <div class="detail" id="evaluate_tagged_expr/3">
   <div class="detail-header">
-    <a href="#evaluate_tagged_expr/2" class="detail-link" title="Link to this function">
+    <a href="#evaluate_tagged_expr/3" class="detail-link" title="Link to this function">
       <i class="icon-link"></i>
     </a>
-    <span class="signature">evaluate_tagged_expr(arg, handlers)</span>
+    <span class="signature">evaluate_tagged_expr(arg, converter, handlers)</span>
 
   </div>
 
   <section class="docstring">
     <p>  interprets a tagged expression using the tagged reversible representation and
-  handlers passed in as a keyword list. Does not operate at all
-  on the contents of the extracted list.</p>
+  handlers passed in as a keyword list.</p>
 <h2>Example:</h2>
 <pre><code class="iex elixir">iex&gt; tagged = {:tag, :foo, &quot;blarg&quot;}
-iex&gt; handler = fn(_tag, val, _handlers) -&gt; val &lt;&gt; &quot;-converted&quot; end
+iex&gt; handler = fn(_tag, val, _converter, _handlers) -&gt; val &lt;&gt; &quot;-converted&quot; end
 iex&gt; Exdn.evaluate_tagged_expr(tagged, [{:foo, handler}]
 &quot;blarg-converted&quot;</code></pre>
 
@@ -392,11 +404,30 @@ <h2>Examples:</h2>
 iex&gt; Exdn.from_elixir! %{1 =&gt; :foo, 2 =&gt; :bar}
 &quot;{1 :foo 2 :bar}&quot;
 
+iex&gt; Exdn.from_elixir! %SomeStruct{foo: 1, bar: 2}
+&quot;{:foo 1 :bar 2}&quot;
+
 iex&gt; Exdn.from_elixir! {:tag, :inst, &quot;1985-04-12T23:20:50.52Z&quot;}
 &quot;#inst &quot;1985-04-12T23:20:50.52Z&quot;&quot;</code></pre>
 
   </section>
 </div>
+<div class="detail" id="standard_handlers/0">
+  <div class="detail-header">
+    <a href="#standard_handlers/0" class="detail-link" title="Link to this function">
+      <i class="icon-link"></i>
+    </a>
+    <span class="signature">standard_handlers()</span>
+
+  </div>
+
+  <section class="docstring">
+    <p>   handlers for standard edn tagged expressions #inst and #uuid. If you need to supply
+   your own custom handlers for other tags, you may wish to append them to this list of
+   handlers.</p>
+
+  </section>
+</div>
 <div class="detail" id="tagged_char_to_string/1">
   <div class="detail-header">
     <a href="#tagged_char_to_string/1" class="detail-link" title="Link to this function">
@@ -432,12 +463,12 @@ <h2>Example:</h2>
 
   </section>
 </div>
-<div class="detail" id="to_elixir/2">
+<div class="detail" id="to_elixir/3">
   <div class="detail-header">
-    <a href="#to_elixir/2" class="detail-link" title="Link to this function">
+    <a href="#to_elixir/3" class="detail-link" title="Link to this function">
       <i class="icon-link"></i>
     </a>
-    <span class="signature">to_elixir(val, handlers \\ standard_handlers)</span>
+    <span class="signature">to_elixir(val, converter \\ fn x -&gt; x end, handlers \\ standard_handlers)</span>
 
   </div>
 
@@ -447,19 +478,20 @@ <h2>Example:</h2>
  whose first element is <code class="inline">:ok</code> — if there is an error the first element will
  be <code class="inline">:error</code> and the second the error that was raised.</p>
 <h2>Examples:</h2>
-<p>   iex&gt; Exdn.to_elixir “{1 :foo, 2 :bar}”
-   {:ok, %{1 =&gt; :foo, 2 =&gt; :bar}}</p>
-<p>   iex&gt; Exdn.to_elixir “{:foo, \a, \b #foo “blarg” }”
-   {:error, %RuntimeError{:message =&gt; “Handler not found for tag foo with tagged expression blarg”}}</p>
+<pre><code class="iex elixir">iex&gt; Exdn.to_elixir &quot;{1 :foo, 2 :bar}&quot;
+{:ok, %{1 =&gt; :foo, 2 =&gt; :bar}}
+
+iex&gt; Exdn.to_elixir &quot;{:foo, \a, \b #foo &quot;blarg&quot; }&quot;
+{:error, %RuntimeError{:message =&gt; &quot;Handler not found for tag foo with tagged expression blarg&quot;}}</code></pre>
 
   </section>
 </div>
-<div class="detail" id="to_elixir!/2">
+<div class="detail" id="to_elixir!/3">
   <div class="detail-header">
-    <a href="#to_elixir!/2" class="detail-link" title="Link to this function">
+    <a href="#to_elixir!/3" class="detail-link" title="Link to this function">
       <i class="icon-link"></i>
     </a>
-    <span class="signature">to_elixir!(edn, handlers \\ standard_handlers)</span>
+    <span class="signature">to_elixir!(edn, converter \\ fn x -&gt; x end, handlers \\ standard_handlers)</span>
 
   </div>
 
@@ -468,7 +500,8 @@ <h2>Examples:</h2>
    conversion as chars are converted to strings, and tagged expressions are
    interpreted. This function can throw exceptions; for example, if a tagged
    expression cannot be interpreted.</p>
-<p>   The second (optional) argument allows you to supply your own handlers for
+<p>   The second (optional) argument</p>
+<p>   The third (optional) argument allows you to supply your own handlers for
    the interpretation of tagged expressions. These should be in the form of a
    keyword list. The first element of each pair should be a keyword corresponding
    to the tag, and the second element a function of three parameters
@@ -516,6 +549,19 @@ <h2>Examples:</h2>
 iex&gt; Exdn.to_elixir! &quot;{1 :foo, 2 :bar}&quot;
 %{1 =&gt; :foo, 2 =&gt; :bar}
 
+# You can also transform maps to Elixir structs by providing your own converter in the second argument:
+iex&gt; defmodule FooStruct do
+...&gt;    defstruct foo: &quot;default&quot;
+...&gt; end
+iex&gt; converter = fn map -&gt;
+...&gt;    case map do
+...&gt;       %{:foo =&gt; _} -&gt; struct(FooStruct, map)
+...&gt;       anything_else -&gt; anything_else
+...&gt;     end
+...&gt;   end
+iex&gt;  Exdn.to_elixir! &quot;{:foo 1, :bar 2}&quot;, converter
+%FooStruct{foo: 1}
+
 # Tagged expressions are converted. Standard converters for #inst and #uuid are included:
 iex&gt; Exdn.to_elixir! &quot;#inst &quot;1985-04-12T23:20:50.52Z&quot;&quot;
 %Calendar.DateTime{abbr: &quot;UTC&quot;, day: 12, hour: 23, min: 20, month: 4, sec: 50,

diff --git a/doc/api-reference.html b/doc/api-reference.html
@@ -5,7 +5,7 @@
     <meta http-equiv="x-ua-compatible" content="ie=edge">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <meta name="generator" content="ExDoc v0.11.3">
-    <title>API Reference – exdn v1.0.1</title>
+    <title>API Reference – exdn v2.0.0</title>
     <link rel="stylesheet" href="dist/app-ddd9717ad9.css" />
     <script src="dist/sidebar_items.js"></script>
   </head>
@@ -27,7 +27,7 @@ <h1 class="sidebar-projectName">
         exdn
       </h1>
       <h2 class="sidebar-projectVersion">
-        v1.0.1
+        v2.0.0
       </h2>
     </div>
 
@@ -58,7 +58,7 @@ <h2 class="sidebar-projectVersion">
   <div id="content" class="content-inner">
 
   <h1>
-    <small class="visible-xs">exdn v1.0.1</small>
+    <small class="visible-xs">exdn v2.0.0</small>
     API Reference
   </h1>
 

diff --git a/doc/dist/sidebar_items.js b/doc/dist/sidebar_items.js
diff --git a/doc/index.html b/doc/index.html
@@ -2,7 +2,7 @@
 <html>
   <head>
     <meta charset="utf-8">
-    <title>exdn v1.0.1 – Documentation</title>
+    <title>exdn v2.0.0 – Documentation</title>
     <meta http-equiv="refresh" content="0; url=api-reference.html">
     <meta name="robots" content="noindex">
     <meta name="generator" content="ExDoc v0.11.3">

diff --git a/lib/exdn.ex b/lib/exdn.ex
@@ -21,7 +21,7 @@ defmodule Exdn do
 
     ## Type mappings:
 
-      edn	              | Elixir generated by `to_elixir` functions
+      edn	              | Elixir generated by `to_elixir` functions (when no custom converter is provided)
       ---------------   | -----------------------------------------
       integer	          | integer
       float	            | float
@@ -47,6 +47,7 @@ defmodule Exdn do
       tagged list `{:list, [...]}`                            | list
       list                                                    | vector
       map                                                     | map
+      struct                                                  | map
       mapset                                                  | set
       tagged atom `{:symbol, atom}`                           | symbol
       tagged tuple with tag and value `{:tag, Symbol, Value}` | tagged elements
@@ -150,11 +151,11 @@ defmodule Exdn do
 
 ## Examples:
 
-     iex> Exdn.to_elixir "{1 :foo, 2 :bar}"
-     {:ok, %{1 => :foo, 2 => :bar}}
+      iex> Exdn.to_elixir "{1 :foo, 2 :bar}"
+      {:ok, %{1 => :foo, 2 => :bar}}
 
-     iex> Exdn.to_elixir "{:foo, \\a, \\b #foo \"blarg\" }"
-     {:error, %RuntimeError{:message => "Handler not found for tag foo with tagged expression blarg"}}
+      iex> Exdn.to_elixir "{:foo, \\a, \\b #foo \"blarg\" }"
+      {:error, %RuntimeError{:message => "Handler not found for tag foo with tagged expression blarg"}}
   """
   def to_elixir(val, converter \\ (fn x -> x end), handlers \\ standard_handlers) do
     try do
@@ -382,7 +383,11 @@ defmodule Exdn do
     end
   end
 
-  # Handlers
+  @doc """
+     handlers for standard edn tagged expressions #inst and #uuid. If you need to supply
+     your own custom handlers for other tags, you may wish to append them to this list of
+     handlers.
+  """
   def standard_handlers do
     timestamp_handler = { :inst, fn(_tag, val, _converter, _handlers) -> inst_handler(val) end }
     uuid_handler = { :uuid, fn(_tag, val, _converter, _handlers) -> val |> to_string end }