Skip remaining bits in the current byte to reach the next byte boundary. If already aligned, this is a no-op. Use after bit-level parsing to resume byte-aligned operations.

Wrap a parser to allow backtracking on failure. If the inner parser fails after consuming input, attempt resets the consumed flag so that one_of can try the next alternative.

let parser = bitty.one_of([
  bitty.attempt(bytes.tag(<<0xCA, 0xFE>>)),
  bytes.tag(<<0xCA, 0x11>>),
])
let assert Ok(Nil) = bitty.run(parser, on: <<0xCA, 0x11>>)

Push name onto the error context stack on failure, creating a breadcrumb trail (e.g. ["TLS record", "handshake", "certificate"]).

let parser = num.u8() |> bitty.context(in: "header")
let assert Error(e) = bitty.run(parser, on: <<>>)
assert e.context == ["header"]

Commit to the current parse path on success. After cut, a later failure will not backtrack past this point, producing better error messages. Typically used after matching a tag or discriminator.

use _ <- bitty.then(bitty.cut(bytes.tag(<<0x01>>)))
use value <- bitty.then(num.u8())
bitty.success(value)

Succeed only if all input has been consumed. Fails with "end of input" expected if bytes remain.

Create a parser that always fails with the given message without consuming any input.

Convert a Result(a, e) into a parser: Ok(value) succeeds with the value, Error(e) fails with the inspected error as the message. Useful for lifting fallible conversions (e.g. bit_array.to_string) into a parser pipeline with use syntax.

Replace the expected list in a parse error with name. Useful for giving user-friendly names to complex parsers.

let parser = num.u8() |> bitty.label(named: "message type")
let assert Error(e) = bitty.run(parser, on: <<>>)
assert e.expected == ["message type"]

Return the current Location in the input without consuming anything.

Repeat a parser zero or more times, collecting results into a list. The inner parser must consume input on each iteration; a non-consuming parser causes an immediate error to prevent infinite loops. Stops when the parser fails without consuming input.

let assert Ok(values) =
  bitty.run(bitty.many(num.u8()), on: <<1, 2, 3>>)
assert values == [1, 2, 3]

Like many, but requires at least one successful match.

Transform the result of a parser by applying f to the parsed value.

Try each parser in order, returning the first success. A parser that consumes input before failing will not backtrack — wrap alternatives in attempt if backtracking is needed. Errors from non-consuming failures at the same position are merged.

let parser = bitty.one_of([
  bitty.attempt(bytes.tag(<<0x01>>) |> bitty.map(fn(_) { "one" })),
  bytes.tag(<<0x02>>) |> bitty.map(fn(_) { "two" }),
])
let assert Ok("two") = bitty.run(parser, on: <<0x02>>)

Try a parser, returning Some(value) on success or None if it fails without consuming input. A consuming failure still propagates.

Run a parser exactly count times, collecting results into a list.

Run a parser on the given input, requiring it to consume all bytes. Returns Error if parsing fails or if unconsumed input remains.

let assert Ok(byte) = bitty.run(num.u8(), on: <<0xFF>>)
assert byte == 255

Run a parser on the given input, returning the parsed value and any unconsumed bytes. Does not require all input to be consumed.

let assert Ok(#(byte, rest)) =
  bitty.run_partial(num.u8(), on: <<0xAA, 0xBB>>)
assert byte == 0xAA
assert rest == <<0xBB>>

Like run_partial, but also returns the Location where the parser stopped. Useful for incremental or streaming parsing.

Create a parser that always succeeds with the given value without consuming any input.

Sequence two parsers: run parser, then pass its result to next to get the second parser. Designed for Gleam’s use syntax:

use length <- bitty.then(num.u8())
use data <- bitty.then(bytes.take(length))
bitty.success(data)

Run inner on a zero-copy window of exactly byte_len bytes. The inner parser must consume the entire window or the parse fails. Requires byte alignment.

use length <- bitty.then(num.u8())
use value <- bitty.then(bitty.within_bytes(length, run: bytes.rest()))
bitty.success(value)

Like within_bytes, but the inner parser may stop early. Returns the parsed value and any unconsumed bytes from the window as a tuple. Requires byte alignment.