# Module Topkg.OS.Cmd

    module Cmd: sig .. end

Running commands.

## Command existence

    val exists : Topkg.Cmd.t -> bool Topkg.result

`exists cmd` is `true` if the executable of `cmd` can be found in the path and `false` otherwise.

    val must_exist : Topkg.Cmd.t -> Topkg.Cmd.t Topkg.result

`must_exist cmd` is `cmd` if the executable of `cmd` can be found in the path and an error otherwise.

## Running commands

    val run : ?err:Topkg.fpath -> Topkg.Cmd.t -> unit Topkg.result

`run cmd` runs the command `cmd`. `std{i,o,err}` are connected to the invoking process' standard channels. If `err` is specified `stderr` is redirected to the given file (e.g. `Topkg.OS.File.null`).

    val run_status : ?err:Topkg.fpath -> Topkg.Cmd.t -> [ `Exited of int ] Topkg.result

`run_status cmd` is like `Topkg.OS.Cmd.run`, but doesn't error on non-zero exit status.

## Capturing standard output

    type run_status = Topkg.Cmd.t * [ `Exited of int ]

The type for run statuses, the command that was run and the run status.

    val success : ('a * run_status) Topkg.result -> 'a Topkg.result

`success r` is:

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

    type run_out

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

    val out_string : ?trim:bool ->
           run_out -> (string * run_status) Topkg.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) Topkg.result

`out_lines ~trim` is like `Topkg.OS.Cmd.out_string` but the result is cut on newlines (`'\n'`).

    val out_file : Topkg.fpath ->
           run_out -> (unit * run_status) Topkg.result

`out_file f o` writes the standard output `o` to file `f`.

    val out_stdout : run_out -> (unit * run_status) Topkg.result

`out_stdout o` redirects the standard output `o` to the current process standard output.

    val to_string : ?trim:bool -> run_out -> string Topkg.result

`to_string` is `(out_string ?trim o |> success)`.

    val to_lines : ?trim:bool -> run_out -> string list Topkg.result

`to_lines ?trim o` is `(out_string ?trim o |> success)`.

    val to_file : Topkg.fpath -> run_out -> unit Topkg.result

`to_file f o` is `(out_file f o |> success)`

    val run_out : ?err:Topkg.fpath -> Topkg.Cmd.t -> run_out

`run_out cmd` represents the standard output of the command run `cmd`. `std{i,err}` are connected to the invoking prcoess stream and standard output can be consumed with `Topkg.OS.Cmd.to_string`, `Topkg.OS.Cmd.to_lines` or `Topkg.OS.Cmd.to_file`. If `err` is specified `stderr` is redirected to the given file.