Elaborate README; add a section for ppx_tyre.

Author: paurkedal

README.md

@@ -1,19 +1,32 @@
-[![Build Status](https://travis-ci.org/paurkedal/ppx_regexp.svg?branch=master)](https://travis-ci.org/paurkedal/ppx_compose)
+[![Build Status][ci-build-status]][ci]
 
-`ppx_regexp` - Matching Regular Expressions with OCaml Patterns
----------------------------------------------------------------
+# Two PPXes for Working with Regular Expressions
+
+This repo provides two PPXes providing regular expression-based routing:
+
+- `ppx_regexp` maps to [re][] with the conventional last-match extraction
+  into `string` and `string option`.  It works directly on strings.
+- `ppx_tyre` maps to [Tyre][tyre] providing typed extraction into options,
+  lists, tuples, objects, and polymorphic variants.  It defines `Tyre.t` and
+  `Tyre.route` values.
+
+Another difference is that `ppx_regexp` works directly on strings
+essentially hiding the library calls, while `ppx_tyre` provides `Tyre.t` and
+`Tyre.route` which can be composed an applied using the Tyre library.
+
+## `ppx_regexp` - Regular Expression Matching with OCaml Patterns
 
 This syntax extension turns
 ```ocaml
-match%pcre x with
+function%pcre
 | {|re1|} -> e1
 ...
 | {|reN|} -> eN
 | _ -> e0
 ```
-into suitable invocations of the
-[Re library](https://github.com/ocaml/ocaml-re).  The patterns are plain
-strings of the form accepted by `Re_pcre`, with the following additions:
+into suitable invocations of the [Re library][re], and similar for
+`match%pcre`.  The patterns are plain strings of the form accepted by
+`Re_pcre`, with the following additions:
 
   - `(?<var>...)` defines a group and binds whatever it matches as `var`.
     The type of `var` will be `string` if the match is guaranteed given that
@@ -27,7 +40,7 @@ A variable is allowed for the universal case and is bound to the matched
 string.  A regular alias is currently not allowed for patterns, since it is
 not obvious whether is should bind the full string or group 0.
 
-## Example
+### Example
 
 The following prints out times and hosts for SMTP connections to the Postfix
 daemon:
@@ -51,6 +64,35 @@ let () = Lwt_main.run begin
 end
 ```
 
+## `ppx_tyre` - Syntax Support for Tyre Routes
+
+This PPX compiles
+```ocaml
+    [%tyre {|re|}]
+```
+into `'a Tyre.t` and
+```ocaml
+    function%tyre
+    | {|re1|} as x1 -> e1
+    ...
+    | {|reN|} as x2 -> eN
+```
+into `'a Type.route`, where `re`, `re1`, ... are regular expressions
+expressed in a slightly extended subset of PCRE.  The interpretations are:
+
+- `re?` extracts an option of what `re` extracts.
+- `re+`, `re*`, `re{n,m}` extracts a list of what `re` extracts.
+- `(?@qname)` refers to any identifier bound to a typed regular expression
+  of type `'a Tyre.t`.
+- One or more `(?<v>re)` at the top level can be used to bind variables
+  instead of `as ...`.
+- One or more `(?<v>re)` in a sequence extracts an object where each method
+  `v` is bound to what `re` extracts.
+- An alternative with one `(?<v>re)` per branch extracts a polymorphic
+  variant where each constructor `` `v`` receives what `re` extracts as its
+  argument.
+- `(?&v:qname)` is a shortcut for `(?<v>(?&qname))`.
+
 ## Limitations
 
 ### No Pattern Guards
@@ -72,3 +114,9 @@ ideally produce a counter-example.
 The processor is currently new and not well tested.  Please break it and
 file bug reports in the GitHub issue tracker.  Any exception raised by
 generated code except for `Match_failure` is a bug.
+
+
+[ci]: https://travis-ci.org/paurkedal/ppx_compose
+[ci-build-status]: https://travis-ci.org/paurkedal/ppx_regexp.svg?branch=master
+[re]: https://github.com/ocaml/ocaml-re
+[tyre]: https://github.com/Drup/tyre

ppx_tyre.descr

@@ -18,6 +18,8 @@ expressed in a slightly extended subset of PCRE.  The interpretations are:
 - `re+`, `re*`, `re{n,m}` extracts a list of what `re` extracts.
 - `(?@qname)` refers to any identifier bound to a typed regular expression
   of type `'a Tyre.t`.
+- One or more `(?<v>re)` at the top level can be used to bind variables
+  instead of `as ...`.
 - One or more `(?<v>re)` in a sequence extracts an object where each method
   `v` is bound to what `re` extracts.
 - An alternative with one `(?<v>re)` per branch extracts a polymorphic