package bos
Library
Module
Module type
Parameter
Class
Class type
include module type of struct include Bos.Cmd end
Command lines.
Both command lines and command line fragments using the same are represented with the same type.
When a command line is run, the first element of the line defines the 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 = Bos.Cmd.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 p : Fpath.t -> string
p
is Fpath.to_string
. This combinator makes path argument specification brief.
Command lines
val line_exec : t -> string option
line_exec l
is l
's first element, usually the executable name.
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
Conversions and pretty printing
val of_string : string -> (t, Rresult.R.msg) Rresult.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 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_values : ?slip:string -> ('a -> string) -> 'a list -> t
of_values ?slip conv l
is like of_list
but acts on a list of values, each converted to an argument with conv
.
val pp : Format.formatter -> t -> unit
pp ppf l
formats an unspecified representation of l
on ppf
.
val dump : Format.formatter -> t -> unit
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)