Overview

Miso.Util.Parser is an internal parser combinator library that operates over a token stream produced by Miso.Util.Lexer. It is used by miso's JSON pipeline (Miso.JSON.Parser) and the client-side router (Miso.Router). It is not designed for general application use, but is exposed for downstream code that needs to build custom parsers.

Core types

newtype ParserT r token m a = Parser
  { runParserT :: r -> token -> m (a, token) }

type Parser token a = ParserT () [token] [] a

ParserT is a monad transformer parameterised by:

• r — a read-only environment (accessible via askParser)
• token — the input stream type (typically [t])
• m — the result monad; using [] gives non-deterministic/backtracking parsing
• a — the parsed result

The Parser token a convenience alias fixes r = () and m = [], which gives a standard backtracking parser over a [token] stream.

Primitive combinators

anyToken    :: ParserT r [a] [] a         -- consume any single token
satisfy     :: (a -> Bool) -> ParserT r [a] [] a  -- consume if predicate holds
token_      :: Eq t => t -> Parser t t    -- match a specific token
peek        :: Parser a a                 -- look ahead without consuming
endOfInput  :: Parser a ()                -- succeed only at end of stream
allTokens   :: ParserT r a [] a           -- return the entire remaining stream
modifyTokens :: (t -> t) -> ParserT r t [] ()  -- transform the token stream
askParser   :: ParserT r token [] r       -- read the environment
errorOut    :: e -> ParserT r e [] ()     -- inject a custom error token

Error type

data ParseError a token
  = UnexpectedParse [token]  -- input remained after a successful parse
  | LexicalError LexerError  -- upstream lex failure
  | Ambiguous [(a, [token])] -- multiple distinct parses
  | NoParses token           -- no parse succeeded
  | EmptyStream              -- input was empty

Running a parser

parse :: Parser token a -> [token] -> Either (ParseError a token) a

parse returns Right only when exactly one parse consumes all input. Ambiguous or partial parses produce a Left error.

See also

• Miso.Util.Lexer — produces the token stream consumed here
• Miso.JSON.Parser — JSON parser built on this module
• Miso.Router — URI/route parser built on this module
• Miso.Util — sepBy, oneOf used alongside parsers