mirror of
https://github.com/c-cube/linol.git
synced 2025-12-06 03:05:31 -05:00
32 lines
36 KiB
HTML
32 lines
36 KiB
HTML
<!DOCTYPE html>
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Term (cmdliner.Cmdliner.Term)</title><meta charset="utf-8"/><link rel="stylesheet" href="../../../_odoc-theme/odoc.css"/><meta name="generator" content="odoc 3.0.0"/><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">Index</a> » <a href="../../index.html">cmdliner</a> » <a href="../index.html">Cmdliner</a> » Term</nav><header class="odoc-preamble"><h1>Module <code><span>Cmdliner.Term</span></code></h1><p>Terms.</p><p>A term is evaluated by a program to produce a <a href="#type-result" title="Term.result">result</a>, which can be turned into an <a href="#exits" title="exits">exit status</a>. A term made of terms referring to <a href="../Arg/index.html" title="Arg">command line arguments</a> implicitly defines a command line syntax.</p></header><div class="odoc-tocs"><nav class="odoc-toc odoc-local-toc"><ul><li><a href="#terms">Terms</a></li><li><a href="#interacting-with-cmdliner's-evaluation">Interacting with Cmdliner's evaluation</a></li><li><a href="#deprecated">Deprecated Term evaluation interface</a><ul><li><a href="#tinfo">Term information</a></li><li><a href="#evaluation">Evaluation</a></li><li><a href="#exits">Turning evaluation results into exit codes</a></li></ul></li></ul></nav></div><div class="odoc-content"><h2 id="terms"><a href="#terms" class="anchor"></a>Terms</h2><div class="odoc-spec"><div class="spec type anchored" id="type-t"><a href="#type-t" class="anchor"></a><code><span><span class="keyword">type</span> <span>+'a t</span></span></code></div><div class="spec-doc"><p>The type for terms evaluating to values of type 'a.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-const"><a href="#val-const" class="anchor"></a><code><span><span class="keyword">val</span> const : <span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>const v</code> is a term that evaluates to <code>v</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-($)"><a href="#val-($)" class="anchor"></a><code><span><span class="keyword">val</span> ($) : <span><span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span class="type-var">'b</span>)</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>f $ v</code> is a term that evaluates to the result of applying the evaluation of <code>v</code> to the one of <code>f</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-app"><a href="#val-app" class="anchor"></a><code><span><span class="keyword">val</span> app : <span><span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span class="type-var">'b</span>)</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>app</code> is <a href="#val-($)"><code>($)</code></a>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-map"><a href="#val-map" class="anchor"></a><code><span><span class="keyword">val</span> map : <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span class="type-var">'b</span>)</span> <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>map f t</code> is <code>app (const f) t</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-product"><a href="#val-product" class="anchor"></a><code><span><span class="keyword">val</span> product : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span><span class="type-var">'b</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span>(<span class="type-var">'a</span> * <span class="type-var">'b</span>)</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>product t0 t1</code> is <code>app (app (map (fun x y -> (x, y)) t0) t1)</code></p></div></div><div class="odoc-spec"><div class="spec module anchored" id="module-Syntax"><a href="#module-Syntax" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Syntax/index.html">Syntax</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div><div class="spec-doc"><p><code>let</code> operators.</p></div></div><h2 id="interacting-with-cmdliner's-evaluation"><a href="#interacting-with-cmdliner's-evaluation" class="anchor"></a>Interacting with Cmdliner's evaluation</h2><div class="odoc-spec"><div class="spec value anchored" id="val-term_result"><a href="#val-term_result" class="anchor"></a><code><span><span class="keyword">val</span> term_result : <span><span class="optlabel">?usage</span>:bool <span class="arrow">-></span></span> <span><span><span><span>(<span class="type-var">'a</span>, <span>[ <span>`Msg of string</span> ]</span>)</span> <a href="../../../ocaml/Stdlib/index.html#type-result">result</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>term_result ~usage t</code> evaluates to</p><ul><li><code>`Ok v</code> if <code>t</code> evaluates to <code>Ok v</code></li><li><code>`Error `Term</code> with the error message <code>e</code> and usage shown according to <code>usage</code> (defaults to <code>false</code>), if <code>t</code> evaluates to <code>Error (`Msg e)</code>.</li></ul><p>See also <a href="#val-term_result'"><code>term_result'</code></a>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-term_result'"><a href="#val-term_result'" class="anchor"></a><code><span><span class="keyword">val</span> term_result' : <span><span class="optlabel">?usage</span>:bool <span class="arrow">-></span></span> <span><span><span><span>(<span class="type-var">'a</span>, string)</span> <a href="../../../ocaml/Stdlib/index.html#type-result">result</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>term_result'</code> is like <a href="#val-term_result"><code>term_result</code></a> but with a <code>string</code> error case.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-cli_parse_result"><a href="#val-cli_parse_result" class="anchor"></a><code><span><span class="keyword">val</span> cli_parse_result : <span><span><span><span>(<span class="type-var">'a</span>, <span>[ <span>`Msg of string</span> ]</span>)</span> <a href="../../../ocaml/Stdlib/index.html#type-result">result</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>cli_parse_result t</code> is a term that evaluates to:</p><ul><li><code>`Ok v</code> if <code>t</code> evaluates to <code>Ok v</code>.</li><li><code>`Error `Parse</code> with the error message <code>e</code> if <code>t</code> evaluates to <code>Error (`Msg e)</code>.</li></ul><p>See also <a href="#val-cli_parse_result'"><code>cli_parse_result'</code></a>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-cli_parse_result'"><a href="#val-cli_parse_result'" class="anchor"></a><code><span><span class="keyword">val</span> cli_parse_result' : <span><span><span><span>(<span class="type-var">'a</span>, string)</span> <a href="../../../ocaml/Stdlib/index.html#type-result">result</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>cli_parse_result'</code> is like <a href="#val-cli_parse_result"><code>cli_parse_result</code></a> but with a <code>string</code> error case.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-main_name"><a href="#val-main_name" class="anchor"></a><code><span><span class="keyword">val</span> main_name : <span>string <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>main_name</code> is a term that evaluates to the main command name; that is the name of the tool.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-choice_names"><a href="#val-choice_names" class="anchor"></a><code><span><span class="keyword">val</span> choice_names : <span><span>string list</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>choice_names</code> is a term that evaluates to the names of the commands that are children of the main command.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-with_used_args"><a href="#val-with_used_args" class="anchor"></a><code><span><span class="keyword">val</span> with_used_args : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span>(<span class="type-var">'a</span> * <span>string list</span>)</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>with_used_args t</code> is a term that evaluates to <code>t</code> tupled with the arguments from the command line that where used to evaluate <code>t</code>.</p></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-ret"><a href="#type-ret" class="anchor"></a><code><span><span class="keyword">type</span> <span>'a ret</span></span><span> = </span><span>[ </span></code><ol><li id="type-ret.Help" class="def variant constructor anchored"><a href="#type-ret.Help" class="anchor"></a><code><span>| </span><span>`Help <span class="keyword">of</span> <a href="../Manpage/index.html#type-format">Manpage.format</a> * <span>string option</span></span></code></li><li id="type-ret.Error" class="def variant constructor anchored"><a href="#type-ret.Error" class="anchor"></a><code><span>| </span><span>`Error <span class="keyword">of</span> bool * string</span></code></li><li id="type-ret.Ok" class="def variant constructor anchored"><a href="#type-ret.Ok" class="anchor"></a><code><span>| </span><span>`Ok <span class="keyword">of</span> <span class="type-var">'a</span></span></code></li></ol><code><span> ]</span></code></div><div class="spec-doc"><p>The type for command return values. See <a href="#val-ret"><code>ret</code></a>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-ret"><a href="#val-ret" class="anchor"></a><code><span><span class="keyword">val</span> ret : <span><span><span><span class="type-var">'a</span> <a href="#type-ret">ret</a></span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>ret v</code> is a term whose evaluation depends on the case to which <code>v</code> evaluates. With :</p><ul><li><code>`Ok v</code>, it evaluates to <code>v</code>.</li><li><code>`Error (usage, e)</code>, the evaluation fails and <code>Cmdliner</code> prints the error <code>e</code> and the term's usage if <code>usage</code> is <code>true</code>.</li><li><code>`Help (format, name)</code>, the evaluation fails and <code>Cmdliner</code> prints a manpage in format <code>format</code>. If <code>name</code> is <code>None</code> this is the the main command's manpage. If <code>name</code> is <code>Some c</code> this is the man page of the sub command <code>c</code> of the main command.</li></ul><p><b>Note.</b> While not deprecated you are encouraged not use this API.</p></div></div><h2 id="deprecated"><a href="#deprecated" class="anchor"></a>Deprecated Term evaluation interface</h2><p>This interface is deprecated in favor of <a href="../Cmd/index.html"><code>Cmdliner.Cmd</code></a>. Follow the compiler deprecation warning hints to transition.</p><h3 id="tinfo"><a href="#tinfo" class="anchor"></a>Term information</h3><p>Term information defines the name and man page of a term. For simple evaluation this is the name of the program and its man page. For multiple term evaluation, this is the name of a command and its man page.</p><div class="odoc-spec"><div class="spec type anchored" id="type-exit_info"><a href="#type-exit_info" class="anchor"></a><code><span><span class="keyword">type</span> exit_info</span></code></div><div class="spec-doc"><p>The type for exit status information.</p><ul class="at-tags"><li class="deprecated"><span class="at-tag">deprecated</span> Use Cmd.Exit.info instead.</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-exit_info"><a href="#val-exit_info" class="anchor"></a><code><span><span class="keyword">val</span> exit_info : <span><span class="optlabel">?docs</span>:string <span class="arrow">-></span></span> <span><span class="optlabel">?doc</span>:string <span class="arrow">-></span></span> <span><span class="optlabel">?max</span>:int <span class="arrow">-></span></span> <span>int <span class="arrow">-></span></span> <a href="#type-exit_info">exit_info</a></span></code></div><div class="spec-doc"><p><code>exit_info ~docs ~doc min ~max</code> describe the range of exit statuses from <code>min</code> to <code>max</code> (defaults to <code>min</code>). <code>doc</code> is the man page information for the statuses, defaults to <code>"undocumented"</code>. <code>docs</code> is the title of the man page section in which the statuses will be listed, it defaults to <a href="../Manpage/index.html#val-s_exit_status"><code>Manpage.s_exit_status</code></a>.</p><p>In <code>doc</code> the <a href="../../tool_man.html#doclang" title="doclang">documentation markup language</a> can be used with following variables:</p><ul><li><code>$(status)</code>, the value of <code>min</code>.</li><li><code>$(status_max)</code>, the value of <code>max</code>.</li><li>The variables mentioned in <a href="#val-info"><code>info</code></a></li></ul><ul class="at-tags"><li class="deprecated"><span class="at-tag">deprecated</span> Use Cmd.Exit.info instead.</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-default_exits"><a href="#val-default_exits" class="anchor"></a><code><span><span class="keyword">val</span> default_exits : <span><a href="#type-exit_info">exit_info</a> list</span></span></code></div><div class="spec-doc"><p><code>default_exits</code> is information for exit status <a href="#val-exit_status_success"><code>exit_status_success</code></a> added to <a href="#val-default_error_exits"><code>default_error_exits</code></a>.</p><ul class="at-tags"><li class="deprecated"><span class="at-tag">deprecated</span> Use Cmd.Exit.defaults or Cmd.info's defaults ~exits value instead.</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-default_error_exits"><a href="#val-default_error_exits" class="anchor"></a><code><span><span class="keyword">val</span> default_error_exits : <span><a href="#type-exit_info">exit_info</a> list</span></span></code></div><div class="spec-doc"><p><code>default_error_exits</code> is information for exit statuses <a href="#val-exit_status_cli_error"><code>exit_status_cli_error</code></a> and <a href="#val-exit_status_internal_error"><code>exit_status_internal_error</code></a>.</p><ul class="at-tags"><li class="deprecated"><span class="at-tag">deprecated</span> List.filter the Cmd.Exit.defaults value instead.</li></ul></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-env_info"><a href="#type-env_info" class="anchor"></a><code><span><span class="keyword">type</span> env_info</span></code></div><div class="spec-doc"><p>The type for environment variable information.</p><ul class="at-tags"><li class="deprecated"><span class="at-tag">deprecated</span> Use Cmd.Env.info instead.</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-env_info"><a href="#val-env_info" class="anchor"></a><code><span><span class="keyword">val</span> env_info : <span><span class="optlabel">?docs</span>:string <span class="arrow">-></span></span> <span><span class="optlabel">?doc</span>:string <span class="arrow">-></span></span> <span>string <span class="arrow">-></span></span> <a href="#type-env_info">env_info</a></span></code></div><div class="spec-doc"><p><code>env_info ~docs ~doc var</code> describes an environment variable <code>var</code>. <code>doc</code> is the man page information of the environment variable, defaults to <code>"undocumented"</code>. <code>docs</code> is the title of the man page section in which the environment variable will be listed, it defaults to <a href="../Manpage/index.html#val-s_environment"><code>Cmdliner.Manpage.s_environment</code></a>.</p><p>In <code>doc</code> the <a href="../../tool_man.html#doclang" title="doclang">documentation markup language</a> can be used with following variables:</p><ul><li><code>$(env)</code>, the value of <code>var</code>.</li><li>The variables mentioned in <a href="#val-info"><code>info</code></a></li></ul><ul class="at-tags"><li class="deprecated"><span class="at-tag">deprecated</span> Use Cmd.Env.info instead.</li></ul></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-info"><a href="#type-info" class="anchor"></a><code><span><span class="keyword">type</span> info</span></code></div><div class="spec-doc"><p>The type for term information.</p><ul class="at-tags"><li class="deprecated"><span class="at-tag">deprecated</span> Use Cmd.info instead.</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-info"><a href="#val-info" class="anchor"></a><code><span><span class="keyword">val</span> info :
|
||
<span><span class="optlabel">?man_xrefs</span>:<span><a href="../Manpage/index.html#type-xref">Manpage.xref</a> list</span> <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?man</span>:<span><a href="../Manpage/index.html#type-block">Manpage.block</a> list</span> <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?envs</span>:<span><a href="#type-env_info">env_info</a> list</span> <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?exits</span>:<span><a href="#type-exit_info">exit_info</a> list</span> <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?sdocs</span>:string <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?docs</span>:string <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?doc</span>:string <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?version</span>:string <span class="arrow">-></span></span>
|
||
<span>string <span class="arrow">-></span></span>
|
||
<a href="#type-info">info</a></span></code></div><div class="spec-doc"><p><code>info sdocs man docs doc version name</code> is a term information such that:</p><ul><li><code>name</code> is the name of the program or the command.</li><li><code>version</code> is the version string of the program, ignored for commands.</li><li><code>doc</code> is a one line description of the program or command used for the <code>NAME</code> section of the term's man page. For commands this description is also used in the list of commands of the main term's man page.</li><li><code>docs</code>, only for commands, the title of the section of the main term's man page where it should be listed (defaults to <a href="../Manpage/index.html#val-s_commands"><code>Manpage.s_commands</code></a>).</li><li><code>sdocs</code> defines the title of the section in which the standard <code>--help</code> and <code>--version</code> arguments are listed (defaults to <a href="../Manpage/index.html#val-s_options"><code>Manpage.s_options</code></a>).</li><li><code>exits</code> is a list of exit statuses that the term evaluation may produce.</li><li><code>envs</code> is a list of environment variables that influence the term's evaluation.</li><li><code>man</code> is the text of the man page for the term.</li><li><code>man_xrefs</code> are cross-references to other manual pages. These are used to generate a <a href="../Manpage/index.html#val-s_see_also"><code>Manpage.s_see_also</code></a> section.</li></ul><p><code>doc</code>, <code>man</code>, <code>envs</code> support the <a href="../../tool_man.html#doclang" title="doclang">documentation markup language</a> in which the following variables are recognized:</p><ul><li><code>$(tname)</code> the term's name.</li><li><code>$(mname)</code> the main term's name.</li></ul><ul class="at-tags"><li class="deprecated"><span class="at-tag">deprecated</span> Use Cmd.info instead.</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-name"><a href="#val-name" class="anchor"></a><code><span><span class="keyword">val</span> name : <span><a href="#type-info">info</a> <span class="arrow">-></span></span> string</span></code></div><div class="spec-doc"><p><code>name ti</code> is the name of the term information.</p><ul class="at-tags"><li class="deprecated"><span class="at-tag">deprecated</span> Use Cmd.name instead.</li></ul></div></div><h3 id="evaluation"><a href="#evaluation" class="anchor"></a>Evaluation</h3><div class="odoc-spec"><div class="spec type anchored" id="type-result"><a href="#type-result" class="anchor"></a><code><span><span class="keyword">type</span> <span>'a result</span></span><span> = </span><span>[ </span></code><ol><li id="type-result.Ok" class="def variant constructor anchored"><a href="#type-result.Ok" class="anchor"></a><code><span>| </span><span>`Ok <span class="keyword">of</span> <span class="type-var">'a</span></span></code></li><li id="type-result.Error" class="def variant constructor anchored"><a href="#type-result.Error" class="anchor"></a><code><span>| </span><span>`Error <span class="keyword">of</span> <span>[ `Parse <span>| `Term</span> <span>| `Exn</span> ]</span></span></code></li><li id="type-result.Version" class="def variant constructor anchored"><a href="#type-result.Version" class="anchor"></a><code><span>| </span><span>`Version</span></code></li><li id="type-result.Help" class="def variant constructor anchored"><a href="#type-result.Help" class="anchor"></a><code><span>| </span><span>`Help</span></code></li></ol><code><span> ]</span></code></div><div class="spec-doc"><p>The type for evaluation results.</p><ul><li><code>`Ok v</code>, the term evaluated successfully and <code>v</code> is the result.</li><li><code>`Version</code>, the version string of the main term was printed on the help formatter.</li><li><code>`Help</code>, man page about the term was printed on the help formatter.</li><li><code>`Error `Parse</code>, a command line parse error occurred and was reported on the error formatter.</li><li><code>`Error `Term</code>, a term evaluation error occurred and was reported on the error formatter (see <a href="#val-ret"><code>Term.ret</code></a>').</li><li><code>`Error `Exn</code>, an exception <code>e</code> was caught and reported on the error formatter (see the <code>~catch</code> parameter of <a href="#val-eval"><code>eval</code></a>).</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-eval"><a href="#val-eval" class="anchor"></a><code><span><span class="keyword">val</span> eval :
|
||
<span><span class="optlabel">?help</span>:<a href="../../../ocaml/Stdlib/Format/index.html#type-formatter">Stdlib.Format.formatter</a> <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?err</span>:<a href="../../../ocaml/Stdlib/Format/index.html#type-formatter">Stdlib.Format.formatter</a> <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?catch</span>:bool <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?env</span>:<span>(<span>string <span class="arrow">-></span></span> <span>string option</span>)</span> <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?argv</span>:<span>string array</span> <span class="arrow">-></span></span>
|
||
<span><span>(<span><span class="type-var">'a</span> <a href="#type-t">t</a></span> * <a href="#type-info">info</a>)</span> <span class="arrow">-></span></span>
|
||
<span><span class="type-var">'a</span> <a href="#type-result">result</a></span></span></code></div><div class="spec-doc"><p><code>eval help err catch argv (t,i)</code> is the evaluation result of <code>t</code> with command line arguments <code>argv</code> (defaults to <code>Sys.argv</code>).</p><p>If <code>catch</code> is <code>true</code> (default) uncaught exceptions are intercepted and their stack trace is written to the <code>err</code> formatter.</p><p><code>help</code> is the formatter used to print help or version messages (defaults to <code>Format.std_formatter</code>). <code>err</code> is the formatter used to print error messages (defaults to <code>Format.err_formatter</code>).</p><p><code>env</code> is used for environment variable lookup, the default uses <code>Sys.getenv</code>.</p><ul class="at-tags"><li class="deprecated"><span class="at-tag">deprecated</span> Use Cmd.v and one of Cmd.eval* instead.</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-eval_choice"><a href="#val-eval_choice" class="anchor"></a><code><span><span class="keyword">val</span> eval_choice :
|
||
<span><span class="optlabel">?help</span>:<a href="../../../ocaml/Stdlib/Format/index.html#type-formatter">Stdlib.Format.formatter</a> <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?err</span>:<a href="../../../ocaml/Stdlib/Format/index.html#type-formatter">Stdlib.Format.formatter</a> <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?catch</span>:bool <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?env</span>:<span>(<span>string <span class="arrow">-></span></span> <span>string option</span>)</span> <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?argv</span>:<span>string array</span> <span class="arrow">-></span></span>
|
||
<span><span>(<span><span class="type-var">'a</span> <a href="#type-t">t</a></span> * <a href="#type-info">info</a>)</span> <span class="arrow">-></span></span>
|
||
<span><span><span>(<span><span class="type-var">'a</span> <a href="#type-t">t</a></span> * <a href="#type-info">info</a>)</span> list</span> <span class="arrow">-></span></span>
|
||
<span><span class="type-var">'a</span> <a href="#type-result">result</a></span></span></code></div><div class="spec-doc"><p><code>eval_choice help err catch argv (t,i) choices</code> is like <a href="#val-eval"><code>eval</code></a> except that if the first argument on the command line is not an option name it will look in <code>choices</code> for a term whose information has this name and evaluate it.</p><p>If the command name is unknown an error is reported. If the name is unspecified the "main" term <code>t</code> is evaluated. <code>i</code> defines the name and man page of the program.</p><ul class="at-tags"><li class="deprecated"><span class="at-tag">deprecated</span> Use Cmd.group and one of Cmd.eval* instead.</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-eval_peek_opts"><a href="#val-eval_peek_opts" class="anchor"></a><code><span><span class="keyword">val</span> eval_peek_opts :
|
||
<span><span class="optlabel">?version_opt</span>:bool <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?env</span>:<span>(<span>string <span class="arrow">-></span></span> <span>string option</span>)</span> <span class="arrow">-></span></span>
|
||
<span><span class="optlabel">?argv</span>:<span>string array</span> <span class="arrow">-></span></span>
|
||
<span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">-></span></span>
|
||
<span><span class="type-var">'a</span> option</span> * <span><span class="type-var">'a</span> <a href="#type-result">result</a></span></span></code></div><div class="spec-doc"><p><code>eval_peek_opts version_opt argv t</code> evaluates <code>t</code>, a term made of optional arguments only, with the command line <code>argv</code> (defaults to <code>Sys.argv</code>). In this evaluation, unknown optional arguments and positional arguments are ignored.</p><p>The evaluation returns a pair. The first component is the result of parsing the command line <code>argv</code> stripped from any help and version option if <code>version_opt</code> is <code>true</code> (defaults to <code>false</code>). It results in:</p><ul><li><code>Some _</code> if the command line would be parsed correctly given the <em>partial</em> knowledge in <code>t</code>.</li><li><code>None</code> if a parse error would occur on the options of <code>t</code></li></ul><p>The second component is the result of parsing the command line <code>argv</code> without stripping the help and version options. It indicates what the evaluation would result in on <code>argv</code> given the partial knowledge in <code>t</code> (for example it would return <code>`Help</code> if there's a help option in <code>argv</code>). However in contrasts to <a href="#val-eval"><code>eval</code></a> and <a href="#val-eval_choice"><code>eval_choice</code></a> no side effects like error reporting or help output occurs.</p><p><b>Note.</b> Positional arguments can't be peeked without the full specification of the command line: we can't tell apart a positional argument from the value of an unknown optional argument.</p><ul class="at-tags"><li class="deprecated"><span class="at-tag">deprecated</span> Use Cmd.eval_peek_opts instead.</li></ul></div></div><h3 id="exits"><a href="#exits" class="anchor"></a>Turning evaluation results into exit codes</h3><p><b>Note.</b> If you are using the following functions to handle the evaluation result of a term you should add <a href="#val-default_exits"><code>default_exits</code></a> to the term's information <a href="#val-info" title="info"><code>~exits</code></a> argument.</p><p><b>WARNING.</b> You should avoid status codes strictly greater than 125 as those may be used by <a href="https://www.gnu.org/software/bash/manual/html_node/Exit-Status.html">some</a> shells.</p><div class="odoc-spec"><div class="spec value anchored" id="val-exit_status_success"><a href="#val-exit_status_success" class="anchor"></a><code><span><span class="keyword">val</span> exit_status_success : int</span></code></div><div class="spec-doc"><p><code>exit_status_success</code> is 0, the exit status for success.</p><ul class="at-tags"><li class="deprecated"><span class="at-tag">deprecated</span> Use Cmd.Exit.ok instead.</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-exit_status_cli_error"><a href="#val-exit_status_cli_error" class="anchor"></a><code><span><span class="keyword">val</span> exit_status_cli_error : int</span></code></div><div class="spec-doc"><p><code>exit_status_cli_error</code> is 124, an exit status for command line parsing errors.</p><ul class="at-tags"><li class="deprecated"><span class="at-tag">deprecated</span> Use Cmd.Exit.cli_error instead.</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-exit_status_internal_error"><a href="#val-exit_status_internal_error" class="anchor"></a><code><span><span class="keyword">val</span> exit_status_internal_error : int</span></code></div><div class="spec-doc"><p><code>exit_status_internal_error</code> is 125, an exit status for unexpected internal errors.</p><ul class="at-tags"><li class="deprecated"><span class="at-tag">deprecated</span> Use Cmd.Exit.internal_error instead.</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-exit_status_of_result"><a href="#val-exit_status_of_result" class="anchor"></a><code><span><span class="keyword">val</span> exit_status_of_result : <span><span class="optlabel">?term_err</span>:int <span class="arrow">-></span></span> <span><span>unit <a href="#type-result">result</a></span> <span class="arrow">-></span></span> int</span></code></div><div class="spec-doc"><p><code>exit_status_of_result ~term_err r</code> is an <code>exit(3)</code> status code determined from <code>r</code> as follows:</p><ul><li><a href="#val-exit_status_success"><code>exit_status_success</code></a> if <code>r</code> is one of <code>`Ok ()</code>, <code>`Version</code>, <code>`Help</code></li><li><code>term_err</code> if <code>r</code> is <code>`Error `Term</code>, <code>term_err</code> defaults to <code>1</code>.</li><li><a href="#val-exit_status_cli_error"><code>exit_status_cli_error</code></a> if <code>r</code> is <code>`Error `Parse</code></li><li><a href="#val-exit_status_internal_error"><code>exit_status_internal_error</code></a> if <code>r</code> is <code>`Error `Exn</code></li></ul><ul class="at-tags"><li class="deprecated"><span class="at-tag">deprecated</span> Use Cmd.eval instead.</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-exit_status_of_status_result"><a href="#val-exit_status_of_status_result" class="anchor"></a><code><span><span class="keyword">val</span> exit_status_of_status_result : <span><span class="optlabel">?term_err</span>:int <span class="arrow">-></span></span> <span><span>int <a href="#type-result">result</a></span> <span class="arrow">-></span></span> int</span></code></div><div class="spec-doc"><p><code>exit_status_of_status_result</code> is like <a href="#val-exit_status_of_result"><code>exit_status_of_result</code></a> except for <code>`Ok n</code> where <code>n</code> is used as the status exit code.</p><ul class="at-tags"><li class="deprecated"><span class="at-tag">deprecated</span> Use Cmd.eval' instead.</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-exit"><a href="#val-exit" class="anchor"></a><code><span><span class="keyword">val</span> exit : <span><span class="optlabel">?term_err</span>:int <span class="arrow">-></span></span> <span><span>unit <a href="#type-result">result</a></span> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>exit ~term_err r</code> is <code>Stdlib.exit @@ exit_status_of_result ~term_err r</code></p><ul class="at-tags"><li class="deprecated"><span class="at-tag">deprecated</span> Use Stdlib.exit and Cmd.eval instead.</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-exit_status"><a href="#val-exit_status" class="anchor"></a><code><span><span class="keyword">val</span> exit_status : <span><span class="optlabel">?term_err</span>:int <span class="arrow">-></span></span> <span><span>int <a href="#type-result">result</a></span> <span class="arrow">-></span></span> unit</span></code></div><div class="spec-doc"><p><code>exit_status ~term_err r</code> is <code>Stdlib.exit @@ exit_status_of_status_result ~term_err r</code></p><ul class="at-tags"><li class="deprecated"><span class="at-tag">deprecated</span> Use Stdlib.exit and Cmd.eval' instead.</li></ul></div></div></div></body></html>
|