unikernel/duniverse/angstrom/lib/angstrom.mli

@@ -0,0 +1,688 @@
+(*----------------------------------------------------------------------------
+    Copyright (c) 2016 Inhabited Type LLC.
+
+    All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions
+    are met:
+
+    1. Redistributions of source code must retain the above copyright
+       notice, this list of conditions and the following disclaimer.
+
+    2. Redistributions in binary form must reproduce the above copyright
+       notice, this list of conditions and the following disclaimer in the
+       documentation and/or other materials provided with the distribution.
+
+    3. Neither the name of the author nor the names of his contributors
+       may be used to endorse or promote products derived from this software
+       without specific prior written permission.
+
+    THIS SOFTWARE IS PROVIDED BY THE CONTRIBUTORS ``AS IS'' AND ANY EXPRESS
+    OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+    WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+    DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE FOR
+    ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+    DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+    OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+    HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+    STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+    ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+    POSSIBILITY OF SUCH DAMAGE.
+  ----------------------------------------------------------------------------*)
+
+(** Parser combinators built for speed and memory-efficiency.
+
+    Angstrom is a parser-combinator library that provides monadic and
+    applicative interfaces for constructing parsers with unbounded lookahead.
+    Its parsers can consume input incrementally, whether in a blocking or
+    non-blocking environment. To achieve efficient incremental parsing,
+    Angstrom offers both a buffered and unbuffered interface to input streams,
+    with the {!module:Unbuffered} interface enabling zero-copy IO. With these
+    features and low-level iteration parser primitives like {!take_while} and
+    {!skip_while}, Angstrom makes it easy to write efficient, expressive, and
+    reusable parsers suitable for high-performance applications. *)
+
+
+type +'a t
+(** A parser for values of type ['a]. *)
+
+
+type bigstring = Bigstringaf.t
+
+(** {2 Basic parsers} *)
+
+val peek_char : char option t
+(** [peek_char] accepts any char and returns it, or returns [None] if the end
+    of input has been reached.
+
+    This parser does not advance the input. Use it for lookahead. *)
+
+val peek_char_fail : char t
+(** [peek_char_fail] accepts any char and returns it. If end of input has been
+    reached, it will fail.
+
+    This parser does not advance the input. Use it for lookahead. *)
+
+val peek_string : int -> string t
+(** [peek_string n] accepts exactly [n] characters and returns them as a
+    string. If there is not enough input, it will fail.
+
+    This parser does not advance the input. Use it for lookahead. *)
+
+val char : char -> char t
+(** [char c] accepts [c] and returns it. *)
+
+val not_char : char -> char t
+(** [not_char] accepts any character that is not [c] and returns the matched
+    character. *)
+
+val any_char : char t
+(** [any_char] accepts any character and returns it. *)
+
+val satisfy : (char -> bool) -> char t
+(** [satisfy f] accepts any character for which [f] returns [true] and
+    returns the accepted character. In the case that none of the parser
+    succeeds, then the parser will fail indicating the offending
+    character. *)
+
+val string : string -> string t
+(** [string s] accepts [s] exactly and returns it. *)
+
+val string_ci : string -> string t
+(** [string_ci s] accepts [s], ignoring case, and returns the matched string,
+    preserving the case of the original input. *)
+
+val skip : (char -> bool) -> unit t
+(** [skip f] accepts any character for which [f] returns [true] and discards
+    the accepted character. [skip f] is equivalent to [satisfy f] but discards
+    the accepted character. *)
+
+val skip_while : (char -> bool) -> unit t
+(** [skip_while f] accepts input as long as [f] returns [true] and discards
+    the accepted characters. *)
+
+val take : int -> string t
+(** [take n] accepts exactly [n] characters of input and returns them as a
+    string. *)
+
+val take_while : (char -> bool) -> string t
+(** [take_while f] accepts input as long as [f] returns [true] and returns the
+    accepted characters as a string.
+
+    This parser does not fail. If [f] returns [false] on the first character,
+    it will return the empty string. *)
+
+val take_while1 : (char -> bool) -> string t
+(** [take_while1 f] accepts input as long as [f] returns [true] and returns the
+    accepted characters as a string.
+
+    This parser requires that [f] return [true] for at least one character of
+    input, and will fail otherwise. *)
+
+val take_till : (char -> bool) -> string t
+(** [take_till f] accepts input as long as [f] returns [false] and returns the
+    accepted characters as a string.
+
+    This parser does not fail. If [f] returns [true] on the first character, it
+    will return the empty string. *)
+
+val consumed : _ t -> string t
+(** [consumed p] runs [p] and returns the contents that were consumed during the
+    parsing as a string *)
+
+val take_bigstring : int -> bigstring t
+(** [take_bigstring n] accepts exactly [n] characters of input and returns them
+    as a newly allocated bigstring. *)
+
+val take_bigstring_while : (char -> bool) -> bigstring t
+(** [take_bigstring_while f] accepts input as long as [f] returns [true] and
+    returns the accepted characters as a newly allocated bigstring.
+
+    This parser does not fail. If [f] returns [false] on the first character,
+    it will return the empty bigstring. *)
+
+val take_bigstring_while1 : (char -> bool) -> bigstring t
+(** [take_bigstring_while1 f] accepts input as long as [f] returns [true] and
+    returns the accepted characters as a newly allocated bigstring.
+
+    This parser requires that [f] return [true] for at least one character of
+    input, and will fail otherwise. *)
+
+val take_bigstring_till : (char -> bool) -> bigstring t
+(** [take_bigstring_till f] accepts input as long as [f] returns [false] and
+    returns the accepted characters as a newly allocated bigstring.
+
+    This parser does not fail. If [f] returns [true] on the first character, it
+    will return the empty bigstring. *)
+
+val consumed_bigstring : _ t -> bigstring t
+(** [consumed p] runs [p] and returns the contents that were consumed during the
+    parsing as a bigstring *)
+
+val advance : int -> unit t
+(** [advance n] advances the input [n] characters, failing if the remaining
+    input is less than [n]. *)
+
+val end_of_line : unit t
+(** [end_of_line] accepts either a line feed [\n], or a carriage return
+    followed by a line feed [\r\n] and returns unit. *)
+
+val at_end_of_input : bool t
+(** [at_end_of_input] returns whether the end of the end of input has been
+    reached. This parser always succeeds. *)
+
+val end_of_input : unit t
+(** [end_of_input] succeeds if all the input has been consumed, and fails
+    otherwise. *)
+
+val scan : 'state -> ('state -> char -> 'state option) -> (string * 'state) t
+(** [scan init f] consumes until [f] returns [None]. Returns the final state
+    before [None] and the accumulated string *)
+
+val scan_state : 'state -> ('state -> char -> 'state option) -> 'state t
+(** [scan_state init f] is like {!scan} but only returns the final state before
+    [None]. Much more efficient than {!scan}. *)
+
+val scan_string : 'state -> ('state -> char -> 'state option) -> string t
+(** [scan_string init f] is like {!scan} but discards the final state and returns
+    the accumulated string. *)
+
+val int8 : int -> int t
+(** [int8 i] accepts one byte that matches the lower-order byte of [i] and
+    returns unit. *)
+
+val any_uint8 : int t
+(** [any_uint8] accepts any byte and returns it as an unsigned int8. *)
+
+val any_int8 : int t
+(** [any_int8] accepts any byte and returns it as a signed int8. *)
+
+(** Big endian parsers *)
+module BE : sig
+  val int16 : int   -> unit t
+  (** [int16 i] accept two bytes that match the two lower order bytes of [i]
+      and returns unit. *)
+
+  val int32 : int32 -> unit t
+  (** [int32 i] accept four bytes that match the four bytes of [i]
+      and returns unit. *)
+
+  val int64 : int64 -> unit t
+  (** [int64 i] accept eight bytes that match the eight bytes of [i] and
+      returns unit. *)
+
+  val any_int16 : int t
+  val any_int32 : int32 t
+  val any_int64 : int64 t
+  (** [any_intN] reads [N] bits and interprets them as big endian signed integers. *)
+
+  val any_uint16 : int t
+  (** [any_uint16] reads [16] bits and interprets them as a big endian unsigned
+      integer. *)
+
+  val any_float : float t
+  (** [any_float] reads 32 bits and interprets them as a big endian floating
+      point value. *)
+
+  val any_double : float t
+  (** [any_double] reads 64 bits and interprets them as a big endian floating
+      point value. *)
+end
+
+(** Little endian parsers *)
+module LE : sig
+  val int16 : int   -> unit t
+  (** [int16 i] accept two bytes that match the two lower order bytes of [i]
+      and returns unit. *)
+
+  val int32 : int32 -> unit t
+  (** [int32 i] accept four bytes that match the four bytes of [i]
+      and returns unit. *)
+
+  val int64 : int64 -> unit t
+  (** [int32 i] accept eight bytes that match the eight bytes of [i] and
+      returns unit. *)
+
+  val any_int16 : int t
+  val any_int32 : int32 t
+  val any_int64 : int64 t
+  (** [any_intN] reads [N] bits and interprets them as little endian signed
+      integers. *)
+
+  val any_uint16 : int t
+  (** [uint16] reads [16] bits and interprets them as a little endian unsigned
+      integer. *)
+
+  val any_float : float t
+  (** [any_float] reads 32 bits and interprets them as a little endian floating
+      point value. *)
+
+  val any_double : float t
+  (** [any_double] reads 64 bits and interprets them as a little endian floating
+      point value. *)
+end
+
+
+(** {2 Combinators} *)
+
+val option : 'a -> 'a t -> 'a t
+(** [option v p] runs [p], returning the result of [p] if it succeeds and [v]
+    if it fails. *)
+
+
+val both : 'a t -> 'b t -> ('a * 'b) t
+(** [both p q] runs [p] followed by [q] and returns both results in a tuple *)
+
+val list : 'a t list -> 'a list t
+(** [list ps] runs each [p] in [ps] in sequence, returning a list of results of
+    each [p]. *)
+
+val count : int -> 'a t -> 'a list t
+(** [count n p] runs [p] [n] times, returning a list of the results. *)
+
+val many : 'a t -> 'a list t
+(** [many p] runs [p] {i zero} or more times and returns a list of results from
+    the runs of [p]. *)
+
+val many1 : 'a t -> 'a list t
+(** [many1 p] runs [p] {i one} or more times and returns a list of results from
+    the runs of [p]. *)
+
+val many_till : 'a t -> _ t -> 'a list t
+(** [many_till p e] runs parser [p] {i zero} or more times until action [e]
+    succeeds and returns the list of result from the runs of [p]. *)
+
+val sep_by : _ t -> 'a t -> 'a list t
+(** [sep_by s p] runs [p] {i zero} or more times, interspersing runs of [s] in between. *)
+
+val sep_by1 : _ t -> 'a t -> 'a list t
+(** [sep_by1 s p] runs [p] {i one} or more times, interspersing runs of [s] in between. *)
+
+val skip_many : _ t -> unit t
+(** [skip_many p] runs [p] {i zero} or more times, discarding the results. *)
+
+val skip_many1 : _ t -> unit t
+(** [skip_many1 p] runs [p] {i one} or more times, discarding the results. *)
+
+val fix : ('a t -> 'a t) -> 'a t
+(** [fix f] computes the fixpoint of [f] and runs the resultant parser. The
+    argument that [f] receives is the result of [fix f], which [f] must use,
+    paradoxically, to define [fix f].
+
+    [fix] is useful when constructing parsers for inductively-defined types
+    such as sequences, trees, etc. Consider for example the implementation of
+    the {!many} combinator defined in this library:
+
+{[let many p =
+  fix (fun m ->
+    (cons <$> p <*> m) <|> return [])]}
+
+    [many p] is a parser that will run [p] zero or more times, accumulating the
+    result of every run into a list, returning the result. It's defined by
+    passing [fix] a function. This function assumes its argument [m] is a
+    parser that behaves exactly like [many p]. You can see this in the
+    expression comprising the left hand side of the alternative operator
+    [<|>]. This expression runs the parser [p] followed by the parser [m], and
+    after which the result of [p] is cons'd onto the list that [m] produces.
+    The right-hand side of the alternative operator provides a base case for
+    the combinator: if [p] fails and the parse cannot proceed, return an empty
+    list.
+
+    Another way to illustrate the uses of [fix] is to construct a JSON parser.
+    Assuming that parsers exist for the basic types such as [false], [true],
+    [null], strings, and numbers, the question then becomes how to define a
+    parser for objects and arrays? Both contain values that are themselves JSON
+    values, so it seems as though it's impossible to write a parser that will
+    accept JSON objects and arrays before writing a parser for JSON values as a
+    whole.
+
+    This is the exact situation that [fix] was made for. By defining the
+    parsers for arrays and objects within the function that you pass to [fix],
+    you will gain access to a parser that you can use to parse JSON values, the
+    very parser you are defining!
+
+{[let json =
+  fix (fun json ->
+    let arr = char '[' *> sep_by (char ',') json <* char ']' in
+    let obj = char '{' *> ... json ... <* char '}' in
+    choice [str; num; arr json, ...])]} *)
+
+(** [fix_lazy] is like [fix], but after the function reaches [max_steps]
+    deep, it wraps up the remaining computation and yields
+    back to the root of the parsing loop where it continues from there.
+
+    This is an effective way to break up the stack trace into more managable
+    chunks, which is important for Js_of_ocaml due to the lack of tailrec
+    optimizations for CPS-style tail calls. When compiling for Js_of_ocaml,
+    [fix] itself is defined as [fix_lazy ~max_steps:20]. *)
+val fix_lazy : max_steps:int -> ('a t -> 'a t) -> 'a t
+
+(** {2 Alternatives} *)
+
+val (<|>) : 'a t -> 'a t -> 'a t
+(** [p <|> q] runs [p] and returns the result if succeeds. If [p] fails, then
+    the input will be reset and [q] will run instead. *)
+
+val choice : ?failure_msg:string -> 'a t list -> 'a t
+(** [choice ?failure_msg ts] runs each parser in [ts] in order until one
+    succeeds and returns that result. In the case that none of the parser
+    succeeds, then the parser will fail with the message [failure_msg], if
+    provided, or a much less informative message otherwise. *)
+
+val (<?>) : 'a t -> string -> 'a t
+(** [p <?> name] associates [name] with the parser [p], which will be reported
+    in the case of failure. *)
+
+val commit : unit t
+(** [commit] prevents backtracking beyond the current position of the input,
+    allowing the manager of the input buffer to reuse the preceding bytes for
+    other purposes.
+
+    The {!module:Unbuffered} parsing interface will report directly to the
+    caller the number of bytes committed to the when returning a
+    {!Unbuffered.state.Partial} state, allowing the caller to reuse those bytes
+    for any purpose. The {!module:Buffered} will keep track of the region of
+    committed bytes in its internal buffer and reuse that region to store
+    additional input when necessary. *)
+
+
+(** {2 Monadic/Applicative interface} *)
+
+val return : 'a -> 'a t
+(** [return v] creates a parser that will always succeed and return [v] *)
+
+val fail : string -> _ t
+(** [fail msg] creates a parser that will always fail with the message [msg] *)
+
+val (>>=) : 'a t -> ('a -> 'b t) -> 'b t
+(** [p >>= f] creates a parser that will run [p], pass its result to [f], run
+    the parser that [f] produces, and return its result. *)
+
+val bind : 'a t -> f:('a -> 'b t) -> 'b t
+(** [bind] is a prefix version of [>>=] *)
+
+val (>>|) : 'a t -> ('a -> 'b) -> 'b t
+(** [p >>| f] creates a parser that will run [p], and if it succeeds with
+    result [v], will return [f v] *)
+
+val (<*>) : ('a -> 'b) t -> 'a t -> 'b t
+(** [f <*> p] is equivalent to [f >>= fun f -> p >>| f]. *)
+
+val (<$>) : ('a -> 'b) -> 'a t -> 'b t
+(** [f <$> p] is equivalent to [p >>| f] *)
+
+val ( *>) : _ t -> 'a t -> 'a t
+(** [p *> q] runs [p], discards its result and then runs [q], and returns its
+    result. *)
+
+val (<* ) : 'a t -> _ t -> 'a t
+(** [p <* q] runs [p], then runs [q], discards its result, and returns the
+    result of [p]. *)
+
+val lift : ('a -> 'b) -> 'a t -> 'b t
+val lift2 : ('a -> 'b -> 'c) -> 'a t -> 'b t -> 'c t
+val lift3 : ('a -> 'b -> 'c -> 'd) -> 'a t -> 'b t -> 'c t -> 'd t
+val lift4 : ('a -> 'b -> 'c -> 'd -> 'e) -> 'a t -> 'b t -> 'c t -> 'd t -> 'e t
+(** The [liftn] family of functions promote functions to the parser monad.
+    For any of these functions, the following equivalence holds:
+
+{[liftn f p1 ... pn = f <$> p1 <*> ... <*> pn]}
+
+    These functions are more efficient than using the applicative interface
+    directly, mostly in terms of memory allocation but also in terms of speed.
+    Prefer them over the applicative interface, even when the arity of the
+    function to be lifted exceeds the maximum [n] for which there is an
+    implementation for [liftn]. In other words, if [f] has an arity of [5] but
+    only [lift4] is provided, do the following:
+
+{[lift4 f m1 m2 m3 m4 <*> m5]}
+
+    Even with the partial application, it will be more efficient than the
+    applicative implementation. *)
+
+val map : 'a t -> f:('a -> 'b) -> 'b t
+val map2 : 'a t -> 'b t -> f:('a -> 'b -> 'c) -> 'c t
+val map3 : 'a t -> 'b t -> 'c t -> f:('a -> 'b -> 'c -> 'd) -> 'd t
+val map4 : 'a t -> 'b t -> 'c t -> 'd t -> f:('a -> 'b -> 'c -> 'd -> 'e) -> 'e t
+(** The [mapn] family of functions are just like [liftn], with a slightly
+    different interface. *)
+
+(** The [Let_syntax] module is intended to be used with the [ppx_let]
+    pre-processor, and just contains copies of functions described elsewhere. *)
+module Let_syntax : sig
+  val return : 'a -> 'a t
+  val ( >>| ) : 'a t -> ('a -> 'b) -> 'b t
+  val ( >>= ) : 'a t -> ('a -> 'b t) -> 'b t
+
+  module Let_syntax : sig
+    val return : 'a -> 'a t
+    val map : 'a t -> f:('a -> 'b) -> 'b t
+    val bind : 'a t -> f:('a -> 'b t) -> 'b t
+    val both : 'a t -> 'b t -> ('a * 'b) t
+    val map2 : 'a t -> 'b t -> f:('a -> 'b -> 'c) -> 'c t
+    val map3 : 'a t -> 'b t -> 'c t -> f:('a -> 'b -> 'c -> 'd) -> 'd t
+    val map4 : 'a t -> 'b t -> 'c t -> 'd t -> f:('a -> 'b -> 'c -> 'd -> 'e) -> 'e t
+  end
+end
+
+val ( let+ ) : 'a t -> ('a -> 'b) -> 'b t
+val ( let* ) : 'a t -> ('a -> 'b t) -> 'b t
+val ( and+ ) : 'a t -> 'b t -> ('a * 'b) t
+
+(** Unsafe Operations on Angstrom's Internal Buffer
+
+    These functions are considered {b unsafe} as they expose the input buffer
+    to client code without any protections against modification, or leaking
+    references. They are exposed to support performance-sensitive parsers that
+    want to avoid allocation at all costs. Client code should take care to
+    write the input buffer callback functions such that they:
+
+    {ul
+    {- do not modify the input buffer {i outside} of the range
+       [\[off, off + len)];}
+    {- do not modify the input buffer {i inside} of the range
+       [\[off, off + len)] if the parser might backtrack; and}
+    {- do not return any direct or indirect references to the input buffer.}}
+
+    If the input buffer callback functions do not do any of these things, then
+    the client may consider their use safe. *)
+module Unsafe : sig
+
+  val take : int -> (bigstring -> off:int -> len:int -> 'a) -> 'a t
+  (** [take n f] accepts exactly [n] characters of input into the parser's
+      internal buffer then calls [f buffer ~off ~len].  [buffer] is the
+      parser's internal buffer.  [off] is the offset from the start of [buffer]
+      containing the requested content.  [len] is the length of the requested
+      content.  [len] is guaranteed to be equal to [n]. *)
+
+  val take_while : (char -> bool) -> (bigstring -> off:int -> len:int -> 'a) -> 'a t
+  (** [take_while check f] accepts input into the parser's interal buffer as
+      long as [check] returns [true] then calls [f buffer ~off ~len].  [buffer]
+      is the parser's internal buffer.  [off] is the offset from the start of
+      [buffer] containing the requested content.  [len] is the length of the
+      content matched by [check].
+
+      This parser does not fail. If [check] returns [false] on the first
+      character, [len] will be [0]. *)
+
+  val take_while1 : (char -> bool) -> (bigstring -> off:int -> len:int -> 'a) -> 'a t
+  (** [take_while1 check f] accepts input into the parser's interal buffer as
+      long as [check] returns [true] then calls [f buffer ~off ~len].  [buffer]
+      is the parser's internal buffer.  [off] is the offset from the start of
+      [buffer] containing the requested content.  [len] is the length of the
+      content matched by [check].
+
+      This parser requires that [f] return [true] for at least one character of
+      input, and will fail otherwise. *)
+
+  val take_till : (char -> bool) -> (bigstring -> off:int -> len:int -> 'a) -> 'a t
+  (** [take_till check f] accepts input into the parser's interal buffer as
+      long as [check] returns [false] then calls [f buffer ~off ~len].  [buffer]
+      is the parser's internal buffer.  [off] is the offset from the start of
+      [buffer] containing the requested content.  [len] is the length of the
+      content matched by [check].
+
+      This parser does not fail. If [check] returns [true] on the first
+      character, [len] will be [0]. *)
+
+  val peek : int -> (bigstring -> off:int -> len:int -> 'a) -> 'a t
+  (** [peek n ~f] accepts exactly [n] characters and calls [f buffer ~off ~len]
+      with [len = n]. If there is not enough input, it will fail.
+
+      This parser does not advance the input. Use it for lookahead. *)
+end
+
+
+(** {2 Running} *)
+
+module Consume : sig
+  type t =
+    | Prefix
+    | All
+end
+
+val parse_bigstring : consume:Consume.t -> 'a t -> bigstring -> ('a, string) result
+
+(** [parse_bigstring ~consume t bs] runs [t] on [bs]. The parser will receive
+    an [`Eof] after all of [bs] has been consumed. Passing {!Prefix} in the
+    [consume] argument allows the parse to successfully complete without
+    reaching eof.  To require the parser to reach eof, pass {!All} in the
+    [consume] argument.
+
+    For use-cases requiring that the parser be fed input incrementally, see the
+    {!module:Buffered} and {!module:Unbuffered} modules below. *)
+
+
+val parse_string : consume:Consume.t -> 'a t -> string -> ('a, string) result
+(** [parse_string ~consume t bs] runs [t] on [bs]. The parser will receive an
+    [`Eof] after all of [bs] has been consumed. Passing {!Prefix} in the
+    [consume] argument allows the parse to successfully complete without
+    reaching eof.  To require the parser to reach eof, pass {!All} in the
+    [consume] argument.
+
+    For use-cases requiring that the parser be fed input incrementally, see the
+    {!module:Buffered} and {!module:Unbuffered} modules below. *)
+
+
+(** 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. *)
+module Buffered : sig
+  type unconsumed =
+    { buf : bigstring
+    ; off : int
+    ; len : int }
+
+  type input =
+    [ `Bigstring of bigstring
+    | `String    of string ]
+
+  type 'a state =
+    | Partial of ([ input | `Eof ] -> 'a state) (** The parser requires more input. *)
+    | Done    of unconsumed * 'a (** The parser succeeded. *)
+    | 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. *)
+
+end
+
+(** 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. *)
+module Unbuffered : sig
+  type more =
+    | Complete
+    | Incomplete
+
+  type 'a state =
+    | Partial of 'a partial (** The parser requires more input. *)
+    | Done    of int * 'a (** The parser succeeded, consuming specified bytes. *)
+    | Fail    of int * string list * string (** The parser failed, consuming specified bytes. *)
+  and 'a partial =
+    { 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. *)
+    ; 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. *)
+end
+
+(** {2 Expert Parsers}
+
+    For people that know what they're doing. If you want to use them, read the
+    code. No further documentation will be provided. *)
+
+val pos : int t
+val available : int t