Merge pull request #4 from inhabitedtype/docs

docs

README.md

@@ -1,10 +1,12 @@
 # Faraday
 
-Faraday is a library of low-level primitives for writing serializers for
-user-defined datatypes. Its primitives provide the user fine-grained control
-over copying and allocation behavior, and presents serialization output in a
-form that is suitable for use with vectorized writes via the [writev][] system
-call or any other platform or application-specific output interfaces.
+Faraday is a library for writing fast and memory-efficient serializers. Its
+core type and related operation gives the user fine-grained control over
+copying and allocation behavior while serializing user-defined types, and
+presents the output in a form that makes it possible to use vectorized write
+operations, such as the [writev][] system call, or any other platform or
+application-specific output APIs.
+
 
 [![Build Status](https://travis-ci.org/inhabitedtype/faraday.svg?branch=master)](https://travis-ci.org/inhabitedtype/faraday)
 
@@ -20,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

_oasis

@@ -9,7 +9,14 @@ License:     BSD-3-clause
 Plugins:     META (0.4), DevFiles (0.4)
 BuildTools:  ocamlbuild
 OCamlVersion:>= 4.02
-Synopsis:    Serialization library built for speed and memory-efficiency
+Synopsis:    A library for writing fast and memory-efficient serializers.
+Description:
+    Faraday is a library for writing fast and memory-efficient serializers. Its
+    core type and related operation gives the user fine-grained control over
+    copying and allocation behavior while serializing user-defined types, and
+    presents the output in a form that makes it possible to use vectorized
+    write operations, such as the writev system call, or any other platform or
+    application-specific output APIs.
 
 
 Flag async

lib/META

@@ -1,7 +1,7 @@
 # OASIS_START
-# DO NOT EDIT (digest: ab59c28122af5ac111219914acc302f6)
+# DO NOT EDIT (digest: 9e3bce218cef899cb8c71404bb9e4802)
 version = "dev"
-description = "Serialization library built for speed and memory-efficiency"
+description = "A library for writing fast and memory-efficient serializers."
 requires = "bigarray ocplib-endian ocplib-endian.bigstring"
 archive(byte) = "faraday.cma"
 archive(byte, plugin) = "faraday.cma"
@@ -10,7 +10,7 @@ archive(native, plugin) = "faraday.cmxs"
 exists_if = "faraday.cma"
 package "lwt-unix" (
  version = "dev"
- description = "Serialization library built for speed and memory-efficiency"
+ description = "A library for writing fast and memory-efficient serializers."
  requires = "faraday.lwt lwt.unix"
  archive(byte) = "faraday_lwt_unix.cma"
  archive(byte, plugin) = "faraday_lwt_unix.cma"
@@ -21,7 +21,7 @@ package "lwt-unix" (
 
 package "lwt" (
  version = "dev"
- description = "Serialization library built for speed and memory-efficiency"
+ description = "A library for writing fast and memory-efficient serializers."
  requires = "faraday lwt"
  archive(byte) = "faraday_lwt.cma"
  archive(byte, plugin) = "faraday_lwt.cma"
@@ -32,7 +32,7 @@ package "lwt" (
 
 package "async" (
  version = "dev"
- description = "Serialization library built for speed and memory-efficiency"
+ description = "A library for writing fast and memory-efficient serializers."
  requires = "async core faraday threads"
  archive(byte) = "faraday_async.cma"
  archive(byte, plugin) = "faraday_async.cma"

lib/faraday.mli

@@ -33,12 +33,13 @@
 
 (** Serialization primitives built for speed an memory-efficiency.
 
-    Faraday is a library of low-level primitives for writing serializers for
-    user-defined datatypes. Its primitives provide the user fine-grained
-    control over copying and allocation behavior, and presents serialization
-    output in a form that is suitable for use with vectorized writes via the
-    [writev] system call or any other platform or application-specific output
-    subsystem.
+
+    Faraday is a library for writing fast and memory-efficient serializers. Its
+    core type and related operation gives the user fine-grained control over
+    copying and allocation behavior while serializing user-defined types, and
+    presents the output in a form that makes it possible to use vectorized
+    write operations, such as the [writev][] system call, or any other platform
+    or application-specific output APIs.
 
     A Faraday serializer manages an internal buffer and a queue of output
     buffers. The output bufferes may be a sub range of the serializer's
@@ -99,6 +100,16 @@ val write_bigstring : t -> ?off:int -> ?len:int -> bigstring -> unit
     serializer's internal buffer. It is safe to modify [bytes] after this call
     returns.  *)
 
+val write_gen
+  :  t
+  -> length:('a -> int)
+  -> blit:('a -> int -> bigstring -> int -> int -> unit)
+  -> ?off:int
+  -> ?len:int
+  -> 'a -> unit
+(** [write_gen t ~length ~blit ?off ?len x] copies [x] into the serializer's
+    internal buffer using the provided [length] and [blit] operations. *)
+
 val write_char : t -> char -> unit
 (** [write_char t char] copies [char] into the serializer's internal buffer. *)