mirror of
https://github.com/c-cube/linol.git
synced 2025-12-11 13:38:47 -05:00
5 lines
13 KiB
HTML
5 lines
13 KiB
HTML
<!DOCTYPE html>
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Completion (cmdliner.Cmdliner.Arg.Completion)</title><meta charset="utf-8"/><link rel="stylesheet" href="../../../../_odoc-theme/odoc.css"/><meta name="generator" content="odoc 3.1.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> » <a href="../index.html">Arg</a> » Completion</nav><header class="odoc-preamble"><h1>Module <code><span>Arg.Completion</span></code></h1><p>Argument completion.</p><p>This module provides a type to describe how positional and optional argument values of <a href="../index.html#type-conv" title="Arg.conv">argument converters</a> can be completed. It defines which completion directives from the <a href="../../../cli.html#completion_protocol" title="completion_protocol">protocol</a> get emitted by your tool for the argument.</p><p><b>Note.</b> Subcommand and option name are completed automatically by the library itself and <a href="../index.html#predef" title="predef">prefined argument converters</a> already have completions built-in whenever appropriate.</p></header><div class="odoc-tocs"><nav class="odoc-toc odoc-local-toc"><ul><li><a href="#directives">Completion directives</a></li><li><a href="#completion">Completion</a></li></ul></nav></div><div class="odoc-content"><h2 id="directives"><a href="#directives" class="anchor"></a>Completion directives</h2><div class="odoc-spec"><div class="spec type anchored" id="type-directive"><a href="#type-directive" class="anchor"></a><code><span><span class="keyword">type</span> <span>'a directive</span></span></code></div><div class="spec-doc"><p>The type for a completion directive for values of type <code>'a</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-value"><a href="#val-value" class="anchor"></a><code><span><span class="keyword">val</span> value : <span><span class="optlabel">?doc</span>:string <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="#type-directive">directive</a></span></span></code></div><div class="spec-doc"><p><code>value v ~doc</code> indicates that the token to complete could be replaced by the value <code>v</code> as serialized by the argument's formatter <a href="../Conv/index.html#val-pp"><code>Conv.pp</code></a>. <code>doc</code> is ANSI styled UTF-8 text documenting the value, defaults to <code>""</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-string"><a href="#val-string" class="anchor"></a><code><span><span class="keyword">val</span> string : <span><span class="optlabel">?doc</span>:string <span class="arrow">-></span></span> <span>string <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="#type-directive">directive</a></span></span></code></div><div class="spec-doc"><p><code>string s ~doc</code> indicates that the token to complete could be replaced by the string <code>s</code>. <code>doc</code> is ANSI styled UTF-8 text documenting the value, defaults to <code>""</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-files"><a href="#val-files" class="anchor"></a><code><span><span class="keyword">val</span> files : <span><span class="type-var">'a</span> <a href="#type-directive">directive</a></span></span></code></div><div class="spec-doc"><p><code>files</code> indicates that the token to complete could be replaced with files that the shell deems suitable.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-dirs"><a href="#val-dirs" class="anchor"></a><code><span><span class="keyword">val</span> dirs : <span><span class="type-var">'a</span> <a href="#type-directive">directive</a></span></span></code></div><div class="spec-doc"><p><code>dirs</code> indicates that the token to complete could be replaced with directories that the shell deems suitable.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-restart"><a href="#val-restart" class="anchor"></a><code><span><span class="keyword">val</span> restart : <span><span class="type-var">'a</span> <a href="#type-directive">directive</a></span></span></code></div><div class="spec-doc"><p><code>restart</code> indicates that the shell should restart the completion after the positional disambiguation token <code>--</code>.</p><p>This is typically used for tools that end-up invoking other tools like <code>sudo -- TOOL [ARG]…</code>. For the latter a restart completion should be added on all positional arguments. If you allow <code>TOOL</code> to be only a restricted set of tools known to your program you'd eschew <code>restart</code> on the first postional argument but add it to the remaining ones.</p><p><b>Warning.</b> A <code>restart</code> directive is eventually emited only if the completion is requested after a <code>--</code> token. In this case other completions returned alongside by <a href="#type-func"><code>func</code></a> are ignored. Educate your users to use the <code>--</code>, for example mention them in <a href="../../../cookbook.html#manpage_synopsis" title="manpage_synopsis">user defined synopses</a>, it is good cli specification hygiene as it properly delineates argument scopes.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-message"><a href="#val-message" class="anchor"></a><code><span><span class="keyword">val</span> message : <span>string <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="#type-directive">directive</a></span></span></code></div><div class="spec-doc"><p><code>message s</code> is a multi-line, ANSI styled, UTF-8 message reported to end users.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-raw"><a href="#val-raw" class="anchor"></a><code><span><span class="keyword">val</span> raw : <span>string <span class="arrow">-></span></span> <span><span class="type-var">'a</span> <a href="#type-directive">directive</a></span></span></code></div><div class="spec-doc"><p><code>raw s</code> takes over the whole <a href="../../../cli.html#completion_protocol" title="completion_protocol">protocol</a> output (including subcommand and option name completion) with <code>s</code>, you are in charge. Any other directive in the result of <a href="#type-func"><code>func</code></a> is ignored.</p><p><b>Warning.</b> The protocol is unstable, it is not advised to output it yourself. However this can be useful to invoke another tool according to the protocol in the completion function and treat its result as the requested completion.</p></div></div><h2 id="completion"><a href="#completion" class="anchor"></a>Completion</h2><div class="odoc-spec"><div class="spec type anchored" id="type-func"><a href="#type-func" class="anchor"></a><code><span><span class="keyword">type</span> <span>('ctx, 'a) func</span></span><span> =
|
||
<span><span><span class="type-var">'ctx</span> option</span> <span class="arrow">-></span></span>
|
||
<span><span class="label">token</span>:string <span class="arrow">-></span></span>
|
||
<span><span>(<span><span><span class="type-var">'a</span> <a href="#type-directive">directive</a></span> list</span>, string)</span> <a href="../../../../ocaml/Stdlib/index.html#type-result">result</a></span></span></code></div><div class="spec-doc"><p>The type for completion functions.</p><p>Given an optional context determined from a partial command line parse and a token to complete it returns a list of completion directives or an error which is reported to end-users by using a protocol <a href="#val-message"><code>message</code></a>.</p><p>The context is <code>None</code> if no context was given to <a href="#val-make"><code>make</code></a> or if the context failed to parse on the current command line.</p></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-complete"><a href="#type-complete" class="anchor"></a><code><span><span class="keyword">type</span> <span>'a complete</span></span><span> = </span></code><ol><li id="type-complete.Complete" class="def variant constructor anchored"><a href="#type-complete.Complete" class="anchor"></a><code><span>| </span><span><span class="constructor">Complete</span> : <span><span><span class="type-var">'ctx</span> <a href="../../Term/index.html#type-t">Term.t</a></span> option</span> * <span><span>(<span class="type-var">'ctx</span>, <span class="type-var">'a</span>)</span> <a href="#type-func">func</a></span> <span class="arrow">-></span> <span><span class="type-var">'a</span> <a href="#type-complete">complete</a></span></span></code></li></ol></div><div class="spec-doc"><p>The type for completing.</p><p>A completion context specification which captures a partial command line parse (for example the path to a configuration file) and a completion function.</p></div></div><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 completing values parsed into values of type <code>'a</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-make"><a href="#val-make" class="anchor"></a><code><span><span class="keyword">val</span> make : <span><span class="optlabel">?context</span>:<span><span class="type-var">'ctx</span> <a href="../../Term/index.html#type-t">Term.t</a></span> <span class="arrow">-></span></span> <span><span><span>(<span class="type-var">'ctx</span>, <span class="type-var">'a</span>)</span> <a href="#type-func">func</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>make ~context func</code> uses <code>func</code> to complete.</p><p><code>context</code> defines a commmand line fragment that is evaluated before performing the completion. It the evaluation is successful the result is given to the completion function. Otherwise <code>None</code> is given.</p><p><b>Warning.</b> <code>context</code> must be part of the term of the command in which you use the completion otherwise the context will always be <code>None</code> in the function.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-complete"><a href="#val-complete" class="anchor"></a><code><span><span class="keyword">val</span> complete : <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> <a href="#type-complete">complete</a></span></span></code></div><div class="spec-doc"><p><code>complete c</code> completes with <code>c</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-complete_files"><a href="#val-complete_files" class="anchor"></a><code><span><span class="keyword">val</span> complete_files : <span><span class="type-var">'a</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>complete_files</code> holds a context insensitive function that always returns <code>Ok [</code><a href="#val-files"><code>files</code></a><code>]</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-complete_dirs"><a href="#val-complete_dirs" class="anchor"></a><code><span><span class="keyword">val</span> complete_dirs : <span><span class="type-var">'a</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>complete_dirs</code> holds a context insensitive function that always returns <code>Ok [</code><a href="#val-dirs"><code>dirs</code></a><code>]</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-complete_paths"><a href="#val-complete_paths" class="anchor"></a><code><span><span class="keyword">val</span> complete_paths : <span><span class="type-var">'a</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>complete_paths</code> holds a context insensitive function that always returns <code>Ok [</code><a href="#val-files"><code>files</code></a><code>;</code><a href="#val-dirs"><code>dirs</code></a><code>]</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-complete_restart"><a href="#val-complete_restart" class="anchor"></a><code><span><span class="keyword">val</span> complete_restart : <span><span class="type-var">'a</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>complete_dirs</code> holds a context insensitive function that always returns <code>Ok [</code><a href="#val-restart"><code>restart</code></a><code>]</code>.</p></div></div></div></body></html>
|