@@ -1,33 +1,35 @@
11name: syntax
22version: 1.0.0.0
3−synopsis: Syntax descriptions for unified parsing and pretty-printing.
3+synopsis: Reversible parsing and pretty-printing.
44description:
5− 'syntax' allows you to write a single syntax description and instantiate is both as a parser and a pretty printer.
5+ "syntax" allows you to write a single syntax description and instantiate is both as a parser and a pretty printer.
66 .
7− The interface is based on a custom Functor\/Applicative\/Monad hierarchy, provided by the 'semi-iso' package. You fmap using
8− a semi-isomorphism instead of function. A semi-isomorphism is a isomorphism that can fail in both directions, with slightly
9− weakened laws. It is worth to note that @Iso@s and @Prism@s from 'lens' are valid semi-isomorphisms :)
7+ Syntax descriptions are written in applicative or arrow style. The library uses a custom hierarchy, provided by the
8+ "semi-iso" package. Most of the time you will be using operators like '/$/' and '/*/', just like parser combinators.
9+ When more power is needed - e.g. when the syntax depends on the parsed or printed value - you turn to arrows.
1010 .
11− Once you write a description you can, for example turn it into an Attoparsec parser, or into a 'Data.Syntax.Printer.Text.Printer'.
11+ Semi-isomorphisms from "semi-iso" are the basic building block of syntax descriptions. I recommend reading
12+ the hackage page of "semi-iso" first, as it contains much more information.
1213 .
13− See @syntax-example@ and @syntax-example-json@ for examples, @syntax-attoparsec@ and @syntax-printer@ for a parser/printer implementation.
14+ Once you write a syntax description (polymorphic in the syntax category) you can instantiate it both as a parser or as
15+ a pretty-printer. The library "syntax-attoparsec" gives you the ability to extract an Attoparsec parser. Pretty-printing
16+ is implemented by the "syntax-printer" library, which uses Text and ByteString builders. (Note that formatting is handled
17+ by "syntax" itself, not by the printer library)
1418 .
15− The library was inspired by:
19+ Advanced formatting and parsing (for example indentation, haskell layout rule) is implemented as category transformers
20+ (similar to monad transformers). Currently only simple indentation is implemented (in "Data.Syntax.Indent") - basically
21+ a reader category transformer that tracks current indentation level. I plan on implementing Haskell layout rule in the
22+ future (as a reusable transformer).
1623 .
17− * Rendel, Tillmann, and Klaus Ostermann. "Invertible syntax descriptions: unifying parsing and pretty printing." ACM Sigplan Notices. Vol. 45. No. 11. ACM, 2010.
24+ Note that the library can work with both text and binary data. There are no binary combinators implemented - yet.
25+ Alas, these are not only useful combinators missing! I will slowly but steadily implement them over time
26+ (but these category transformers look so much more interesting for now ;).
1827 .
19− TODO:
28+ EXAMPLES! See @syntax-example@ and @syntax-example-json@ for examples.
2029 .
21− * Research relative monads and relative monad transformers. Indent is basically a Reader monad over a syntax. How would a State monad look?
30+ * "syntax-example" implements a simple lambda calculus.
2231 .
23− * Try to implement Haskell layout rule.
24− .
25− * Combinators for binary data formats, vectors.
26− .
27− * Better error messages.
28− .
29− * Maybe an implementation of do notation for SemiIsoMonad with QuasiQuoters, like the codo notation for comonads.
30−
32+ * "syntax-example-json" implements a json parser and pretty printer.
3133license: MIT
3234license-file: LICENSE
3335author: Paweł Nowak
@@ -46,5 +48,5 @@ library
4648 Data.Syntax.Char
4749 Data.Syntax.Combinator
4850 Data.Syntax.Indent
49− build-depends: base >= 4 && < 5, mono-traversable, lens >= 4, semi-iso >= 1.0.0.0, scientific >= 0.3, text
51+ build-depends: base >= 4 && < 5, mono-traversable, lens >= 4, semi-iso >= 1, scientific >= 0.3, text, vector
5052 default-language: Haskell2010