Module Shell

module Shell: sig .. end
Shell scripting in OCaml.

This module contains basic blocks for shell scripting in OCaml. It tends to be safer than just using Unix.system because it handles errors more strictly.

Process handling

type 'a with_process_flags = ?use_extra_path:bool ->
?timeout:Core.Std.Time.Span.t option ->
?working_dir:string ->
?setuid:int ->
?setgid:int ->
?env:[ `Extend of (string * string) list | `Replace of (string * string) list ] ->
?verbose:bool -> ?echo:bool -> ?input:string -> ?keep_open:bool -> 'a
This type is an umbrella type for all the command that dispatch a process. It comes with a list of arguments whose default value can be tweaked by set_defaults.

type 'a with_run_flags = ?expect:int list -> 'a with_process_flags 
This is the list of flags for normal process dispatch. It is an extension of with_process_flags.

Basic run functions

In all the functions below the command is specified with two arguments. The first one is a string representing the process to run. The second one is the list of arguments to pass.

Although the arguments do not need to be escaped there is still a risk that they might be interpreted as flags when they aren't. Most basic unix utilities provide the ability to pass arguments after "--" to avoid this.

Usage example:

    let patch = run_full ~expect:[0;1] "diff" ["-u";"--";file1;file2]

type 'a cmd = string -> string list -> 'a 
val run : unit cmd with_run_flags
Runs a command and discards its output.
val run_lines : ?eol:char -> string list cmd with_run_flags
Runs a command and returns its output line separated. Note: most commands print a newline at the end of their output so the shell prompt appears on its own line. If the output ends in a newline, it is stripped before splitting the output into a string list to avoid there being a final element in the list containing just the empty string.

In some cases, the newline should not be stripped (e.g., "cat" will not "add" a newline). If you care, use run_full for the entire buffer.

val run_one : ?eol:char -> string option cmd with_run_flags
Returns the first line of the command's output. (This function might terminate the program early the same way that piping through grep would)
val run_one_exn : ?eol:char -> string cmd with_run_flags
val run_full : string cmd with_run_flags
Return the full command's output in one string. See the note in run_lines.
val run_fold : ?eol:char ->
init:'a ->
f:('a -> string -> 'a * [ `Continue | `Stop ]) ->
'a cmd with_run_flags
Fold over the lines in the stdout of a process; The `Continue/`Stop argument is there to allow early returning. eol specifies the end of line character used to separate the lines outputted by the the program

Dispatch to /bin/bash

All these function take a format (like printf) and run it through the shell.

Usage example:

    sh "cp -- %s %s" (Filename.quote file1)  (Filename.quote file2)

In general it is recommended to avoid using those too much and to prefer the run* family of function instead because it avoids pitfall like escaping issues and is much more straightforward to think about.

type ('a, 'ret) sh_cmd = ('a, unit, string, 'ret) Pervasives.format4 -> 'a 
val sh : ('a, unit) sh_cmd with_run_flags
val sh_lines : ('a, string list) sh_cmd with_run_flags
val sh_full : ('a, string) sh_cmd with_run_flags
val sh_one : ('a, string option) sh_cmd with_run_flags
val sh_one_exn : ('a, string) sh_cmd with_run_flags
val noninteractive_ssh_options : string list
val noninteractive_no_hostkey_checking_options : string list
type 'a with_ssh_flags = ?ssh_options:string list -> ?user:string -> host:string -> 'a 
val ssh : ('a, unit) sh_cmd with_run_flags with_ssh_flags
val ssh_lines : ('a, string list) sh_cmd with_run_flags with_ssh_flags
val ssh_full : ('a, string) sh_cmd with_run_flags with_ssh_flags
val ssh_one : ('a, string option) sh_cmd with_run_flags with_ssh_flags
val ssh_one_exn : ('a, string) sh_cmd with_run_flags with_ssh_flags

Test dispatches

Usage example:

    if Shell.test "diff" ["-q";"--";file1;file2] then
       Printf.printf "Files %S and %S are the same\n%!" file1 file2;

type 'a with_test_flags = ?true_v:int list -> ?false_v:int list -> 'a with_process_flags 
This is the list of flags for dispatching processes in test mode. This is used to test the return code of the dispatched program. The return value of these functions will be : The default values are:
val test : bool cmd with_test_flags
val sh_test : ('a, bool) sh_cmd with_test_flags
val ssh_test : ('a, bool) sh_cmd with_test_flags with_ssh_flags
val extra_path : string list Pervasives.ref
variable used by dispatch command to find binaries not in the path. The default values contains only directory which should be in PATH and is only useful in environments where the PATH variable has been blown away.
module Process: sig .. end
Process dispatching

Small helper commands

val mkdir : ?p:unit -> ?perm:int -> string -> unit
val cp : ?overwrite:bool -> ?perm:Core.Std.Unix.file_perm -> string -> string -> unit
val ln : ?s:unit -> ?f:unit -> string -> string -> unit
val rm : ?r:unit -> ?f:unit -> string -> unit
val mv : string -> string -> unit
Raises "Failed_command"
val whoami : ?real:bool -> unit -> string
Get the username. By default, the effective username. If real is true, get the real username.
val which : ?use_extra_path:bool -> string -> string option
val scp : ?compress:bool ->
?recurse:bool -> ?user:string -> host:string -> string -> string -> unit
scp user host from to copy local file from to to