Module OS.Cmd

Executing commands.

Tool existence and search

val find_tool : ?⁠search:Fpath.t list -> Cmd.t -> (Fpath.t option, 'e) result

find_tool ~search cmd is the path to the tool of cmd as found by the tool search procedure in search.

val get_tool : ?⁠search:Fpath.t list -> Cmd.t -> (Fpath.t, 'e) result

get_tool cmd is like find_tool except it errors if the tool path cannot be found.

val exists : ?⁠search:Fpath.t list -> Cmd.t -> (bool, 'e) result

exists ~search cmd is Ok true if find_tool finds a path and Ok false if it does not.

val must_exist : ?⁠search:Fpath.t list -> Cmd.t -> (Cmd.t, 'e) result

must_exist ~search cmd is Ok cmd if get_tool succeeds.

val resolve : ?⁠search:Fpath.t list -> Cmd.t -> (Cmd.t, 'e) result

resolve ~search cmd is like must_exist except the tool of the resulting command value has the path to the tool of cmd as determined by get_tool.

val search_path_dirs : ?⁠sep:string -> string -> (Fpath.t list, 'e) result

search_path_dirs ~sep s parses sep seperated file paths from s. sep is not allowed to appear in the file paths, it defaults to ";" if Sys.win32 is true and ":" otherwise.

Command runs

Run statuses & information

type status = [
| `Exited of int
| `Signaled of int
]

The type for process exit statuses.

val pp_status : status Fmt.t

pp_status is a formatter for statuses.

type run_info

The type for run information.

val run_info_cmd : run_info -> Cmd.t

run_info_cmd ri is the command that was run.

type run_status = run_info * status

The type for run statuses the run information and the process exit status.

val success : ('a * run_status, 'e) result -> ('a, 'e) result

success r is:

  • Ok v if r = Ok (v, (_, `Exited 0))
  • Error _ otherwise. Non `Exited 0 statuses are turned into an error message.

Run standard errors

type run_err

The type for representing the standard error of a command run.

val err_file : ?⁠append:bool -> Fpath.t -> run_err

err_file f is a standard error that writes to file f. If append is true (defaults to false) the data is appended to f.

val err_null : run_err

err_null is err_file File.null.

val err_run_out : run_err

err_run_out is a standard error that is redirected to the run's standard output.

val err_stderr : run_err

err_stderr is a standard error that is redirected to the current process standard error.

Run standard inputs

type run_in

The type for representing the standard input of a command run.

val in_string : string -> run_in

in_string s is a standard input that reads s.

val in_file : Fpath.t -> run_in

in_file f is a standard input that reads from file f.

val in_null : run_in

in_null is in_file File.null.

val in_stdin : run_in

in_stdin is a standard input that reads from the current process standard input.

Run standard outputs

type run_out

The type for representing the standard output and status of a command run.

val out_string : ?⁠trim:bool -> run_out -> (string * run_status, 'e) result

out_string ~trim o captures the standard output o as a string. If trim is true (default) the result is passed through String.trim.

val out_lines : ?⁠trim:bool -> run_out -> (string list * run_status, 'e) result

out_lines is like out_string but the result is splitted on newlines ('\n'). If the standard output is empty then the empty list is returned.

val out_file : ?⁠append:bool -> Fpath.t -> run_out -> (unit * run_status, 'e) result

out_file f o writes the standard output o to file f. If append is true (defaults to false) the data is appended to f.

val out_run_in : run_out -> (run_in, 'e) result

out_run_in o is a run input that can be used to feed the standard output of o to the standard input of another, single, command run. Note that when the function returns the command run of o may not be terminated yet. The run using the resulting input will report an unsucessful status or error of o rather than its own error.

val out_null : run_out -> (unit * run_status, 'e) result

out_null o is out_file File.null o.

val out_stdout : run_out -> (unit * run_status, 'e) result

to_stdout o redirects the standard output o to the current process standard output.

Extracting success

val to_string : ?⁠trim:bool -> run_out -> (string, 'e) result

to_string ~trim o is (out_string ~trim o |> success).

val to_lines : ?⁠trim:bool -> run_out -> (string list, 'e) result

to_lines ~trim o is (out_lines ~trim o |> success).

val to_file : ?⁠append:bool -> Fpath.t -> run_out -> (unit, 'e) result

to_file ?append f o is (out_file ?append f o |> success).

val to_null : run_out -> (unit, 'e) result

to_null o is to_file File.null o.

val to_stdout : run_out -> (unit, 'e) result

to_stdout o is (out_stdout o |> success).

Run specifications

val run_io : ?⁠env:Env.t -> ?⁠err:run_err -> Cmd.t -> run_in -> run_out

run_io ~env ~err cmd i represents the standard output of the command run cmd performed in process environment env with its standard error output handled according to err (defaults to err_stderr) and standard input connected to i. Note that the command run is not started before the output is consumed, see run standard outputs.

val run_out : ?⁠env:Env.t -> ?⁠err:run_err -> Cmd.t -> run_out

run_out ?env ?err cmd is (in_stdin |> run_io ?env ?err cmd).

val run_in : ?⁠env:Env.t -> ?⁠err:run_err -> Cmd.t -> run_in -> (unit, 'e) result

run_in ?env ?err cmd i is (run_io ?env ?err cmd |> to_stdout).

val run : ?⁠env:Env.t -> ?⁠err:run_err -> Cmd.t -> (unit, 'e) result

run ?env ?err cmd is (in_stdin |> run_io ?env ?err cmd |> to_stdout).

val run_status : ?⁠env:Env.t -> ?⁠err:run_err -> ?⁠quiet:bool -> Cmd.t -> (status, 'e) result

run_status ?env ?err ?quiet cmd is (in_stdin |> run_io ?env ?err ?cmd |> out_stdout) and extracts the run status.

If quiet is true (defaults to false), in_stdin and out_stdout are respectively replaced by in_null and out_null and err defaults to err_null rather than err_stderr.

Examples