parser_gleam

Package Version Hex Docs

A porting of parser-ts, purescript-eulalie to Gleam

Usage

gleam_parser works on the principle of constructing parsers from smaller parsers using various combinator functions.

A parser is a function which takes an input Stream, and returns a ParseResult value which can be either a success or an error.

The type of parsers is defined like this:

pub type Parser(i, a) =
  fn(Stream(i)) -> ParseResult(i, a)

Data Types

pub type Stream(a) {
  Stream(buffer: List(a), cursor: Int)
}

A Stream just contains an list of input data, and an index into this list. While many Streams will be created during a parse operation, we only ever keep a single copy of the list they wrap.

pub type ParseResult(i, a) =
  Result(ParseSuccess(i, a), ParseError(i))

A ParseResult is what’s returned from a parser, and signals whether it succeeded or failed. It wraps one of two result values, ParseSuccess and ParseError.

pub type ParseSuccess(i, a) {
  ParseSuccess(value: a, next: Stream(i), start: Stream(i))
}

A ParseSuccess contains three properties: the value we parsed (an arbitrary value), the next input to be parsed (a Stream) and the point in the stream where we started parsing (also a Stream).

pub type ParseError(i) {
  ParseError(input: Stream(i), expected: List(String), fatal: Bool)
}

Finally, a ParseError simply contains an input property (a Stream) which points to the exact position where the parsing failed, and a set of string descriptions of expected inputs. It also contains a fatal flag, which signifies to the either combinator that we should stop parsing immediately instead of trying further parsers.

Parser Combinators

The most basic parsers form the building blocks from which you can assemble more complex parsers:

The two fundamental parser combinators are:

Using these, you can construct more advanced parser combinators. Some particularly useful combinators are predefined:

Other predefined parsers are digit, space, alphanum, letter, upper and lower, which match one character of their respective types, and their inverse counterparts, notDigit, notSpace, notAlphanum, notLetter, notUpper and notLower. There are also whitespace matchers spaces and spaces1, and their opposites, notSpaces and notSpaces1.

Installation

If available on Hex this package can be added to your Gleam project:

gleam add parser_gleam

and its documentation can be found at https://hexdocs.pm/parser_gleam.