-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Reversible parsing and pretty-printing. -- -- "syntax" allows you to write a single syntax description and -- instantiate is both as a parser and a pretty printer. -- -- Syntax descriptions are written in applicative or arrow style. The -- library uses a custom typeclass hierarchy, provided by the "semi-iso" -- package. Most of the time you will be using operators like /$/, -- /*/ and /+/ (= <|>), just like parser -- combinators. When more power is needed - e.g. when the syntax depends -- on the parsed or printed value - you turn to arrows. -- -- Semi-isomorphisms from "semi-iso" are the basic building block of -- syntax descriptions. I recommend reading the hackage page of -- "semi-iso" first, as it contains much more information. -- -- Once you write a syntax description (polymorphic in the syntax -- category) you can instantiate it both as a parser or as a -- pretty-printer. The library "syntax-attoparsec" gives you the ability -- to extract an Attoparsec parser. Pretty-printing is implemented by the -- "syntax-printer" library, which uses Text and ByteString builders. -- (Note that formatting is handled by "syntax" itself, not by the -- printer library) -- -- Advanced formatting and parsing (for example indentation, haskell -- layout rule) is implemented as category transformers (similar to monad -- transformers). Currently only simple indentation is implemented (in -- Data.Syntax.Indent) - basically a reader category transformer -- that tracks current indentation level. I plan on implementing Haskell -- layout rule in the future. -- -- The library can work with both text and binary data. Alas, there are -- no binary combinators implemented yet. I will implement them when i -- have the time (but these category transformers look so much more -- interesting for now ;). -- -- EXAMPLES! See syntax-example and syntax-example-json -- for examples. -- -- @package syntax @version 1.0.0.0 -- | Reversible parsing and pretty-printing. module Data.Syntax -- | An abstract syntax description based on semi-isomorphisms. -- -- This class can be implemented by both parsers and printers. -- -- The usual use is to write a polymorphic syntax description and -- instantiate it both as a parser and a printer. Examples are available -- in 'syntax-example' and 'syntax-example-json' packages. -- -- Methods of this class try to mimic Data.Attoparsec.Text -- interface. class (SIArrow syn, IsSequence (Seq syn), Eq (Seq syn), Eq (Element (Seq syn))) => Syntax syn where type family Seq syn :: * char c = rev (exact c) /$/ anyChar notChar c = bifiltered (/= c) /$/ anyChar satisfy p = bifiltered p /$/ anyChar satisfyWith ai p = bifiltered p . ai /$/ anyChar string s = rev (exact s) /$/ take (olength s) take n = packed /$/ sireplicate n anyChar takeWhile p = packed /$/ simany (satisfy p) takeWhile1 p = packed /$/ sisome (satisfy p) takeTill p = takeWhile (not . p) takeTill1 p = takeWhile1 (not . p) vecN n e = packed /$/ sireplicate n e ivecN n e = (packed /$/) $ sisequence $ map (\ (i, e') -> constant i ^>> e' >>> first (sipure (constant i)) >># unit . swapped) $ zip [0 .. n - 1] (replicate n e) uvecN n e = packed /$/ sireplicate n e uivecN n e = (packed /$/) $ sisequence $ map (\ (i, e') -> constant i ^>> e' >>> first (sipure (constant i)) >># unit . swapped) $ zip [0 .. n - 1] (replicate n e) anyChar :: Syntax syn => syn () (Element (Seq syn)) char :: Syntax syn => Element (Seq syn) -> syn () () notChar :: Syntax syn => Element (Seq syn) -> syn () (Element (Seq syn)) satisfy :: Syntax syn => (Element (Seq syn) -> Bool) -> syn () (Element (Seq syn)) satisfyWith :: Syntax syn => ASemiIso' a (Element (Seq syn)) -> (a -> Bool) -> syn () a string :: Syntax syn => Seq syn -> syn () () take :: Syntax syn => Int -> syn () (Seq syn) takeWhile :: Syntax syn => (Element (Seq syn) -> Bool) -> syn () (Seq syn) takeWhile1 :: Syntax syn => (Element (Seq syn) -> Bool) -> syn () (Seq syn) takeTill :: Syntax syn => (Element (Seq syn) -> Bool) -> syn () (Seq syn) takeTill1 :: Syntax syn => (Element (Seq syn) -> Bool) -> syn () (Seq syn) vecN :: Syntax syn => Int -> syn () a -> syn () (Vector a) ivecN :: Syntax syn => Int -> syn Int (Int, a) -> syn () (Vector a) uvecN :: (Syntax syn, Unbox a) => Int -> syn () a -> syn () (Vector a) uivecN :: (Syntax syn, Unbox a) => Int -> syn Int (Int, a) -> syn () (Vector a) -- | Execute a computation in an isolated context. -- -- The motivating example: you want to write a function -- -- 
--   serializeList :: Syntax syn => syn () a -> syn () [a]
--
-- -- Notice that we cannot just use simany, because the first syn () -- a could eat the entire sequence (even though we printed more than -- 1 value!), so we have to insert some kind of separators between the -- element. But how can we be sure that syn () a will not eat -- our separators? We can't! Thats why we have to do the parsing in two -- stages: first extract the sequence between separators, then run the -- syn () a on this sequence. class Syntax syn => Isolable syn isolate :: Isolable syn => syn () b -> syn (Seq syn) b -- | An isomorphism between a sequence and a list of its elements. packed :: IsSequence seq => Iso' seq [Element seq] instance Syntax syn => Syntax (ReaderCT env syn) -- | Combinators that work with any sequence type. module Data.Syntax.Combinator -- | One or zero occurences of f. optional :: SIArrow cat => cat () a -> cat () (Maybe a) -- | Like optional, but specialized for (). opt :: SIArrow cat => cat () () -> cat () () -- | Parser one or zero occurences of f, but prints nothing. opt_ :: SIArrow cat => cat () () -> cat () () -- | Tries to apply the actions in the list in order, until one of them -- succeeds. Returns the value of the succeeding action. choice :: SIArrow cat => [cat () a] -> cat () a -- | Combine two alternatives. eitherOf :: SIArrow cat => cat () a -> cat () b -> cat () (Either a b) -- | manyTill p end applies action p zero or more times until -- action end succeeds, and returns the list of values returned by p. manyTill :: SIArrow cat => cat () a -> cat () () -> cat () [a] -- | Zero or more occurences of v separated by s. sepBy :: SIArrow cat => cat () a -> cat () () -> cat () [a] -- | One or more occurences of v separated by s. sepBy1 :: SIArrow cat => cat () a -> cat () () -> cat () [a] -- | A string of given length. takeArr :: Syntax syn => syn Int (Seq syn) -- | Constant size vector with separators. -- -- vecNSepBy n e sep describes a size n vector with -- elements e separated by sep. vecNSepBy :: Syntax syn => Int -> syn () a -> syn () () -> syn () (Vector a) -- | Constant size vector with separators and index-aware elements. -- -- ivecNSepBy n e sep describes a size n vector with -- elements e separated by sep. Each element gets its -- index and should output a value and the index unchanged. ivecNSepBy :: Syntax syn => Int -> syn Int (Int, a) -> syn () () -> syn () (Vector a) -- | Runtime sized vector. The size can depend on the result of some -- computation. -- -- vec e describes a vector with elements e. vec :: Syntax syn => syn () a -> syn Int (Vector a) -- | Runtime sized vector with separators. The size can depend on the -- result of some computation. -- -- vecSepBy e sep describes a vector with elements e -- separated by sep. vecSepBy :: Syntax syn => syn () a -> syn () () -> syn Int (Vector a) -- | Runtime sized vector with index-aware elements. The size can depend on -- the result of some computation. -- -- ivec e describes a vector with elements e. ivec :: Syntax syn => syn Int (Int, a) -> syn Int (Vector a) -- | Runtime sized vector with index-aware elements and separators. The -- size can depend on the result of some computation. -- -- ivecSepBy e sep describes a vector with elements e -- separated by sep. ivecSepBy :: Syntax syn => syn Int (Int, a) -> syn () () -> syn Int (Vector a) -- | Constant size unboxed vector with separators. -- -- uvecNSepBy n e sep describes a size n vector with -- elements e separated by sep. uvecNSepBy :: (Syntax syn, Unbox a) => Int -> syn () a -> syn () () -> syn () (Vector a) -- | Constant size unboxed vector with separators and index-aware elements. -- -- uivecNSepBy n e sep describes a size n vector with -- elements e separated by sep. Each element gets its -- index and should output a value and the index unchanged. uivecNSepBy :: (Syntax syn, Unbox a) => Int -> syn Int (Int, a) -> syn () () -> syn () (Vector a) -- | Runtime sized unboxed vector. The size can depend on the result of -- some computation. -- -- uvec e describes a vector with elements e. uvec :: (Syntax syn, Unbox a) => syn () a -> syn Int (Vector a) -- | Runtime sized unboxed vector with separators. The size can depend on -- the result of some computation. -- -- uvecSepBy e sep describes a vector with elements e -- separated by sep. uvecSepBy :: (Syntax syn, Unbox a) => syn () a -> syn () () -> syn Int (Vector a) -- | Runtime sized unboxed vector with index-aware elements. The size can -- depend on the result of some computation. -- -- uivec e describes a vector with elements e. uivec :: (Syntax syn, Unbox a) => syn Int (Int, a) -> syn Int (Vector a) -- | Runtime sized unboxed vector with index-aware elements and separators. -- The size can depend on the result of some computation. -- -- uivecSepBy e sep describes a vector with elements e -- separated by sep. uivecSepBy :: (Syntax syn, Unbox a) => syn Int (Int, a) -> syn () () -> syn Int (Vector a) -- | Common combinators that work with sequences of chars. module Data.Syntax.Char -- | Syntax constrainted to sequences of chars. -- -- Note: methods of this class do not have default implementations (for -- now), because their code is quite ugly and already written in most -- parser libraries. class (Syntax syn, Element (Seq syn) ~ Char) => SyntaxChar syn decimal :: (SyntaxChar syn, Integral a) => syn () a hexadecimal :: (SyntaxChar syn, Integral a, Bits a) => syn () a realFloat :: (SyntaxChar syn, RealFloat a) => syn () a scientific :: SyntaxChar syn => syn () Scientific -- | An useful synonym for SyntaxChars with Text sequences. type SyntaxText syn = (SyntaxChar syn, Seq syn ~ Text) -- | A number with an optional leading + or - sign character. signed :: (Real a, SyntaxChar syn) => syn () a -> syn () a -- | Accepts zero or more spaces. Generates a single space. spaces :: SyntaxChar syn => syn () () -- | Accepts zero or more spaces. Generates no output. spaces_ :: SyntaxChar syn => syn () () -- | Accepts one or more spaces. Generates a single space. spaces1 :: SyntaxChar syn => syn () () -- | Accepts a single newline. Generates a newline. endOfLine :: SyntaxChar syn => syn () () -- | A decimal digit. digitDec :: SyntaxChar syn => syn () Int -- | An octal digit. digitOct :: SyntaxChar syn => syn () Int -- | A hex digit. digitHex :: SyntaxChar syn => syn () Int instance SyntaxChar syn => SyntaxChar (ReaderCT env syn) -- | Provides a very simple indentation as a category transformer. module Data.Syntax.Indent -- | Adds indentation to a syntax description. data Indent cat a b -- | runIndent m tab runs the Indent transformer using -- tab once for each level of indentation. runIndent :: Indent cat a b -> cat () () -> cat a b -- | Inserts a new line and correct indentation, but does not require any -- formatting when parsing (it just skips all white space). breakLine :: SyntaxChar syn => Indent syn () () -- | Increases the indentation level of its argument by one. indented :: Indent cat a b -> Indent cat a b instance Category cat => Category (Indent cat) instance Products cat => Products (Indent cat) instance Coproducts cat => Coproducts (Indent cat) instance CatPlus cat => CatPlus (Indent cat) instance SIArrow cat => SIArrow (Indent cat) instance SyntaxChar syn => SyntaxChar (Indent syn) instance Syntax syn => Syntax (Indent syn) instance CatTrans Indent