Module Angstrom.Buffered

Buffered parsing interface.

Parsers run through this module perform internal buffering of input. The parser state will keep track of unconsumed input and attempt to minimize memory allocation and copying. The Buffered.state.Partial parser state will accept newly-read, incremental input and copy it into the internal buffer. Users can feed parser states using the feed function. As a result, the interface is much easier to use than the one exposed by the Unbuffered module.

On success or failure, any unconsumed input will be returned to the user for additional processing. The buffer that the unconsumed input is returned in can also be reused.

type unconsumed = {
  1. buf : bigstring;
  2. off : int;
  3. len : int;
}
type input = [
  1. | `Bigstring of bigstring
  2. | `String of string
]
type 'a state =
  1. | Partial of [ input | `Eof ] -> 'a state
    (*

    The parser requires more input.

    *)
  2. | Done of unconsumed * 'a
    (*

    The parser succeeded.

    *)
  3. | Fail of unconsumed * string list * string
    (*

    The parser failed.

    *)
val parse : ?initial_buffer_size:int -> 'a t -> 'a state

parse ?initial_buffer_size t runs t and awaits input if needed. parse will allocate a buffer of size initial_buffer_size (defaulting to 4k bytes) to do input buffering and automatically grows the buffer as needed.

val feed : 'a state -> [ input | `Eof ] -> 'a state

feed state input supplies the parser state with more input. If state is Partial, then parsing will continue where it left off. Otherwise, the parser is in a Fail or Done state, in which case the input will be copied into the state's buffer for later use by the caller.

val state_to_option : 'a state -> 'a option

state_to_option state returns Some v if the parser is in the Done (bs, v) state and None otherwise. This function has no effect on the current state of the parser.

val state_to_result : 'a state -> ('a, string) result

state_to_result state returns Ok v if the parser is in the Done (bs, v) state and Error msg if it is in the Fail or Partial state.

This function has no effect on the current state of the parser.

val state_to_unconsumed : _ state -> unconsumed option

state_to_unconsumed state returns Some bs if state = Done(bs, _) or state = Fail(bs, _, _) and None otherwise.