Module Angstrom.Unbuffered

Unbuffered parsing interface.

Use this module for total control over memory allocation and copying. Parsers run through this module perform no internal buffering. Instead, the user is responsible for managing a buffer containing the entirety of the input that has yet to be consumed by the parser. The Unbuffered.state.Partial parser state reports to the user how much input the parser consumed during its last run, via the Unbuffered.partial.committed field. This area of input must be discarded before parsing can resume. Once additional input has been collected, the unconsumed input as well as new input must be passed to the parser state via the Unbuffered.partial.continue function, together with an indication of whether there is Unbuffered.more input to come.

The logic that must be implemented in order to make proper use of this module is intricate and tied to your OS environment. It's advisable to use the Buffered module when initially developing and testing your parsers. For production use-cases, consider the Async and Lwt support that this library includes before attempting to use this module directly.

type more =
  1. | Complete
  2. | Incomplete
type 'a state =
  1. | Partial of 'a partial
    (*

    The parser requires more input.

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

    The parser succeeded, consuming specified bytes.

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

    The parser failed, consuming specified bytes.

    *)
and 'a partial = {
  1. committed : int;
    (*

    The number of bytes committed during the last input feeding. Callers must drop this number of bytes from the beginning of the input on subsequent calls. See commit for additional details.

    *)
  2. continue : bigstring -> off:int -> len:int -> more -> 'a state;
    (*

    A continuation of a parse that requires additional input. The input should include all uncommitted input (as reported by previous partial states) in addition to any new input that has become available, as well as an indication of whether there is more input to come.

    *)
}
val parse : 'a t -> 'a state

parse t runs t and await input if needed.

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.