package core_unix
Install
Dune Dependency
Authors
Maintainers
Sources
md5=f9a74834f239874286d84ec99d75e5fa
sha512=d020db759cde35c0e9d9919dee2c0ea5bb5b7a5ee75515be922d816f28eb9f74dba37e6e424a636e362eab5120b2c1e672f4e5ba798f2dac7974c0e135f80faf
doc/core_unix.command_unix/Command_unix/index.html
Module Command_unix
Source
include module type of struct include Core.Command end
include module type of Core_kernel.Command
with module Shape := Core_kernel.Command.Shape
with module Deprecated := Core_kernel.Command.Deprecated
module Auto_complete = Core.Command.Auto_complete
module Arg_type = Core.Command.Arg_type
Argument types.
module Flag = Core.Command.Flag
Command-line flag specifications.
module Anons = Core.Command.Anons
Anonymous command-line argument specification.
module Param = Core.Command.Param
Command-line parameter specification.
module Let_syntax = Core.Command.Let_syntax
module Spec = Core.Command.Spec
The old interface for command-line specifications -- Do Not Use.
val basic_spec : ('main, Core_kernel__.Import.unit) basic_spec_command
basic_spec ~summary ?readme spec main
is a basic command that executes a function main
which is passed parameters parsed from the command line according to spec
. summary
is to contain a short one-line description of its behavior. readme
is to contain any longer description of its behavior that will go on that command's help screen.
val basic : Core_kernel__.Import.unit basic_command
Same general behavior as basic_spec
, but takes a command line specification built up using Params
instead of Spec
.
val group :
summary:Core_kernel__.Import.string ->
?readme:(Core_kernel__.Import.unit -> Core_kernel__.Import.string) ->
?preserve_subcommand_order:Core_kernel__.Import.unit ->
?body:
(path:Core_kernel__.Import.string Core_kernel__.Import.list ->
Core_kernel__.Import.unit) ->
(Core_kernel__.Import.string * t) Core_kernel__.Import.list ->
t
group ~summary subcommand_alist
is a compound command with named subcommands, as found in subcommand_alist
. summary
is to contain a short one-line description of the command group. readme
is to contain any longer description of its behavior that will go on that command's help screen.
NOTE: subcommand names containing underscores will be rejected; use dashes instead.
body
is called when no additional arguments are passed -- in particular, when no subcommand is passed. Its path
argument is the subcommand path by which the group command was reached.
val lazy_group :
summary:Core_kernel__.Import.string ->
?readme:(Core_kernel__.Import.unit -> Core_kernel__.Import.string) ->
?preserve_subcommand_order:Core_kernel__.Import.unit ->
?body:
(path:Core_kernel__.Import.string Core_kernel__.Import.list ->
Core_kernel__.Import.unit) ->
(Core_kernel__.Import.string * t) Core_kernel__.Import.list
Core_kernel__.Lazy.t ->
t
lazy_group
is the same as group
, except that the list of subcommands may be generated lazily.
val exec :
summary:Core_kernel__.Import.string ->
?readme:(Core_kernel__.Import.unit -> Core_kernel__.Import.string) ->
?child_subcommand:Core_kernel__.Import.string Core_kernel__.Import.list ->
path_to_exe:
[ `Absolute of Core_kernel__.Import.string
| `Relative_to_argv0 of Core_kernel__.Import.string
| `Relative_to_me of Core_kernel__.Import.string ] ->
Core_kernel__.Import.unit ->
t
exec ~summary ~path_to_exe
runs exec
on the executable at path_to_exe
. If path_to_exe
is `Absolute path
then path
is executed without any further qualification. If it is `Relative_to_me path
then Filename.dirname Sys.executable_name ^ "/" ^ path
is executed instead. All of the usual caveats about Sys.executable_name
apply: specifically, it may only return an absolute path in Linux. On other operating systems it will return Sys.argv.(0)
. If it is `Relative_to_argv0 path
then Sys.argv.(0) ^ "/" ^ path
is executed.
The child_subcommand
argument allows referencing a subcommand one or more levels below the top-level of the child executable. It should not be used to pass flags or anonymous arguments to the child.
Care has been taken to support nesting multiple executables built with Command. In particular, recursive help and autocompletion should work as expected.
NOTE: Non-Command executables can be used with this function but will still be executed when help -recursive
is called or autocompletion is attempted (despite the fact that neither will be particularly helpful in this case). This means that if you have a shell script called "reboot-everything.sh" that takes no arguments and reboots everything no matter how it is called, you shouldn't use it with exec
.
Additionally, no loop detection is attempted, so if you nest an executable within itself, help -recursive
and autocompletion will hang forever (although actually running the subcommand will work).
of_lazy thunk
constructs a lazy command that is forced only when necessary to run it or extract its shape.
val summary : t -> Core_kernel__.Import.string
Extracts the summary string for a command.
val run :
?verbose_on_parse_error:bool ->
?version:string ->
?build_info:string ->
?argv:string list ->
?extend:(string list -> string list) ->
?when_parsing_succeeds:(unit -> unit) ->
t ->
unit
Runs a command against Sys.argv
, or argv
if it is specified.
extend
can be used to add extra command line arguments to basic subcommands of the command. extend
will be passed the (fully expanded) path to a command, and its output will be appended to the list of arguments being processed. For example, suppose a program like this is compiled into exe
:
let bar = Command.basic ___
let foo = Command.group ~summary:___ ["bar", bar]
let main = Command.group ~summary:___ ["foo", foo]
let () = Command.run ~extend:(fun _ -> ["-baz"]) main
Then if a user ran exe f b
, extend
would be passed ["foo"; "bar"]
and "-baz"
would be appended to the command line for processing by bar
. This can be used to add a default flags section to a user config file.
verbose_on_parse_error
controls whether to print a line suggesting the user try the "-help" flag when an exception is raised while parsing the arguments. By default it is true.
when_parsing_succeeds
is invoked after argument parsing has completed successfully, but before the main function of the associated command has run. One use-case is for performing logging when a command is being invoked, where there's no reason to log incorrect invocations or -help calls.
Deprecated
should be used only by Deprecated_command
. At some point it will go away.