Data.GraphViz.Parsing

The Commitment class is an abstraction over all the current concrete representations of monadic/applicative parser combinators in this package. The common feature is two-level error-handling. Some primitives must be implemented specific to each parser type (e.g. depending on whether the parser has a running state, or whether it is lazy). But given those primitives, large numbers of combinators do not depend any further on the internal structure of the particular parser.

A functor with application, providing operations to

• embed pure expressions (pure), and

• sequence computations and combine their results (<*> and liftA2).

A minimal complete definition must include implementations of pure and of either <*> or liftA2. If it defines both, then they must behave the same as their default definitions:

(<*>) = liftA2 id

liftA2 f x y = f Prelude.<$> x <*> y

Further, any definition must satisfy the following:

Identity

pure id <*> v = v

Composition

pure (.) <*> u <*> v <*> w = u <*> (v <*> w)

Homomorphism

pure f <*> pure x = pure (f x)

Interchange

u <*> pure y = pure ($ y) <*> u

The other methods have the following default definitions, which may be overridden with equivalent specialized implementations:

• u *> v = (id <$ u) <*> v

• u <* v = liftA2 const u v

As a consequence of these laws, the Functor instance for f will satisfy

• fmap f x = pure f <*> x

It may be useful to note that supposing

forall x y. p (q x y) = f x . g y

it follows from the above that

liftA2 p (liftA2 q u v) = liftA2 f u . liftA2 g v

If f is also a Monad, it should satisfy

• pure = return

• m1 <*> m2 = m1 >>= (\x1 -> m2 >>= (\x2 -> return (x1 x2)))

• (*>) = (>>)

(which implies that pure and <*> satisfy the applicative functor laws).

A monoid on applicative functors.

If defined, some and many should be the least solutions of the equations:

• some v = (:) Prelude.<$> v <*> many v

• many v = some v <|> pure []

Examples

>>> Nothing <|> Just 42Just 42

>>> [1, 2] <|> [3, 4][1,2,3,4]

>>> empty <|> print (2^15)32768

This Parser datatype is a specialised parsing monad with error reporting. Whereas the standard version can be used for arbitrary token types, this version is specialised to Text input only.

An infix synonym for fmap.

The name of this operator is an allusion to Prelude.$. Note the similarities between their types:

 ($)  ::              (a -> b) ->   a ->   b
(<$>) :: Functor f => (a -> b) -> f a -> f b

Whereas Prelude.$ is function application, <$> is function application lifted over a Functor.

Examples

Convert from a Maybe Int to a Maybe String using show:

>>> show <$> NothingNothing

>>> show <$> Just 3Just "3"

Convert from an Either Int Int to an Either Int String using show:

>>> show <$> Left 17Left 17

>>> show <$> Right 17Right "17"

Double each element of a list:

>>> (*2) <$> [1,2,3][2,4,6]

Apply even to the second element of a pair:

>>> even <$> (2,2)(2,True)

Parse a bracketed item, discarding the brackets. If everything matches except the closing bracket, the whole parse fails soft, which can give less-than-satisfying error messages. If you want better error messages, try calling with e.g. bracket open (commit close) item

Query the internal state.

Update the internal state.

Replace all locations in the input with the same value. The default definition is fmap . const, but this may be overridden with a more efficient version.

Examples

Perform a computation with Maybe and replace the result with a constant value if it is Just:

>>> 'a' <$ Just 2Just 'a'>>> 'a' <$ NothingNothing

A variant of <*> with the types of the arguments reversed. It differs from flip (<*>) in that the effects are resolved in the order the arguments are presented.

Examples

>>> (<**>) (print 1) (id <$ print 2)12

>>> flip (<*>) (print 1) (id <$ print 2)21

>>> ZipList [4, 5, 6] <**> ZipList [(+1), (*2), (/3)]ZipList {getZipList = [5.0,10.0,2.0]}

Lift a function to actions. Equivalent to Functor's fmap but implemented using only Applicative's methods: liftA f a = pure f <*> a

As such this function may be used to implement a Functor instance from an Applicative one.

Examples

Using the Applicative instance for Lists:

>>> liftA (+1) [1, 2][2,3]

Or the Applicative instance for Maybe

>>> liftA (+1) (Just 3)Just 4

Lift a ternary function to actions.

Simply return the next token in the input tokenstream.

A return type like Either, that distinguishes not only between right and wrong answers, but also has commitment, so that a failure cannot be undone. This should only be used for writing very primitive parsers - really it is an internal detail of the library. The z type is the remaining unconsumed input.

One or none.

It is useful for modelling any computation that is allowed to fail.

Examples

Using the Alternative instance of Control.Monad.Except, the following functions:

>>> import Control.Monad.Except

>>> canFail = throwError "it failed" :: Except String Int>>> final = return 42                :: Except String Int

Can be combined by allowing the first function to fail:

>>> runExcept $ canFail *> finalLeft "it failed"

>>> runExcept $ optional canFail *> finalRight 42

Parse a non-empty list of items separated by discarded junk.

The Const functor.

Examples

>>> fmap (++ "World") (Const "Hello")Const "Hello"

Because we ignore the second type parameter to Const, the Applicative instance, which has (<*>) :: Monoid m => Const m (a -> b) -> Const m a -> Const m b essentially turns into Monoid m => m -> m -> m, which is (<>)

>>> Const [1, 2, 3] <*> Const [4, 5, 6]Const [1,2,3,4,5,6]

The sum of a collection of actions using (<|>), generalizing concat.

asum is just like msum, but generalised to Alternative.

Examples

Basic usage:

>>> asum [Just "Hello", Nothing, Just "World"]Just "Hello"

Apply a parsed function to a parsed value. Rather like ordinary function application lifted into parsers.

Return the next token if it satisfies the given predicate.

Succeed if the end of file/input has been reached, fail otherwise.

Parse a non-empty list of items.

Parse a list of items separated by discarded junk.

'exactly n p' parses precisely n items, using the parser p, in sequence.

The PolyParse class is an abstraction gathering all of the common features that a two-level error-handling parser requires: the applicative parsing interface, the monadic interface, and commitment.

There are two additional basic combinators that we expect to be implemented afresh for every concrete type, but which (for technical reasons) cannot be class methods. They are next and satisfy.

adjustErrBad is just like adjustErr except it also raises the severity of the error.

Parse a list of items, discarding the start, end, and separator items.

x discard y parses both x and y, but discards the result of y. Rather like const lifted into parsers.

When a simple fail is not strong enough, use failBad for emphasis. An emphasised (severe) error cannot be overridden by choice operators.

manyFinally e t parses a possibly-empty sequence of e's, terminated by a t. The final t is discarded. Any parse failures could be due either to a badly-formed terminator or a badly-formed element, so it raises both possible errors.

manyFinally' is like manyFinally, except when the terminator parser overlaps with the element parser. In manyFinally e t, the parser t is tried only when parser e fails, whereas in manyFinally' e t, the parser t is always tried first, then parser e only if the terminator is not found. For instance, manyFinally (accept "01") (accept "0") on input "0101010" returns ["01","01","01"], whereas manyFinally' with the same arguments and input returns [].

Parse the first alternative in the list that succeeds.

'upto n p' parses n or fewer items, using the parser p, in sequence.

many1Satisfy p is a more efficient fused version of many1 (satisfy p)

manySatisfy p is a more efficient fused version of many (satisfy p)

p onFail q means parse p, unless p fails, in which case parse q instead. Can be chained together to give multiple attempts to parse something. (Note that q could itself be a failing parser, e.g. to change the error message from that defined in p to something different.) However, a severe failure in p cannot be ignored.

Push some tokens back onto the front of the input stream and reparse. This is useful e.g. for recursively expanding macros. When the user-parser recognises a macro use, it can lookup the macro expansion from the parse state, lex it, and then stuff the lexed expansion back down into the parser.

Deliver the entire internal state.

Lists, but with an Applicative functor based on zipping.

Examples

In contrast to the Applicative for GHC.List.List:

>>> (+) <$> [1, 2, 3] <*> [4, 5, 6][5,6,7,6,7,8,7,8,9]

The Applicative instance of ZipList applies the operation by pairing up the elements, analogous to zipWithN

>>> (+) <$> ZipList [1, 2, 3] <*> ZipList [4, 5, 6]ZipList {getZipList = [5,7,9]}

>>> (,,,) <$> ZipList [1, 2] <*> ZipList [3, 4] <*> ZipList [5, 6] <*> ZipList [7, 8]ZipList {getZipList = [(1,3,5,7),(2,4,6,8)]}

>>> ZipList [(+1), (^2), (/ 2)] <*> ZipList [5, 5, 5]ZipList {getZipList = [6.0,25.0,2.5]}

A ReadS-like type alias.

Parse the required value, returning also the rest of the input Text that hasn't been parsed (for debugging purposes).

Parse the required value with the assumption that it will parse all of the input Text.

A variant of runParser where it is assumed that the provided parsing function consumes all of the Text input (with the exception of whitespace at the end).

If unable to parse Dot code properly, throw a GraphvizException.

If unable to parse Dot code properly, throw a GraphvizException, with the error containing the remaining unparsed code..

The opposite of bracket.

Use this when you do not want numbers to be treated as Bool values.

Parse a Text that doesn't need to be quoted.

Determine if this String represents a number. Boolean parameter determines if exponents are considered part of numbers for this.

Used when quotes are explicitly required;

Parse a Text where the provided Chars (as well as " and \) are escaped and the second list of Chars are those that are not permitted. Note: does not parse surrounding quotes. The Bool value indicates whether empty Texts are allowed or not.

Assumes that any letter is ASCII for case-insensitive comparisons.

Parse a floating point number that actually contains decimals. Bool flag indicates whether values that need to be quoted are parsed.

Parses at least one whitespace character.

Parses zero or more whitespace characters.

Parse and discard optional surrounding whitespace.

Parses a newline.

Consume all whitespace and newlines until a line with non-whitespace is reached. The whitespace on that line is not consumed.

Try to parse a list of the specified type; returns an empty list if parsing fails.

Return an empty list if parsing a list fails.

Parses and returns all characters up till the end of the line, but does not touch the newline characters.