Module B0_std.CmdSource

Command lines.

Command line values specify the command line arguments given to tools spawns. In certain contexts the command line value is the full specification of the tool spawn, in this case the first element of the line defines the program to invoke. In other contexts the tool to invoke and its arguments are kept separate.

examples.

B00 artefact. This module allows to unstamp command arguments. Unstamped arguments have no special semantics as far as the command line is concerned they simply indicate that the argument value itself does not influence the outputs of the tool. Unstamped arguments do not appear in the command line stamp which is used to memoize tool spawns. A typical example of unstamped arguments are file paths to inputs: it's often the file contents not the actual file path that determines the tool output; beware though that some tool use both the file path contents and the actual file path in their outputs.

Command lines

Sourcetype t

The type for command lines. A command line is a list of command line arguments.

Sourceval is_empty : t -> bool

is_empty l is true iff l is an empty list of arguments.

Sourceval empty : t

empty is an empty list of arguments.

Sourceval atom : string -> t

atom a is the atomic argument a.

Sourceval append : t -> t -> t

append l1 l2 appends arguments l2 to l1.

Sourceval unstamp : t -> t

unstamp l indicates that arguments l do not influence the tool's invocation outputs. These arguments are omitted from the command line's stamp.

Derived combinators

Sourceval (%) : t -> string -> t

l % a is append l (arg a).

Sourceval (%%) : t -> t -> t

l1 % l2 is append l1 l2.

Sourceval if' : bool -> t -> t

if' cond l is l if cond is true and empty otherwise.

Sourceval int : int -> t

int i is arg (string_of_int i).

Sourceval float : float -> t

float f is arg (float_of_int f).

Sourceval path : Fpath.t -> t

path p is arg (Fpath.to_string p).

Sourceval list : ?slip:string -> string list -> t

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.

Sourceval paths : ?slip:string -> Fpath.t list -> t

paths ?slip ps is of_list ?slip Fpath.to_string ps.

Sourceval of_list : ?slip:string -> ('a -> string) -> 'a list -> t

of_list ?slip conv l is args ?slip (List.map conv l).

Sourceval rev_list : ?slip:string -> string list -> t

rev_list ?slip l is list ?slip (List.rev l).

  • deprecated
Sourceval of_rev_list : ?slip:string -> ('a -> string) -> 'a list -> t

of_rev_list ?slip conv l is args ?slip (List.rev_map conv l).

  • deprecated
Sourceval rev_paths : ?slip:string -> Fpath.t list -> t

rev_paths ?slip ps is of_rev_list ?slip Fpath.to_string ps.

  • deprecated

Tools

Sourcetype tool = Fpath.t

The type for command line tools. A command line tool is represented by a file path according to the POSIX convention for exec(3). If it is made of a single segment, for example Fpath.v "ocaml", it represents a program name to be looked up via a search procedure; for example in the PATH environment variable. If it is a file path with multiple segments (POSIX would say if they contain a slash characters) the program is the file itself.

Sourceval tool : t -> tool option

tool l is l's first element. This is None if the line is empty or if the first element can't be parsed to a tool.

Sourceval set_tool : tool -> t -> t option

set_tool tool l replaces l's first element with tool. This is None if l is empty.

Sourceval get_tool : t -> tool

get_tool is like tool but raises Invalid_argument in case of error.

Sourceval pp_tool : tool Fmt.t

pp_tool formats a tool for the TTY.

Predicates

Sourceval is_singleton : t -> bool

is_singleton l is true iff l has a single argument.

Converting

Sourceval fold : arg:(string -> 'a) -> unstamp:('a -> 'a) -> append:('a -> 'a -> 'a) -> empty:'a -> t -> 'a

fold ~arg ~unstamp ~append ~empty l folds over l's structure.

Sourceval iter_enc : arg:('a -> string -> unit) -> unstamp:('a -> unit) -> append:('a -> unit) -> empty:('a -> unit) -> 'a -> t -> unit
Sourceval to_list : t -> string list

to_list l converts l to a list of strings.

Sourceval to_stamp : t -> string list

to_stamp l is the sequence of stamped arguments.

Sourceval to_list_and_stamp : t -> string list * string list

to_list_and_stamp l is a l as a list of strings tuppled with its stamp: the sequence of stamped arguments.

Sourceval to_string : t -> string

to_string l converts l to a string that can be passed to the command(3) POSIX system call.

Sourceval of_string : string -> (t, string) 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.

Sourceval pp : t Fmt.t

pp ppf l formats an unspecified representation of l on ppf.

Sourceval pp_dump : t Fmt.t

pp_dump ppf l dumps and unspecified representation of l on ppf.

Examples

let ls p = Cmd.(atom "ls" % "-a" % path p)
let tar archive dir =
  Cmd.(atom "tar" % "-cvf" %% unstamp (path archive) %% path dir)

let opam cmd = Cmd.(atom "opam" % cmd)
let opam_install pkgs = Cmd.(opam "install" %% list pkgs)

let ocamlc ?(debug = false) file =
  Cmd.(atom "ocamlc" % "-c" % if' debug (atom "-g") %% path file)

let ocamlopt ?(profile = false) ?(debug = false) incs file =
  let profile = Cmd.(if' profile (atom "-p")) in
  let debug = Cmd.(if' debug (atom "-g")) in
  let incs = Cmd.(unstamp (paths ~slip:"-I" incs)) in
  Cmd.(atom "ocamlopt" % "-c" %% debug %% profile %% incs %%
       unstamp (path file))