package shexp

  1. Overview
  2. Docs
package shexp
Legend:
Page
Library
Module
Module type
Parameter
Class
Class type
Source

Module Std.ProcessSource

  • deprecated [since 2017-02] use Shexp_process. The Std.Process sub-module is no longer needed

The Shexp process monad

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.

Sourcemodule Context : sig ... end

Execution contexts

Sourceval eval : ?context: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.

Sourcemodule Logged : sig ... end
Sourcemodule Traced : sig ... end
Sourcemodule Prim : sig ... end
Sourcemodule type Debugger = sig ... end

shexp_process allows one to plug a debugger in the evaluator. Logged and Traced are essentially two non-interactive debuggers.

Sourcemodule With_debug (Dbg : Debugger) : sig ... end

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.

Sourcemodule Exit_status = Exit_status
Sourceval run_exit_status : string -> string list -> 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 -> Exit_status.t t
Sourceval call_bool : ?true_v:int list -> ?false_v:int list -> string list -> bool t
Sourcemodule Background_command : sig ... end
Sourceval spawn : string -> string list -> 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.

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

Sourcemodule Std_io = Std_io
Sourceval echo : ?where: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) format4 -> 'a
Sourceval eprintf : ('a, unit, string, unit t) 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:(Std_io.t list * 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:(Std_io.t list * Std_io.t) -> 'a t -> 'b t -> ('a * 'b) t

pipe_both 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 : Std_io.t list -> 'a t -> ('a * string) t

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

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

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

Redirections

Sourceval redirect : 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:Std_io.t -> ?stdout:Std_io.t -> ?stderr: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 Infix : sig ... end
Sourcemodule Let_syntax : sig ... end

Open this module when using ppx_let

Sourcemodule List : sig ... end
OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct