-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | indentation sensitive parser-combinators for parsec
--   
--   This library provides functions for use in parsing indentation
--   sensitive contexts. It parses blocks of lines all indented to the same
--   level as well as lines continued at an indented level below.
@package indents
@version 0.5.0.1


-- | Some internals. They are exposed for your convenience but can change
--   in between patch releases.
module Text.Parsec.Indent.Internal

-- | We use our own position type that doesn't require a
--   <tt>SourceName</tt>.
data Indentation
Indentation :: !Int -> !Int -> Indentation
[iLine] :: Indentation -> !Int
[iColumn] :: Indentation -> !Int
prettyIndentation :: Indentation -> String
prettyLine :: Indentation -> String
instance GHC.Internal.Show.Show Text.Parsec.Indent.Internal.Indentation


-- | <h1>Introduction</h1>
--   
--   The <a>Indent</a> module provides an <i>implicit</i> indentation
--   parser. For complex parsers split over many functions, this requires a
--   good understanding from the programmer which indentation is being
--   referenced.
--   
--   This module fixes that problem by explicitly passing around
--   indentation as a first-class value. This commonly makes complex
--   parsers less concise but easier to understand.
--   
--   <h1>The problem with reference indentation</h1>
--   
--   Many functions from that module (<tt>indented</tt>,
--   <tt>checkIndent</tt>, <tt>sameOrIndented</tt>...) use a <i>reference
--   indentation</i>. This <i>reference indentation</i> is stored in the
--   <tt>IndentParserT</tt> type. It can be set by calling
--   <tt>withPos</tt>, but also by other functions such as <tt>block</tt>.
--   
--   Consider the following code snippet:
--   
--   <pre>
--   import qualified Text.Parsec.Indent as I
--   
--   p = I.withPos $ do
--     foo
--     I.block $ I.checkIndent &gt;&gt; bar
--   </pre>
--   
--   <tt>I.checkIndent</tt>, in this case, will always succeed, since we
--   are comparing the current indentation to the implicit reference
--   indentation set by <tt>I.block</tt>, not by <tt>I.withPos</tt>, and
--   there is no way to do the latter.
--   
--   <h1>Explicit indentation</h1>
--   
--   This module makes indentation first-class rather than implicit, so we
--   can provide a good implementation without relying on <tt>withPos</tt>:
--   
--   <pre>
--   import qualified Text.Parsec.Indent as I
--   import qualified Text.Parsec.Indent.Explicit as EI
--   
--   p = do
--     indentation &lt;- EI.indentation
--     foo
--     I.block $ EI.checkIndent indentation &gt;&gt; bar
--   </pre>
--   
--   In order to preserve backwards-compatibility, the names in this module
--   are chosen to match their counterparts in <a>Text.Parsec.Indent</a>.
module Text.Parsec.Indent.Explicit

-- | We use our own position type that doesn't require a
--   <tt>SourceName</tt>.
data Indentation

-- | Obtain the current indentation, to be used as a reference later.
indentation :: forall (m :: Type -> Type) s u. Monad m => ParsecT s u m Indentation

-- | Parses only when indented past the level of the reference
indented :: forall (m :: Type -> Type) s z u. (Monad m, Stream s m z) => Indentation -> ParsecT s u m ()

-- | Parses only when indented past the level of the reference or on the
--   same line
sameOrIndented :: forall (m :: Type -> Type) s z u. (Monad m, Stream s m z) => Indentation -> ParsecT s u m ()

-- | Parses only on the same line as the reference
same :: forall (m :: Type -> Type) s z u. (Monad m, Stream s m z) => Indentation -> ParsecT s u m ()

-- | Parses a block of lines at the same indentation level starting at the
--   current position
block :: forall (m :: Type -> Type) s z u a. (Monad m, Stream s m z) => ParsecT s u m a -> ParsecT s u m [a]

-- | Ensures the current indentation level matches that of the reference
checkIndent :: forall (m :: Type -> Type) s z u. (Monad m, Stream s m z) => Indentation -> ParsecT s u m ()

-- | Ensures that there is no indentation.
topLevel :: forall (m :: Type -> Type) s z u. (Monad m, Stream s m z) => ParsecT s u m ()

-- | Ensures that there is at least some indentation.
notTopLevel :: forall (m :: Type -> Type) s z u. (Monad m, Stream s m z) => ParsecT s u m ()

module Text.Parsec.Indent

-- | Indentation transformer.
type IndentT (m :: Type -> Type) = ReaderT Indentation m

-- | Indentation sensitive parser type. Usually <tt>m</tt> will be
--   <a>Identity</a> as with any <a>ParsecT</a>. In that case you can use
--   the simpler <a>IndentParser</a> type.
type IndentParserT s u (m :: Type -> Type) a = ParsecT s u IndentT m a

-- | A simplified <a>IndentParserT</a>.
type IndentParser s u a = IndentParserT s u Identity a

-- | Simplified version of <a>runIndentT</a>.
runIndent :: IndentT Identity a -> a

-- | This is a convenience function which wraps <a>runIndentT</a> and
--   <a>runParserT</a>.
runIndentParserT :: (Monad m, Stream s (IndentT m) t) => IndentParserT s u m a -> u -> SourceName -> s -> m (Either ParseError a)

-- | This is another convenience function. Use this instead of
--   <a>runIndentParserT</a> if <tt>m</tt> is <a>Identity</a>.
runIndentParser :: Stream s (IndentT Identity) t => IndentParser s u a -> u -> SourceName -> s -> Either ParseError a

-- | <tt> <a>withBlock</a> f a p </tt> parses <tt> a </tt> followed by an
--   indented block of <tt> p </tt> combining them with <tt> f </tt>
withBlock :: forall (m :: Type -> Type) s z a b c u. (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

-- | Like <a>withBlock</a>, but throws away initial parse result
withBlock' :: forall (m :: Type -> Type) s z u a b. (Monad m, Stream s (IndentT m) z) => IndentParserT s u m a -> IndentParserT s u m b -> IndentParserT s u m [b]

-- | Parses a block of lines at the same indentation level
block :: forall (m :: Type -> Type) s z u a. (Monad m, Stream s (IndentT m) z) => IndentParserT s u m a -> IndentParserT s u m [a]

-- | Parses only when indented past the level of the reference
indented :: forall (m :: Type -> Type) s z u. (Monad m, Stream s (IndentT m) z) => IndentParserT s u m ()

-- | Parses only on the same line as the reference
same :: forall (m :: Type -> Type) s z u. (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
sameOrIndented :: forall (m :: Type -> Type) s z u. (Monad m, Stream s (IndentT m) z) => IndentParserT s u m ()

-- | Ensures the current indentation level matches that of the reference
checkIndent :: forall (m :: Type -> Type) s z u. (Monad m, Stream s (IndentT m) z) => IndentParserT s u m ()

-- | Ensures that there is no indentation.
topLevel :: forall (m :: Type -> Type) s z u. (Monad m, Stream s (IndentT m) z) => IndentParserT s u m ()

-- | Ensures that there is at least some indentation.
notTopLevel :: forall (m :: Type -> Type) s z u. (Monad m, Stream s (IndentT m) z) => IndentParserT s u m ()

-- | Parses using the current location for indentation reference
withPos :: forall (m :: Type -> Type) s z u a. (Monad m, Stream s (IndentT m) z) => IndentParserT s u m a -> IndentParserT s u m a

-- | parses with surrounding brackets
indentBrackets :: forall (m :: Type -> Type) s z u a. (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
indentAngles :: forall (m :: Type -> Type) s z u a. (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
indentBraces :: forall (m :: Type -> Type) s z u a. (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
indentParens :: forall (m :: Type -> Type) s z u a. (Monad m, Stream s (IndentT m) z) => GenTokenParser s u (IndentT m) -> IndentParserT s u m a -> IndentParserT s u m a

-- | <a>&lt;+/&gt;</a> is to indentation sensitive parsers what <a>ap</a>
--   is to monads
(<+/>) :: forall (m :: Type -> Type) s z u a b. (Monad m, Stream s (IndentT m) z) => IndentParserT s u m (a -> b) -> IndentParserT s u m a -> IndentParserT s u m b

-- | <a>&lt;-/&gt;</a> is like <a>&lt;+/&gt;</a>, but doesn't apply the
--   function to the parsed value
(<-/>) :: forall (m :: Type -> Type) s z u a b. (Monad m, Stream s (IndentT m) z) => IndentParserT s u m a -> IndentParserT s u m b -> IndentParserT s u m a

-- | Like <a>&lt;+/&gt;</a> but applies the second parser many times
(<*/>) :: forall (m :: Type -> Type) s z u a b. (Monad m, Stream s (IndentT m) z) => IndentParserT s u m ([a] -> b) -> IndentParserT s u m a -> IndentParserT s u m b

-- | Like <a>&lt;+/&gt;</a> but applies the second parser optionally using
--   the <a>Optional</a> datatype
(<?/>) :: forall (m :: Type -> Type) s z u a b. (Monad m, Stream s (IndentT m) z) => IndentParserT s u m (a -> b) -> Optional s u m a -> IndentParserT s u m b

-- | Datatype used to optional parsing
data Optional s u (m :: Type -> Type) a
Opt :: a -> IndentParserT s u m a -> Optional s u (m :: Type -> Type) a
