Module B0.Cmd

module Cmd: sig .. end
Command lines.

Both command lines and command line fragments are represented with the same type.

When a command line is executed, the first element of the line defines the tool (program) name and each other element is an argument that will be passed as is in the program's argv array: no shell interpretation or any form of argument quoting and/or concatenation occurs.

See examples.



Command line fragments


type t 
The type for command line fragments.
val v : string -> t
v cmd is a new command line (or command line fragment) whose first argument is cmd.
val empty : t
empty is an empty command line.
val is_empty : t -> bool
is_empty l is true iff l is empty.
val (%) : t -> string -> t
l % arg adds arg to the command line l.
val (%%) : t -> t -> t
l %% frag appends the line fragment frag to l.
val add_arg : t -> string -> t
add_arg l arg is l % arg.
val add_args : t -> t -> t
add_args l frag is l %% frag.
val on : bool -> t -> t
on bool line is line if bool is true and B0.Cmd.empty otherwise.
val p : B0.Fpath.t -> string
p is B0.Fpath.to_string. This combinator makes path argument specification brief.

Command lines


val line_tool : t -> string option
line_tool l is l's first element, usually the executable tool name or file path.
val get_line_tool : t -> string
get_line_tool l is like B0.Cmd.line_tool but
Raises Invalid_argument if there's no first element.
val line_args : t -> string list
line_args is l's command line arguments, the elements of l without the command name.

Predicates and comparison


val equal : t -> t -> bool
equal l l' is true iff l and l' are litterally equal.
val compare : t -> t -> int
compare l l' is a total order on command lines.

Conversions and pretty printing


val of_string : string -> t B0.result
of_string s tokenizes s into a command line. The tokens are recognized according to the token production of the following grammar which should be mostly be compatible with POSIX shell tokenization.
white   ::= ' ' | '\t' | '\n' | '\x0B' | '\x0C' | '\r'
squot   ::= '\''
dquot   ::= '\"'
bslash  ::= '\\'
tokens  ::= white+ tokens | token tokens | ϵ
token   ::= ([^squot dquot white] | squoted | dquoted) token | ϵ
squoted ::= squot [^squot]* squot
dquoted ::= dquot (qchar | [^dquot])* dquot
qchar   ::= bslash (bslash | dquot | '$' | '`' | '\n')
qchar are substitued by the byte they escape except for '\n' which removes the backslash and newline from the byte stream. squoted and dquoted represent the bytes they enclose.
val to_string : t -> string
to_string l converts l to a string that can be passed to the command(3) POSIX system call.
val to_list : t -> string list
to_list l is l as a list of strings.
val to_rev_list : t -> string list
to_rev_list l is l as a reversed list of strings.
val of_list : ?slip:string -> string list -> t
of_list ?slip l is a command line from the list of arguments l. If slip is specified it is added on the command line before each element of l.
val of_rev_list : string list -> t
of_rev_list l is a command line from the reversed list of arguments l.
val of_values : ?slip:string -> ('a -> string) -> 'a list -> t
of_values ?slip conv l is like B0.Cmd.of_list but acts on a list of values, each converted to an argument with conv.
val of_fpaths : ?slip:string -> B0.Fpath.t list -> t
of_fpaths ?slip ps is like B0.Cmd.of_list but acts on a list of paths.
val pp : t B0.Fmt.t
pp ppf l formats an unspecified representation of l on ppf.
val dump : t B0.Fmt.t
dump ppf l dumps and unspecified representation of l on ppf.

Examples

let ls path = Cmd.(v "ls" % "-a" % p path)

let tar archive path = Cmd.(v "tar" % "-cvf" % p archive % p path)

let opam cmd = Cmd.(v "opam" % cmd)

let opam_install pkgs = Cmd.(opam "install" %% of_list pkgs)

let ocamlc ?(debug = false) file =
  Cmd.(v "ocamlc" % "-c" %% on debug (v "-g") % p file)

let ocamlopt ?(profile = false) ?(debug = false) incs file =
  let profile = Cmd.(on profile @@ v "-p"in
  let debug = Cmd.(on debug @@ v "-g"in
  let incs = Cmd.of_list ~slip:"-I" incs in
  Cmd.(v "ocamlopt" % "-c" %% debug %% profile %% incs % p file)