linol/cmdliner/cli.html

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>cli (cmdliner.cli)</title><meta charset="utf-8"/><link rel="stylesheet" href="../_odoc-theme/odoc.css"/><meta name="generator" content="odoc 2.4.3"/><meta name="viewport" content="width=device-width,initial-scale=1.0"/><script src="../highlight.pack.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body class="odoc"><nav class="odoc-nav"><a href="index.html">Up</a> – <a href="index.html">cmdliner</a> &#x00BB; cli</nav><header class="odoc-preamble"><h1 id="cmdline"><a href="#cmdline" class="anchor"></a>Command line interface</h1><p>For tools evaluating a command without sub commands the most general form of invocation is:</p><pre class="language-ocaml"><code>tool [OPTION]… [ARG]…</code></pre><p>The tool automatically reponds to the <code>--help</code> option by printing the help. If a version string is provided in the <a href="Cmdliner/Cmd/index.html#val-info" title="Cmdliner.Cmd.info">command information</a>, it also automatically responds to the <code>--version</code> option by printing this string on standard output.</p><p>Command line arguments are either <a href="#optargs" title="optargs"><em>optional</em></a> or <a href="#posargs" title="posargs"><em>positional</em></a>. Both can be freely interleaved but since <code>Cmdliner</code> accepts many optional forms this may result in ambiguities. The special <a href="#posargs" title="posargs">token <code>--</code></a> can be used to resolve them; anything that follows it is treated as a positional argument.</p><p>Tools evaluating commands with sub commands have this form of invocation</p><pre class="language-ocaml"><code>tool [COMMAND]… [OPTION]… [ARG]…</code></pre><p>Commands automatically respond to the <code>--help</code> option by printing their help. The sequence of <code>COMMAND</code> strings must be the first strings following the tool name – as soon as an optional argument is seen the search for a sub command stops. Command names may be specified by a prefixe as long as they are not ambiguous.</p></header><nav class="odoc-toc"><ul><li><a href="#optargs">Optional arguments</a></li><li><a href="#posargs">Positional arguments</a></li><li><a href="#envlookup">Environment variables</a></li><li><a href="#reserved">Reserved option names</a></li></ul></nav><div class="odoc-content"><h2 id="optargs"><a href="#optargs" class="anchor"></a>Optional arguments</h2><p>An optional argument is specified on the command line by a <em>name</em> possibly followed by a <em>value</em>.</p><p>The name of an option can be short or long.</p><ul><li>A <em>short</em> name is a dash followed by a single alphanumeric character: <code>-h</code>, <code>-q</code>, <code>-I</code>.</li><li>A <em>long</em> name is two dashes followed by alphanumeric characters and dashes: <code>--help</code>, <code>--silent</code>, <code>--ignore-case</code>.</li></ul><p>More than one name may refer to the same optional argument. For example in a given program the names <code>-q</code>, <code>--quiet</code> and <code>--silent</code> may all stand for the same boolean argument indicating the program to be quiet. Long names can be specified by any non ambiguous prefix.</p><p>The value of an option can be specified in three different ways.</p><ul><li>As the next token on the command line: <code>-o a.out</code>, <code>--output a.out</code>.</li><li>Glued to a short name: <code>-oa.out</code>.</li><li>Glued to a long name after an equal character: <code>--output=a.out</code>.</li></ul><p>Glued forms are especially useful if the value itself starts with a dash as is the case for negative numbers, <code>--min=-10</code>.</p><p>An optional argument without a value is either a <em>flag</em> (see <a href="Cmdliner/Arg/index.html#val-flag"><code>Cmdliner.Arg.flag</code></a>, <a href="Cmdliner/Arg/index.html#val-vflag"><code>Cmdliner.Arg.vflag</code></a>) or an optional argument with an optional value (see the <code>~vopt</code> argument of <a href="Cmdliner/Arg/index.html#val-opt"><code>Cmdliner.Arg.opt</code></a>).</p><p>Short flags can be grouped together to share a single dash and the group can end with a short option. For example assuming <code>-v</code> and <code>-x</code> are flags and <code>-f</code> is a short option:</p><ul><li><code>-vx</code> will be parsed as <code>-v -x</code>.</li><li><code>-vxfopt</code> will be parsed as <code>-v -x -fopt</code>.</li><li><code>-vxf opt</code> will be parsed as <code>-v -x -fopt</code>.</li><li><code>-fvx</code> will be parsed as <code>-f=vx</code>.</li></ul><h2 id="posargs"><a href="#posargs" class="anchor"></a>Positional arguments</h2><p>Positional arguments are tokens on the command line that are not option names and are not the value of an optional argument. They are numbered from left to right starting with zero.</p><p>Since positional arguments may be mistaken as the optional value of an optional argument or they may need to look like option names, anything that follows the special token <code>&quot;--&quot;</code> on the command line is considered to be a positional argument:</p><pre class="language-ocaml"><code>tool --option -- we -are --all positional --argu=ments</code></pre><h2 id="envlookup"><a href="#envlookup" class="anchor"></a>Environment variables</h2><p>Non-required command line arguments can be backed up by an environment variable. If the argument is absent from the command line and that the environment variable is defined, its value is parsed using the argument converter and defines the value of the argument.</p><p>For <a href="Cmdliner/Arg/index.html#val-flag"><code>Cmdliner.Arg.flag</code></a> and <a href="Cmdliner/Arg/index.html#val-flag_all"><code>Cmdliner.Arg.flag_all</code></a> that do not have an argument converter a boolean is parsed from the lowercased variable value as follows:</p><ul><li><code>&quot;&quot;</code>, <code>&quot;false&quot;</code>, <code>&quot;no&quot;</code>, <code>&quot;n&quot;</code> or <code>&quot;0&quot;</code> is <code>false</code>.</li><li><code>&quot;true&quot;</code>, <code>&quot;yes&quot;</code>, <code>&quot;y&quot;</code> or <code>&quot;1&quot;</code> is <code>true</code>.</li><li>Any other string is an error.</li></ul><p>Note that environment variables are not supported for <a href="Cmdliner/Arg/index.html#val-vflag"><code>Cmdliner.Arg.vflag</code></a> and <a href="Cmdliner/Arg/index.html#val-vflag_all"><code>Cmdliner.Arg.vflag_all</code></a>.</p><h2 id="reserved"><a href="#reserved" class="anchor"></a>Reserved option names</h2><p>Using the cmdliner library puts the following constraints o</p><ul><li>The option name <code>--cmdliner</code> is reserved by the library.</li><li>The option name <code>--help</code>, (and <code>--version</code> if you specify a version string) is reserved by the library. Using it as a term or option name may result in undefined behaviour.</li><li>Defining the same option or command name via two different arguments or terms is illegal and raises <code>Invalid_argument</code>.</li></ul></div></body></html>
		`<!DOCTYPE html>`
		<html xmlns="http://www.w3.org/1999/xhtml"><head><title>cli (cmdliner.cli)</title><meta charset="utf-8"/><link rel="stylesheet" href="../_odoc-theme/odoc.css"/><meta name="generator" content="odoc 2.4.3"/><meta name="viewport" content="width=device-width,initial-scale=1.0"/><script src="../highlight.pack.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body class="odoc"><nav class="odoc-nav"><a href="index.html">Up</a> – <a href="index.html">cmdliner</a> » cli</nav><header class="odoc-preamble"><h1 id="cmdline"><a href="#cmdline" class="anchor"></a>Command line interface</h1><p>For tools evaluating a command without sub commands the most general form of invocation is:</p><pre class="language-ocaml"><code>tool [OPTION]… [ARG]…</code></pre><p>The tool automatically reponds to the <code>--help</code> option by printing the help. If a version string is provided in the <a href="Cmdliner/Cmd/index.html#val-info" title="Cmdliner.Cmd.info">command information</a>, it also automatically responds to the <code>--version</code> option by printing this string on standard output.</p><p>Command line arguments are either <a href="#optargs" title="optargs"><em>optional</em></a> or <a href="#posargs" title="posargs"><em>positional</em></a>. Both can be freely interleaved but since <code>Cmdliner</code> accepts many optional forms this may result in ambiguities. The special <a href="#posargs" title="posargs">token <code>--</code></a> can be used to resolve them; anything that follows it is treated as a positional argument.</p><p>Tools evaluating commands with sub commands have this form of invocation</p><pre class="language-ocaml"><code>tool [COMMAND]… [OPTION]… [ARG]…</code></pre><p>Commands automatically respond to the <code>--help</code> option by printing their help. The sequence of <code>COMMAND</code> strings must be the first strings following the tool name – as soon as an optional argument is seen the search for a sub command stops. Command names may be specified by a prefixe as long as they are not ambiguous.</p></header><nav class="odoc-toc"><ul><li><a href="#optargs">Optional arguments</a></li><li><a href="#posargs">Positional arguments</a></li><li><a href="#envlookup">Environment variables</a></li><li><a href="#reserved">Reserved option names</a></li></ul></nav><div class="odoc-content"><h2 id="optargs"><a href="#optargs" class="anchor"></a>Optional arguments</h2><p>An optional argument is specified on the command line by a <em>name</em> possibly followed by a <em>value</em>.</p><p>The name of an option can be short or long.</p><ul><li>A <em>short</em> name is a dash followed by a single alphanumeric character: <code>-h</code>, <code>-q</code>, <code>-I</code>.</li><li>A <em>long</em> name is two dashes followed by alphanumeric characters and dashes: <code>--help</code>, <code>--silent</code>, <code>--ignore-case</code>.</li></ul><p>More than one name may refer to the same optional argument. For example in a given program the names <code>-q</code>, <code>--quiet</code> and <code>--silent</code> may all stand for the same boolean argument indicating the program to be quiet. Long names can be specified by any non ambiguous prefix.</p><p>The value of an option can be specified in three different ways.</p><ul><li>As the next token on the command line: <code>-o a.out</code>, <code>--output a.out</code>.</li><li>Glued to a short name: <code>-oa.out</code>.</li><li>Glued to a long name after an equal character: <code>--output=a.out</code>.</li></ul><p>Glued forms are especially useful if the value itself starts with a dash as is the case for negative numbers, <code>--min=-10</code>.</p><p>An optional argument without a value is either a <em>flag</em> (see <a href="Cmdliner/Arg/index.html#val-flag"><code>Cmdliner.Arg.flag</code></a>, <a href="Cmdliner/Arg/index.html#val-vflag"><code>Cmdliner.Arg.vflag</code></a>) or an optional argument with an optional value (see the <code>~vopt</code> argument of <a href="Cmdliner/Arg/index.html#val-opt"><code>Cmdliner.Arg.opt</code></a>).</p><p>Short flags can be grouped together to share a single dash and the group can end with a short option. For example assuming <code>-v</code> and <code>-x</code> are flags and <code>-f</code> is a short option:</p><ul><li><code>-vx</code> will be parsed as <code>-v -x</code>.</li><li><code>-vxfopt</code> will be parsed as <code>-v -x -fopt</code>.</li><li><code>-vxf opt</code> will be parsed as <code>-v -x -fopt</code>.</li><li><code>-fvx</code> will be parsed as <code>-f=vx</code>.</li></ul><h2 id="posargs"><a href="#posargs" class="anchor"></a>Positional arguments</h2><p>Positional arguments are tokens on the command line that are not option names and are not the value of an optional argument. They are numbered from left to right starting with zero.</p><p>Since positional arguments may be mistaken as the optional value of an optional argument or they may need to look like option names, anything that follows the special token <code>"--"</code> on the command line is considered to be a positional argument:</p><pre class="language-ocaml"><code>tool --option -- we -are --all positional --argu=ments</code></pre><h2 id="envlookup"><a href="#envlookup" class="anchor"></a>Environment variables</h2><p>Non-required command line arguments can be backed up by an environment variable. If the argument is absent from the command line and that the environment variable is defined, its value is parsed using the argument converter and defines the value of the argument.</p><p>For <a href="Cmdliner/Arg/index.html#val-flag"><code>Cmdliner.Arg.flag</code></a> and <a href="Cmdliner/Arg/index.html#val-flag_all"><code>Cmdliner.Arg.flag_all</code></a> that do not have an argument converter a boolean is parsed from the lowercased variable value as follows:</p><ul><li><code>""</code>, <code>"false"</code>, <code>"no"</code>, <code>"n"</code> or <code>"0"</code> is <code>false</code>.</li><li><code>"true"</code>, <code>"yes"</code>, <code>"y"</code> or <code>"1"</code> is <code>true</code>.</li><li>Any other string is an error.</li></ul><p>Note that environment variables are not supported for <a href="Cmdliner/Arg/index.html#val-vflag"><code>Cmdliner.Arg.vflag</code></a> and <a href="Cmdliner/Arg/index.html#val-vflag_all"><code>Cmdliner.Arg.vflag_all</code></a>.</p><h2 id="reserved"><a href="#reserved" class="anchor"></a>Reserved option names</h2><p>Using the cmdliner library puts the following constraints o</p><ul><li>The option name <code>--cmdliner</code> is reserved by the library.</li><li>The option name <code>--help</code>, (and <code>--version</code> if you specify a version string) is reserved by the library. Using it as a term or option name may result in undefined behaviour.</li><li>Defining the same option or command name via two different arguments or terms is illegal and raises <code>Invalid_argument</code>.</li></ul></div></body></html>