@ciao-lang/ts-ciao-interface

Version:

Simple Ciao interface for node.

58 lines (57 loc) • 13.4 kB

HTML

<!DOCTYPE HTML><html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/><meta name="theme-color" content="#273f79"/><link rel="stylesheet" href="lpdoc.css" type="text/css"/><script type="text/javascript" src="lpdoc.js"></script><title>Parse and return command-line options — The Ciao System v1.22</title></head><body><div class="lpdoc-page fixleftbar"><a href="#" id="sidebar-toggle-button" class="lpdoc-navbutton"><span id="sidebar-button-arrow">☰</span></a><div id="sidebar" class="lpdoc-sidebar"><div style="height: 40px; margin-left: auto; margin-right: auto"><img src="ciao-logo_autofig.png" width=auto height=100%></div><div class="lpdoc-nav"><span class="lpdoc-on-right"><a class="lpdoc-navbutton" href="ExtraLibs.html">↑</a><a class="lpdoc-navbutton" href="menu_generator.html">←</a><a class="lpdoc-navbutton" href="system_extra.html">→</a><a class="lpdoc-navbutton" href="ciaosearch.html">🔍</a></span><span><a href="ciaofulltoc.html">TOC</a></span></div><hr></hr><ul class="lpdoc-itemize-sectpath"><li><a href="ciao.html">The Ciao System</a> »<br/> </li><li><a href="ExtraLibs.html">PART VIII - Additional libraries</a> »<br/> </li><li><a href=""><strong>Parse and return command-line options</strong></a></li></ul><hr></hr><em>ON THIS PAGE</em><ul><li><a href="#Usage and interface">Usage and interface</a></li><li><a href="#Documentation on exports">Documentation on exports</a></li><li><a href="#Documentation on internals">Documentation on internals</a></li><li><a href="#Documentation on imports">Documentation on imports</a></li></ul></div><div class="lpdoc-main"><div id=""><h1>Parse and return command-line options</h1><a class="lpdoc-idx-anchor" href="ciaosearch.html#getopts"></a> <strong>Author(s):</strong> <a class="lpdoc-idx-anchor" id="Manuel Carro" href="ciaosearch.html#Manuel Carro">Manuel Carro</a>.<p><div id="Usage and interface"><h2>Usage and interface</h2><div class="lpdoc-cartouche"><ul><li><strong>Library usage:</strong><br/><tt>:- use_module(library(getopts)).</tt><li><strong>Exports:</strong><br/><ul class="lpdoc-itemize-minus"><li><em>Predicates:</em><br/><a class="lpdoc-idx-anchor" id="0" href="#getopts/4"><tt>getopts/4</tt></a>, <a class="lpdoc-idx-anchor" id="1" href="#cl_option/2"><tt>cl_option/2</tt></a>. </ul></ul></div></div><div id="Documentation on exports"><h2>Documentation on exports</h2><div><div class="lpdoc-defname"><span class="lpdoc-predtag">PREDICATE</span><a class="lpdoc-idx-anchor" id="getopts/4" href="ciaosearch.html#getopts/4">getopts/4</a></div><div class="lpdoc-deftext"><p><span class="lpdoc-usage-header">Usage:</span><span class="lpdoc-usage-decl"><tt>getopts(Arguments,Opts,Matched,Rest)</tt> </span><p><a class="lpdoc-idx-anchor" id="2" href="ciaosearch.html#Ciao Prolog">Ciao Prolog</a> parses the command-line arguments of its executables and passes them as a list of atoms to the <a class="lpdoc-idx-anchor" id="3" href="ciaosearch.html#main/1"><tt>main/1</tt></a> predicate. Thus, a shell invocation such as<p><a class="lpdoc-idx-anchor" id="4" href="ciaosearch.html#./my_program -file input.txt -file input2.txt --output_file out.txt -create-dir --decode --unsorte"><tt>./my_program -file input.txt -file input2.txt --output_file out.txt -create-dir --decode --unsorte</tt></a> <p>makes <a class="lpdoc-idx-anchor" id="5" href="ciaosearch.html#main/1"><tt>main/1</tt></a> receive an argument such as<p><a class="lpdoc-idx-anchor" id="6" href="ciaosearch.html#['-file', 'input.txt', '-file', 'input2.txt', '--output_file', 'out.txt', '-create-dir', '--decode', '--unsorte']"><tt>['-file', 'input.txt', '-file', 'input2.txt', '--output_file', 'out.txt', '-create-dir', '--decode', '--unsorte']</tt></a> <p> <a class="lpdoc-idx-anchor" id="7" href="#getopts/4"><tt>getopts/4</tt></a> can be used to parse such an command-line option list. passed in the <span class="lpdoc-var">Arguments</span> parameter. <span class="lpdoc-var">Opts</span> is a list of expected options, each option being an <em>option spec</em>, i.e., a term of the form <tt>atom/arity</tt>. For every <tt>atom</tt> a command-line option of the form <tt>'--atom'</tt> or <tt>'-atom'</tt> is expected, with <tt>arity</tt> arguments following it. An <tt>arity</tt> of zero can be omitted. For each matched option spec, the list <span class="lpdoc-var">Matched</span> will contain a term of the form <tt>atom(Arg1, Arg2, ..., Argn)</tt>, where <a class="lpdoc-idx-anchor" id="8" href="ciaosearch.html#n = arity"><tt>n = arity</tt></a>. The list <span class="lpdoc-var">Rest</span> will contain the unmatched element in <span class="lpdoc-var">Arguments</span>.<p><span class="lpdoc-var">Rest</span> will respect the relative order of the elements in <span class="lpdoc-var">Arguments</span>. The matching elements in <span class="lpdoc-var">Matched</span> appear in the same order as the options in <span class="lpdoc-var">Opts</span>, and for every option in <span class="lpdoc-var">Opts</span>, its matches appear in the order as they came in <span class="lpdoc-var">Arguments</span>.<p>Assuming <span class="lpdoc-var">Arguments</span> is <a class="lpdoc-idx-anchor" id="9" href="ciaosearch.html#['-file', 'input.txt', '-file', 'input2.txt', '--output_file', 'out.txt', '-create-dir', '--decode', '--unsorte']"><tt>['-file', 'input.txt', '-file', 'input2.txt', '--output_file', 'out.txt', '-create-dir', '--decode', '--unsorte']</tt></a>, some possible uses of <a class="lpdoc-idx-anchor" id="10" href="#getopts/4"><tt>getopts/4</tt></a> follow.<p><ul> <li>Check that a simple option has been selected: <pre class="lpdoc-codeblock">?- getopts(Args, ['create-dir'], M, R). Args = ... M = ['create-dir'], R = ['-file','input.txt','-file','input2.txt','--output_file', 'out.txt','--decode','--unsorte'] </pre> <p><li>Which argument was given to an option expecting an additional value? <pre class="lpdoc-codeblock">1 ?- getopts(Args, [output_file/1], M, R). Args = ... M = [output_file('out.txt')], R = ['-file','input.txt','-file','input2.txt','-create-dir', '--decode','--unsorte'] 1 ?- getopts(Args, [output_file/1], [output_file(F)], R). Args = .. F = 'out.txt', R = ['-file','input.txt','-file','input2.txt','-create-dir', '--decode','--unsorte'] </pre> <p><li>Extract options (and associated values) which can appear several times. <pre class="lpdoc-codeblock">1 ?- getopts(Args, [file/1], M, R). Args = ... M = [file('input.txt'),file('input2.txt')], R = ['--output_file','out.txt','-create-dir','--decode', '--unsorte'] </pre> <p><li> Was decoding selected? <pre class="lpdoc-codeblock">1 ?- getopts(Args, [decode], [_], R). Args = ... R = ['-file','input.txt','-file','input2.txt','--output_file', 'out.txt', '-create-dir','--unsorte'] </pre> <p><li>Was encoding selected? <pre class="lpdoc-codeblock">1 ?- getopts(Args, [encoding], [_], R). no </pre> <p><li>Was decoding <strong>not</strong> selected? <pre class="lpdoc-codeblock">1 ?- getopts(Args, [decode], [], R). no </pre> <p><li>Are all the options passed to the program legal options? If this is not the case, which option(s) is/are not legal? <pre class="lpdoc-codeblock">1 ?- getopts(Args, [file/1, output_file/1, 'create-dir', encode, decode, unsorted], _, R). Args = ... R = ['--unsorte'] ? </pre> </ul> <p>The complexity of <a class="lpdoc-idx-anchor" id="11" href="ciaosearch.html#getopts/1"><tt>getopts/1</tt></a> is currently <em>O(La x Lo)</em>, where <em>La</em> is the length of the argument list and <em>Lo</em> is the length of the option list.<p></p><ul class="lpdoc-itemize-minus"><li><em>Call and exit should be compatible with:</em><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="12" href="basic_props.html#list/2"><tt>basic_props:list/2</tt></a>)</span><span><span class="lpdoc-var">Arguments</span> is a list of <span class="lpdoc-var">atom</span>s. </span><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="13" href="basic_props.html#list/2"><tt>basic_props:list/2</tt></a>)</span><span><span class="lpdoc-var">Opts</span> is a list of <span class="lpdoc-var">spec</span>s. </span><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="14" href="basic_props.html#list/2"><tt>basic_props:list/2</tt></a>)</span><span><span class="lpdoc-var">Matched</span> is a list of <span class="lpdoc-var">term</span>s. </span><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="15" href="basic_props.html#list/2"><tt>basic_props:list/2</tt></a>)</span><span><span class="lpdoc-var">Rest</span> is a list of <span class="lpdoc-var">term</span>s. </span> <li><em>The following properties should hold at call time:</em><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="16" href="term_typing.html#nonvar/1"><tt>term_typing:nonvar/1</tt></a>)</span><span><span class="lpdoc-var">Arguments</span> is currently a term which is not a free variable. </span><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="17" href="term_typing.html#nonvar/1"><tt>term_typing:nonvar/1</tt></a>)</span><span><span class="lpdoc-var">Opts</span> is currently a term which is not a free variable. </span> </ul></div></div><p> <div><div class="lpdoc-defname"><span class="lpdoc-predtag">PREDICATE</span><a class="lpdoc-idx-anchor" id="cl_option/2" href="ciaosearch.html#cl_option/2">cl_option/2</a></div><div class="lpdoc-deftext"><p><span class="lpdoc-usage-header">Usage:</span><span class="lpdoc-usage-decl"><tt>cl_option(Arguments,Option)</tt> </span><p>Check that <span class="lpdoc-var">Option</span> is an option in <span class="lpdoc-var">Arguments</span>.</p><ul class="lpdoc-itemize-minus"><li><em>Call and exit should be compatible with:</em><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="18" href="basic_props.html#list/2"><tt>basic_props:list/2</tt></a>)</span><span><span class="lpdoc-var">Arguments</span> is a list of <span class="lpdoc-var">atom</span>s. </span><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="20" href="#spec/1"><tt>getopts:spec/1</tt></a>)</span><span><span class="lpdoc-var">Option</span> is <a class="lpdoc-idx-anchor" id="19" href="ciaosearch.html#AtomName/Arity"><tt>AtomName/Arity</tt></a> </span> <li><em>The following properties should hold at call time:</em><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="21" href="term_typing.html#nonvar/1"><tt>term_typing:nonvar/1</tt></a>)</span><span><span class="lpdoc-var">Arguments</span> is currently a term which is not a free variable. </span><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="22" href="term_typing.html#nonvar/1"><tt>term_typing:nonvar/1</tt></a>)</span><span><span class="lpdoc-var">Option</span> is currently a term which is not a free variable. </span> </ul></div></div><p> </div><div id="Documentation on internals"><h2>Documentation on internals</h2><div><div class="lpdoc-defname"><span class="lpdoc-predtag">REGTYPE</span><a class="lpdoc-idx-anchor" id="spec/1" href="ciaosearch.html#spec/1">spec/1</a></div><div class="lpdoc-deftext"><p><span class="lpdoc-usage-header">Usage:</span><span class="lpdoc-usage-decl"><tt>spec(Spec)</tt> </span><p><span class="lpdoc-var">Spec</span> is <a class="lpdoc-idx-anchor" id="23" href="ciaosearch.html#AtomName/Arity"><tt>AtomName/Arity</tt></a></p><ul class="lpdoc-itemize-minus"></ul></div></div><p> </div><div id="Documentation on imports"><h2>Documentation on imports</h2>This module has the following direct dependencies:<ul class="lpdoc-itemize-minus"><li><em>System library modules:</em><br/><a class="lpdoc-idx-anchor" id="24" href="lists.html"><tt>lists</tt></a>. <li><em>Packages:</em><br/><a class="lpdoc-idx-anchor" id="25" href="ciaosearch.html#prelude"><tt>prelude</tt></a>, <a class="lpdoc-idx-anchor" id="26" href="ciaosearch.html#initial"><tt>initial</tt></a>, <a class="lpdoc-idx-anchor" id="27" href="condcomp_doc.html"><tt>condcomp</tt></a>, <a class="lpdoc-idx-anchor" id="28" href="assertions_doc.html"><tt>assertions</tt></a>, <a class="lpdoc-idx-anchor" id="29" href="ciaosearch.html#assertions/assertions_basic"><tt>assertions/assertions_basic</tt></a>, <a class="lpdoc-idx-anchor" id="30" href="basicmodes_doc.html"><tt>basicmodes</tt></a>, <a class="lpdoc-idx-anchor" id="31" href="regtypes_doc.html"><tt>regtypes</tt></a>. </ul></div></div><div class="lpdoc-footer">Generated with LPdoc using Ciao</div></div><div class="lpdoc-clearer"></div></div></body></html>