Module B0_std.Cmd
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.
B0 artefact. This module allows to shield
command arguments. Shielded 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 file outputs of the tool. As such shielded arguments do not appear in the command line signature which is used to memoize tool spawns. A typical example of shielded argument 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
val is_empty : t -> bool
is_empty l
istrue
iffl
is an empty list of arguments.
val empty : t
empty
is an empty list of arguments.
val arg : string -> t
arg a
is the argumenta
.
Derived combinators
val args : ?slip:string -> string list -> t
args ?slip l
is a command line from the list of argumentsl
. Ifslip
is specified it is added on the command line before each element ofl
.
val of_list : ?slip:string -> ('a -> string) -> 'a list -> t
of_list ?slip conv l
isargs
?slip (List.map conv l)
.
val of_rev_list : ?slip:string -> ('a -> string) -> 'a list -> t
of_rev_list ?slip conv l
isargs
?slip (List.rev_map conv l)
.
val rev_paths : ?slip:string -> Fpath.t list -> t
rev_paths ?slip ps
isof_rev_list
?slip Fpath.to_string ps
.
Tools
type 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 exampleFpath.v "ocaml"
, it represents a program name to be looked up via a search procedure; for example in thePATH
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.
val tool : t -> tool option
tool l
isl
's first element. This isNone
if the line isempty
or if the first element can't be parsed to a Tools.
Predicates
val is_singleton : t -> bool
is_singleton l
istrue
iffl
has a single argument.
Converting
val to_list : t -> string list
to_list l
convertsl
to a list of strings.
val to_sig : t -> string list
to_sig l
is the sequence of unshielded arguments.
val to_list_and_sig : t -> string list * string list
to_list_and_sig l
is al
as a list of strings tuppled with its signature: the sequence of unshielded arguments.
val to_string : t -> string
to_string l
convertsl
to a string that can be passed to thecommand(3)
POSIX system call.
val of_string : string -> (t, string) Stdlib.result
of_string s
tokenizess
into a command line. The tokens are recognized according to thetoken
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
anddquoted
represent the bytes they enclose.
Examples
let ls p = Cmd.(arg "ls" % "-a" % path p)
let tar archive dir =
Cmd.(arg "tar" % "-cvf" %% shield (path archive) %% path dir)
let opam cmd = Cmd.(arg "opam" % cmd)
let opam_install pkgs = Cmd.(opam "install" %% args pkgs)
let ocamlc ?(debug = false) file =
Cmd.(arg "ocamlc" % "-c" % if' debug (arg "-g") %% path file)
let ocamlopt ?(profile = false) ?(debug = false) incs file =
let profile = Cmd.(if' profile (arg "-p")) in
let debug = Cmd.(if' debug (arg "-g")) in
let incs = Cmd.(shield (paths ~slip:"-I" incs)) in
Cmd.(arg "ocamlopt" % "-c" %% debug %% profile %% incs %% shield (path file))