Module Shtream

module Shtream: sig .. end

Base module for shtreams, an abstraction of producers of typed data.

Shtreams are modeled on the standard library's Stream module, but provide additional features. The main difference is that a shtream is easily converted to and from another kind of data source: an in_channel. A shtream may be constructed from a channel (or a data source such as a command to run) by providing a reader to extract shtream elements from the in_channel. When converting a shtream back to a channel with Shtream.channel_of, if the shtream was constructed from a channel in the first place, that channel is returned, but if some of the shtream construction is happening internally, a child process is spawned to compute the shtream asynchronously.

Operations in this module are all indifferent to the type of elements in the Shtream.t. See modules AnyShtream, LineShtream, and StringShtream for operations specialized on the element type. Most shtream operations are common to all Shtream modules; these may also be found in Shtream.COMMON.

exception Failure

Raised on attempts to retrieve elements from an empty Shtream.t. Callbacks such as the argument to Shtream.from or Shtream.map may raise this to indicate the end of the shtream they are producing.

type 'a t

A shtream with elements of type 'a

exception CoFailure

Raised if a coshtream is no longer accepting data. This could happen, for example, were the shtream-consuming function to return before exhausting the shtream.

type 'a co_t

A coshtream accepting elements of type 'a

Basic Shtream Operations

val from : (int -> 'a option) -> 'a t

val close : 'a t -> unit

val of_list : 'a list -> 'a t

val list_of : 'a t -> 'a list

val of_stream : 'a Stream.t -> 'a t

val stream_of : 'a t -> 'a Stream.t

val npeek : ?n:int -> 'a t -> 'a list

val peek : ?n:int -> 'a t -> 'a option

val empty : 'a t -> unit

val is_empty : 'a t -> bool

val status : 'a t -> Proc.status option

val junk : ?n:int -> 'a t -> unit

val next : 'a t -> 'a

val next' : 'a t -> 'a option

val iter : ('a -> unit) -> 'a t -> unit

val filter : ('a -> bool) -> 'a t -> 'a t

val map : ('a -> 'b) -> 'a t -> 'b t

val concat_map : ('a -> 'b list) -> 'a t -> 'b t

val fold_left : ('a -> 'b -> 'a) -> 'a -> 'b t -> 'a

val fold_right : ('a -> 'b Lazy.t -> 'b) -> 'a t -> 'b -> 'b

val nil : unit -> 'a t

val insert : 'a -> 'a t -> unit

val cons : 'a -> 'a t -> 'a t

val append : 'a t -> 'a t -> 'a t

val try_again : unit -> 'a

val warn : ('a, unit, string, 'b) Pervasives.format4 -> 'a

val fail_with : Proc.status -> 'a

type error_handler = [ `Exception of exn | `Warning of string ] -> unit

The type for a shtream error handler. If a shtream generator calls warn s then the error handler receives `Warning s. If a shtream generator raises an exception e, then the error_handler receives `Exception e.

val current_error_handler : error_handler Pervasives.ref

val ignore_errors : error_handler

val warn_on_errors : error_handler

val die_on_errors : error_handler

val die_silently_on_errors : error_handler

val coshtream_of : ?procref:Channel.procref -> ('a t -> 'b) -> 'a co_t

val conil : unit -> 'a co_t

val conext : 'a co_t -> 'a -> unit

val coclose : 'a co_t -> unit

val annihilate : 'a t -> 'a co_t -> unit

val from_low : ?close:(unit -> unit) -> (int -> 'a) -> 'a t

val claim : 'a t -> 'a t

val set_reader : 'a t -> (Pervasives.in_channel -> 'a) -> unit

val hint_reader : 'a t -> Reader.t -> unit

type protector = Util.protector

Alias for Util.protector

val add_protection : protector -> 'a t -> unit

val add_cleanup : (unit -> unit) -> 'a t -> unit

val channel_of : ?procref:Channel.procref ->
       ?before:(unit -> unit) ->
       ?after:(unit -> unit) ->
       ('a -> unit) -> 'a t -> Pervasives.in_channel

val of_channel : ?hint:(Reader.raw_line -> 'a) ->
       (Pervasives.in_channel -> 'a) -> Pervasives.in_channel -> 'a t

val of_file : ?hint:(Reader.raw_line -> 'a) ->
       (Pervasives.in_channel -> 'a) -> string -> 'a t

val of_command : ?procref:Channel.procref ->
       ?dups:Channel.dup_spec ->
       ?hint:(Reader.raw_line -> 'a) ->
       (Pervasives.in_channel -> 'a) -> string -> 'a t

val of_program : ?procref:Channel.procref ->
       ?dups:Channel.dup_spec ->
       ?hint:(Reader.raw_line -> 'a) ->
       (Pervasives.in_channel -> 'a) ->
       ?path:bool -> string -> ?argv0:string -> string list -> 'a t

val of_thunk : ?procref:Channel.procref ->
       ?dups:Channel.dup_spec ->
       ?hint:(Reader.raw_line -> 'a) ->
       (Pervasives.in_channel -> 'a) -> (unit -> unit) -> 'a t

module type COMMON = sig .. end