    -- |
    -- Module      :  Text.Megaparsec
    -- Copyright   :  © 2015–2017 Megaparsec contributors
    --                © 2007 Paolo Martini
    --                © 1999–2001 Daan Leijen
    -- License     :  FreeBSD
    --
    -- Maintainer  :  Mark Karpov <markkarpov92@gmail.com>
    -- Stability   :  experimental
    -- Portability :  portable
    --
    -- This module includes everything you need to get started writing a parser.
    -- If you are new to Megaparsec and don't know where to begin, take a look
    -- at the tutorials <https://markkarpov.com/learn-haskell.html#megaparsec-tutorials>.
    --
    -- By default this module is set up to parse character data. If you'd like
    -- to parse the result of your own tokenizer you should start with the
    -- following imports:
    --
    -- > import Text.Megaparsec.Prim
    -- > import Text.Megaparsec.Combinator
    --
    -- Then you can implement your own version of 'satisfy' on top of the
    -- 'token' primitive, etc.
    --
    -- The typical import section looks like this:
    --
    -- > import Text.Megaparsec
    -- > import Text.Megaparsec.String
    -- > -- import Text.Megaparsec.ByteString
    -- > -- import Text.Megaparsec.ByteString.Lazy
    -- > -- import Text.Megaparsec.Text
    -- > -- import Text.Megaparsec.Text.Lazy
    --
    -- As you can see the second import depends on the data type you want to use
    -- as input stream. It just defines the useful type-synonym @Parser@.
    --
    -- Megaparsec 5 uses some type-level machinery to provide flexibility
    -- without compromising on type safety. Thus type signatures are sometimes
    -- necessary to avoid ambiguous types. If you're seeing a error message that
    -- reads like “Ambiguous type variable @e0@ arising from … prevents the
    -- constraint @(ErrorComponent e0)@ from being resolved”, you need to give
    -- an explicit signature to your parser to resolve the ambiguity. It's a
    -- good idea to provide type signatures for all top-level definitions.
    --
    -- Megaparsec is capable of a lot. Apart from this standard functionality
    -- you can parse permutation phrases with "Text.Megaparsec.Perm",
    -- expressions with "Text.Megaparsec.Expr", and even entire languages with
    -- "Text.Megaparsec.Lexer". These modules should be imported explicitly
    -- along with the two modules mentioned above.

    module Text.Megaparsec
      ( -- * Running parser
        Parsec
      , ParsecT
      , parse
      , parseMaybe
      , parseTest
      , runParser
      , runParser'
      , runParserT
      , runParserT'
        -- * Combinators
      , (A.<|>)
      -- $assocbo
      , A.many
      -- $many
      , A.some
      -- $some
      , A.optional
      -- $optional
      , unexpected
      , match
      , region
      , failure
      , (<?>)
      , label
      , hidden
      , try
      , lookAhead
      , notFollowedBy
      , withRecovery
      , observing
      , eof
      , token
      , tokens
      , between
      , choice
      , count
      , count'
      , eitherP
      , endBy
      , endBy1
      , manyTill
      , someTill
      , option
      , sepBy
      , sepBy1
      , sepEndBy
      , sepEndBy1
      , skipMany
      , skipSome
        -- * Character parsing
      , newline
      , crlf
      , eol
      , tab
      , space
      , controlChar
      , spaceChar
      , upperChar
      , lowerChar
      , letterChar
      , alphaNumChar
      , printChar
      , digitChar
      , octDigitChar
      , hexDigitChar
      , markChar
      , numberChar
      , punctuationChar
      , symbolChar
      , separatorChar
      , asciiChar
      , latin1Char
      , charCategory
      , char
      , char'
      , anyChar
      , oneOf
      , oneOf'
      , noneOf
      , noneOf'
      , satisfy
      , string
      , string'
        -- * Textual source position
      , Pos
      , mkPos
      , unPos
      , unsafePos
      , InvalidPosException (..)
      , SourcePos (..)
      , initialPos
      , sourcePosPretty
        -- * Error messages
      , ErrorItem (..)
      , ErrorComponent (..)
      , Dec (..)
      , ParseError (..)
      , ShowToken (..)
      , ShowErrorComponent (..)
      , parseErrorPretty
        -- * Debugging
      , dbg
        -- * Low-level operations
      , Stream (..)
      , State (..)
      , getInput
      , setInput
      , getPosition
      , getNextTokenPosition
      , setPosition
      , pushPosition
      , popPosition
      , getTokensProcessed
      , setTokensProcessed
      , getTabWidth
      , setTabWidth
      , getParserState
      , setParserState
      , updateParserState )
    where

    import qualified Control.Applicative as A

    import Text.Megaparsec.Char
    import Text.Megaparsec.Combinator
    import Text.Megaparsec.Error
    import Text.Megaparsec.Pos
    import Text.Megaparsec.Prim

    -- $assocbo
    --
    -- This combinator implements choice. The parser @p \<|> q@ first applies
    -- @p@. If it succeeds, the value of @p@ is returned. If @p@ fails
    -- /without consuming any input/, parser @q@ is tried.
    --
    -- The parser is called /predictive/ since @q@ is only tried when parser @p@
    -- didn't consume any input (i.e. the look ahead is 1). This
    -- non-backtracking behaviour allows for both an efficient implementation of
    -- the parser combinators and the generation of good error messages.

    -- $many
    --
    -- @many p@ applies the parser @p@ /zero/ or more times and returns a list
    -- of the returned values of @p@. Note that if the @p@ parser fails
    -- consuming input, then the entire @many p@ parser fails with the error
    -- message @p@ produced instead of just stopping iterating. In these cases
    -- wrapping @p@ with 'try' may be desirable.
    --
    -- > identifier = (:) <$> letter <*> many (alphaNumChar <|> char '_')

    -- $some
    --
    -- @some p@ applies the parser @p@ /one/ or more times and returns a list of
    -- the returned values of @p@. The note about behavior of the combinator in
    -- the case when @p@ fails consuming input (see 'A.many') applies to 'some'
    -- as well.
    --
    -- > word = some letter

    -- $optional
    --
    -- @optional p@ tries to apply the parser @p@. It will parse @p@ or nothing.
    -- It only fails if @p@ fails after consuming input. On success result of
    -- @p@ is returned inside of 'Just', on failure 'Nothing' is returned.