Text.Parsec.Indent

Documentation

A module to construct indentation aware parsers. Many programming language have indentation based syntax rules e.g. python and Haskell. This module exports combinators to create such parsers.

The input source can be thought of as a list of tokens. Abstractly each token occurs at a line and a column and has a width. The column number of a token measures is indentation. If t1 and t2 are two tokens then we say that indentation of t1 is more than t2 if the column number of occurrence of t1 is greater than that of t2.

Currently this module supports two kind of indentation based syntactic structures which we now describe:

Block

A block of indentation c is a sequence of tokens with indentation at least c. Examples for a block is a where clause of Haskell with no explicit braces.

Line fold

A line fold starting at line l and indentation c is a sequence of tokens that start at line l and possibly continue to subsequent lines as long as the indentation is greater than c. Such a sequence of lines need to be folded to a single line. An example is MIME headers. Line folding based binding separation is used in Haskell as well.

Types

type IndentT m = ReaderT Indentation m

Indentation transformer.

type IndentParserT s u m a = ParsecT s u (IndentT m) a

Indentation sensitive parser type. Usually m will be Identity as with any ParsecT. In that case you can use the simpler IndentParser type.

type IndentParser s u a = IndentParserT s u Identity a

A simplified IndentParserT.

runIndent :: IndentT Identity a -> a

Simplified version of runIndentT.

runIndentParserT

Arguments

:: (Monad m, Stream s (IndentT m) t)

=> IndentParserT s u m a

Parser to run

-> u

User state

-> SourceName

Source name

-> s

Input for the parser

-> m (Either ParseError a)

Result

This is a convenience function which wraps runIndentT and runParserT.

runIndentParser

Arguments

:: Stream s (IndentT Identity) t

=> IndentParser s u a

Parser to run

-> u

User state

-> SourceName

Source name

-> s

Input for the parser

-> Either ParseError a

Result

This is another convenience function. Use this instead of runIndentParserT if m is Identity.

Blocks

withBlock :: (Monad m, Stream s (IndentT m) z) => (a -> [b] -> c) -> IndentParserT s u m a -> IndentParserT s u m b -> IndentParserT s u m c

withBlock f a p parses a followed by an indented block of p combining them with f

withBlock' :: (Monad m, Stream s (IndentT m) z) => IndentParserT s u m a -> IndentParserT s u m b -> IndentParserT s u m [b]

Like withBlock, but throws away initial parse result

block :: (Monad m, Stream s (IndentT m) z) => IndentParserT s u m a -> IndentParserT s u m [a]

Parses a block of lines at the same indentation level

Indentation Checking

indented :: (Monad m, Stream s (IndentT m) z) => IndentParserT s u m ()

Parses only when indented past the level of the reference

same :: (Monad m, Stream s (IndentT m) z) => IndentParserT s u m ()

Parses only on the same line as the reference

sameOrIndented :: (Monad m, Stream s (IndentT m) z) => IndentParserT s u m ()

Parses only when indented past the level of the reference or on the same line

checkIndent :: (Monad m, Stream s (IndentT m) z) => IndentParserT s u m ()

Ensures the current indentation level matches that of the reference

topLevel :: (Monad m, Stream s (IndentT m) z) => IndentParserT s u m ()

Ensures that there is no indentation.

notTopLevel :: (Monad m, Stream s (IndentT m) z) => IndentParserT s u m ()

Ensures that there is at least some indentation.

withPos :: (Monad m, Stream s (IndentT m) z) => IndentParserT s u m a -> IndentParserT s u m a

Parses using the current location for indentation reference

Paired characters

indentBrackets :: (Monad m, Stream s (IndentT m) z) => GenTokenParser s u (IndentT m) -> IndentParserT s u m a -> IndentParserT s u m a

parses with surrounding brackets

indentAngles :: (Monad m, Stream s (IndentT m) z) => GenTokenParser s u (IndentT m) -> IndentParserT s u m a -> IndentParserT s u m a

parses with surrounding angle brackets

indentBraces :: (Monad m, Stream s (IndentT m) z) => GenTokenParser s u (IndentT m) -> IndentParserT s u m a -> IndentParserT s u m a

parses with surrounding braces

indentParens :: (Monad m, Stream s (IndentT m) z) => GenTokenParser s u (IndentT m) -> IndentParserT s u m a -> IndentParserT s u m a

parses with surrounding parentheses

Line Fold Chaining

Any chain using these combinators must used with withPos

(<+/>) :: (Monad m, Stream s (IndentT m) z) => IndentParserT s u m (a -> b) -> IndentParserT s u m a -> IndentParserT s u m b

<+/> is to indentation sensitive parsers what ap is to monads

(<-/>) :: (Monad m, Stream s (IndentT m) z) => IndentParserT s u m a -> IndentParserT s u m b -> IndentParserT s u m a

<-/> is like <+/>, but doesn't apply the function to the parsed value

(<*/>) :: (Monad m, Stream s (IndentT m) z) => IndentParserT s u m ([a] -> b) -> IndentParserT s u m a -> IndentParserT s u m b

Like <+/> but applies the second parser many times

(<?/>) :: (Monad m, Stream s (IndentT m) z) => IndentParserT s u m (a -> b) -> Optional s u m a -> IndentParserT s u m b

Like <+/> but applies the second parser optionally using the Optional datatype

data Optional s u m a

Datatype used to optional parsing

Constructors

Opt a (IndentParserT s u m a)