ReadMe.md

   1 ### Main differences with respect to `ParsleyHaskell`
   2
   3 - Primitive grammar combinators are extensible, including the optimization pass for which they are the current top-level combinator.
   4
   5 - Error messages are based upon the farthest input position reached (not yet implemented in `ParsleyHaskell`) and a there is a preliminary support for error messages based upon [labeled failures](https://dl.acm.org/doi/10.1145/2851613.2851750).
   6
   7 - Minimal input length checks ("horizon" checks) required for a successful parsing are statically computed using a [polyfix](http://okmij.org/ftp/Computation/fixed-point-combinators.html#Poly-variadic) to see beyond calls to subroutines, which is not (yet) possible in `ParsleyHaskell`.
   8
   9 - No dependency upon GHC plugins: `lift-plugin`, `idioms-plugin` or `parsley-garnish` for users. Those provide convenient syntaxic-sugar (by quoting an Haskell expression as itself and its `TemplateHaskell` equivalent) for writing grammar productions, but are experimental, but I do not understand them that much and do not feel confortable to maintain them in case their authors abandon them.
  10
  11 - No dependency upon `dependent-map` by keeping observed sharing in `def` and `ref` combinators, instead of passing by a `DMap`. And also when introducing the join-points optimization, where fresh `TemplateHaskell` names are also directly used instead of passing by a `DMap`.
  12
  13 - No support (yet?) for general purpose registers in the `Machine` producing the `TemplateHaskell` splices. Hence `symantic-parser` generates parser much slower than `ParsleyHaskell`, comparable to `attoparsec` in the Brainfuck benchmark.
  14
  15 - License is `AGPL-3-or-later` not `BSD-3-Clause`.
  16
  17 - Testing grammars have their generated machines and `TemplateHaskell` splices followed by golden tests.
  18
  19 ### Main goals
  20
  21 - For me to better understand [ParsleyHaskell](https://github.com/j-mie6/ParsleyHaskell), and find a manageable balance between simplicity of the codebase and features of the parser. And by doing so, challenging and showcasing symantic techniques.
  22
  23 - To support the parsing of tree-like data structures instead of only string-like data structures. Eg. to validate XML using RelaxNG in [symantic-xml](https://hackage.haskell.org/package/symantic-xml) or to perform routing of HTTP requests in [symantic-http-server](http://hackage.haskell.org/package/symantic-http-server). This is currently done in those packages using `megaparsec`, but `megaparsec` is not conceived for such input, and is less principled when it comes to optimizing, like merging alternatives.
  24
  25 ### Implementation techniques
  26
  27 #### Typed Tagless-Final
  28 The syntax of grammars are term-level combinators defined in type-classes,
  29 and their semantics are data-types having instances of those type-classes.
  30 And the same technique is applied for machine instructions and grammar productions.
  31
  32 For automatic deriving, `DefaultSignatures` are supplied, see `Symantic.Typed.Derive`.
  33
  34 For pattern-matching, data-families indexed by the syntaxic type-class are supplied,
  35 see `Symantic.Typed.Data`.