Commits

Sebastien Mondet committed 3f2a5cd

doc: improve the `README.md` file

Comments (0)

Files changed (1)

 EDSL For Parsing S-Expressions
 ==============================
 
-When opening `Sexp_parser_edsl` you get a `Meta_parser` module
-implementing the `META_PARSER` interface.
+This is an experiment.  When opening `Sexp_parser_edsl` you get a
+`Meta_parser` module implementing the `META_PARSER` interface, which
+provides construction functions for building S-Expression parsing
+specifications in an embeded DSL.
 
 
 Example
 
 OCaml types this specification as:
 
-```
+```ocaml
 val parser :
   (expr,
    _[> `wrong_plus_expression of Sexp_parser_edsl.Meta_parser.location ])
 
 which means that `parser` is parser specification (`Meta_parser.t`)
 that parses to `expr`, and the standard parsing errors (see
-`META_PARSER.syntax_error`) will be augmented with
+`META_PARSER.syntax_error`) will be augmented with the
 `wrong_plus_expression` case.
 
 
-```
+Then, we define the `parse_expr` function using the parser
+specification:
+
+```ocaml
 let parse_expr input =
   Meta_parser.parse_string parser input
      ~syntax_error:(fun loc e -> `Syntax (loc, e))
   Sexp_parser_edsl.result = <fun>
 ```
 
+and we can start testing:
+
 ```ocaml
 let e1 = parse_expr "(+ 42 (+ 4.2 51) (+ 1))"
 ```
 
-```
+```ocaml
 val e1 :
-  (expr,
-   _[> `Syntax of
-         Sexp_parser_edsl.Meta_parser.location *
-         _[> `no_matching_rule of string
-           | `not_a_float of string
-           | `not_an_integer of string
-           | `nothing_left_to_try of string option * string
-           | `sexp of exn ]
-     | `wrong_plus_expression of Sexp_parser_edsl.Meta_parser.location ])
+  (expr, ...)
   Sexp_parser_edsl.result =
   `Ok
     (Binop_plus (Binop_plus (Int 42, Binop_plus (Float 4.2, Int 51)), Int 1))
 ```
 
-we see that the `"(+ 1)"` has been parser as `Int 1` (see special case
+we see that the `"(+ 1)"` has been parsed to `Int 1` (see special case
 above).
 
+Another example, when the parsing fails:
 
 ```ocaml
 let e2 = parse_expr "(+ 42 (+ 4.2 51) (+) (+ 1))"
 ```
 
-```
+the error value gives the location of the whole `Try_in_order`
+expression, more refined locations are *future work*:
+
+```ocaml
 val e2 :
   ... Sexp_parser_edsl.result =
   `Error