Module Biocaml_transform (.ml)

module Biocaml_transform: sig .. end

Buffered transforms. A buffered transform represents a method for converting a stream of inputs to a stream of outputs. However, inputs can also be buffered, i.e. you can feed inputs to the transform and pull out outputs later. There is no requirement that 1 input produces exactly 1 output. It is common that multiple input values are needed to construct a single output, and vice versa.

Buffered transforms serve as a general method for working with streams of data and flexibly composing mappings from inputs to outputs. The buffering aspect supports asynchronous programming interfaces. Parsers and printers throughout Biocaml are implemented with this module whenever possible.

Often mappings need to account for errors, e.g. an input string cannot be converted to an integer. Several methods below explicitly support buffered transforms where the output type is a Result.t.

type ('input, 'output) t

Type of a buffered transform converting 'inputs to 'outputs.

exception Feeding_stopped_transform of string

Exception thrown when feed is called on a transform after it has been stopped.

val make : ?name:string ->
       feed:('input -> unit) ->
       next:(bool -> [ `end_of_stream | `not_ready | `output of 'output ]) ->
       unit -> ('input, 'output) t

make ~feed ~next () creates a transform that can be fed with feed and read from with next.

feed input should store input in a buffer, which is presumably a shared state also available to next.

next stopped should remove values from the buffer, convert it to an `output and return this output, or return `not_ready if there are not enough buffered inputs to create an output value, or return `end_of_stream if the buffer has been stopped, as determined by the supplied argument, and there is no more input.

Depending on the specifics of the transform, it may be the case that the buffer has been stopped but there is not enough input to create an output value. It is the caller's choice how to handle this or any other kind of error, e.g. make the return type a Result.t.

name an optional name for the transform that will be used in error messages.

val feed : ('input, 'output) t -> 'input -> unit

feed t i stores i into the buffered transform.
Raises Feeding_stopped_transform name if called on a t that has been stopped.

val next : ('input, 'output) t ->
       [ `end_of_stream | `not_ready | `output of 'output ]

next t returns an output value if possible, `not_ready if t needs to be fed with more input before it can produce an output, or `end_of_stream if t has been stopped and has no more data.

val stop : ('input, 'output) t -> unit

stop t declares t to be stopped, which means subsequent calls to:

feed t _ will raise Feeding_stopped_transform. Feeding a stopped transform is not allowed.

next t will eventually return `end_of_stream, not necessarily the immediate next call as there may still be buffered values available for output.

val name : ('input, 'output) t -> string option

name t returns the name of t.

val identity : ?name:string -> unit -> ('a, 'a) t

identity () returns a transform that simply returns its inputs as outputs without modification.

val to_stream_fun : ('input, 'output) t -> 'input Stream.t -> 'output Stream.t

to_stream_fun t returns a function f that behaves like t but the inputs and outputs are on standard OCaml streams.

val in_channel_strings_to_stream : ?buffer_size:int ->
       Pervasives.in_channel ->
       (string, 'output) t -> 'output Stream.t

in_channel_strings_to_stream ic t returns a stream of 'outputs given a transform t that knows how to produce 'outputs from strings. The strings are read from the in_channel.

Compose

Buffered transforms are mutable and one should not expect nice mathematical properties from composing them. The intention here is to provide building blocks that allow the creation of more complex transforms from simpler ones. Only the final resultant transform should be used. Feeding/reading the transforms being composed is likely to lead to violations of the stated behavior of the above operations.

val on_input : ('b, 'c) t -> f:('a -> 'b) -> ('a, 'c) t

on_input f t returns a transform that converts its inputs with f and feeds the results to t.

val on_output : ('a, 'b) t -> f:('b -> 'c) -> ('a, 'c) t

on_output t f returns a transform that behaves like t except the outputs are first converted by f.

val compose : ('a, 'b) t ->
       ('b, 'c) t -> ('a, 'c) t

compose t u composes t and u.

val mix : ('a1, 'b1) t ->
       ('a2, 'b2) t ->
       f:('b1 -> 'b2 -> 'c) -> ('a1 * 'a2, 'c) t

mix t u f returns a transform that takes as input a pair of the inputs expected by t and u, and outputs a single value that is the result of applying f to the outputs of t and u.

val filter_compose : ('il, 'ol) t ->
       ('ir, 'our) t ->
       destruct:('ol -> [ `No of 'filtered | `Yes of 'ir ]) ->
       reconstruct:([ `Done of 'our | `Filtered of 'filtered ] -> 'result) ->
       ('il, 'result) t

filter_compose t u ~destruct ~reconstruct produces a transform that feeds a filtered subset of ts outputs to u. Only those outputs ol of t for which destruct ol returns `Yes are passsed on to u. The filterd out values are combined with u's output using reconstruct.

val split_and_merge : ('il, 'ol) t ->
       ('ir, 'our) t ->
       split:('input -> [ `left of 'il | `right of 'ir ]) ->
       merge:([ `left of 'ol | `right of 'our ] -> 'output) ->
       ('input, 'output) t

split_and_merge t u ~split ~merge returns a transform whose input is split using split, passing the result either to t or u, and then the outputs of t and u are combined using merge. There is no guarantee about the order in which the inputs are fed to t and u (it depends on the buffering done by the individual input transforms).

Result.t Outputs

Operations analogous to those above, but for transforms whose output types are Result.ts.

val make_result : ?name:string ->
       feed:('input -> unit) ->
       next:(bool ->
             [ `end_of_stream | `not_ready | `output of ('a, 'b) Core.Result.t ]) ->
       unit -> ('input, ('a, 'b) Core.Result.t) t

Like Biocaml_transform.make but the output is a Result.t. Also, Biocaml_transform.stop is automatically called when an error occurs.

val on_ok : ('input, ('ok, 'error) Core.Result.t) t ->
       f:('ok -> 'still_ok) ->
       ('input, ('still_ok, 'error) Core.Result.t) t

Like on_output but on the successful part of the output.

val on_error : ('input, ('ok, 'error) Core.Result.t) t ->
       f:('error -> 'another_errror) ->
       ('input, ('ok, 'another_errror) Core.Result.t) t

Like on_output but on the erroneous part of the output.

val compose_results : on_error:([ `left of 'error_left | `right of 'error_right ] -> 'error) ->
       ('input_left, ('middle, 'error_left) Core.Result.t) t ->
       ('middle, ('output_right, 'error_right) Core.Result.t) t ->
       ('input_left, ('output_right, 'error) Core.Result.t) t

compose_results t u is like Biocaml_transform.compose but for transforms returning Result.ts. The on_error function specifies how errors in t or u should be converted into those in the resultant transform.

val compose_results_merge_error : ('a, ('b, 'el) Core.Result.t) t ->
       ('b, ('d, 'er) Core.Result.t) t ->
       ('a, ('d, [ `left of 'el | `right of 'er ]) Core.Result.t)
       t

Like Biocaml_transform.compose_results but with a pre-specified on_error function.

val compose_result_left : ('input_left, ('middle, 'error) Core.Result.t) t ->
       ('middle, 'output_right) t ->
       ('input_left, ('output_right, 'error) Core.Result.t) t

Like Biocaml_transform.compose_results but only the first transform returns Result.ts.

Communication with other libraries

class type [['input, 'output]] object_t = object .. end

Generic transform type.

val to_object : ('a, 'b) t -> ('a, 'b) object_t

val of_object : ('a, 'b) object_t -> ('a, 'b) t

Deprecated

module Line_oriented: sig .. end

A buffering parsing_buffer for line-oriented formats.

module Printer_queue: sig .. end

A generic buffering printer.

Low-level API

val make_general : ?name:string ->
       next:(unit -> [ `end_of_stream | `not_ready | `output of 'output ]) ->
       feed:('input -> unit) ->
       stop:(unit -> unit) -> unit -> ('input, 'output) t

The most general way to make a transform. All make functions above are implemented with this one.