Consumes any single item from the input except for the end of file.

import pears

assert pears.parse_string_all("x", any()) == Ok("x")

Applies the given parser n or more times.

import pears

assert pears.parse_string_all("aaa", at_least(token("a"), 2)) == Ok(["a", "a", "a"])
let assert Error(_) = pears.parse_string_all("a", at_least(token("a"), 2))

Applies the given parser up to n times.

import pears

let assert Ok(parsed) = pears.parse_string("aaa", at_most(token("a"), 2))
assert parsed.value == ["a", "a"]

Applies the given parser between the open and close parsers, returning the result of the inner parser.

import pears

assert pears.parse_string_all("(a)", between(token("a"), token("("), token(")"))) == Ok("a")

Parses one or more occurrences of the given parser separated by operator, combining the values from left to right with the functions operator returns. Use it for left-associative operators like -:

import gleam/int
import pears
import pears/chars

let minus = replace(token("-"), int.subtract)
assert pears.parse_string_all("10-2-3", chain_left(chars.natural(), minus)) == Ok(5)

Like chain_left, but combines the values from right to left, so 10-2-3 becomes 10-(2-3):

import gleam/int
import pears
import pears/chars

let minus = replace(token("-"), int.subtract)
assert pears.parse_string_all("10-2-3", chain_right(chars.natural(), minus)) == Ok(11)

Tries to apply the given parsers in order and returns the result of the first one that succeeds. If all fail, returns the error that got furthest.

import pears

let operator = choice([token("+"), token("-"), token("*")])
assert pears.parse_string_all("*", operator) == Ok("*")

Consumes the end of the input and returns a Nil value. Fails if there is any input left.

import pears

let assert Ok(_) = pears.parse_string("a", then_skip(token("a"), eof()))
let assert Error(_) = pears.parse_string("ab", then_skip(token("a"), eof()))

Applies the given parser exactly n times.

import pears

assert pears.parse_string_all("aaa", exactly(token("a"), 3)) == Ok(["a", "a", "a"])
let assert Error(_) = pears.parse_string_all("aa", exactly(token("a"), 3))

Fails at the current position with message.

import pears.{Custom}

assert pears.parse_string("a", fail("not supported")) == Error(Custom(0, "not supported"))

Leaves the parser out of error messages, e.g. for optional whitespace.

import pears.{UnexpectedToken}

let parser = skip_then(hidden(many0(token(" "))), token("a"))
assert pears.parse_string("x", parser) == Error(UnexpectedToken(0, ["\"a\""], "x"))

Reports name as expected when the parser fails without consuming input.

import pears.{UnexpectedToken}
import pears/chars

let number = label(many1(chars.digit()), "number")
assert pears.parse_string("x", number) == Error(UnexpectedToken(0, ["number"], "x"))

Lazily applies the given parser allowing for recursive parsers.

f is called every time the parser runs, so keep it cheap. Every level of nesting in the input also adds to the call stack: on JavaScript, input nested more than a few hundred levels deep can overflow it.

Examples

Parsing a recursive list of chars:

pub type Tree(a) {
  Leaf(a)
  Node(List(Tree(a)))
}

fn tree_parser() -> Parser(Char, Tree(Int)) {
  let tree = lazy(tree_parser)
  let leaf = map(number(), Leaf)
  let node =
    tree
    |> sep_by0(token(","))
    |> between(token("["), token("]"))
    |> map(Node)
  or(leaf, node)
}

Applies the given parser zero or more times.

Stops as soon as the parser fails or succeeds without consuming any input.

import pears

assert pears.parse_string_all("aaa", many0(token("a"))) == Ok(["a", "a", "a"])
assert pears.parse_string_all("", many0(token("a"))) == Ok([])

Applies the given parser one or more times.

import pears

assert pears.parse_string_all("aaa", many1(token("a"))) == Ok(["a", "a", "a"])
let assert Error(_) = pears.parse_string_all("", many1(token("a")))

Applies the given parser until end succeeds, returning the results of the parser. end is consumed but its result is dropped.

import pears
import pears/chars

let comment = skip_then(chars.string("/*"), many_till(any(), chars.string("*/")))
assert pears.parse_string_all("/*hi*/", comment) == Ok(["h", "i"])

Maps the result of a parser to a new value using a mapper function.

import pears
import pears/chars

assert pears.parse_string_all("21", map(chars.natural(), fn(n) { n * 2 })) == Ok(42)

Maps the error of a parser to a new error using a mapper function.

import pears.{Custom}

let parser = map_error(token("a"), fn(error) { Custom(error.position, "expected an a") })
assert pears.parse_string("b", parser) == Error(Custom(0, "expected an a"))

Consumes an item that is not included in the given list.

import pears

assert pears.parse_string_all("x", none_of(["+", "-"])) == Ok("x")

Succeeds without consuming any input if the parser fails, and fails if it succeeds.

import pears
import pears/chars

let letter = satisfying(fn(c) { string.contains("abcdefghijklmnopqrstuvwxyz", c) })
let keyword = then_skip(chars.string("let"), not_followed_by(letter))
let assert Ok(_) = pears.parse_string("let x", keyword)
let assert Error(_) = pears.parse_string("letter", keyword)

Consumes an item that is included in the given list.

import pears

assert pears.parse_string_all("-", one_of(["+", "-"])) == Ok("-")

Applies the given parser and wraps the result in an Option, returning None if the parser fails instead of an error.

import pears

assert pears.parse_string_all("-", optional(token("-"))) == Ok(Some("-"))
assert pears.parse_string_all("", optional(token("-"))) == Ok(None)

Tries the first parser, and if it fails, the second one. The second parser starts where the first one did, even if the first consumed input before failing.

import pears
import pears/chars

let parser = or(chars.string("ab"), chars.string("ac"))
assert pears.parse_string_all("ac", parser) == Ok("ac")

Applies both parsers and returns a tuple of the results.

import pears

assert pears.parse_string_all("ab", pair(token("a"), token("b"))) == Ok(#("a", "b"))

Runs the parser without consuming any input.

import pears

assert pears.parse_string_all("a", pair(peek(token("a")), token("a"))) == Ok(#("a", "a"))

Creates a parser that returns the consumed tokens instead of its parsed value.

import pears
import pears/chars

let decimal = recognize(pair(chars.natural(), pair(token("."), chars.natural())))
assert pears.parse_string_all("1.05", decimal) == Ok(["1", ".", "0", "5"])

Maps the result of a parser to a constant value.

import pears
import pears/chars

assert pears.parse_string_all("yes", replace(chars.string("yes"), True)) == Ok(True)

Consumes a single item from the input that satisfies the given predicate function.

import pears

let vowel = satisfying(fn(c) { string.contains("aeiou", c) })
assert pears.parse_string_all("e", vowel) == Ok("e")

Parses zero or more occurrences of the given parser separated by the given separator.

import pears
import pears/chars

assert pears.parse_string_all("1,2,3", sep_by0(chars.natural(), token(","))) == Ok([1, 2, 3])
assert pears.parse_string_all("", sep_by0(chars.natural(), token(","))) == Ok([])

Parses one or more occurrences of the given parser separated by the given separator.

import pears
import pears/chars

assert pears.parse_string_all("1,2,3", sep_by1(chars.natural(), token(","))) == Ok([1, 2, 3])
let assert Error(_) = pears.parse_string_all("", sep_by1(chars.natural(), token(",")))

Like sep_by0, but allows a trailing separator.

import pears

assert pears.parse_string_all("a,a,", sep_end_by0(token("a"), token(","))) == Ok(["a", "a"])
assert pears.parse_string_all("", sep_end_by0(token("a"), token(","))) == Ok([])

Like sep_by1, but allows a trailing separator.

import pears

assert pears.parse_string_all("a,a,", sep_end_by1(token("a"), token(","))) == Ok(["a", "a"])
let assert Error(_) = pears.parse_string_all(",", sep_end_by1(token("a"), token(",")))

Applies the given parsers in sequence and returns a list of the results

import pears

assert pears.parse_string_all("abc", seq([token("a"), token("b"), token("c")])) == Ok(["a", "b", "c"])

Applies the first parser and then the second parser, returning the result of the second parser.

import pears

assert pears.parse_string_all("ab", skip_then(token("a"), token("b"))) == Ok("b")

Returns value without consuming any input.

import pears

assert pears.parse_string_all("", succeed(1)) == Ok(1)

Runs the parser and passes its result to next, which returns the parser to run on the rest of the input. Works well with use:

import pears
import pears/chars

let integer = {
  use sign <- then(optional(token("-")))
  use number <- then(chars.natural())
  case sign {
    Some(_) -> succeed(-number)
    None -> succeed(number)
  }
}

assert pears.parse_string_all("-42", integer) == Ok(-42)

Applies the first parser and then the second parser, returning the result of the first parser.

import pears

assert pears.parse_string_all("ab", then_skip(token("a"), token("b"))) == Ok("a")

Consumes a single item from the input that is equal to the given item.

import pears

assert pears.parse_string_all("a", token("a")) == Ok("a")
assert pears.parse_all([1, 2], pair(token(1), token(2))) == Ok(#(1, 2))

Maps the result of a parser with a function that can fail. If it returns Error(message), parsing fails with that message at the position where the parser started.

import pears.{Custom}
import pears/chars

let byte =
  try_map(chars.natural(), fn(n) {
    case n < 256 {
      True -> Ok(n)
      False -> Error("number must be below 256")
    }
  })
assert pears.parse_string_all("255", byte) == Ok(255)
assert pears.parse_string_all("256", byte) == Error(Custom(0, "number must be below 256"))

Maps a parser that returns an Option to a parser that returns a value or a default value.

import pears

assert pears.parse_string_all("", unwrap(optional(token("-")), "+")) == Ok("+")

Returns the parsed value together with the span of tokens the parser consumed.

import pears.{Span}
import pears/chars

let parser = skip_then(chars.string("let "), with_span(chars.string("x")))
assert pears.parse_string_all("let x", parser) == Ok(#("x", Span(4, 5)))