wren/manual_src/pages/api/argparse.html

{# retoor <retoor@molodetz.nl> #}
{% extends 'page.html' %}

{% set page_title = "argparse" %}
{% set breadcrumb = [{"url": "api/index.html", "title": "API Reference"}, {"title": "argparse"}] %}
{% set prev_page = {"url": "api/html.html", "title": "html"} %}
{% set next_page = {"url": "api/wdantic.html", "title": "wdantic"} %}

{% block article %}
                <h1>argparse</h1>

                <p>The <code>argparse</code> module provides command-line argument parsing with support for positional arguments, optional flags, type conversion, and help generation.</p>

                <pre><code>import "argparse" for ArgumentParser</code></pre>

                <h2>ArgumentParser Class</h2>

                <div class="class-header">
                    <h3>ArgumentParser</h3>
                    <p>Command-line argument parser</p>
                </div>

                <h3>Constructors</h3>

                <div class="method-signature">
                    <span class="method-name">ArgumentParser.new</span>() → <span class="type">ArgumentParser</span>
                </div>
                <p>Creates a new argument parser with no description.</p>

                <div class="method-signature">
                    <span class="method-name">ArgumentParser.new</span>(<span class="param">description</span>) → <span class="type">ArgumentParser</span>
                </div>
                <p>Creates a new argument parser with a description shown in help.</p>
                <ul class="param-list">
                    <li><span class="param-name">description</span> <span class="param-type">(String)</span> - Description of the program</li>
                </ul>

                <h3>Properties</h3>

                <div class="method-signature">
                    <span class="method-name">prog</span> → <span class="type">String</span>
                </div>
                <p>Gets or sets the program name shown in help output.</p>

                <div class="method-signature">
                    <span class="method-name">description</span> → <span class="type">String</span>
                </div>
                <p>Gets or sets the program description.</p>

                <h3>Instance Methods</h3>

                <div class="method-signature">
                    <span class="method-name">addArgument</span>(<span class="param">name</span>) → <span class="type">ArgumentParser</span>
                </div>
                <p>Adds an argument with default options. Returns the parser for chaining.</p>
                <ul class="param-list">
                    <li><span class="param-name">name</span> <span class="param-type">(String)</span> - Argument name (positional) or flag (starts with <code>-</code>)</li>
                </ul>

                <div class="method-signature">
                    <span class="method-name">addArgument</span>(<span class="param">name</span>, <span class="param">options</span>) → <span class="type">ArgumentParser</span>
                </div>
                <p>Adds an argument with specified options.</p>
                <ul class="param-list">
                    <li><span class="param-name">name</span> <span class="param-type">(String)</span> - Argument name or flag</li>
                    <li><span class="param-name">options</span> <span class="param-type">(Map)</span> - Configuration options</li>
                </ul>

                <div class="method-signature">
                    <span class="method-name">parseArgs</span>() → <span class="type">Map</span>
                </div>
                <p>Parses arguments from <code>Process.arguments</code>.</p>

                <div class="method-signature">
                    <span class="method-name">parseArgs</span>(<span class="param">args</span>) → <span class="type">Map</span>
                </div>
                <p>Parses the provided argument list.</p>
                <ul class="param-list">
                    <li><span class="param-name">args</span> <span class="param-type">(List)</span> - List of argument strings</li>
                    <li><span class="returns">Returns:</span> Map of argument names to values</li>
                </ul>

                <div class="method-signature">
                    <span class="method-name">printHelp</span>()
                </div>
                <p>Prints formatted help information to stdout.</p>

                <h2>Argument Options</h2>

                <table>
                    <tr>
                        <th>Option</th>
                        <th>Type</th>
                        <th>Description</th>
                    </tr>
                    <tr>
                        <td><code>long</code></td>
                        <td>String</td>
                        <td>Long form of the flag (e.g., <code>--verbose</code>)</td>
                    </tr>
                    <tr>
                        <td><code>type</code></td>
                        <td>String</td>
                        <td><code>"string"</code>, <code>"int"</code>, <code>"float"</code>, or <code>"bool"</code></td>
                    </tr>
                    <tr>
                        <td><code>default</code></td>
                        <td>any</td>
                        <td>Default value if not provided</td>
                    </tr>
                    <tr>
                        <td><code>required</code></td>
                        <td>Bool</td>
                        <td>Whether the argument is required</td>
                    </tr>
                    <tr>
                        <td><code>help</code></td>
                        <td>String</td>
                        <td>Help text description</td>
                    </tr>
                    <tr>
                        <td><code>choices</code></td>
                        <td>List</td>
                        <td>List of valid values</td>
                    </tr>
                    <tr>
                        <td><code>action</code></td>
                        <td>String</td>
                        <td>How to handle the argument</td>
                    </tr>
                    <tr>
                        <td><code>nargs</code></td>
                        <td>String/Num</td>
                        <td>Number of values to consume</td>
                    </tr>
                    <tr>
                        <td><code>dest</code></td>
                        <td>String</td>
                        <td>Name for the result map key</td>
                    </tr>
                </table>

                <h2>Actions</h2>

                <table>
                    <tr>
                        <th>Action</th>
                        <th>Description</th>
                    </tr>
                    <tr>
                        <td><code>store</code></td>
                        <td>Store the value (default)</td>
                    </tr>
                    <tr>
                        <td><code>storeTrue</code></td>
                        <td>Store <code>true</code> when flag is present</td>
                    </tr>
                    <tr>
                        <td><code>storeFalse</code></td>
                        <td>Store <code>false</code> when flag is present</td>
                    </tr>
                    <tr>
                        <td><code>count</code></td>
                        <td>Count occurrences of the flag</td>
                    </tr>
                    <tr>
                        <td><code>append</code></td>
                        <td>Append values to a list</td>
                    </tr>
                </table>

                <h2>Nargs Values</h2>

                <table>
                    <tr>
                        <th>Value</th>
                        <th>Description</th>
                    </tr>
                    <tr>
                        <td><code>*</code></td>
                        <td>Zero or more values (returns list)</td>
                    </tr>
                    <tr>
                        <td><code>+</code></td>
                        <td>One or more values (returns list)</td>
                    </tr>
                    <tr>
                        <td><code>N</code> (number)</td>
                        <td>Exactly N values (returns list)</td>
                    </tr>
                </table>

                <h2>Examples</h2>

                <h3>Basic Usage</h3>
                <pre><code>import "argparse" for ArgumentParser

var parser = ArgumentParser.new("File processing utility")
parser.prog = "myapp"

parser.addArgument("filename", {"help": "Input file to process"})
parser.addArgument("-o", {
    "long": "--output",
    "help": "Output file path",
    "default": "output.txt"
})

var args = parser.parseArgs()
System.print("Input: %(args["filename"])")
System.print("Output: %(args["output"])")</code></pre>

                <h3>Boolean Flags</h3>
                <pre><code>import "argparse" for ArgumentParser

var parser = ArgumentParser.new()
parser.addArgument("-v", {
    "long": "--verbose",
    "action": "storeTrue",
    "help": "Enable verbose output"
})
parser.addArgument("-q", {
    "long": "--quiet",
    "action": "storeFalse",
    "dest": "verbose",
    "help": "Disable verbose output"
})

var args = parser.parseArgs(["-v"])
System.print(args["verbose"])  // true</code></pre>

                <h3>Type Conversion</h3>
                <pre><code>import "argparse" for ArgumentParser

var parser = ArgumentParser.new()
parser.addArgument("-n", {
    "long": "--count",
    "type": "int",
    "default": 1,
    "help": "Number of iterations"
})
parser.addArgument("-t", {
    "long": "--threshold",
    "type": "float",
    "default": 0.5,
    "help": "Detection threshold"
})

var args = parser.parseArgs(["-n", "10", "-t", "0.75"])
System.print(args["count"])      // 10 (Num)
System.print(args["threshold"])  // 0.75 (Num)</code></pre>

                <h3>Multiple Values</h3>
                <pre><code>import "argparse" for ArgumentParser

var parser = ArgumentParser.new()
parser.addArgument("files", {
    "nargs": "+",
    "help": "Files to process"
})
parser.addArgument("-e", {
    "long": "--exclude",
    "action": "append",
    "help": "Patterns to exclude"
})

var args = parser.parseArgs(["file1.txt", "file2.txt", "-e", "*.tmp", "-e", "*.bak"])
System.print(args["files"])    // ["file1.txt", "file2.txt"]
System.print(args["exclude"])  // ["*.tmp", "*.bak"]</code></pre>

                <h3>Choices</h3>
                <pre><code>import "argparse" for ArgumentParser

var parser = ArgumentParser.new()
parser.addArgument("-f", {
    "long": "--format",
    "choices": ["json", "xml", "csv"],
    "default": "json",
    "help": "Output format"
})

var args = parser.parseArgs(["-f", "csv"])
System.print(args["format"])  // csv</code></pre>

                <h3>Verbosity Counter</h3>
                <pre><code>import "argparse" for ArgumentParser

var parser = ArgumentParser.new()
parser.addArgument("-v", {
    "action": "count",
    "help": "Increase verbosity"
})

var args = parser.parseArgs(["-v", "-v", "-v"])
System.print(args["v"])  // 3</code></pre>

                <div class="admonition note">
                    <div class="admonition-title">Note</div>
                    <p>Argument names starting with <code>-</code> are treated as optional flags. Names without a leading dash are positional arguments. Hyphens in argument names are converted to underscores in the result map.</p>
                </div>
{% endblock %}