mirror of
https://github.com/nim-lang/Nim.git
synced 2026-02-17 16:38:33 +00:00
Deploy to GitHub pages
This commit is contained in:
github-actions[bot]
694
parseopt.html
Normal file
694
parseopt.html
Normal file
@@ -0,0 +1,694 @@
|
||||
<?xml version="1.0" encoding="utf-8" ?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||||
<!-- This file is generated by Nim. -->
|
||||
<html xmlns="https://www.w3.org/1999/xhtml" xml:lang="en" lang="en" data-theme="auto">
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>std/parseopt</title>
|
||||
|
||||
<!-- Google fonts -->
|
||||
<link href='https://fonts.googleapis.com/css?family=Lato:400,600,900' rel='stylesheet' type='text/css'/>
|
||||
<link href='https://fonts.googleapis.com/css?family=Source+Code+Pro:400,500,600' rel='stylesheet' type='text/css'/>
|
||||
|
||||
<!-- Favicon -->
|
||||
<link rel="shortcut icon" href="data:image/x-icon;base64,AAABAAEAEBAAAAEAIABoBAAAFgAAACgAAAAQAAAAIAAAAAEAIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AAAAAAUAAAAF////AP///wD///8A////AP///wD///8A////AP///wD///8A////AAAAAAIAAABbAAAAlQAAAKIAAACbAAAAmwAAAKIAAACVAAAAWwAAAAL///8A////AP///wD///8A////AAAAABQAAADAAAAAYwAAAA3///8A////AP///wD///8AAAAADQAAAGMAAADAAAAAFP///wD///8A////AP///wAAAACdAAAAOv///wD///8A////AP///wD///8A////AP///wD///8AAAAAOgAAAJ3///8A////AP///wAAAAAnAAAAcP///wAAAAAoAAAASv///wD///8A////AP///wAAAABKAAAAKP///wAAAABwAAAAJ////wD///8AAAAAgQAAABwAAACIAAAAkAAAAJMAAACtAAAAFQAAABUAAACtAAAAkwAAAJAAAACIAAAAHAAAAIH///8A////AAAAAKQAAACrAAAAaP///wD///8AAAAARQAAANIAAADSAAAARf///wD///8AAAAAaAAAAKsAAACk////AAAAADMAAACcAAAAnQAAABj///8A////AP///wAAAAAYAAAAGP///wD///8A////AAAAABgAAACdAAAAnAAAADMAAAB1AAAAwwAAAP8AAADpAAAAsQAAAE4AAAAb////AP///wAAAAAbAAAATgAAALEAAADpAAAA/wAAAMMAAAB1AAAAtwAAAOkAAAD/AAAA/wAAAP8AAADvAAAA3gAAAN4AAADeAAAA3gAAAO8AAAD/AAAA/wAAAP8AAADpAAAAtwAAAGUAAAA/AAAA3wAAAP8AAAD/AAAA/wAAAP8AAAD/AAAA/wAAAP8AAAD/AAAA/wAAAP8AAADfAAAAPwAAAGX///8A////AAAAAEgAAADtAAAAvwAAAL0AAADGAAAA7wAAAO8AAADGAAAAvQAAAL8AAADtAAAASP///wD///8A////AP///wD///8AAAAAO////wD///8A////AAAAAIcAAACH////AP///wD///8AAAAAO////wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A//8AAP//AAD4HwAA7/cAAN/7AAD//wAAoYUAAJ55AACf+QAAh+EAAAAAAADAAwAA4AcAAP5/AAD//wAA//8AAA=="/>
|
||||
<link rel="icon" type="image/png" sizes="32x32" href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAABmJLR0QA/wD/AP+gvaeTAAAACXBIWXMAAA3XAAAN1wFCKJt4AAAAB3RJTUUH4QQQEwksSS9ZWwAAAk1JREFUWMPtll2ITVEUx39nn/O7Y5qR8f05wtCUUr6ZIS++8pEnkZInPImneaCQ5METNdOkeFBKUhMPRIkHKfEuUZSUlGlKPN2TrgfncpvmnntnmlEyq1Z7t89/rf9a6+y99oZxGZf/XeIq61EdtgKXgdXA0xrYAvBjOIF1AI9zvjcC74BSpndrJPkBWDScTF8Aa4E3wDlgHbASaANmVqlcCnwHvgDvgVfAJ+AikAAvgfVZwLnSVZHZaOuKoQi3ZOMi4NkYkpe1p4J7A8BpYAD49hfIy/oqG0+hLomiKP2L5L+1ubn5115S+3OAn4EnwBlgMzCjyt6ZAnQCJ4A7wOs88iRJHvw50HoujuPBoCKwHWiosy8MdfZnAdcHk8dxXFJ3VQbQlCTJvRBCGdRbD4M6uc5glpY3eAihpN5S5w12diSEcCCEcKUO4ljdr15T76ur1FDDLIQQ3qv71EdDOe3Kxj3leRXyk+pxdWnFWod6Wt2bY3de3aSuUHcPBVimHs7mK9WrmeOF6lR1o9qnzskh2ar2qm1qizpfXaPeVGdlmGN5pb09qMxz1Xb1kLqgzn1RyH7JUXW52lr5e/Kqi9qpto7V1atuUzfnARrV7jEib1T76gG2qxdGmXyiekkt1GswPTtek0aBfJp6YySGBfWg2tPQ0FAYgf1stUfdmdcjarbYJEniKIq6gY/Aw+zWHAC+p2labGpqiorFYgGYCEzN7oQdQClN07O1/EfDyGgC0ALMBdYAi4FyK+4H3gLPsxfR1zRNi+NP7nH5J+QntnXe5B5mpfQAAAAASUVORK5CYII=">
|
||||
|
||||
<!-- CSS -->
|
||||
<link rel="stylesheet" type="text/css" href="nimdoc.out.css?v=2.3.1">
|
||||
|
||||
<!-- JS -->
|
||||
<script type="text/javascript" src="dochack.js?v=2.3.1"></script>
|
||||
</head>
|
||||
<body>
|
||||
<div class="document" id="documentId">
|
||||
<div class="container">
|
||||
<h1 class="title">std/parseopt</h1>
|
||||
<div class="row">
|
||||
<div class="three columns">
|
||||
<div class="theme-select-wrapper">
|
||||
<label for="theme-select">Theme: </label>
|
||||
<select id="theme-select" onchange="setTheme(this.value)">
|
||||
<option value="auto">🌗 Match OS</option>
|
||||
<option value="dark">🌑 Dark</option>
|
||||
<option value="light">🌕 Light</option>
|
||||
</select>
|
||||
</div>
|
||||
<div id="global-links">
|
||||
<ul class="simple-boot">
|
||||
<li><a href="manual.html">Manual</a></li>
|
||||
<li><a href="lib.html">Standard library</a></li>
|
||||
<li> <a id="indexLink" href="theindex.html">Index</a></li>
|
||||
<li><a href="compiler/theindex.html">Compiler docs</a></li>
|
||||
<li><a href="https://nim-lang.github.io/fusion/theindex.html">Fusion docs</a></li>
|
||||
<li><a href="https://nim-lang.github.io/Nim/">devel</a>, <a href="https://nim-lang.org/documentation.html">stable</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div id="searchInputDiv">
|
||||
Search: <input type="search" id="searchInput"
|
||||
oninput="search()" />
|
||||
</div>
|
||||
|
||||
<ul class="simple simple-toc" id="toc-list">
|
||||
<li><a class="reference" id="supported-syntax_toc" href="#supported-syntax">Supported Syntax</a></li>
|
||||
<li><a class="reference" id="parsing_toc" href="#parsing">Parsing</a></li>
|
||||
<li><a class="reference" id="nimshortnoval-and-nimlongnoval_toc" href="#nimshortnoval-and-nimlongnoval"><tt class="docutils literal"><span class="pre"><span class="Identifier">shortNoVal</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">longNoVal</span></span></tt></a></li>
|
||||
<li><a class="reference" id="parser-modes_toc" href="#parser-modes">Parser Modes</a></li>
|
||||
<ul class="simple"><li><a class="reference" id="parser-modes-mode-differences_toc" href="#parser-modes-mode-differences">Mode Differences</a></li>
|
||||
<li><a class="reference" id="parser-modes-modeminusspecific-behavior_toc" href="#parser-modes-modeminusspecific-behavior">Mode-Specific Behavior</a></li>
|
||||
</ul><li><a class="reference" id="custom-rule-sets_toc" href="#custom-rule-sets">Custom Rule Sets</a></li>
|
||||
<li><a class="reference" id="see-also_toc" href="#see-also">See also</a></li>
|
||||
<li>
|
||||
<a class="reference reference-toplevel" href="#6" id="56">Imports</a>
|
||||
</li>
|
||||
<li>
|
||||
<details open>
|
||||
<summary><a class="reference reference-toplevel" href="#7" id="57">Types</a></summary>
|
||||
<ul class="simple simple-toc-section">
|
||||
<li><a class="reference" href="#CliMode" title="CliMode = enum
|
||||
LaxMode, ## The most forgiving mode
|
||||
NimMode, ## Nim parsing rules (default)
|
||||
GnuMode ## GNU-style parsing">CliMode</a></li>
|
||||
<li><a class="reference" href="#CmdLineKind" title="CmdLineKind = enum
|
||||
cmdEnd, ## End of command line reached
|
||||
cmdArgument, ## An argument such as a filename
|
||||
cmdLongOption, ## A long option such as --option
|
||||
cmdShortOption ## A short option such as -c">CmdLineKind</a></li>
|
||||
<li><a class="reference" href="#OptParser" title="OptParser = object of RootObj
|
||||
kind*: CmdLineKind ## The detected command line token
|
||||
key*, val*: string ## Key and value pair; the key is the option
|
||||
## or the argument, and the value is not "" if
|
||||
## the option was given a value">OptParser</a></li>
|
||||
|
||||
</ul>
|
||||
</details>
|
||||
</li>
|
||||
<li>
|
||||
<details open>
|
||||
<summary><a class="reference reference-toplevel" href="#12" id="62">Procs</a></summary>
|
||||
<ul class="simple simple-toc-section">
|
||||
<ul class="simple nested-toc-section">cmdLineRest
|
||||
<li><a class="reference" href="#cmdLineRest%2COptParser" title="cmdLineRest(p: OptParser): string">cmdLineRest(p: OptParser): string</a></li>
|
||||
|
||||
</ul>
|
||||
<ul class="simple nested-toc-section">initOptParser
|
||||
<li><a class="reference" href="#initOptParser%2Cstring%2Cset%5Bchar%5D%2Cseq%5Bstring%5D%2Cbool" title="initOptParser(cmdline = ""; shortNoVal: set[char] = {};
|
||||
longNoVal: seq[string] = @[]; allowWhitespaceAfterColon: bool): OptParser">initOptParser(cmdline = ""; shortNoVal: set[char] = {};
|
||||
longNoVal: seq[string] = @[]; allowWhitespaceAfterColon: bool): OptParser</a></li>
|
||||
<li><a class="reference" href="#initOptParser%2Cstring%2Cset%5Bchar%5D%2Cseq%5Bstring%5D%2CCliMode" title="initOptParser(cmdline = ""; shortNoVal: set[char] = {};
|
||||
longNoVal: seq[string] = @[]; mode: CliMode = NimMode): OptParser">initOptParser(cmdline = ""; shortNoVal: set[char] = {};
|
||||
longNoVal: seq[string] = @[]; mode: CliMode = NimMode): OptParser</a></li>
|
||||
<li><a class="reference" href="#initOptParser%2Cseq%5Bstring%5D%2Cset%5Bchar%5D%2Cseq%5Bstring%5D%2Cbool" title="initOptParser(cmdline: seq[string]; shortNoVal: set[char] = {};
|
||||
longNoVal: seq[string] = @[]; allowWhitespaceAfterColon: bool): OptParser">initOptParser(cmdline: seq[string]; shortNoVal: set[char] = {};
|
||||
longNoVal: seq[string] = @[]; allowWhitespaceAfterColon: bool): OptParser</a></li>
|
||||
<li><a class="reference" href="#initOptParser%2Cseq%5Bstring%5D%2Cset%5Bchar%5D%2Cseq%5Bstring%5D%2CCliMode" title="initOptParser(cmdline: seq[string]; shortNoVal: set[char] = {};
|
||||
longNoVal: seq[string] = @[]; mode: CliMode = NimMode): OptParser">initOptParser(cmdline: seq[string]; shortNoVal: set[char] = {};
|
||||
longNoVal: seq[string] = @[]; mode: CliMode = NimMode): OptParser</a></li>
|
||||
|
||||
</ul>
|
||||
<ul class="simple nested-toc-section">next
|
||||
<li><a class="reference" href="#next%2COptParser" title="next(p: var OptParser)">next(p: var OptParser)</a></li>
|
||||
|
||||
</ul>
|
||||
<ul class="simple nested-toc-section">remainingArgs
|
||||
<li><a class="reference" href="#remainingArgs%2COptParser" title="remainingArgs(p: OptParser): seq[string]">remainingArgs(p: OptParser): seq[string]</a></li>
|
||||
|
||||
</ul>
|
||||
|
||||
</ul>
|
||||
</details>
|
||||
</li>
|
||||
<li>
|
||||
<details open>
|
||||
<summary><a class="reference reference-toplevel" href="#15" id="65">Iterators</a></summary>
|
||||
<ul class="simple simple-toc-section">
|
||||
<ul class="simple nested-toc-section">getopt
|
||||
<li><a class="reference" href="#getopt.i%2Cseq%5Bstring%5D%2Cset%5Bchar%5D%2Cseq%5Bstring%5D%2CCliMode" title="getopt(cmdline: seq[string] = @[]; shortNoVal: set[char] = {};
|
||||
longNoVal: seq[string] = @[]; mode: CliMode = NimMode): tuple[
|
||||
kind: CmdLineKind, key, val: string]">getopt(cmdline: seq[string] = @[]; shortNoVal: set[char] = {};
|
||||
longNoVal: seq[string] = @[]; mode: CliMode = NimMode): tuple[
|
||||
kind: CmdLineKind, key, val: string]</a></li>
|
||||
<li><a class="reference" href="#getopt.i%2COptParser" title="getopt(p: var OptParser): tuple[kind: CmdLineKind, key, val: string]">getopt(p: var OptParser): tuple[kind: CmdLineKind, key, val: string]</a></li>
|
||||
|
||||
</ul>
|
||||
|
||||
</ul>
|
||||
</details>
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
|
||||
</div>
|
||||
<div class="nine columns" id="content">
|
||||
<a href="https://github.com/nim-lang/Nim/tree/devel/lib/pure/parseopt.nim#L1" class="link-seesrc" target="_blank">Source</a>
|
||||
<a href="https://github.com/nim-lang/Nim/edit/devel/lib/pure/parseopt.nim#L1" class="link-seesrc" target="_blank" >Edit</a>
|
||||
|
||||
<div id="tocRoot"></div>
|
||||
|
||||
<p class="module-desc">This module provides the standard Nim command line parser. It supports one convenience iterator over all command line options and some lower-level features.
|
||||
<h1><a class="toc-backref" id="supported-syntax" href="#supported-syntax">Supported Syntax</a></h1><p>The syntax described here applies to the default way the parser works. The behavior is configurable, though, and two additional modes are supported, see the details: <a class="reference internal" href="#parser-modes">Parser Modes</a>.</p>
|
||||
<p>Parsing also depends on whether the <tt class="docutils literal"><span class="pre"><span class="Identifier">shortNoVal</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">longNoVal</span></span></tt> parameters are omitted/empty or provided. The details are described in a <a class="reference external" href="#nimshortnoval-and-nimlongnoval">later section</a>.</p>
|
||||
<p>The following syntax is supported:</p>
|
||||
<ol class="simple"><li>Short options: <tt class="docutils literal"><span class="pre"><span class="Operator">-</span><span class="Identifier">a</span><span class="Punctuation">:</span><span class="DecNumber">5</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Operator">-</span><span class="Identifier">b</span><span class="Operator">=</span><span class="DecNumber">5</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Operator">-</span><span class="Identifier">cde</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Operator">-</span><span class="Identifier">fgh</span><span class="Operator">=</span><span class="DecNumber">5</span></span></tt></li>
|
||||
<li>Long options: <tt class="docutils literal"><span class="pre"><span class="Operator">--</span><span class="Identifier">foo</span><span class="Punctuation">:</span><span class="Identifier">bar</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Operator">--</span><span class="Identifier">foo</span><span class="Operator">=</span><span class="Identifier">bar</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Operator">--</span><span class="Identifier">foo</span></span></tt></li>
|
||||
<li>Arguments: everything that does not start with a <tt class="docutils literal"><span class="pre"><span class="Operator">-</span></span></tt></li>
|
||||
</ol>
|
||||
<p>Passing values to options <strong>requires</strong> a separator (<tt class="docutils literal"><span class="pre"><span class="Punctuation">:</span></span></tt>/<tt class="docutils literal"><span class="pre"><span class="Operator">=</span></span></tt>), short options (flags) can be bundled together and the last one can take a value.</p>
|
||||
<p>Option values can begin with the separator character (<tt class="docutils literal"><span class="pre"><span class="Punctuation">:</span></span></tt>/<tt class="docutils literal"><span class="pre"><span class="Operator">=</span></span></tt>), so all of the following is valid:</p>
|
||||
<ul class="simple"><li>option <tt class="docutils literal"><span class="pre"><span class="Identifier">foo</span></span></tt>, value <tt class="docutils literal"><span class="pre"><span class="Punctuation">:</span></span></tt>: <tt class="docutils literal"><span class="pre"><span class="Operator">--</span><span class="Identifier">foo</span><span class="Punctuation">:</span><span class="Punctuation">:</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Operator">--</span><span class="Identifier">foo</span><span class="Operator">=:</span></span></tt></li>
|
||||
<li>option <tt class="docutils literal"><span class="pre"><span class="Identifier">foo</span></span></tt>, value <tt class="docutils literal"><span class="pre"><span class="Operator">=</span></span></tt>: <tt class="docutils literal"><span class="pre"><span class="Operator">--</span><span class="Identifier">foo</span><span class="Punctuation">:</span><span class="Operator">=</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Operator">--</span><span class="Identifier">foo</span><span class="Operator">==</span></span></tt></li>
|
||||
</ul>
|
||||
<p>The <tt class="docutils literal"><span class="pre"><span class="Operator">--</span></span></tt> option, commonly used to denote that every token that follows is an argument, is interpreted as a long option, and its name is the empty string. Trailing arguments can be accessed with <a class="reference external" href="#remainingArgs,OptParser">remainingArgs</a> or <a class="reference external" href="#cmdLineRest,OptParser">cmdLineRest</a>.</p>
|
||||
|
||||
<h1><a class="toc-backref" id="parsing" href="#parsing">Parsing</a></h1><p>To parse command line options, use the <a class="reference external" href="#getopt.i,OptParser">getopt iterator</a>. It initializes the <a class="reference external" href="#OptParser">OptParser</a> object internally and iterates through the command line options.</p>
|
||||
<p>For each token, the parser's <tt class="docutils literal"><span class="pre"><span class="Identifier">kind</span></span></tt> (<a class="reference external" href="#CmdLineKind">CmdLineKind enum</a>.), <tt class="docutils literal"><span class="pre"><span class="Identifier">key</span></span></tt>, and <tt class="docutils literal"><span class="pre"><span class="Identifier">val</span></span></tt> fields are yielded.</p>
|
||||
<p>For long and short options, <tt class="docutils literal"><span class="pre"><span class="Identifier">key</span></span></tt> is the option's name, and <tt class="docutils literal"><span class="pre"><span class="Identifier">val</span></span></tt> is either the option's value, if given, or an empty string. For arguments, the <tt class="docutils literal"><span class="pre"><span class="Identifier">key</span></span></tt> field contains the argument itself, and <tt class="docutils literal"><span class="pre"><span class="Identifier">val</span></span></tt> is unused (empty).</p>
|
||||
<p>Here is an example: </p>
|
||||
|
||||
<p><strong class="examples_text">Example:</strong></p>
|
||||
<pre class="listing"><span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">parseopt</span>
|
||||
<span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">os</span>
|
||||
|
||||
<span class="Keyword">let</span> <span class="Identifier">cmds</span> <span class="Operator">=</span> <span class="StringLit">"-ab -e:5 --foo --bar=20 file.txt"</span><span class="Operator">.</span><span class="Identifier">parseCmdLine</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
|
||||
<span class="Keyword">var</span> <span class="Identifier">output</span><span class="Punctuation">:</span> <span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">string</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Operator">@</span><span class="Punctuation">[</span><span class="Punctuation">]</span>
|
||||
<span class="Comment"># If cmds is not supplied, real arguments will be retrieved by the `os` module</span>
|
||||
<span class="Keyword">for</span> <span class="Identifier">kind</span><span class="Punctuation">,</span> <span class="Identifier">key</span><span class="Punctuation">,</span> <span class="Identifier">val</span> <span class="Keyword">in</span> <span class="Identifier">getopt</span><span class="Punctuation">(</span><span class="Identifier">cmds</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
|
||||
<span class="Keyword">case</span> <span class="Identifier">kind</span>
|
||||
<span class="Keyword">of</span> <span class="Identifier">cmdEnd</span><span class="Punctuation">:</span> <span class="Keyword">break</span>
|
||||
<span class="Keyword">of</span> <span class="Identifier">cmdShortOption</span><span class="Punctuation">,</span> <span class="Identifier">cmdLongOption</span><span class="Punctuation">:</span>
|
||||
<span class="Keyword">if</span> <span class="Identifier">val</span> <span class="Operator">==</span> <span class="StringLit">""</span><span class="Punctuation">:</span>
|
||||
<span class="Identifier">output</span><span class="Operator">.</span><span class="Identifier">add</span><span class="Punctuation">(</span><span class="StringLit">"Option: "</span> <span class="Operator">&</span> <span class="Identifier">key</span><span class="Punctuation">)</span>
|
||||
<span class="Keyword">else</span><span class="Punctuation">:</span>
|
||||
<span class="Identifier">output</span><span class="Operator">.</span><span class="Identifier">add</span><span class="Punctuation">(</span><span class="StringLit">"Option and value: "</span> <span class="Operator">&</span> <span class="Identifier">key</span> <span class="Operator">&</span> <span class="StringLit">", "</span> <span class="Operator">&</span> <span class="Identifier">val</span><span class="Punctuation">)</span>
|
||||
<span class="Keyword">of</span> <span class="Identifier">cmdArgument</span><span class="Punctuation">:</span>
|
||||
<span class="Identifier">output</span><span class="Operator">.</span><span class="Identifier">add</span><span class="Punctuation">(</span><span class="StringLit">"Argument: "</span> <span class="Operator">&</span> <span class="Identifier">key</span><span class="Punctuation">)</span>
|
||||
|
||||
<span class="Identifier">doAssert</span> <span class="Identifier">output</span> <span class="Operator">==</span> <span class="Operator">@</span><span class="Punctuation">[</span>
|
||||
<span class="StringLit">"Option: a"</span><span class="Punctuation">,</span>
|
||||
<span class="StringLit">"Option: b"</span><span class="Punctuation">,</span>
|
||||
<span class="StringLit">"Option and value: e, 5"</span><span class="Punctuation">,</span>
|
||||
<span class="StringLit">"Option: foo"</span><span class="Punctuation">,</span>
|
||||
<span class="StringLit">"Option and value: bar, 20"</span><span class="Punctuation">,</span>
|
||||
<span class="StringLit">"Argument: file.txt"</span>
|
||||
<span class="Punctuation">]</span></pre><p>The <a class="reference external" href="#OptParser">OptParser</a> can be initialized with <a class="reference external" href="#initOptParser,string,set[char],seq[string]">initOptParser</a>. The <a class="reference external" href="#next,OptParser">next</a> proc advances the parser by one token.</p>
|
||||
<p>When iterating the object manually with <a class="reference external" href="#next,OptParser">next</a>, reaching the end of the command line is signalled by setting the <tt class="docutils literal"><span class="pre"><span class="Identifier">kind</span></span></tt> field to <tt class="docutils literal"><span class="pre"><span class="Identifier">cmdEnd</span></span></tt>.</p>
|
||||
<p>To set a default value for an option, assign the default value to a variable beforehand, then update it while parsing. </p>
|
||||
|
||||
<p><strong class="examples_text">Example:</strong></p>
|
||||
<pre class="listing"><span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">parseopt</span>
|
||||
<span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">strutils</span>
|
||||
|
||||
<span class="Keyword">var</span> <span class="Identifier">varName</span><span class="Punctuation">:</span> <span class="Identifier">string</span> <span class="Operator">=</span> <span class="StringLit">"defaultValue"</span>
|
||||
|
||||
<span class="Keyword">for</span> <span class="Identifier">kind</span><span class="Punctuation">,</span> <span class="Identifier">key</span><span class="Punctuation">,</span> <span class="Identifier">val</span> <span class="Keyword">in</span> <span class="Identifier">getopt</span><span class="Punctuation">(</span><span class="Operator">@</span><span class="Punctuation">[</span><span class="StringLit">"--varName:HELLO"</span><span class="Punctuation">]</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
|
||||
<span class="Keyword">case</span> <span class="Identifier">kind</span>
|
||||
<span class="Keyword">of</span> <span class="Identifier">cmdArgument</span><span class="Punctuation">:</span>
|
||||
<span class="Keyword">discard</span>
|
||||
<span class="Keyword">of</span> <span class="Identifier">cmdLongOption</span><span class="Punctuation">,</span> <span class="Identifier">cmdShortOption</span><span class="Punctuation">:</span>
|
||||
<span class="Keyword">case</span> <span class="Identifier">key</span>
|
||||
<span class="Keyword">of</span> <span class="StringLit">"varName"</span><span class="Punctuation">:</span> <span class="Comment"># --varName:<value> in the console when executing</span>
|
||||
<span class="Identifier">varName</span> <span class="Operator">=</span> <span class="Identifier">val</span><span class="Operator">.</span><span class="Identifier">toLowerAscii</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Comment"># do input sanitization in production</span>
|
||||
<span class="Keyword">of</span> <span class="Identifier">cmdEnd</span><span class="Punctuation">:</span>
|
||||
<span class="Keyword">discard</span>
|
||||
|
||||
<span class="Identifier">doAssert</span> <span class="Identifier">varName</span> <span class="Operator">==</span> <span class="StringLit">"hello"</span></pre>
|
||||
<h1><a class="toc-backref" id="nimshortnoval-and-nimlongnoval" href="#nimshortnoval-and-nimlongnoval"><tt class="docutils literal"><span class="pre"><span class="Identifier">shortNoVal</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">longNoVal</span></span></tt></a></h1><p>The optional <tt class="docutils literal"><span class="pre"><span class="Identifier">shortNoVal</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">longNoVal</span></span></tt> parameters in <a class="reference external" href="#initOptParser,string,set[char],seq[string]">initOptParser</a> and <a class="reference external" href="#getopt.i,OptParser">getopt iterator</a> are for specifying which short and long options do not accept values.</p>
|
||||
<p>When <tt class="docutils literal"><span class="pre"><span class="Identifier">shortNoVal</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="Identifier">longNoVal</span></span></tt> is non-empty, using the separators (<tt class="docutils literal"><span class="pre"><span class="Punctuation">:</span></span></tt>/<tt class="docutils literal"><span class="pre"><span class="Operator">=</span></span></tt>) becomes non-mandatory and users can separate a value from long options (that are not supplied to the corresponding argument) by whitespace or, in the case of a short option, by writing the value directly adjacent to the option.</p>
|
||||
<p>For short options, <tt class="docutils literal"><span class="pre"><span class="Operator">-</span><span class="Identifier">j4</span></span></tt> becomes supported syntax (parsed as option <tt class="docutils literal"><span class="pre"><span class="Identifier">j</span></span></tt> with value <tt class="docutils literal"><span class="pre"><span class="DecNumber">4</span></span></tt> instead of two separate options <tt class="docutils literal"><span class="pre"><span class="Identifier">j</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="DecNumber">4</span></span></tt>). For long options, <tt class="docutils literal"><span class="pre"><span class="Operator">--</span><span class="Identifier">foo</span> <span class="Identifier">bar</span></span></tt> becomes supported syntax in all <a class="reference external" href="Parser Modes">modes</a>.</p>
|
||||
<p>In <tt class="docutils literal"><span class="pre"><span class="Identifier">LaxMode</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">GnuMode</span></span></tt>, short options can also take values from the next argument (<tt class="docutils literal"><span class="pre"><span class="Operator">-</span><span class="Identifier">c</span> <span class="Identifier">val</span></span></tt>), but this does <strong>not</strong> work in the default <tt class="docutils literal"><span class="pre"><span class="Identifier">Nim</span></span></tt> mode.</p>
|
||||
<p>As more options which do not accept values are added to your program, remember to amend <tt class="docutils literal"><span class="pre"><span class="Identifier">shortNoVal</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">longNoVal</span></span></tt> accordingly.</p>
|
||||
<p>The parser does not validate the input for syntax mistakes, thus, options can still have values if passed explicitly by the user, even when they are marked as <tt class="docutils literal"><span class="pre"><span class="Identifier">shortNoVal</span></span></tt>/<tt class="docutils literal"><span class="pre"><span class="Identifier">longNoVal</span></span></tt>.</p>
|
||||
<p>This behavior allows associating an option with the mistakenly passed value: </p>
|
||||
|
||||
<p><strong class="examples_text">Example:</strong></p>
|
||||
<pre class="listing"><span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">parseopt</span>
|
||||
<span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Punctuation">[</span><span class="Identifier">sequtils</span><span class="Punctuation">,</span> <span class="Identifier">os</span><span class="Punctuation">]</span>
|
||||
|
||||
<span class="Keyword">let</span> <span class="Identifier">cmds</span> <span class="Operator">=</span> <span class="StringLit">"-n:9 --foo:bar"</span><span class="Operator">.</span><span class="Identifier">parseCmdLine</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
|
||||
<span class="Keyword">let</span> <span class="Identifier">parsed</span> <span class="Operator">=</span> <span class="Identifier">toSeq</span><span class="Punctuation">(</span><span class="Identifier">cmds</span><span class="Operator">.</span><span class="Identifier">getopt</span><span class="Punctuation">(</span><span class="Identifier">shortNoVal</span> <span class="Operator">=</span> <span class="Punctuation">{</span><span class="Punctuation">'</span><span class="Identifier">n</span><span class="CharLit">'}, longNoVal = @["foo"]))</span>
|
||||
<span class="Keyword">for</span> <span class="Punctuation">(</span><span class="Identifier">kind</span><span class="Punctuation">,</span> <span class="Identifier">key</span><span class="Punctuation">,</span> <span class="Identifier">val</span><span class="Punctuation">)</span> <span class="Keyword">in</span> <span class="Identifier">parsed</span><span class="Punctuation">:</span>
|
||||
<span class="Keyword">case</span> <span class="Identifier">kind</span>
|
||||
<span class="Keyword">of</span> <span class="Identifier">cmdEnd</span><span class="Punctuation">:</span> <span class="Keyword">raise</span> <span class="Identifier">newException</span><span class="Punctuation">(</span><span class="Identifier">AssertionDefect</span><span class="Punctuation">,</span> <span class="StringLit">"Unreachable"</span><span class="Punctuation">)</span>
|
||||
<span class="Keyword">of</span> <span class="Identifier">cmdShortOption</span><span class="Punctuation">,</span> <span class="Identifier">cmdLongOption</span><span class="Punctuation">:</span>
|
||||
<span class="Keyword">if</span> <span class="Identifier">key</span> <span class="Keyword">in</span> <span class="Punctuation">[</span><span class="StringLit">"n"</span><span class="Punctuation">,</span> <span class="StringLit">"foo"</span><span class="Punctuation">]</span> <span class="Keyword">and</span> <span class="Identifier">val</span> <span class="Operator">!=</span> <span class="StringLit">""</span><span class="Punctuation">:</span>
|
||||
<span class="Comment"># Substitute for proper error handling in your code</span>
|
||||
<span class="Keyword">discard</span> <span class="StringLit">"Option "</span> <span class="Operator">&</span> <span class="Identifier">key</span> <span class="Operator">&</span> <span class="StringLit">" can't take values!"</span>
|
||||
<span class="Keyword">else</span><span class="Punctuation">:</span> <span class="Keyword">discard</span>
|
||||
<span class="Keyword">of</span> <span class="Identifier">cmdArgument</span><span class="Punctuation">:</span> <span class="Keyword">discard</span>
|
||||
<span class="Identifier">doAssert</span> <span class="Identifier">parsed</span> <span class="Operator">==</span> <span class="Operator">@</span><span class="Punctuation">[</span>
|
||||
<span class="Punctuation">(</span><span class="Identifier">cmdShortOption</span><span class="Punctuation">,</span> <span class="StringLit">"n"</span><span class="Punctuation">,</span> <span class="StringLit">"9"</span><span class="Punctuation">)</span><span class="Punctuation">,</span>
|
||||
<span class="Punctuation">(</span><span class="Identifier">cmdLongOption</span><span class="Punctuation">,</span> <span class="StringLit">"foo"</span><span class="Punctuation">,</span> <span class="StringLit">"bar"</span><span class="Punctuation">)</span><span class="Punctuation">]</span></pre><div class="admonition admonition-warning"><span class="admonition-warning-text"><b>Important:</b></span>
|
||||
Next-argument value-taking for short/long options is only enabled when <tt class="docutils literal"><span class="pre"><span class="Identifier">shortNoVal</span></span></tt>/<tt class="docutils literal"><span class="pre"><span class="Identifier">longNoVal</span></span></tt> are non-empty. If your program has <em>no</em> options that take no value, you still must pass a non-empty placeholder (for example, <tt class="docutils literal"><span class="pre"><span class="Identifier">shortNoVal</span> <span class="Operator">=</span> <span class="Punctuation">{</span><span class="Punctuation">'</span><span class="Operator">\</span><span class="DecNumber">0'</span><span class="Punctuation">}</span></span></tt> and/or <tt class="docutils literal"><span class="pre"><span class="Identifier">longNoVal</span> <span class="Operator">=</span> <span class="Operator">@</span><span class="Punctuation">[</span><span class="StringLit">""</span><span class="Punctuation">]</span></span></tt>) to enable this form.</div>
|
||||
<p>The following example illustrates the difference between having an empty <tt class="docutils literal"><span class="pre"><span class="Identifier">shortNoVal</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">longNoVal</span></span></tt>, which is the default, and providing arguments for those two parameters: </p>
|
||||
|
||||
<p><strong class="examples_text">Example:</strong></p>
|
||||
<pre class="listing"><span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">parseopt</span>
|
||||
|
||||
<span class="Keyword">proc</span> <span class="Identifier">format</span><span class="Punctuation">(</span><span class="Identifier">kind</span><span class="Punctuation">:</span> <span class="Identifier">CmdLineKind</span><span class="Punctuation">;</span> <span class="Identifier">key</span><span class="Punctuation">,</span> <span class="Identifier">val</span><span class="Punctuation">:</span> <span class="Identifier">string</span><span class="Punctuation">)</span><span class="Punctuation">:</span> <span class="Identifier">string</span> <span class="Operator">=</span>
|
||||
<span class="Keyword">case</span> <span class="Identifier">kind</span>
|
||||
<span class="Keyword">of</span> <span class="Identifier">cmdEnd</span><span class="Punctuation">:</span> <span class="Keyword">raise</span> <span class="Identifier">newException</span><span class="Punctuation">(</span><span class="Identifier">AssertionDefect</span><span class="Punctuation">,</span> <span class="StringLit">"Unreachable"</span><span class="Punctuation">)</span>
|
||||
<span class="Keyword">of</span> <span class="Identifier">cmdShortOption</span><span class="Punctuation">,</span> <span class="Identifier">cmdLongOption</span><span class="Punctuation">:</span>
|
||||
<span class="Keyword">if</span> <span class="Identifier">val</span> <span class="Operator">==</span> <span class="StringLit">""</span><span class="Punctuation">:</span> <span class="StringLit">"Option: "</span> <span class="Operator">&</span> <span class="Identifier">key</span>
|
||||
<span class="Keyword">else</span><span class="Punctuation">:</span> <span class="StringLit">"Option and value: "</span> <span class="Operator">&</span> <span class="Identifier">key</span> <span class="Operator">&</span> <span class="StringLit">", "</span> <span class="Operator">&</span> <span class="Identifier">val</span>
|
||||
<span class="Keyword">of</span> <span class="Identifier">cmdArgument</span><span class="Punctuation">:</span> <span class="StringLit">"Argument: "</span> <span class="Operator">&</span> <span class="Identifier">key</span>
|
||||
|
||||
<span class="Keyword">let</span> <span class="Identifier">cmdLine</span> <span class="Operator">=</span> <span class="StringLit">"-j4 --first bar"</span>
|
||||
<span class="Keyword">var</span> <span class="Identifier">output1</span><span class="Punctuation">,</span> <span class="Identifier">output2</span><span class="Punctuation">:</span> <span class="Identifier">seq</span><span class="Punctuation">[</span><span class="Identifier">string</span><span class="Punctuation">]</span> <span class="Operator">=</span> <span class="Operator">@</span><span class="Punctuation">[</span><span class="Punctuation">]</span>
|
||||
|
||||
<span class="Keyword">var</span> <span class="Identifier">emptyNoVal</span> <span class="Operator">=</span> <span class="Identifier">initOptParser</span><span class="Punctuation">(</span><span class="Identifier">cmdLine</span><span class="Punctuation">)</span>
|
||||
<span class="Keyword">for</span> <span class="Identifier">kind</span><span class="Punctuation">,</span> <span class="Identifier">key</span><span class="Punctuation">,</span> <span class="Identifier">val</span> <span class="Keyword">in</span> <span class="Identifier">emptyNoVal</span><span class="Operator">.</span><span class="Identifier">getopt</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
|
||||
<span class="Identifier">output1</span><span class="Operator">.</span><span class="Identifier">add</span> <span class="Identifier">format</span><span class="Punctuation">(</span><span class="Identifier">kind</span><span class="Punctuation">,</span> <span class="Identifier">key</span><span class="Punctuation">,</span> <span class="Identifier">val</span><span class="Punctuation">)</span>
|
||||
|
||||
<span class="Identifier">doAssert</span> <span class="Identifier">output1</span> <span class="Operator">==</span> <span class="Operator">@</span><span class="Punctuation">[</span>
|
||||
<span class="StringLit">"Option: j"</span><span class="Punctuation">,</span>
|
||||
<span class="StringLit">"Option: 4"</span><span class="Punctuation">,</span>
|
||||
<span class="StringLit">"Option: first"</span><span class="Punctuation">,</span>
|
||||
<span class="StringLit">"Argument: bar"</span>
|
||||
<span class="Punctuation">]</span>
|
||||
|
||||
<span class="Keyword">var</span> <span class="Identifier">withNoVal</span> <span class="Operator">=</span> <span class="Identifier">cmdLine</span><span class="Operator">.</span><span class="Identifier">initOptParser</span><span class="Punctuation">(</span><span class="Identifier">shortNoVal</span> <span class="Operator">=</span> <span class="Punctuation">{</span><span class="Punctuation">'</span><span class="Identifier">c</span><span class="CharLit">'},</span>
|
||||
<span class="Identifier">longNoVal</span> <span class="Operator">=</span> <span class="Operator">@</span><span class="Punctuation">[</span><span class="StringLit">"second"</span><span class="Punctuation">]</span><span class="Punctuation">)</span>
|
||||
<span class="Keyword">for</span> <span class="Identifier">kind</span><span class="Punctuation">,</span> <span class="Identifier">key</span><span class="Punctuation">,</span> <span class="Identifier">val</span> <span class="Keyword">in</span> <span class="Identifier">withNoVal</span><span class="Operator">.</span><span class="Identifier">getopt</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
|
||||
<span class="Identifier">output2</span><span class="Operator">.</span><span class="Identifier">add</span> <span class="Identifier">format</span><span class="Punctuation">(</span><span class="Identifier">kind</span><span class="Punctuation">,</span> <span class="Identifier">key</span><span class="Punctuation">,</span> <span class="Identifier">val</span><span class="Punctuation">)</span>
|
||||
|
||||
<span class="Identifier">doAssert</span> <span class="Identifier">output2</span> <span class="Operator">==</span> <span class="Operator">@</span><span class="Punctuation">[</span>
|
||||
<span class="StringLit">"Option and value: j, 4"</span><span class="Punctuation">,</span>
|
||||
<span class="StringLit">"Option and value: first, bar"</span>
|
||||
<span class="Punctuation">]</span></pre>
|
||||
<h1><a class="toc-backref" id="parser-modes" href="#parser-modes">Parser Modes</a></h1><div class="admonition admonition-warning"><span class="admonition-warning-text"><b>Warning:</b></span>
|
||||
Modes other than the default (<tt class="docutils literal"><span class="pre"><span class="Identifier">Nim</span></span></tt>) are <strong>experimental</strong> and may change in future releases.</div>
|
||||
<p>The parser supports several distinct rule sets that change how options are interpreted:</p>
|
||||
<ol class="simple"><li><strong>LaxMode</strong>: Most forgiving mode, combines <tt class="docutils literal"><span class="pre"><span class="Identifier">Nim</span></span></tt> with POSIX-like short option handling. Tries to follow the <a class="reference external" href="https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap12.html">POSIX</a> guidelines where possible.</li>
|
||||
<li><strong>NimMode</strong>: Standard Nim parsing rules (default).</li>
|
||||
<li><strong>GnuMode</strong>: GNU-inspired parsing (e.g. <tt class="docutils literal"><span class="pre"><span class="Operator">=</span></span></tt> as the only delimiter). Puts some additional restrictions, following some of the <a class="reference external" href="https://sourceware.org/glibc/manual/latest/html_node/Argument-Syntax.html">GNU</a> conventions.</li>
|
||||
</ol>
|
||||
<p>Modes are ordered from most relaxed to strictest. The names were chosen to set general user expectations and full compliance is neither achieved nor planned.</p>
|
||||
|
||||
<h2><a class="toc-backref" id="parser-modes-mode-differences" href="#parser-modes-mode-differences">Mode Differences</a></h2><p><strong>NimMode</strong> (default):</p>
|
||||
<ul class="simple"><li>Short options require adjacent values or explicit delimiters: <tt class="docutils literal"><span class="pre"><span class="Operator">-</span><span class="Identifier">cval</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Operator">-</span><span class="Identifier">c</span><span class="Punctuation">:</span><span class="Identifier">val</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Operator">-</span><span class="Identifier">c</span><span class="Operator">=</span><span class="Identifier">val</span></span></tt></li>
|
||||
<li>Short options follow POSIX-style bundling rules</li>
|
||||
<li>Next-argument value taking (<tt class="docutils literal"><span class="pre"><span class="Operator">-</span><span class="Identifier">c</span> <span class="Identifier">val</span></span></tt>) is <strong>not</strong> supported by default</li>
|
||||
<li>Supports both <tt class="docutils literal"><span class="pre"><span class="Punctuation">:</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Operator">=</span></span></tt> as delimiters</li>
|
||||
<li>Allows whitespace around delimiters</li>
|
||||
<li>Values starting with <tt class="docutils literal"><span class="pre"><span class="Operator">-</span></span></tt> are interpreted as new options</li>
|
||||
</ul>
|
||||
<p><strong>LaxMode</strong>:</p>
|
||||
<ul class="simple"><li>Essentially the Nim mode with some relaxations for short options:<ul class="simple"><li>Allows short options to take values from the next argument: <tt class="docutils literal"><span class="pre"><span class="Operator">-</span><span class="Identifier">c</span> <span class="Identifier">val</span></span></tt></li>
|
||||
<li>Supports bundled short options with trailing value: <tt class="docutils literal"><span class="pre"><span class="Operator">-</span><span class="Identifier">abc</span> <span class="Identifier">val</span></span></tt></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>Values starting with <tt class="docutils literal"><span class="pre"><span class="Operator">-</span></span></tt> can be consumed as option arguments</li>
|
||||
</ul>
|
||||
<p><strong>GnuMode</strong>:</p>
|
||||
<ul class="simple"><li>Only <tt class="docutils literal"><span class="pre"><span class="Operator">=</span></span></tt> is treated as a delimiter (<tt class="docutils literal"><span class="pre"><span class="Punctuation">:</span></span></tt> is not a delimiter)</li>
|
||||
<li>No whitespace allowed around <tt class="docutils literal"><span class="pre"><span class="Operator">=</span></span></tt></li>
|
||||
<li>Short options can take next-argument values (<tt class="docutils literal"><span class="pre"><span class="Operator">-</span><span class="Identifier">c</span> <span class="Identifier">val</span></span></tt>), but only whitespace is allowed as a delimiter, separators parse as part of the value</li>
|
||||
<li>Short options follow POSIX-style bundling rules</li>
|
||||
<li>Values starting with <tt class="docutils literal"><span class="pre"><span class="Operator">-</span></span></tt> can be consumed as option arguments</li>
|
||||
<li>Known discrepancies compared to GNU getopt:<ul class="simple"><li>No notion of optional/mandatory arguments, colon (<tt class="docutils literal"><span class="pre"><span class="Punctuation">:</span></span></tt>) doesn't indicate them and overall is not a special character.</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<h2><a class="toc-backref" id="parser-modes-modeminusspecific-behavior" href="#parser-modes-modeminusspecific-behavior">Mode-Specific Behavior</a></h2><p>The parser's behavior varies significantly between modes, particularly around how options consume their values:</p>
|
||||
<p><strong>Short Options</strong></p>
|
||||
<p>Consider <tt class="docutils literal"><span class="pre"><span class="Operator">-</span><span class="Identifier">c</span> <span class="Identifier">val</span></span></tt>:</p>
|
||||
<ul class="simple"><li>In <tt class="docutils literal"><span class="pre"><span class="Identifier">Nim</span></span></tt> mode: <tt class="docutils literal"><span class="pre"><span class="Operator">-</span><span class="Identifier">c</span></span></tt> is parsed as an option without a value, and <tt class="docutils literal"><span class="pre"><span class="Identifier">val</span></span></tt> is parsed as a separate argument, regardless of <tt class="docutils literal"><span class="pre"><span class="Identifier">shortNoVal</span></span></tt> being empty or not.</li>
|
||||
<li>In <tt class="docutils literal"><span class="pre"><span class="Identifier">Lax</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">Gnu</span></span></tt> modes:<ul class="simple"><li>When <tt class="docutils literal"><span class="pre"><span class="Identifier">shortNoVal</span></span></tt> is empty, or not empty and <tt class="docutils literal"><span class="pre"><span class="Operator">-</span><span class="Identifier">c</span></span></tt> is in it: Same as <tt class="docutils literal"><span class="pre"><span class="Identifier">Nim</span></span></tt>, parsed as option <tt class="docutils literal"><span class="pre"><span class="Operator">-</span><span class="Identifier">c</span></span></tt> followed by argument <tt class="docutils literal"><span class="pre"><span class="Identifier">val</span></span></tt>.</li>
|
||||
<li>When <tt class="docutils literal"><span class="pre"><span class="Operator">-</span><span class="Identifier">c</span></span></tt> is not in <tt class="docutils literal"><span class="pre"><span class="Identifier">shortNoVal</span></span></tt>: parsed as option <tt class="docutils literal"><span class="pre"><span class="Operator">-</span><span class="Identifier">c</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Identifier">val</span></span></tt> is consumed as its value.</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
<p>Consider <tt class="docutils literal"><span class="pre"><span class="Operator">-</span><span class="Identifier">c</span><span class="Operator">-</span><span class="DecNumber">10</span></span></tt>:</p>
|
||||
<ul class="simple"><li>If <tt class="docutils literal"><span class="pre"><span class="Identifier">shortNoVal</span></span></tt> value is empty, all three modes parse three separate short options: <tt class="docutils literal"><span class="pre"><span class="Identifier">c</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="DecNumber">1</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="DecNumber">0</span></span></tt>.</li>
|
||||
<li>Otherwise, if <tt class="docutils literal"><span class="pre"><span class="Operator">-</span><span class="Identifier">c</span></span></tt> is not in <tt class="docutils literal"><span class="pre"><span class="Identifier">shortNoVal</span></span></tt>:<ul class="simple"><li><tt class="docutils literal"><span class="pre"><span class="Identifier">Nim</span></span></tt>: <tt class="docutils literal"><span class="pre"><span class="Operator">-</span><span class="Identifier">c</span></span></tt> is an option without an argument. <tt class="docutils literal"><span class="pre"><span class="Operator">-</span><span class="DecNumber">10</span></span></tt> is interpreted as a an option <tt class="docutils literal"><span class="pre"><span class="Operator">-</span><span class="DecNumber">1</span></span></tt> with the <tt class="docutils literal"><span class="pre"><span class="DecNumber">0</span></span></tt> argument.</li>
|
||||
<li><tt class="docutils literal"><span class="pre"><span class="Identifier">Lax</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">Gnu</span></span></tt> modes: <tt class="docutils literal"><span class="pre"><span class="Operator">-</span><span class="DecNumber">10</span></span></tt> is consumed as the value of <tt class="docutils literal"><span class="pre"><span class="Operator">-</span><span class="Identifier">c</span></span></tt> (allowing negative number values).</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
<p><strong>Long Options</strong></p>
|
||||
<p>Consider <tt class="docutils literal"><span class="pre"><span class="Operator">--</span><span class="Identifier">foo</span><span class="Punctuation">:</span><span class="Identifier">bar</span></span></tt>:</p>
|
||||
<ul class="simple"><li><tt class="docutils literal"><span class="pre"><span class="Identifier">Nim</span></span></tt>: <tt class="docutils literal"><span class="pre"><span class="Punctuation">:</span></span></tt> is a valid delimiter, so <tt class="docutils literal"><span class="pre"><span class="Identifier">bar</span></span></tt> is the value of <tt class="docutils literal"><span class="pre"><span class="Operator">--</span><span class="Identifier">foo</span></span></tt>.</li>
|
||||
<li><tt class="docutils literal"><span class="pre"><span class="Identifier">LaxMode</span></span></tt>: same as <tt class="docutils literal"><span class="pre"><span class="Identifier">Nim</span></span></tt>.</li>
|
||||
<li><tt class="docutils literal"><span class="pre"><span class="Identifier">Gnu</span></span></tt>: only <tt class="docutils literal"><span class="pre"><span class="Operator">=</span></span></tt> is a valid delimiter, so this parses as an option named <tt class="docutils literal"><span class="pre"><span class="Identifier">foo</span><span class="Punctuation">:</span><span class="Identifier">bar</span></span></tt> without a value (unless <tt class="docutils literal"><span class="pre"><span class="Identifier">longNoVal</span></span></tt> is non-empty and allows next-argument consumption).</li>
|
||||
</ul>
|
||||
<p>Consider <tt class="docutils literal"><span class="pre"><span class="Operator">--</span><span class="Identifier">foo</span> <span class="Operator">=</span><span class="Identifier">bar</span></span></tt>:</p>
|
||||
<ul class="simple"><li><tt class="docutils literal"><span class="pre"><span class="Identifier">Nim</span></span></tt>: whitespace around delimiters is allowed, so <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">bar</span></span></tt> is the value of <tt class="docutils literal"><span class="pre"><span class="Operator">--</span><span class="Identifier">foo</span></span></tt>.</li>
|
||||
<li><tt class="docutils literal"><span class="pre"><span class="Identifier">LaxMode</span></span></tt>: same as <tt class="docutils literal"><span class="pre"><span class="Identifier">Nim</span></span></tt>.</li>
|
||||
<li><tt class="docutils literal"><span class="pre"><span class="Identifier">Gnu</span></span></tt>: whitespace around <tt class="docutils literal"><span class="pre"><span class="Operator">=</span></span></tt> is not allowed, so <tt class="docutils literal"><span class="pre"><span class="Operator">--</span><span class="Identifier">foo</span></span></tt> is an option without a value, and <tt class="docutils literal"><span class="pre"><span class="Operator">=</span><span class="Identifier">bar</span></span></tt> is parsed as an argument.</li>
|
||||
</ul>
|
||||
|
||||
<h1><a class="toc-backref" id="custom-rule-sets" href="#custom-rule-sets">Custom Rule Sets</a></h1><div class="admonition admonition-warning"><span class="admonition-warning-text"><b>Warning:</b></span>
|
||||
Custom rule sets are unsupported and not tested</div>
|
||||
<p>If you require parsing rules beyond the three provided modes, it's possible to define a custom parser behavior by specifying a set of individual parser rules.</p>
|
||||
<p>Due to this feature being unsupported, it requires importing the private symbols of the module (with <tt class="docutils literal"><span class="pre"><span class="Keyword">import</span> <span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">parseopt</span> <span class="Punctuation">{</span><span class="Operator">.</span><span class="Identifier">all</span><span class="Operator">.</span><span class="Punctuation">}</span></span></tt>) and utilizing the unexported <tt class="docutils literal"><span class="pre"><span class="Identifier">initOptParser</span></span></tt> overload, which accepts <tt class="docutils literal"><span class="pre"><span class="Identifier">set</span><span class="Punctuation">[</span><span class="Identifier">ParserRules</span><span class="Punctuation">]</span></span></tt> (see the <tt class="docutils literal"><span class="pre"><span class="Identifier">ParserRules</span></span></tt> enum in the code for details).</p>
|
||||
|
||||
<h1><a class="toc-backref" id="see-also" href="#see-also">See also</a></h1><ul class="simple"><li><a class="reference external" href="os.html">os module</a> for lower-level command line parsing procs</li>
|
||||
<li><a class="reference external" href="parseutils.html">parseutils module</a> for helpers that parse tokens, numbers, identifiers, etc.</li>
|
||||
<li><a class="reference external" href="strutils.html">strutils module</a> for common string handling operations</li>
|
||||
<li><a class="reference external" href="json.html">json module</a> for a JSON parser</li>
|
||||
<li><a class="reference external" href="parsecfg.html">parsecfg module</a> for a configuration file parser</li>
|
||||
<li><a class="reference external" href="parsecsv.html">parsecsv module</a> for a simple CSV (comma separated value) parser</li>
|
||||
<li><a class="reference external" href="parsexml.html">parsexml module</a> for a XML / HTML parser</li>
|
||||
<li><a class="reference external" href="lib.html#pure-libraries-parsers">other parsers</a> for more parsers</li>
|
||||
<li><a class="reference external" href="https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap12.html">POSIX</a> - The Open Group Base Specifications Issue 8. Utility Conventions</li>
|
||||
<li><a class="reference external" href="https://sourceware.org/glibc/manual/latest/html_node/Argument-Syntax.html">GNU</a> - GNU C Library reference manual. 26.1.1 Program Argument Syntax Conventions</li>
|
||||
</ul>
|
||||
</p>
|
||||
<div class="section" id="6">
|
||||
<h1><a class="toc-backref" href="#6">Imports</a></h1>
|
||||
<dl class="item">
|
||||
<a class="reference external" href="os.html">os</a>
|
||||
</dl>
|
||||
</div>
|
||||
<div class="section" id="7">
|
||||
<h1><a class="toc-backref" href="#7">Types</a></h1>
|
||||
<dl class="item">
|
||||
<div id="CliMode">
|
||||
<dt><pre><a href="parseopt.html#CliMode"><span class="Identifier">CliMode</span></a> <span class="Other">=</span> <span class="Keyword">enum</span>
|
||||
<span class="Identifier">LaxMode</span><span class="Other">,</span> <span class="Comment">## The most forgiving mode</span>
|
||||
<span class="Identifier">NimMode</span><span class="Other">,</span> <span class="Comment">## Nim parsing rules (default)</span>
|
||||
<span class="Identifier">GnuMode</span> <span class="Comment">## GNU-style parsing</span></pre></dt>
|
||||
<dd>
|
||||
|
||||
Parser behavior profiles used to control parser behavior. See <a class="reference internal" href="#parser-modes">Parser Modes</a> for details.
|
||||
<a href="https://github.com/nim-lang/Nim/tree/devel/lib/pure/parseopt.nim#L346" class="link-seesrc" target="_blank">Source</a>
|
||||
<a href="https://github.com/nim-lang/Nim/edit/devel/lib/pure/parseopt.nim#L346" class="link-seesrc" target="_blank" >Edit</a>
|
||||
|
||||
</dd>
|
||||
</div>
|
||||
<div id="CmdLineKind">
|
||||
<dt><pre><a href="parseopt.html#CmdLineKind"><span class="Identifier">CmdLineKind</span></a> <span class="Other">=</span> <span class="Keyword">enum</span>
|
||||
<span class="Identifier">cmdEnd</span><span class="Other">,</span> <span class="Comment">## End of command line reached</span>
|
||||
<span class="Identifier">cmdArgument</span><span class="Other">,</span> <span class="Comment">## An argument such as a filename</span>
|
||||
<span class="Identifier">cmdLongOption</span><span class="Other">,</span> <span class="Comment">## A long option such as --option</span>
|
||||
<span class="Identifier">cmdShortOption</span> <span class="Comment">## A short option such as -c</span></pre></dt>
|
||||
<dd>
|
||||
|
||||
The detected command line token.
|
||||
<a href="https://github.com/nim-lang/Nim/tree/devel/lib/pure/parseopt.nim#L369" class="link-seesrc" target="_blank">Source</a>
|
||||
<a href="https://github.com/nim-lang/Nim/edit/devel/lib/pure/parseopt.nim#L369" class="link-seesrc" target="_blank" >Edit</a>
|
||||
|
||||
</dd>
|
||||
</div>
|
||||
<div id="OptParser">
|
||||
<dt><pre><a href="parseopt.html#OptParser"><span class="Identifier">OptParser</span></a> <span class="Other">=</span> <span class="Keyword">object</span> <span class="Keyword">of</span> <a href="system.html#RootObj"><span class="Identifier">RootObj</span></a>
|
||||
<span class="Identifier">kind</span><span class="Operator">*</span><span class="Other">:</span> <a href="parseopt.html#CmdLineKind"><span class="Identifier">CmdLineKind</span></a> <span class="Comment">## The detected command line token</span>
|
||||
<span class="Identifier">key</span><span class="Operator">*</span><span class="Other">,</span> <span class="Identifier">val</span><span class="Operator">*</span><span class="Other">:</span> <a href="system.html#string"><span class="Identifier">string</span></a> <span class="Comment">## Key and value pair; the key is the option</span>
|
||||
<span class="Comment">## or the argument, and the value is not "" if</span>
|
||||
<span class="Comment">## the option was given a value</span></pre></dt>
|
||||
<dd>
|
||||
|
||||
<p>
|
||||
Implementation of the command line parser.</p>
|
||||
<p>To initialize it, use the <a class="reference external" href="#initOptParser,string,set[char],seq[string],CliMode">initOptParser proc</a>. <a class="reference external" href="#next,OptParser">next</a> is used to advance the parser state and move through the parsed tokens.</p>
|
||||
|
||||
<a href="https://github.com/nim-lang/Nim/tree/devel/lib/pure/parseopt.nim#L374" class="link-seesrc" target="_blank">Source</a>
|
||||
<a href="https://github.com/nim-lang/Nim/edit/devel/lib/pure/parseopt.nim#L374" class="link-seesrc" target="_blank" >Edit</a>
|
||||
|
||||
</dd>
|
||||
</div>
|
||||
|
||||
</dl>
|
||||
</div>
|
||||
<div class="section" id="12">
|
||||
<h1><a class="toc-backref" href="#12">Procs</a></h1>
|
||||
<dl class="item">
|
||||
<div id="cmdLineRest-procs-all">
|
||||
<div id="cmdLineRest,OptParser">
|
||||
<dt><pre><span class="Keyword">proc</span> <a href="#cmdLineRest%2COptParser"><span class="Identifier">cmdLineRest</span></a><span class="Other">(</span><span class="Identifier">p</span><span class="Other">:</span> <a href="parseopt.html#OptParser"><span class="Identifier">OptParser</span></a><span class="Other">)</span><span class="Other">:</span> <a href="system.html#string"><span class="Identifier">string</span></a> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">gcsafe</span><span class="Other">,</span> <span class="Identifier">extern</span><span class="Other">:</span> <span class="StringLit">"npo$1"</span><span class="Other">,</span> <span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span>
|
||||
<span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">forbids</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
|
||||
<dd>
|
||||
|
||||
<p>Retrieves the rest of the command line that has not been parsed yet.</p>
|
||||
<p>See also:</p>
|
||||
<ul class="simple"><li><a class="reference external" href="#remainingArgs,OptParser">remainingArgs proc</a></li>
|
||||
</ul>
|
||||
|
||||
<p><strong class="examples_text">Example:</strong></p>
|
||||
<pre class="listing"><span class="Keyword">var</span> <span class="Identifier">p</span> <span class="Operator">=</span> <span class="Identifier">initOptParser</span><span class="Punctuation">(</span><span class="StringLit">"--left -r:2 -- foo.txt bar.txt"</span><span class="Punctuation">)</span>
|
||||
<span class="Keyword">while</span> <span class="Identifier">true</span><span class="Punctuation">:</span>
|
||||
<span class="Identifier">p</span><span class="Operator">.</span><span class="Identifier">next</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
|
||||
<span class="Keyword">if</span> <span class="Identifier">p</span><span class="Operator">.</span><span class="Identifier">kind</span> <span class="Operator">==</span> <span class="Identifier">cmdLongOption</span> <span class="Keyword">and</span> <span class="Identifier">p</span><span class="Operator">.</span><span class="Identifier">key</span> <span class="Operator">==</span> <span class="StringLit">""</span><span class="Punctuation">:</span> <span class="Comment"># Look for "--"</span>
|
||||
<span class="Keyword">break</span>
|
||||
<span class="Identifier">doAssert</span> <span class="Identifier">p</span><span class="Operator">.</span><span class="Identifier">cmdLineRest</span> <span class="Operator">==</span> <span class="StringLit">"foo.txt bar.txt"</span></pre>
|
||||
<a href="https://github.com/nim-lang/Nim/tree/devel/lib/pure/parseopt.nim#L713" class="link-seesrc" target="_blank">Source</a>
|
||||
<a href="https://github.com/nim-lang/Nim/edit/devel/lib/pure/parseopt.nim#L713" class="link-seesrc" target="_blank" >Edit</a>
|
||||
|
||||
</dd>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
<div id="initOptParser-procs-all">
|
||||
<div id="initOptParser,string,set[char],seq[string],bool">
|
||||
<dt><pre><span class="Keyword">proc</span> <a href="#initOptParser%2Cstring%2Cset%5Bchar%5D%2Cseq%5Bstring%5D%2Cbool"><span class="Identifier">initOptParser</span></a><span class="Other">(</span><span class="Identifier">cmdline</span> <span class="Other">=</span> <span class="StringLit">""</span><span class="Other">;</span> <span class="Identifier">shortNoVal</span><span class="Other">:</span> <a href="system.html#set"><span class="Identifier">set</span></a><span class="Other">[</span><a href="system.html#char"><span class="Identifier">char</span></a><span class="Other">]</span> <span class="Other">=</span> <span class="Other">{</span><span class="Other">}</span><span class="Other">;</span>
|
||||
<span class="Identifier">longNoVal</span><span class="Other">:</span> <a href="system.html#seq"><span class="Identifier">seq</span></a><span class="Other">[</span><a href="system.html#string"><span class="Identifier">string</span></a><span class="Other">]</span> <span class="Other">=</span> <span class="Operator">@</span><span class="Other">[</span><span class="Other">]</span><span class="Other">;</span> <span class="Identifier">allowWhitespaceAfterColon</span><span class="Other">:</span> <a href="system.html#bool"><span class="Identifier">bool</span></a><span class="Other">)</span><span class="Other">:</span> <a href="parseopt.html#OptParser"><span class="Identifier">OptParser</span></a> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">deprecated</span><span class="Other">:</span> <span class="StringLit">"`allowWhitespaceAfterColon` is deprecated, use parser modes instead"</span><span class="Other">,</span>
|
||||
<span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">ReadIOEffect</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">forbids</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
|
||||
<dd>
|
||||
<div class="deprecation-message">
|
||||
<b>Deprecated:</b> `allowWhitespaceAfterColon` is deprecated, use parser modes instead
|
||||
</div>
|
||||
|
||||
<p>This is an overload for continued support of the legacy <tt class="docutils literal"><span class="pre"><span class="Identifier">allowWhitespaceAfterColon</span></span></tt> option. It modifies the default parser mode so that the passed value is respected.</p>
|
||||
<p>Current default parser mode behaves as if <tt class="docutils literal"><span class="pre"><span class="Identifier">true</span></span></tt> was passed (old default).</p>
|
||||
<ul class="simple"><li><tt class="docutils literal"><span class="pre"><span class="Identifier">allowWhitespaceAfterColon</span></span></tt>: When <tt class="docutils literal"><span class="pre"><span class="Identifier">true</span></span></tt>, allows forms like <tt class="docutils literal"><span class="pre"><span class="Operator">--</span><span class="Identifier">option</span><span class="Punctuation">:</span> <span class="Identifier">value</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="Operator">--</span><span class="Identifier">option</span><span class="Operator">=</span> <span class="Identifier">value</span></span></tt> where the value is in the next token after the delimiter. When <tt class="docutils literal"><span class="pre"><span class="Identifier">false</span></span></tt>, the value must be in the same token as the delimiter.</li>
|
||||
</ul>
|
||||
|
||||
<a href="https://github.com/nim-lang/Nim/tree/devel/lib/pure/parseopt.nim#L551" class="link-seesrc" target="_blank">Source</a>
|
||||
<a href="https://github.com/nim-lang/Nim/edit/devel/lib/pure/parseopt.nim#L551" class="link-seesrc" target="_blank" >Edit</a>
|
||||
|
||||
</dd>
|
||||
</div>
|
||||
<div id="initOptParser,string,set[char],seq[string],CliMode">
|
||||
<dt><pre><span class="Keyword">proc</span> <a href="#initOptParser%2Cstring%2Cset%5Bchar%5D%2Cseq%5Bstring%5D%2CCliMode"><span class="Identifier">initOptParser</span></a><span class="Other">(</span><span class="Identifier">cmdline</span> <span class="Other">=</span> <span class="StringLit">""</span><span class="Other">;</span> <span class="Identifier">shortNoVal</span><span class="Other">:</span> <a href="system.html#set"><span class="Identifier">set</span></a><span class="Other">[</span><a href="system.html#char"><span class="Identifier">char</span></a><span class="Other">]</span> <span class="Other">=</span> <span class="Other">{</span><span class="Other">}</span><span class="Other">;</span>
|
||||
<span class="Identifier">longNoVal</span><span class="Other">:</span> <a href="system.html#seq"><span class="Identifier">seq</span></a><span class="Other">[</span><a href="system.html#string"><span class="Identifier">string</span></a><span class="Other">]</span> <span class="Other">=</span> <span class="Operator">@</span><span class="Other">[</span><span class="Other">]</span><span class="Other">;</span> <span class="Identifier">mode</span><span class="Other">:</span> <a href="parseopt.html#CliMode"><span class="Identifier">CliMode</span></a> <span class="Other">=</span> <span class="Identifier">NimMode</span><span class="Other">)</span><span class="Other">:</span> <a href="parseopt.html#OptParser"><span class="Identifier">OptParser</span></a> {.
|
||||
<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">ReadIOEffect</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">forbids</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
|
||||
<dd>
|
||||
|
||||
<p>Initializes the command line parser from a command line string.</p>
|
||||
<p>The <tt class="docutils literal"><span class="pre"><span class="Identifier">cmdline</span></span></tt> string is parsed into tokens using shell-like quoting rules.</p>
|
||||
<p><strong>Parameters:</strong></p>
|
||||
<ul class="simple"><li><tt class="docutils literal"><span class="pre"><span class="Identifier">cmdline</span></span></tt>: Command line string to parse. If empty, the real command line as provided by the <tt class="docutils literal"><span class="pre"><span class="Identifier">os</span></span></tt> module is retrieved instead. If the command line is not available, an assertion will be raised.</li>
|
||||
<li><tt class="docutils literal"><span class="pre"><span class="Identifier">shortNoVal</span></span></tt>: Set of short option characters that do not accept values. See <a class="reference external" href="#nimshortnoval-and-nimlongnoval">shortNoVal and longNoVal</a> for details.</li>
|
||||
<li><tt class="docutils literal"><span class="pre"><span class="Identifier">longNoVal</span></span></tt>: Sequence of long option names that do not accept values. See <a class="reference external" href="#nimshortnoval-and-nimlongnoval">shortNoVal and longNoVal</a> for details.</li>
|
||||
<li><tt class="docutils literal"><span class="pre"><span class="Identifier">mode</span></span></tt>: Parser behavior profile (<tt class="docutils literal"><span class="pre"><span class="Identifier">NimMode</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Identifier">LaxMode</span></span></tt>, or <tt class="docutils literal"><span class="pre"><span class="Identifier">GnuMode</span></span></tt>). See <a class="reference internal" href="#parser-modes">Parser Modes</a> for details.</li>
|
||||
</ul>
|
||||
<p><strong>Note:</strong> This does not provide a way of passing default values to arguments.</p>
|
||||
<p>See also:</p>
|
||||
<ul class="simple"><li><a class="reference external" href="#getopt.i,OptParser">getopt iterator</a></li>
|
||||
</ul>
|
||||
|
||||
<p><strong class="examples_text">Example:</strong></p>
|
||||
<pre class="listing"><span class="Keyword">var</span> <span class="Identifier">p</span> <span class="Operator">=</span> <span class="Identifier">initOptParser</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
|
||||
<span class="Identifier">p</span> <span class="Operator">=</span> <span class="Identifier">initOptParser</span><span class="Punctuation">(</span><span class="StringLit">"--left --debug:3 -l -r:2"</span><span class="Punctuation">)</span>
|
||||
<span class="Identifier">p</span> <span class="Operator">=</span> <span class="Identifier">initOptParser</span><span class="Punctuation">(</span><span class="StringLit">"--left --debug:3 -l -r:2"</span><span class="Punctuation">,</span>
|
||||
<span class="Identifier">shortNoVal</span> <span class="Operator">=</span> <span class="Punctuation">{</span><span class="Punctuation">'</span><span class="Identifier">l</span><span class="CharLit">'}, longNoVal = @["left"])</span></pre>
|
||||
<a href="https://github.com/nim-lang/Nim/tree/devel/lib/pure/parseopt.nim#L520" class="link-seesrc" target="_blank">Source</a>
|
||||
<a href="https://github.com/nim-lang/Nim/edit/devel/lib/pure/parseopt.nim#L520" class="link-seesrc" target="_blank" >Edit</a>
|
||||
|
||||
</dd>
|
||||
</div>
|
||||
<div id="initOptParser,seq[string],set[char],seq[string],bool">
|
||||
<dt><pre><span class="Keyword">proc</span> <a href="#initOptParser%2Cseq%5Bstring%5D%2Cset%5Bchar%5D%2Cseq%5Bstring%5D%2Cbool"><span class="Identifier">initOptParser</span></a><span class="Other">(</span><span class="Identifier">cmdline</span><span class="Other">:</span> <a href="system.html#seq"><span class="Identifier">seq</span></a><span class="Other">[</span><a href="system.html#string"><span class="Identifier">string</span></a><span class="Other">]</span><span class="Other">;</span> <span class="Identifier">shortNoVal</span><span class="Other">:</span> <a href="system.html#set"><span class="Identifier">set</span></a><span class="Other">[</span><a href="system.html#char"><span class="Identifier">char</span></a><span class="Other">]</span> <span class="Other">=</span> <span class="Other">{</span><span class="Other">}</span><span class="Other">;</span>
|
||||
<span class="Identifier">longNoVal</span><span class="Other">:</span> <a href="system.html#seq"><span class="Identifier">seq</span></a><span class="Other">[</span><a href="system.html#string"><span class="Identifier">string</span></a><span class="Other">]</span> <span class="Other">=</span> <span class="Operator">@</span><span class="Other">[</span><span class="Other">]</span><span class="Other">;</span> <span class="Identifier">allowWhitespaceAfterColon</span><span class="Other">:</span> <a href="system.html#bool"><span class="Identifier">bool</span></a><span class="Other">)</span><span class="Other">:</span> <a href="parseopt.html#OptParser"><span class="Identifier">OptParser</span></a> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">deprecated</span><span class="Other">:</span> <span class="StringLit">"`allowWhitespaceAfterColon` is deprecated, use parser modes instead"</span><span class="Other">,</span>
|
||||
<span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">ReadIOEffect</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">forbids</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
|
||||
<dd>
|
||||
<div class="deprecation-message">
|
||||
<b>Deprecated:</b> `allowWhitespaceAfterColon` is deprecated, use parser modes instead
|
||||
</div>
|
||||
|
||||
<p>This is an overload for continued support of the legacy <tt class="docutils literal"><span class="pre"><span class="Identifier">allowWhitespaceAfterColon</span></span></tt> option. It modifies the default parser mode so that the passed value is respected.</p>
|
||||
<p>Current default parser mode behaves as if <tt class="docutils literal"><span class="pre"><span class="Identifier">true</span></span></tt> was passed (old default)</p>
|
||||
<ul class="simple"><li><tt class="docutils literal"><span class="pre"><span class="Identifier">allowWhitespaceAfterColon</span></span></tt>: When <tt class="docutils literal"><span class="pre"><span class="Identifier">true</span></span></tt>, allows forms like <tt class="docutils literal"><span class="pre"><span class="Operator">--</span><span class="Identifier">option</span><span class="Punctuation">:</span> <span class="Identifier">value</span></span></tt> or <tt class="docutils literal"><span class="pre"><span class="Operator">--</span><span class="Identifier">option</span><span class="Operator">=</span> <span class="Identifier">value</span></span></tt> where the value is in the next token after the delimiter. When <tt class="docutils literal"><span class="pre"><span class="Identifier">false</span></span></tt>, the value must be in the same token as the delimiter.</li>
|
||||
</ul>
|
||||
|
||||
<a href="https://github.com/nim-lang/Nim/tree/devel/lib/pure/parseopt.nim#L502" class="link-seesrc" target="_blank">Source</a>
|
||||
<a href="https://github.com/nim-lang/Nim/edit/devel/lib/pure/parseopt.nim#L502" class="link-seesrc" target="_blank" >Edit</a>
|
||||
|
||||
</dd>
|
||||
</div>
|
||||
<div id="initOptParser,seq[string],set[char],seq[string],CliMode">
|
||||
<dt><pre><span class="Keyword">proc</span> <a href="#initOptParser%2Cseq%5Bstring%5D%2Cset%5Bchar%5D%2Cseq%5Bstring%5D%2CCliMode"><span class="Identifier">initOptParser</span></a><span class="Other">(</span><span class="Identifier">cmdline</span><span class="Other">:</span> <a href="system.html#seq"><span class="Identifier">seq</span></a><span class="Other">[</span><a href="system.html#string"><span class="Identifier">string</span></a><span class="Other">]</span><span class="Other">;</span> <span class="Identifier">shortNoVal</span><span class="Other">:</span> <a href="system.html#set"><span class="Identifier">set</span></a><span class="Other">[</span><a href="system.html#char"><span class="Identifier">char</span></a><span class="Other">]</span> <span class="Other">=</span> <span class="Other">{</span><span class="Other">}</span><span class="Other">;</span>
|
||||
<span class="Identifier">longNoVal</span><span class="Other">:</span> <a href="system.html#seq"><span class="Identifier">seq</span></a><span class="Other">[</span><a href="system.html#string"><span class="Identifier">string</span></a><span class="Other">]</span> <span class="Other">=</span> <span class="Operator">@</span><span class="Other">[</span><span class="Other">]</span><span class="Other">;</span> <span class="Identifier">mode</span><span class="Other">:</span> <a href="parseopt.html#CliMode"><span class="Identifier">CliMode</span></a> <span class="Other">=</span> <span class="Identifier">NimMode</span><span class="Other">)</span><span class="Other">:</span> <a href="parseopt.html#OptParser"><span class="Identifier">OptParser</span></a> {.
|
||||
<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">ReadIOEffect</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">forbids</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
|
||||
<dd>
|
||||
|
||||
<p>Initializes the command line parser.</p>
|
||||
<p><strong>Parameters:</strong></p>
|
||||
<ul class="simple"><li><tt class="docutils literal"><span class="pre"><span class="Identifier">cmdline</span></span></tt>: Sequence of command line arguments to parse. If empty, the real command line as provided by the <tt class="docutils literal"><span class="pre"><span class="Identifier">os</span></span></tt> module is retrieved instead. If the command line is not available, an assertion will be raised.</li>
|
||||
<li><tt class="docutils literal"><span class="pre"><span class="Identifier">shortNoVal</span></span></tt>: Set of short option characters that do not accept values. See <a class="reference external" href="#nimshortnoval-and-nimlongnoval">shortNoVal and longNoVal</a> for details.</li>
|
||||
<li><tt class="docutils literal"><span class="pre"><span class="Identifier">longNoVal</span></span></tt>: Sequence of long option names that do not accept values. See <a class="reference external" href="#nimshortnoval-and-nimlongnoval">shortNoVal and longNoVal</a> for details.</li>
|
||||
<li><tt class="docutils literal"><span class="pre"><span class="Identifier">mode</span></span></tt>: Parser behavior profile (<tt class="docutils literal"><span class="pre"><span class="Identifier">NimMode</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Identifier">LaxMode</span></span></tt>, or <tt class="docutils literal"><span class="pre"><span class="Identifier">GnuMode</span></span></tt>). See <a class="reference internal" href="#parser-modes">Parser Modes</a> for details.</li>
|
||||
</ul>
|
||||
<p>See also:</p>
|
||||
<ul class="simple"><li><a class="reference external" href="#getopt.i,seq[string],set[char],seq[string],CliMode">getopt iterator</a></li>
|
||||
</ul>
|
||||
|
||||
<p><strong class="examples_text">Example:</strong></p>
|
||||
<pre class="listing"><span class="Keyword">var</span> <span class="Identifier">p</span> <span class="Operator">=</span> <span class="Identifier">initOptParser</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
|
||||
<span class="Identifier">p</span> <span class="Operator">=</span> <span class="Identifier">initOptParser</span><span class="Punctuation">(</span><span class="Operator">@</span><span class="Punctuation">[</span><span class="StringLit">"--left"</span><span class="Punctuation">,</span> <span class="StringLit">"--debug:3"</span><span class="Punctuation">,</span> <span class="StringLit">"-l"</span><span class="Punctuation">,</span> <span class="StringLit">"-r:2"</span><span class="Punctuation">]</span><span class="Punctuation">)</span>
|
||||
<span class="Identifier">p</span> <span class="Operator">=</span> <span class="Identifier">initOptParser</span><span class="Punctuation">(</span><span class="Operator">@</span><span class="Punctuation">[</span><span class="StringLit">"--left"</span><span class="Punctuation">,</span> <span class="StringLit">"--debug:3"</span><span class="Punctuation">,</span> <span class="StringLit">"-l"</span><span class="Punctuation">,</span> <span class="StringLit">"-r:2"</span><span class="Punctuation">]</span><span class="Punctuation">,</span>
|
||||
<span class="Identifier">shortNoVal</span> <span class="Operator">=</span> <span class="Punctuation">{</span><span class="Punctuation">'</span><span class="Identifier">l</span><span class="CharLit">'}, longNoVal = @["left"])</span></pre>
|
||||
<a href="https://github.com/nim-lang/Nim/tree/devel/lib/pure/parseopt.nim#L475" class="link-seesrc" target="_blank">Source</a>
|
||||
<a href="https://github.com/nim-lang/Nim/edit/devel/lib/pure/parseopt.nim#L475" class="link-seesrc" target="_blank" >Edit</a>
|
||||
|
||||
</dd>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
<div id="next-procs-all">
|
||||
<div id="next,OptParser">
|
||||
<dt><pre><span class="Keyword">proc</span> <a href="#next%2COptParser"><span class="Identifier">next</span></a><span class="Other">(</span><span class="Identifier">p</span><span class="Other">:</span> <span class="Keyword">var</span> <a href="parseopt.html#OptParser"><span class="Identifier">OptParser</span></a><span class="Other">)</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">gcsafe</span><span class="Other">,</span> <span class="Identifier">extern</span><span class="Other">:</span> <span class="StringLit">"npo$1"</span><span class="Other">,</span> <span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span>
|
||||
<span class="Identifier">forbids</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
|
||||
<dd>
|
||||
|
||||
<p>Parses the next token.</p>
|
||||
<p><tt class="docutils literal"><span class="pre"><span class="Identifier">p</span><span class="Operator">.</span><span class="Identifier">kind</span></span></tt> describes what kind of token has been parsed. <tt class="docutils literal"><span class="pre"><span class="Identifier">p</span><span class="Operator">.</span><span class="Identifier">key</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">p</span><span class="Operator">.</span><span class="Identifier">val</span></span></tt> are set accordingly.</p>
|
||||
|
||||
<p><strong class="examples_text">Example:</strong></p>
|
||||
<pre class="listing"><span class="Keyword">var</span> <span class="Identifier">p</span> <span class="Operator">=</span> <span class="Identifier">initOptParser</span><span class="Punctuation">(</span><span class="StringLit">"--left -r:2 file.txt"</span><span class="Punctuation">)</span>
|
||||
<span class="Identifier">p</span><span class="Operator">.</span><span class="Identifier">next</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
|
||||
<span class="Identifier">doAssert</span> <span class="Identifier">p</span><span class="Operator">.</span><span class="Identifier">kind</span> <span class="Operator">==</span> <span class="Identifier">cmdLongOption</span> <span class="Keyword">and</span> <span class="Identifier">p</span><span class="Operator">.</span><span class="Identifier">key</span> <span class="Operator">==</span> <span class="StringLit">"left"</span>
|
||||
<span class="Identifier">p</span><span class="Operator">.</span><span class="Identifier">next</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
|
||||
<span class="Identifier">doAssert</span> <span class="Identifier">p</span><span class="Operator">.</span><span class="Identifier">kind</span> <span class="Operator">==</span> <span class="Identifier">cmdShortOption</span> <span class="Keyword">and</span> <span class="Identifier">p</span><span class="Operator">.</span><span class="Identifier">key</span> <span class="Operator">==</span> <span class="StringLit">"r"</span> <span class="Keyword">and</span> <span class="Identifier">p</span><span class="Operator">.</span><span class="Identifier">val</span> <span class="Operator">==</span> <span class="StringLit">"2"</span>
|
||||
<span class="Identifier">p</span><span class="Operator">.</span><span class="Identifier">next</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
|
||||
<span class="Identifier">doAssert</span> <span class="Identifier">p</span><span class="Operator">.</span><span class="Identifier">kind</span> <span class="Operator">==</span> <span class="Identifier">cmdArgument</span> <span class="Keyword">and</span> <span class="Identifier">p</span><span class="Operator">.</span><span class="Identifier">key</span> <span class="Operator">==</span> <span class="StringLit">"file.txt"</span>
|
||||
<span class="Identifier">p</span><span class="Operator">.</span><span class="Identifier">next</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
|
||||
<span class="Identifier">doAssert</span> <span class="Identifier">p</span><span class="Operator">.</span><span class="Identifier">kind</span> <span class="Operator">==</span> <span class="Identifier">cmdEnd</span></pre>
|
||||
<a href="https://github.com/nim-lang/Nim/tree/devel/lib/pure/parseopt.nim#L625" class="link-seesrc" target="_blank">Source</a>
|
||||
<a href="https://github.com/nim-lang/Nim/edit/devel/lib/pure/parseopt.nim#L625" class="link-seesrc" target="_blank" >Edit</a>
|
||||
|
||||
</dd>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
<div id="remainingArgs-procs-all">
|
||||
<div id="remainingArgs,OptParser">
|
||||
<dt><pre><span class="Keyword">proc</span> <a href="#remainingArgs%2COptParser"><span class="Identifier">remainingArgs</span></a><span class="Other">(</span><span class="Identifier">p</span><span class="Other">:</span> <a href="parseopt.html#OptParser"><span class="Identifier">OptParser</span></a><span class="Other">)</span><span class="Other">:</span> <a href="system.html#seq"><span class="Identifier">seq</span></a><span class="Other">[</span><a href="system.html#string"><span class="Identifier">string</span></a><span class="Other">]</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">gcsafe</span><span class="Other">,</span> <span class="Identifier">extern</span><span class="Other">:</span> <span class="StringLit">"npo$1"</span><span class="Other">,</span>
|
||||
<span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">forbids</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
|
||||
<dd>
|
||||
|
||||
<p>Retrieves a sequence of the arguments that have not been parsed yet.</p>
|
||||
<p>See also:</p>
|
||||
<ul class="simple"><li><a class="reference external" href="#cmdLineRest,OptParser">cmdLineRest proc</a></li>
|
||||
</ul>
|
||||
|
||||
<p><strong class="examples_text">Example:</strong></p>
|
||||
<pre class="listing"><span class="Keyword">var</span> <span class="Identifier">p</span> <span class="Operator">=</span> <span class="Identifier">initOptParser</span><span class="Punctuation">(</span><span class="StringLit">"--left -r:2 -- foo.txt bar.txt"</span><span class="Punctuation">)</span>
|
||||
<span class="Keyword">while</span> <span class="Identifier">true</span><span class="Punctuation">:</span>
|
||||
<span class="Identifier">p</span><span class="Operator">.</span><span class="Identifier">next</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
|
||||
<span class="Keyword">if</span> <span class="Identifier">p</span><span class="Operator">.</span><span class="Identifier">kind</span> <span class="Operator">==</span> <span class="Identifier">cmdLongOption</span> <span class="Keyword">and</span> <span class="Identifier">p</span><span class="Operator">.</span><span class="Identifier">key</span> <span class="Operator">==</span> <span class="StringLit">""</span><span class="Punctuation">:</span> <span class="Comment"># Look for "--"</span>
|
||||
<span class="Keyword">break</span>
|
||||
<span class="Identifier">doAssert</span> <span class="Identifier">p</span><span class="Operator">.</span><span class="Identifier">remainingArgs</span> <span class="Operator">==</span> <span class="Operator">@</span><span class="Punctuation">[</span><span class="StringLit">"foo.txt"</span><span class="Punctuation">,</span> <span class="StringLit">"bar.txt"</span><span class="Punctuation">]</span></pre>
|
||||
<a href="https://github.com/nim-lang/Nim/tree/devel/lib/pure/parseopt.nim#L728" class="link-seesrc" target="_blank">Source</a>
|
||||
<a href="https://github.com/nim-lang/Nim/edit/devel/lib/pure/parseopt.nim#L728" class="link-seesrc" target="_blank" >Edit</a>
|
||||
|
||||
</dd>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
</dl>
|
||||
</div>
|
||||
<div class="section" id="15">
|
||||
<h1><a class="toc-backref" href="#15">Iterators</a></h1>
|
||||
<dl class="item">
|
||||
<div id="getopt-iterators-all">
|
||||
<div id="getopt.i,seq[string],set[char],seq[string],CliMode">
|
||||
<dt><pre><span class="Keyword">iterator</span> <a href="#getopt.i%2Cseq%5Bstring%5D%2Cset%5Bchar%5D%2Cseq%5Bstring%5D%2CCliMode"><span class="Identifier">getopt</span></a><span class="Other">(</span><span class="Identifier">cmdline</span><span class="Other">:</span> <a href="system.html#seq"><span class="Identifier">seq</span></a><span class="Other">[</span><a href="system.html#string"><span class="Identifier">string</span></a><span class="Other">]</span> <span class="Other">=</span> <span class="Operator">@</span><span class="Other">[</span><span class="Other">]</span><span class="Other">;</span> <span class="Identifier">shortNoVal</span><span class="Other">:</span> <a href="system.html#set"><span class="Identifier">set</span></a><span class="Other">[</span><a href="system.html#char"><span class="Identifier">char</span></a><span class="Other">]</span> <span class="Other">=</span> <span class="Other">{</span><span class="Other">}</span><span class="Other">;</span>
|
||||
<span class="Identifier">longNoVal</span><span class="Other">:</span> <a href="system.html#seq"><span class="Identifier">seq</span></a><span class="Other">[</span><a href="system.html#string"><span class="Identifier">string</span></a><span class="Other">]</span> <span class="Other">=</span> <span class="Operator">@</span><span class="Other">[</span><span class="Other">]</span><span class="Other">;</span> <span class="Identifier">mode</span><span class="Other">:</span> <a href="parseopt.html#CliMode"><span class="Identifier">CliMode</span></a> <span class="Other">=</span> <span class="Identifier">NimMode</span><span class="Other">)</span><span class="Other">:</span> <span class="Keyword">tuple</span><span class="Other">[</span>
|
||||
<span class="Identifier">kind</span><span class="Other">:</span> <a href="parseopt.html#CmdLineKind"><span class="Identifier">CmdLineKind</span></a><span class="Other">,</span> <span class="Identifier">key</span><span class="Other">,</span> <span class="Identifier">val</span><span class="Other">:</span> <a href="system.html#string"><span class="Identifier">string</span></a><span class="Other">]</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">ReadIOEffect</span><span class="Other">]</span><span class="Other">,</span>
|
||||
<span class="Identifier">forbids</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
|
||||
<dd>
|
||||
|
||||
<p>Convenience iterator for iterating over command line arguments.</p>
|
||||
<p>This creates a new <a class="reference external" href="#OptParser">OptParser</a>. If no command line arguments are provided, the real command line as provided by the <tt class="docutils literal"><span class="pre"><span class="Identifier">os</span></span></tt> module is retrieved instead.</p>
|
||||
<p><tt class="docutils literal"><span class="pre"><span class="Identifier">shortNoVal</span></span></tt> and <tt class="docutils literal"><span class="pre"><span class="Identifier">longNoVal</span></span></tt> are used to specify which options do not take values. See the <a class="reference external" href="#nimshortnoval-and-nimlongnoval">documentation about these parameters</a> for more information on how this affects parsing.</p>
|
||||
<p><tt class="docutils literal"><span class="pre"><span class="Identifier">mode</span></span></tt> selects the parser behavior profile (<tt class="docutils literal"><span class="pre"><span class="Identifier">NimMode</span></span></tt>, <tt class="docutils literal"><span class="pre"><span class="Identifier">LaxMode</span></span></tt>, or <tt class="docutils literal"><span class="pre"><span class="Identifier">GnuMode</span></span></tt>). See <a class="reference internal" href="#parser-modes">Parser Modes</a> for details.</p>
|
||||
<p>There is no need to check for <tt class="docutils literal"><span class="pre"><span class="Identifier">cmdEnd</span></span></tt> while iterating. If using <tt class="docutils literal"><span class="pre"><span class="Identifier">getopt</span></span></tt> with case switching, checking for <tt class="docutils literal"><span class="pre"><span class="Identifier">cmdEnd</span></span></tt> is required.</p>
|
||||
<p>See also:</p>
|
||||
<ul class="simple"><li><a class="reference external" href="#initOptParser,seq[string],set[char],seq[string]">initOptParser proc</a></li>
|
||||
</ul>
|
||||
<p><strong>Examples:</strong></p>
|
||||
<p><pre class="listing"><span class="Comment"># these are placeholders, of course</span>
|
||||
<span class="Keyword">proc</span> <span class="Identifier">writeHelp</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Keyword">discard</span>
|
||||
<span class="Keyword">proc</span> <span class="Identifier">writeVersion</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Keyword">discard</span>
|
||||
|
||||
<span class="Keyword">var</span> <span class="Identifier">filename</span><span class="Punctuation">:</span> <span class="Identifier">string</span>
|
||||
<span class="Keyword">let</span> <span class="Identifier">params</span> <span class="Operator">=</span> <span class="Operator">@</span><span class="Punctuation">[</span><span class="StringLit">"--left"</span><span class="Punctuation">,</span> <span class="StringLit">"--debug:3"</span><span class="Punctuation">,</span> <span class="StringLit">"-l"</span><span class="Punctuation">,</span> <span class="StringLit">"-r:2"</span><span class="Punctuation">]</span>
|
||||
|
||||
<span class="Keyword">for</span> <span class="Identifier">kind</span><span class="Punctuation">,</span> <span class="Identifier">key</span><span class="Punctuation">,</span> <span class="Identifier">val</span> <span class="Keyword">in</span> <span class="Identifier">getopt</span><span class="Punctuation">(</span><span class="Identifier">params</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
|
||||
<span class="Keyword">case</span> <span class="Identifier">kind</span>
|
||||
<span class="Keyword">of</span> <span class="Identifier">cmdArgument</span><span class="Punctuation">:</span>
|
||||
<span class="Identifier">filename</span> <span class="Operator">=</span> <span class="Identifier">key</span>
|
||||
<span class="Keyword">of</span> <span class="Identifier">cmdLongOption</span><span class="Punctuation">,</span> <span class="Identifier">cmdShortOption</span><span class="Punctuation">:</span>
|
||||
<span class="Keyword">case</span> <span class="Identifier">key</span>
|
||||
<span class="Keyword">of</span> <span class="StringLit">"help"</span><span class="Punctuation">,</span> <span class="StringLit">"h"</span><span class="Punctuation">:</span> <span class="Identifier">writeHelp</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
|
||||
<span class="Keyword">of</span> <span class="StringLit">"version"</span><span class="Punctuation">,</span> <span class="StringLit">"v"</span><span class="Punctuation">:</span> <span class="Identifier">writeVersion</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
|
||||
<span class="Keyword">of</span> <span class="Identifier">cmdEnd</span><span class="Punctuation">:</span> <span class="Identifier">assert</span><span class="Punctuation">(</span><span class="Identifier">false</span><span class="Punctuation">)</span> <span class="Comment"># cannot happen</span>
|
||||
<span class="Keyword">if</span> <span class="Identifier">filename</span> <span class="Operator">==</span> <span class="StringLit">""</span><span class="Punctuation">:</span>
|
||||
<span class="Comment"># no filename has been written, so we show the help</span>
|
||||
<span class="Identifier">writeHelp</span><span class="Punctuation">(</span><span class="Punctuation">)</span></pre></p>
|
||||
|
||||
<a href="https://github.com/nim-lang/Nim/tree/devel/lib/pure/parseopt.nim#L782" class="link-seesrc" target="_blank">Source</a>
|
||||
<a href="https://github.com/nim-lang/Nim/edit/devel/lib/pure/parseopt.nim#L782" class="link-seesrc" target="_blank" >Edit</a>
|
||||
|
||||
</dd>
|
||||
</div>
|
||||
<div id="getopt.i,OptParser">
|
||||
<dt><pre><span class="Keyword">iterator</span> <a href="#getopt.i%2COptParser"><span class="Identifier">getopt</span></a><span class="Other">(</span><span class="Identifier">p</span><span class="Other">:</span> <span class="Keyword">var</span> <a href="parseopt.html#OptParser"><span class="Identifier">OptParser</span></a><span class="Other">)</span><span class="Other">:</span> <span class="Keyword">tuple</span><span class="Other">[</span><span class="Identifier">kind</span><span class="Other">:</span> <a href="parseopt.html#CmdLineKind"><span class="Identifier">CmdLineKind</span></a><span class="Other">,</span> <span class="Identifier">key</span><span class="Other">,</span> <span class="Identifier">val</span><span class="Other">:</span> <a href="system.html#string"><span class="Identifier">string</span></a><span class="Other">]</span> {.
|
||||
<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">forbids</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
|
||||
<dd>
|
||||
|
||||
<p>Convenience iterator for iterating over the given <a class="reference external" href="#OptParser">OptParser</a>.</p>
|
||||
<p>There is no need to check for <tt class="docutils literal"><span class="pre"><span class="Identifier">cmdEnd</span></span></tt> while iterating. If using <tt class="docutils literal"><span class="pre"><span class="Identifier">getopt</span></span></tt> with case switching, checking for <tt class="docutils literal"><span class="pre"><span class="Identifier">cmdEnd</span></span></tt> is required.</p>
|
||||
<p>See also:</p>
|
||||
<ul class="simple"><li><a class="reference external" href="#initOptParser,string,set[char],seq[string]">initOptParser proc</a></li>
|
||||
</ul>
|
||||
|
||||
<p><strong class="examples_text">Example:</strong></p>
|
||||
<pre class="listing"><span class="Comment"># these are placeholders, of course</span>
|
||||
<span class="Keyword">proc</span> <span class="Identifier">writeHelp</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Keyword">discard</span>
|
||||
<span class="Keyword">proc</span> <span class="Identifier">writeVersion</span><span class="Punctuation">(</span><span class="Punctuation">)</span> <span class="Operator">=</span> <span class="Keyword">discard</span>
|
||||
|
||||
<span class="Keyword">var</span> <span class="Identifier">filename</span><span class="Punctuation">:</span> <span class="Identifier">string</span> <span class="Operator">=</span> <span class="StringLit">""</span>
|
||||
<span class="Keyword">var</span> <span class="Identifier">p</span> <span class="Operator">=</span> <span class="Identifier">initOptParser</span><span class="Punctuation">(</span><span class="StringLit">"--left --debug:3 -l -r:2"</span><span class="Punctuation">)</span>
|
||||
|
||||
<span class="Keyword">for</span> <span class="Identifier">kind</span><span class="Punctuation">,</span> <span class="Identifier">key</span><span class="Punctuation">,</span> <span class="Identifier">val</span> <span class="Keyword">in</span> <span class="Identifier">p</span><span class="Operator">.</span><span class="Identifier">getopt</span><span class="Punctuation">(</span><span class="Punctuation">)</span><span class="Punctuation">:</span>
|
||||
<span class="Keyword">case</span> <span class="Identifier">kind</span>
|
||||
<span class="Keyword">of</span> <span class="Identifier">cmdArgument</span><span class="Punctuation">:</span>
|
||||
<span class="Identifier">filename</span> <span class="Operator">=</span> <span class="Identifier">key</span>
|
||||
<span class="Keyword">of</span> <span class="Identifier">cmdLongOption</span><span class="Punctuation">,</span> <span class="Identifier">cmdShortOption</span><span class="Punctuation">:</span>
|
||||
<span class="Keyword">case</span> <span class="Identifier">key</span>
|
||||
<span class="Keyword">of</span> <span class="StringLit">"help"</span><span class="Punctuation">,</span> <span class="StringLit">"h"</span><span class="Punctuation">:</span> <span class="Identifier">writeHelp</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
|
||||
<span class="Keyword">of</span> <span class="StringLit">"version"</span><span class="Punctuation">,</span> <span class="StringLit">"v"</span><span class="Punctuation">:</span> <span class="Identifier">writeVersion</span><span class="Punctuation">(</span><span class="Punctuation">)</span>
|
||||
<span class="Keyword">of</span> <span class="Identifier">cmdEnd</span><span class="Punctuation">:</span> <span class="Identifier">assert</span><span class="Punctuation">(</span><span class="Identifier">false</span><span class="Punctuation">)</span> <span class="Comment"># cannot happen</span>
|
||||
<span class="Keyword">if</span> <span class="Identifier">filename</span> <span class="Operator">==</span> <span class="StringLit">""</span><span class="Punctuation">:</span>
|
||||
<span class="Comment"># no filename has been given, so we show the help</span>
|
||||
<span class="Identifier">writeHelp</span><span class="Punctuation">(</span><span class="Punctuation">)</span></pre>
|
||||
<a href="https://github.com/nim-lang/Nim/tree/devel/lib/pure/parseopt.nim#L744" class="link-seesrc" target="_blank">Source</a>
|
||||
<a href="https://github.com/nim-lang/Nim/edit/devel/lib/pure/parseopt.nim#L744" class="link-seesrc" target="_blank" >Edit</a>
|
||||
|
||||
</dd>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
</dl>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="twelve-columns footer">
|
||||
<span class="nim-sprite"></span>
|
||||
<br>
|
||||
<small style="color: var(--hint);">Made with Nim. Generated: 2026-02-16 17:37:26 UTC</small>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<script defer data-domain="nim-lang.org" src="https://plausible.io/js/plausible.js"></script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
Reference in New Issue
Block a user