A process monad for shell scripting in OCaml.

include module type of Shexp_process
Sourcemodule Std : sig ... end
Sourcetype 'a t

An 'a t value represent a process pipeline description, that can be evaluated using eval into a value of type 'a. Note that creating an 'a t value has no effect. Effects are only performed when calling eval.

Sourceval eval : ?context:Shexp_process__.Process.Context.t -> 'a t -> 'a

Evaluate the given process in the given environment.

If context is not specified, a temporary one is created. If you are calling eval many times, then creating a context and reusing it is more efficient.

Basic processes

Sourceval return : 'a -> 'a t

Classic monad operations. Note that because shexp_process uses threads under the hood, you should be careful about using global mutable data structures. To communicate values between concurrent processes, use the sync function.

Sourceval bind : 'a t -> f:('a -> 'b t) -> 'b t
Sourceval map : 'a t -> f:('a -> 'b) -> 'b t
Sourceval fail : exn -> _ t

Create a process that fails with the given exception. Evaluation of this process will raise this exception.

Sourceval fork : 'a t -> 'b t -> ('a * 'b) t

fork a b represents two processes that are executed concurrently. The resulting process will block until both a and b have finished and will return both of their results.

This is essentially the same as forking a system process: both process can independently change the current working directory, change their standard out, etc...

Regarding errors, if the evaluation of both processes fail, then only one the exceptions will be kept. It is not specified which one. You should use Traced to get a full trace and see what exceptions are raised and where.

Sourceval fork_unit : 'a t -> unit t -> 'a t

Same as map (fork a b) ~f:(fun (x, ()) -> x)

Sourceval fork_all : 'a t list -> 'a list t

fork_all ps represents List.length ps processes executed concurrently. fork_all generalizes fork from pairs of elements to lists of elements.

Sourceval fork_all_unit : unit t list -> unit t

A slightly more efficient version of map (fork_all ps) ~f:(fun _ -> ())

Sourceval protect : finally:unit t -> 'a t -> 'a t

protect ~finally t protects against execution errors. finally is always executed, even if the evaluation of t raises.

Sourceval reify_exn : ('a -> 'b t) -> 'a -> 'b t

Capture exceptions into the process monad. You can use this if the argument of protect is the result of a function call.

For instance in the following code finally wouldn't be executed:

  let f () = raise Not_found

               protect ~finally (f ())

You can write instead:

  protect ~finally (reify_exn f ())

Running commands

Sourceval run : string -> string list -> unit t

Run an external program. This will fail if the external program does not exists, is signaled or exit with a non-zero exit code.

Sourceval run_exit_code : string -> string list -> int t

Run an external program and return its exit code. This will fail if the external program is signaled.

Sourceval run_exit_status : string -> string list -> Shexp_process.Exit_status.t t

Run an external program and return its exit status.

Sourceval run_bool : ?true_v:int list -> ?false_v:int list -> string -> string list -> bool t

Run an external program, returns true if its exit code is part of true_v and false if it is part of false_v.

Sourceval call : string list -> unit t

Same functions as the 'run' ones above, but take a string list instead. This way, the first element and the others are treated in a homogeneous way. It can ease prepending commands in specific circumstances, e.g. if profile then call ("time" :: command) else call command

E.g. call ["grep"; "-i"; pattern; filename] is equivalent to run "grep" ["-i"; pattern; filename]

Sourceval call_exit_code : string list -> int t
Sourceval call_exit_status : string list -> Shexp_process.Exit_status.t t
Sourceval call_bool : ?true_v:int list -> ?false_v:int list -> string list -> bool t
Sourceval spawn : string -> string list -> Shexp_process__.Process.Background_command.t t

Start an external program but do not wait for its termination. If you never call wait on the result, the process will become a zombie after it terminates.

Sourceval wait : Shexp_process__.Process.Background_command.t -> Shexp_process.Exit_status.t t

Wait for a background command to terminate and return its exit status.

Unix environment

Sourceval find_executable : string -> string option t

Return the absolute path to the given command.

Sourceval find_executable_exn : string -> string t
Sourceval get_env : string -> string option t

Return the value associated to the given environment variable.

Sourceval get_env_exn : string -> string t
Sourceval set_env : string -> string -> 'a t -> 'a t

set_env var value k represents the process k evaluated in a context where the envornment variable var is set to value.

Sourceval unset_env : string -> 'a t -> 'a t

set_env var value k represents the process k evaluated in a context where the environment variable var is unset.

Current working directory

Sourceval cwd_logical : string t

Return the current working directory. Note that there is no guarantee that this directory exists. For instance if a component in this path has is renamed during the evaluation of the process, then this will be a dangling directory.

Sourceval chdir : string -> 'a t -> 'a t

chdir dir k represents the process k evaluated in a context where the current working directory is changed to dir.

IO

Sourceval echo : ?where:Shexp_process.Std_io.t -> ?n:unit -> string -> unit t

Output a string on one of the standard io. ~n:() suppresses the newline output at the end.

Sourceval print : string -> unit t

echo ~where:Stdout

Sourceval eprint : string -> unit t

echo ~where:Stderr

Sourceval printf : ('a, unit, string, unit t) Stdlib.format4 -> 'a
Sourceval eprintf : ('a, unit, string, unit t) Stdlib.format4 -> 'a
Sourceval read_all : string t

Consume all standard input

Sourceval fold_lines : init:'a -> f:('a -> string -> 'a t) -> 'a t

Fold over lines in the input. f is given the line with the end of line. Both "\r\n" and "\n" are treated as end of lines.

Sourceval fold_chunks : sep:char -> init:'a -> f:('a -> string -> 'a t) -> 'a t

Fold over chunks separated by sep in the input. This can be used in conjunction with commands that support ending entries in the output with a '\000' such as find -print0.

Sourceval iter_lines : (string -> unit t) -> unit t
Sourceval iter_chunks : sep:char -> (string -> unit t) -> unit t

Pipes

Sourceval pipe : ?connect:(Shexp_process.Std_io.t list * Shexp_process.Std_io.t) -> unit t -> 'a t -> 'a t

pipe ~connect:(aios, bio) a b is a process obtain by connecting the aios of a to the bio of b. a and b are evaluated in parallel (as with fork).

(aio, bio) defaults to ([Stdout], Stdin).

Sourceval pipe_both : ?connect:(Shexp_process.Std_io.t list * Shexp_process.Std_io.t) -> 'a t -> 'b t -> ('a * 'b) t

pipe_pair a b is a the same as pipe but returns the results of both a and b.

Sourceval epipe : unit t -> 'a t -> 'a t

Same as pipe ~connect:([Stderr], Stdin).

Sourceval epipe_both : 'a t -> 'b t -> ('a * 'b) t
Sourceval capture : Shexp_process.Std_io.t list -> 'a t -> ('a * string) t

capture ios t = pipe_both ~connect:(ios, Stdin) read_all

Sourceval capture_unit : Shexp_process.Std_io.t list -> unit t -> string t

capture_unit ios t = pipe ~connect:(ios, Stdin) read_all

Redirections

Sourceval redirect : Shexp_process.Std_io.t list -> ?perm:int -> flags:Unix.open_flag list -> string -> 'a t -> 'a t

redirect ios ?perm ~flags filename t redirects the following ios to a file in t. perm and flags are passed the same as for Unix.openfile.

Sourceval stdout_to : ?append:unit -> string -> 'a t -> 'a t

Convenient wrappers for redirect

Sourceval stderr_to : ?append:unit -> string -> 'a t -> 'a t
Sourceval outputs_to : ?append:unit -> string -> 'a t -> 'a t
Sourceval stdin_from : string -> 'a t -> 'a t
Sourceval replace_io : ?stdin:Shexp_process.Std_io.t -> ?stdout:Shexp_process.Std_io.t -> ?stderr:Shexp_process.Std_io.t -> 'a t -> 'a t

Replace the given standard io by the given one. For instance to redirect stdout to stderr: replace_io ~stdout:Stderr t

Sourceval out_to_err : 'a t -> 'a t

out_to_err t = replace_io ~stdout:Stderr t

Sourceval err_to_out : 'a t -> 'a t

err_to_out t = replace_io ~stderr:Stdout t

Temporary files & directory

Sourceval temp_dir : string t

Return the current temporary directory

Sourceval set_temp_dir : string -> 'a t -> 'a t

set_temp_dir dir k represents the process k evaluated in a context where the current temporary directory is set to dir.

Sourceval with_temp_file : prefix:string -> suffix:string -> (string -> 'a t) -> 'a t

with_temp_file ~prefix ~suffix f is a process that creates a temporary file and passes it to f. The file is created inside the temporary directory.

When the process returned by f finishes, the file is removed.

Sourceval with_temp_dir : prefix:string -> suffix:string -> (string -> 'a t) -> 'a t

Same as with_temp_file but creates a directory. The directory and its contents are deleted when the process finishes.

FS operations

Sourceval chmod : string -> perm:Unix.file_perm -> unit t
Sourceval chown : string -> uid:int -> gid:int -> unit t
Sourceval mkdir : ?perm:Unix.file_perm -> ?p:unit -> string -> unit t
Sourceval rm : string -> unit t
Sourceval rmdir : string -> unit t
Sourceval mkfifo : ?perm:Unix.file_perm -> string -> unit t
Sourceval rename : string -> string -> unit t
Sourceval stat : string -> Unix.LargeFile.stats t
Sourceval lstat : string -> Unix.LargeFile.stats t
Sourceval readdir : string -> string list t
Sourceval file_exists : string -> bool t
Sourceval rm_rf : string -> unit t

Recursively remove a tree

Misc

Sourceval sleep : float -> unit t

Synchronisation

Sourceval new_channel : 'a Event.channel t
Sourceval sync : 'a Event.event -> 'a t

Misc

Sourcemodule Let_syntax : sig ... end

Open this module when using ppx_let

Sourcemodule type Debugger = Shexp_process.Debugger
Sourcemodule With_debug = Shexp_process.With_debug
Sourcemodule Exit_status = Shexp_process.Exit_status
Sourcemodule Background_command = Shexp_process.Background_command