From 0ec036ca7f7a932d19fa2d8562f72e36766e68d2 Mon Sep 17 00:00:00 2001
From: Spiros Eliopoulos <seliopou@gmail.com>
Date: Sun, 26 Mar 2017 22:04:19 +0000
Subject: [PATCH] docs: update README

---
 README.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/README.md b/README.md
index 81ecdcc..02d598f 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,55 @@ Install the library and its depenencies via [OPAM][opam]:
 opam install faraday
 ```
 
+## Usage
+
+Like its sister project [Angstrom][], Faraday is written with network protocols
+and serialization formats in mind. As such, its source distribution inclues
+implementations of various RFCs that are illustrative of real-world
+applications of the library. This includes a [JSON serializer][json].
+
+[angstrom]: https://github.com/inhabitedtype/angstrom
+[json]: https://github.com/inhabitedtype/faraday/blob/master/examples/rFC7159.ml
+
+In addition, it's appropriate here to include a serializer for the simple
+arithmetic expression language described in Angstrom's README.
+
+```ocaml
+open Faraday
+
+type 'a binop = [
+  | `Sub of 'a * 'a
+  | `Add of 'a * 'a
+  | `Div of 'a * 'a
+  | `Mul of 'a * 'a
+]
+;;
+
+type t = [ `Num of int | t binop ]
+
+let rec serialize ?(prec=0) t expr =
+  match expr with
+  | `Num n          -> write_string t (Printf.sprintf "%d" n)
+  | #binop as binop ->
+    let prec', op, l, r =
+      match binop with
+      | `Sub(l, r) -> 2, '-', l, r
+      | `Add(l, r) -> 3, '+', l, r
+      | `Div(l, r) -> 4, '/', l, r
+      | `Mul(l, r) -> 5, '*', l, r
+    in
+    if prec' < prec then write_char t '(';
+    serialize t ~prec:prec' l;
+    write_char t op;
+    serialize t ~prec:prec' r;
+    if prec' < prec then write_char t ')'
+
+let to_string expr =
+  let t = create 0x1000 in
+  serialize t expr;
+  serialize_to_string t
+```
+
 ## Development
 
 To install development dependencies, pin the package from the root of the