# Module Cf_flow

    module Cf_flow: sig .. end

Lazy stream procesors and their operators.

Overview

A `Cf_flow` value is like a `Cf_seq` value that can take intermediate input to continue generating output. Many of the other modules in the `cf` library use this module.

The semantics of this module are derived from the stream processors in the Fudgets system, as described by Magnus Carlsson and Thomas Hallgren in their joint Ph.D. thesis, chapter 16.

Types

    type ('i, 'o) t = ('i, 'o) cell Stdlib.Lazy.t

A stream processor

    type ('i, 'o) cell =

`|` | `P of `'o * ('i, 'o) t`` | `(*` | Output a value | `*)`
`|` | `Q of `('i -> ('i, 'o) cell)`` | `(*` | Input a value | `*)`
`|` | `Z` | `(*` | Finish processing stream | `*)`

Constructors

    val nil : ('y, 'x) t

A stream processor that reads no input and writes no output.

    val nop : ('x, 'x) t

A stream processor that outputs every input value without change.

    val filter : ('x -> bool) -> ('x, 'x) t

Use `filter f` to construct a stream processor that applies `f` to every input value and outputs only those for which the function result is `true`.

    val map : ('i -> 'o) -> ('i, 'o) t

Use `map f` to construct a stream processor that applies `f` to every input value and outputs the result.

    val optmap : ('i -> 'o option) -> ('i, 'o) t

Use `optmap f` to construct a stream processor that applies `f` to every input value and outputs the result if there is one.

    val listmap : ('i -> 'o list) -> ('i, 'o) t

Use `listmap f` to construct a stream processor that applies `f` to every input value and outputs every element of the resulting list.

    val seqmap : ('i -> 'o Cf_seq.t) -> ('i, 'o) t

Use `listmap f` to construct a stream processor that applies `f` to every input value and outputs every element of the resulting sequence.

    val broadcast : ('i, 'o) t list -> ('i, 'o) t

Use `broadcast ws` to construct a stream processor that combines the input and output of every stream processor in the list `ws` by first rendering all the output from each stream in turn, then ingesting all the input to each stream in turn, until all streams are completed.

    val mapstate : ('s -> 'i -> 's * 'o) -> 's -> ('i, 'o) t

Use `mapstate f s` with an initial state value `s` and a folding function `f` to construct a stream processor that folds the state into every input value to produce an output value and a new state.

    val machine : ('s -> 'i -> ('s * 'o Cf_seq.t) option) -> 's -> ('i, 'o) t

Use `machine f s` with an initial state value `s` and a folding function `f` to construct a stream processor that folds the state into every input value to produce either a sequence of values to output and a new state or the end of stream processing.

Operators

    module Op: sig .. end

Open this module to bring the operator functions into the current scope.

Miscellaneous

    val to_seq : (unit, 'o) t -> 'o Cf_seq.t

Use `to_seq w` to convert a stream processor `w` into the equivalent sequence. This can only work when the stream processor ingests input of the `unit` type.

    val of_seq : 'o Cf_seq.t -> ('i, 'o) t

Use `of_seq z` to convert a sequence into the equivalent stream processor (which never ingests any input).

    val upcase : (char, char) t

A stream processor that converts uppercase US-ASCII characters into lowercase characters. All other characters are unchanged.

    val dncase : (char, char) t

A stream processor that converts lowercase US-ASCII characters into uppercase characters. All other characters are unchanged.

    val commute : ('i, 'o) t -> 'i Cf_seq.t -> 'o Cf_seq.t

Use `commute w z` to produce an output sequence from a flow `w` that ingests its input from the sequence `z`.

    val commute_string : (char, char) t -> string -> string

Use `commute_string w s` to commute the sequence of characters in the string `s` with the flow `w` and compose a new string from the resulting sequence.

    val drain : ('i, 'o) t -> 'o Cf_seq.t

Use `drain w` to produce an output sequence comprised of all the values output from the stream processor `w` until the first input is required.

    val flush : ('i, 'o) t -> ('i, 'o) t

Use `flush w` to discard all the output from the flow `w` until the first input is required.

    val ingestor : ('a Cf_seq.t option, 'a) t

A stream processor that copies to its output every element of its input sequences. The stream processor finishes when it ingests `None`.

This stream processor is helpful for placing at the end of a serial composition to produce a transcoder.

    val transcode : ('i Cf_seq.t option, 'o) t -> 'i Cf_seq.t -> 'o Cf_seq.t

Use `transcode w z` to produce the sequence of output values obtained by executing the transcoder stream processor `w` to ingest every element of the sequence `z`.

    module Transcode: sig .. end

A namespace for the `more` and `last` transcoder functions.

Monad Functions

    val readC : (('i, 'o) t, 'i) Cf_cmonad.t

The continuation monad that returns a value obtained from the flow produced by its evaluation.

    val writeC : 'o -> (('i, 'o) t, unit) Cf_cmonad.t

Use `writeC x` to compose a continuation monad that puts `x` into the flow produced by evaluation and returns the unit value.

    val evalC : (('i, 'o) t, unit) Cf_cmonad.t -> ('i, 'o) t

Use `evalC m` to evaluate the continuation monad `m`, computing the encapsulated flow.

    val readSC : ('s, ('i, 'o) t, 'i) Cf_scmonad.t

The state-continuation monad that returns a value obtained from the flow produced by its evaluation.

    val writeSC : 'o -> ('s, ('i, 'o) t, unit) Cf_scmonad.t

Use `writeSC x` to compose a state-continuation monad that puts `x` into the flow produced by evaluation and returns the unit value.

    val evalSC : ('s, ('i, 'o) t, unit) Cf_scmonad.t -> 's -> ('i, 'o) t

Use `evalSC m s` to evaluate the state-continuation monad `m` with the initial state `s`, computing the encapsulated flow.