nibble

A lexer and parser combinator library inspired by elm/parser.

✨ This project is written in pure Gleam so you can use it anywhere Gleam runs: Erlang, Elixir, Node, Deno, and the browser!

Quick start

If you just want to get a feel for what nibble can do, check out the example below.

import gleam/option.{None, Some}
import nibble.{do, return}
import nibble/lexer

type Point {
  Point(x: Int, y: Int)
}

type Token {
  Num(Int)
  LParen
  RParen
  Comma
}

pub fn main() {
  // Your lexer knows how to take an input string and
  // turn it into a flat list of tokens. You define the
  // type of token you want to use, but nibble will wrap
  // that up in its own `Token` type that includes the
  // source span and original lexeme for each token.
  let lexer =
    lexer.simple([
      lexer.int(Num),
      lexer.token("(", LParen),
      lexer.token(")", RParen),
      lexer.token(",", Comma),
      // Skip over whitespace, we don't care about it!
        lexer.whitespace(Nil)
        |> lexer.ignore,
    ])

  // Your parser(s!) know how to transform a list of
  // tokens into whatever you want. You have the full
  // power of Gleam here, so you can go wild!
  let int_parser = {
    // Use `take_map` to only consume certain kinds of tokens and transform the
    // result.
    use tok <- nibble.take_map("expected number")
    case tok {
      Num(n) -> Some(n)
      _ -> None
    }
  }

  let parser = {
    use _ <- do(nibble.token(LParen))
    use x <- do(int_parser)
    use _ <- do(nibble.token(Comma))
    use y <- do(int_parser)
    use _ <- do(nibble.token(RParen))

    return(Point(x, y))
  }

  let assert Ok(tokens) = lexer.run("(1, 2)", lexer)
  let assert Ok(point) = nibble.run(tokens, parser)

  point.x //=> 1
  point.y //=> 2
}

Installation

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

gleam add nibble

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