Module Fitting

module Fitting: sig .. end

Fittings represent processes, internal or external, that produce, consume, or transform data. This module provides basic constructors to make fittings out of both external UNIX commands and internal Shtream functions, and fitting combinators that combine fittings in a variety of ways.

This module includes both functions specialized to shtreams of Line.t and a functor for creating a structure specialized for sthreams of other types.

Line Fitting Interface

Types

type ('a -> 'b) t

A fitting that consumes values of type 'a and produces values of type 'b.

type 'a elem = 'a LineShtream.elem

type initial = LineShtream.initial

Alias for AnyShtream.ELEM.elem at LineShtream

This is the type of elements that fittings know how to write to external processes.

type 'a shtream = 'a LineShtream.t

Alias for AnyShtream.ELEM.initial at LineShtream

This is the parameter to the type Fitting.elem for specifying the type of elements that fittings know how to read from external processes. That is, fittings constructed from external processes produce values of type initial elem.

type 'a coshtream = 'a LineShtream.co_t

Alias for LineShtream.t

Alias for LineShtream.co_t

type procref = Channel.procref

Alias for Channel.procref

type text = initial elem

Alias for Fitting.initial Fitting.elem

Values

val (-|) : ('a -> 'b) t -> ('b -> 'c) t -> ('a -> 'c) t

Connect the output of one fitting to the input of another. This is the most basic fitting combinator, and bears introduction before the full variety of fitting components.

val pipe : ('a -> 'b) t -> ('b -> 'c) t -> ('a -> 'c) t

Alias for Fitting.(-|)

Basic Fitting Constructors

Producers

Producers are useful for starting off pipelines.

val from_file : string -> ('a -> text) t

Produce the contents of a file. from_file file -| fitting is like

% fitting < file

val from_null : ('a -> text) t

Produce nothing. from_null -| fitting is like

% fitting < /dev/null

val from_gen : Channel.dup_in_source -> ('a -> text) t

Produce the contents of a Channel.dup_in_source.

val from_shtream : 'a shtream -> ('b -> 'a) t

Produce the contents of a shtream.

Consumers

Consumers are useful for ending pipelines.

val to_file : ?clobber:Channel.clobber_spec -> string -> ('a elem -> 'b) t

Redirect standard output to a file. See Channel.clobber_spec for open modes. fitting -| to_file file is like

% fitting > file

val to_null : ('a elem -> 'b) t

Redirect standard output nowhere. fitting -| to_null is like

% fitting > /dev/null

val to_stderr : ('a elem -> 'b) t

Redirect standard output to standard error. fitting -| to_stderr is like

% fitting >&2

val to_gen : Channel.dup_out_source -> ('a elem -> 'b) t

Redirect standard output to Channel.dup_out_source.

val to_coshtream : 'a coshtream -> ('a -> 'b) t

Redirect output to a coshtream. (A coshtream is a consumer in another process.)

Transformers

val command : string -> ('a elem -> text) t

Run an external command as a fitting. The fitting's input is connected to the command's standard input and the fitting's output to the command's standard output. This runs the command in the shell, in the style of Channel.open_command.

val program : ?path:bool ->
       string ->
       ?argv0:string -> string list -> ('a elem -> text) t

Run an external program as a fitting. The fitting's input is connected to the program's standard input and the fitting's output to the program's standard output. This runs the program in the shell, in the style of Channel.open_program.

val thunk : (unit -> unit) -> ('a elem -> text) t

Run a thunk as a fitting. The thunk is run in a child process whose standard input and output are connected to the fitting's input and output.

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

Map each element according to a function. This lifts a function on elements into a fitting component.

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

Filter the input according to a predicate.

val trans : ('a shtream -> 'b shtream) -> ('a -> 'b) t

Transform the input according to a function on shtreams.

val sed_string : (string -> 'a) -> ('b elem -> 'a) t

Like Fitting.sed with a lift from strings.

val grep_string : (string -> bool) -> ('a elem -> 'a elem) t

Filter the input according to a string predicate.

Fitting Combinators

val (/</) : (text -> 'a) t ->
       Channel.dup_spec -> (text -> 'a) t

Redirect some inputs to a fitting. fitting /</ dups performs the redirections specifed by dups for the extent of fitting. For example, fitting /</ [ 4 %<& 0; 0 %< "file" ] is like

% fitting 4<&0 <file

val redirect_in : Channel.dup_spec ->
       (text -> 'a) t -> (text -> 'a) t

Alias for Fitting.(/</)

val (/>/) : ('a -> 'b elem) t ->
       Channel.dup_spec -> ('a -> 'b elem) t

Redirect some outputs from a fitting. fitting />/ dups performs the redirections specifed by dups for the extent of fitting. For example, fitting />/ [ 2 %>& 1 ] is like

% fitting 2>&1

val redirect_out : Channel.dup_spec ->
       ('a -> 'b elem) t -> ('a -> 'b elem) t

Alias for Fitting.(/>/)

val (^>>=) : ('a -> 'b) t ->
       (Proc.status -> ('a -> 'b) t) -> ('a -> 'b) t

Sequence two fittings, with control. Runs its first argument, passes it's exit code to the second argument, and runs the resulting fitting. The second argument can therefore choose what to do based on the result of the first.

The exit code of external processes is the actual exit code as reported by Proc.wait. The exit code of a shtream is 0 unless the shtream terminates by calling Shtream.fail_with n, in which case the code in n. Or, Fitting.yield can return an exit code directly.

val seq : ('a -> 'b) t ->
       (Proc.status -> ('a -> 'b) t) -> ('a -> 'b) t

Alias for Fitting.(^>>=)

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

Sequence two fittings, ignoring the exit code of the first. a ^>> b is exactly a ^>>= fun _ -> b . This is like ; in the shell.

val (&&^) : ('a -> 'b) t -> ('a -> 'b) t -> ('a -> 'b) t

Sequence two fittings, running the second if the first succeeds. If the first fails, skips the second and propagates the exit code from the first. This is like && in the shell.

val (||^) : ('a -> 'b) t -> ('a -> 'b) t -> ('a -> 'b) t

Sequence two fittings, running the second if the first fails. If the first succeeds, skips the second and returns an exit code of 0. This is like || in the shell.

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

Run a list of fittings in sequence with Fitting.(^>>).

val (~&&) : ('a -> 'b) t list -> ('a -> 'b) t

Run a list of fittings in sequence with Fitting.(&&^). Terminates the sequence when any component fails.

val (~||) : ('a -> 'b) t list -> ('a -> 'b) t

Run a list of fittings in sequence with Fitting.(||^). Terminates the sequence when any component succeeds.

val commands : string list -> (text -> text) t

Run a list of commands, piping the output of each into the next.

val yield : Proc.status -> ('a -> 'b) t

Produces a fitting that returns the given exit code. Has no effect on input and output, but can be used to pass a particular code along in a sequence.

val caml : (unit -> ('a -> 'b) t) -> ('a -> 'b) t

Delay an Ocaml thunk until a fitting is run. Given a thunk that produces a fitting, Fitting.caml constructs a new fitting that, when run, forces the thunk and runs the resulting fitting. This allows for Ocaml side-effects at arbitrary points during a fitting.

val (^&=) : (text -> 'a elem) t ->
       (Proc.t -> ('b -> 'c) t) -> ('b -> 'c) t

Run a fitting in the background. bg ^&= fg runs bg in the background, passed its Proc.t to fg, and runs the fitting returned by fg (in the foreground).

Notice that the bg must have input type Fitting.text; it will construct its own input shtream from the standard input.

val par : (text -> 'a elem) t ->
       (Proc.t -> ('b -> 'c) t) -> ('b -> 'c) t

Alias for Fitting.(^&=)

val (^&) : (text -> 'a elem) t ->
       ('b -> 'c) t -> ('b -> 'c) t

Run a fitting in the background, ignore its Proc.t. This backgrounds its first argument and then continues with its second argument in the foreground.

Fitting Runners

val run_source : (text -> 'a) t -> 'a shtream

Run a fitting, returning its output as a shtream. The fitting will take its input from the standard input.

val run_sink : ('a -> 'b elem) t -> 'a coshtream

Run a fitting, returning a costhream connected to its input. The fitting will send its output from the standard output.

val run_list : (text -> 'a) t -> 'a list

Run a fitting, returning its output as a list. The fitting will take its input from the standard input.

val run_shtream : ('a -> 'b) t -> 'a shtream -> 'b shtream

Transform a fitting into a shtream transformer.

val run_in : ?procref:procref ->
       (text -> 'a elem) t -> Pervasives.in_channel

Run a fitting, returning its output as an in_channel. The fitting will take its input from the standard input. If ?procref is provided, the Proc.t of the child process will be stashed.

val run_out : ?procref:procref ->
       (text -> 'a elem) t -> Pervasives.out_channel

Run a fitting, returning its input as an out_channel. The fitting will send its output from the standard output. If ?procref is provided, the Proc.t of the child process will be stashed.

val run_backquote : ?procref:procref ->
       (text -> 'a elem) t -> string

Run a fitting, returning its output collected as a string. The exit code of the child process can be retrieved by providing ?procref.

val run_bg : (text -> 'a elem) t -> Proc.t

Run a fitting in the background, returning its Proc.t. The fitting will take its input from the standard input and send its output to the standard output.

val run : (text -> 'a elem) t -> Proc.status

Run a fitting in the foreground, returning its exit status. The fitting will take its input from the standard input and send its output to the standard output.

Convenient Conversions

These conversions use the Fitting.elem conversions provided to the Fitting.Make functor by AnyShtream.ELEM. The conversion AnyShtream.ELEM.string_of or AnyShtream.ELEM.of_string is completely applied for each of these conversions, so no state (should there be any) is retained in between calls.

val string_of_elem : 'a elem -> string

Convert a shtream element to a string.

val elem_of_string : string -> text

Convert a string to a shtream element.

val int_of_elem : 'a elem -> int

Convert a shtream element to an integer.

val elem_of_int : int -> text

Convert a integer to a shtream element.

val char_of_elem : 'a elem -> char

Convert a shtream element to a character.

val elem_of_char : char -> text

Convert a character to a shtream element.

val float_of_elem : 'a elem -> float

Convert a shtream element to a float.

val elem_of_float : float -> text

Convert a float to a shtream element.

val bool_of_elem : 'a elem -> bool

Convert a shtream element to a boolean.

val elem_of_bool : bool -> text

Convert a boolean to a shtream element.

Functorial Interface

module type SHTREAM = AnyShtream.ANYSHTREAM

The input signature of the functor Fitting.Make.

module type FITTING = sig .. end

The output signature of the functor Fitting.Make.

module Make: functor (Shtream : SHTREAM) -> FITTING 
  with type initial = Shtream.initial
   and type 'a elem      = 'a Shtream.elem
   and type 'a shtream   = 'a Shtream.t
   and type 'a coshtream = 'a Shtream.co_t

Build a new fittings module.