873 lines
32 KiB
HTML
873 lines
32 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8" />
|
|
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<meta name="generator" content="Crystal Docs 1.20.3">
|
|
<meta name="crystal_docs.project_version" content="object_rework-dev">
|
|
<meta name="crystal_docs.project_name" content="CliGenerator">
|
|
|
|
|
|
|
|
<link href="css/style.css" rel="stylesheet" type="text/css" />
|
|
<script type="text/javascript" src="js/doc.js"></script>
|
|
|
|
<meta name="repository-name" content="CliGenerator">
|
|
<title>CliGen - CliGenerator object_rework-dev</title>
|
|
<script type="text/javascript">
|
|
CrystalDocs.base_path = "";
|
|
</script>
|
|
</head>
|
|
<body>
|
|
|
|
<svg class="hidden">
|
|
<symbol id="octicon-link" viewBox="0 0 16 16">
|
|
<path fill="currentColor" fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path>
|
|
</symbol>
|
|
</svg>
|
|
<input type="checkbox" id="sidebar-btn">
|
|
<label for="sidebar-btn" id="sidebar-btn-label">
|
|
<svg class="open" xmlns="http://www.w3.org/2000/svg" height="2em" width="2em" viewBox="0 0 512 512"><title>Open Sidebar</title><path fill="currentColor" d="M80 96v64h352V96H80zm0 112v64h352v-64H80zm0 112v64h352v-64H80z"></path></svg>
|
|
<svg class="close" xmlns="http://www.w3.org/2000/svg" width="2em" height="2em" viewBox="0 0 512 512"><title>Close Sidebar</title><path fill="currentColor" d="m118.6 73.4-45.2 45.2L210.7 256 73.4 393.4l45.2 45.2L256 301.3l137.4 137.3 45.2-45.2L301.3 256l137.3-137.4-45.2-45.2L256 210.7Z"></path></svg>
|
|
</label>
|
|
<div class="sidebar">
|
|
<div class="sidebar-header">
|
|
<div class="search-box">
|
|
<input type="search" class="search-input" placeholder="Search..." spellcheck="false" aria-label="Search">
|
|
</div>
|
|
|
|
<div class="project-summary">
|
|
<h1 class="project-name">
|
|
<a href="index.html">
|
|
CliGenerator
|
|
</a>
|
|
</h1>
|
|
|
|
<span class="project-version">
|
|
object_rework-dev
|
|
</span>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="search-results hidden">
|
|
<ul class="search-list"></ul>
|
|
</div>
|
|
|
|
<div class="types-list">
|
|
<ul>
|
|
|
|
<li class="parent open current" data-id="CliGenerator/CliGen" data-name="cligen">
|
|
<a href="CliGen.html">CliGen</a>
|
|
|
|
<ul>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/App" data-name="cligen::app">
|
|
<a href="CliGen/App.html">App</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/Arg" data-name="cligen::arg">
|
|
<a href="CliGen/Arg.html">Arg</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/ArgReprocessedError" data-name="cligen::argreprocessederror">
|
|
<a href="CliGen/ArgReprocessedError.html">ArgReprocessedError</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/Argument" data-name="cligen::argument">
|
|
<a href="CliGen/Argument.html">Argument</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/BaseCommandNode" data-name="cligen::basecommandnode">
|
|
<a href="CliGen/BaseCommandNode.html">BaseCommandNode</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/BaseFlag" data-name="cligen::baseflag">
|
|
<a href="CliGen/BaseFlag.html">BaseFlag</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/Coercable" data-name="cligen::coercable">
|
|
<a href="CliGen/Coercable.html">Coercable</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/Command" data-name="cligen::command">
|
|
<a href="CliGen/Command.html">Command</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/CommandInfo" data-name="cligen::commandinfo">
|
|
<a href="CliGen/CommandInfo.html">CommandInfo</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/CommandMeta" data-name="cligen::commandmeta">
|
|
<a href="CliGen/CommandMeta.html">CommandMeta</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/CommandNode" data-name="cligen::commandnode(t)">
|
|
<a href="CliGen/CommandNode.html">CommandNode</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/Common" data-name="cligen::common">
|
|
<a href="CliGen/Common.html">Common</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/ConfigurationError" data-name="cligen::configurationerror">
|
|
<a href="CliGen/ConfigurationError.html">ConfigurationError</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/DuplicateCommandError" data-name="cligen::duplicatecommanderror">
|
|
<a href="CliGen/DuplicateCommandError.html">DuplicateCommandError</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/DuplicateFlagError" data-name="cligen::duplicateflagerror">
|
|
<a href="CliGen/DuplicateFlagError.html">DuplicateFlagError</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/Error" data-name="cligen::error">
|
|
<a href="CliGen/Error.html">Error</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/Flag" data-name="cligen::flag(t)">
|
|
<a href="CliGen/Flag.html">Flag</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/FlagArgumentError" data-name="cligen::flagargumenterror">
|
|
<a href="CliGen/FlagArgumentError.html">FlagArgumentError</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/FlagBundleError" data-name="cligen::flagbundleerror">
|
|
<a href="CliGen/FlagBundleError.html">FlagBundleError</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/FlagMeta" data-name="cligen::flagmeta">
|
|
<a href="CliGen/FlagMeta.html">FlagMeta</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/FlagMissingArgumentError" data-name="cligen::flagmissingargumenterror">
|
|
<a href="CliGen/FlagMissingArgumentError.html">FlagMissingArgumentError</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/FlagNotFoundError" data-name="cligen::flagnotfounderror">
|
|
<a href="CliGen/FlagNotFoundError.html">FlagNotFoundError</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/Format" data-name="cligen::format">
|
|
<a href="CliGen/Format.html">Format</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/HelpRequestedError" data-name="cligen::helprequestederror">
|
|
<a href="CliGen/HelpRequestedError.html">HelpRequestedError</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/InternalError" data-name="cligen::internalerror">
|
|
<a href="CliGen/InternalError.html">InternalError</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/InternalVar" data-name="cligen::internalvar">
|
|
<a href="CliGen/InternalVar.html">InternalVar</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/InvalidFlagValueError" data-name="cligen::invalidflagvalueerror">
|
|
<a href="CliGen/InvalidFlagValueError.html">InvalidFlagValueError</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/InvalidOptionError" data-name="cligen::invalidoptionerror">
|
|
<a href="CliGen/InvalidOptionError.html">InvalidOptionError</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/MatchType" data-name="cligen::matchtype">
|
|
<a href="CliGen/MatchType.html">MatchType</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/MissingDispatchError" data-name="cligen::missingdispatcherror">
|
|
<a href="CliGen/MissingDispatchError.html">MissingDispatchError</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/MissingRequiredFlagError" data-name="cligen::missingrequiredflagerror">
|
|
<a href="CliGen/MissingRequiredFlagError.html">MissingRequiredFlagError</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/Parsable" data-name="cligen::parsable">
|
|
<a href="CliGen/Parsable.html">Parsable</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/ParseableInvariantError" data-name="cligen::parseableinvarianterror">
|
|
<a href="CliGen/ParseableInvariantError.html">ParseableInvariantError</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/PreRunCommand" data-name="cligen::preruncommand">
|
|
<a href="CliGen/PreRunCommand.html">PreRunCommand</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/ProxyCommand" data-name="cligen::proxycommand">
|
|
<a href="CliGen/ProxyCommand.html">ProxyCommand</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/Regex" data-name="cligen::regex">
|
|
<a href="CliGen/Regex.html">Regex</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/RegexInvariantError" data-name="cligen::regexinvarianterror">
|
|
<a href="CliGen/RegexInvariantError.html">RegexInvariantError</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/ReservedFlagError" data-name="cligen::reservedflagerror">
|
|
<a href="CliGen/ReservedFlagError.html">ReservedFlagError</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/RunCommand" data-name="cligen::runcommand">
|
|
<a href="CliGen/RunCommand.html">RunCommand</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/RuntimeError" data-name="cligen::runtimeerror">
|
|
<a href="CliGen/RuntimeError.html">RuntimeError</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/SubCommand" data-name="cligen::subcommand">
|
|
<a href="CliGen/SubCommand.html">SubCommand</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/SubCommandInfo" data-name="cligen::subcommandinfo">
|
|
<a href="CliGen/SubCommandInfo.html">SubCommandInfo</a>
|
|
|
|
</li>
|
|
|
|
<li class="parent " data-id="CliGenerator/CliGen/Timeparse" data-name="cligen::timeparse">
|
|
<a href="CliGen/Timeparse.html">Timeparse</a>
|
|
|
|
<ul>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/Timeparse/OperationUnit" data-name="cligen::timeparse::operationunit">
|
|
<a href="CliGen/Timeparse/OperationUnit.html">OperationUnit</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/Timeparse/RelativeOperation" data-name="cligen::timeparse::relativeoperation">
|
|
<a href="CliGen/Timeparse/RelativeOperation.html">RelativeOperation</a>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/TimeParseError" data-name="cligen::timeparseerror">
|
|
<a href="CliGen/TimeParseError.html">TimeParseError</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/Trigger" data-name="cligen::trigger">
|
|
<a href="CliGen/Trigger.html">Trigger</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/UnknownCommandNodeError" data-name="cligen::unknowncommandnodeerror">
|
|
<a href="CliGen/UnknownCommandNodeError.html">UnknownCommandNodeError</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/UnknownFlagError" data-name="cligen::unknownflagerror">
|
|
<a href="CliGen/UnknownFlagError.html">UnknownFlagError</a>
|
|
|
|
</li>
|
|
|
|
<li class=" " data-id="CliGenerator/CliGen/ValidationError" data-name="cligen::validationerror">
|
|
<a href="CliGen/ValidationError.html">ValidationError</a>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
|
|
<div class="main-content">
|
|
<h1 class="type-name">
|
|
|
|
<span class="kind">
|
|
module
|
|
</span> CliGen
|
|
|
|
</h1>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h2>
|
|
<a id="defined-in" class="anchor" href="#defined-in">
|
|
<svg class="octicon-link" aria-hidden="true">
|
|
<use href="#octicon-link"/>
|
|
</svg>
|
|
</a>
|
|
Defined in:
|
|
</h2>
|
|
|
|
|
|
cligen.cr
|
|
|
|
<br/>
|
|
|
|
|
|
cligen/annotations.cr
|
|
|
|
<br/>
|
|
|
|
|
|
cligen/app.cr
|
|
|
|
<br/>
|
|
|
|
|
|
cligen/app/generate.cr
|
|
|
|
<br/>
|
|
|
|
|
|
cligen/arg.cr
|
|
|
|
<br/>
|
|
|
|
|
|
cligen/command.cr
|
|
|
|
<br/>
|
|
|
|
|
|
cligen/command/argument.cr
|
|
|
|
<br/>
|
|
|
|
|
|
cligen/command/define_command_initializer.cr
|
|
|
|
<br/>
|
|
|
|
|
|
cligen/command/define_singleton_init.cr
|
|
|
|
<br/>
|
|
|
|
|
|
cligen/command/generate_gather_handler.cr
|
|
|
|
<br/>
|
|
|
|
|
|
cligen/command/generate_register_command.cr
|
|
|
|
<br/>
|
|
|
|
|
|
cligen/command/help_template.cr
|
|
|
|
<br/>
|
|
|
|
|
|
cligen/command/resolve_value.cr
|
|
|
|
<br/>
|
|
|
|
|
|
cligen/command/subcommand.cr
|
|
|
|
<br/>
|
|
|
|
|
|
cligen/command/validate_command_tree.cr
|
|
|
|
<br/>
|
|
|
|
|
|
cligen/command_node.cr
|
|
|
|
<br/>
|
|
|
|
|
|
cligen/command_node/base.cr
|
|
|
|
<br/>
|
|
|
|
|
|
cligen/command_node/command_meta.cr
|
|
|
|
<br/>
|
|
|
|
|
|
cligen/command_node/subcommand_meta.cr
|
|
|
|
<br/>
|
|
|
|
|
|
cligen/exceptions.cr
|
|
|
|
<br/>
|
|
|
|
|
|
cligen/flag.cr
|
|
|
|
<br/>
|
|
|
|
|
|
cligen/flag/base.cr
|
|
|
|
<br/>
|
|
|
|
|
|
cligen/flag/meta.cr
|
|
|
|
<br/>
|
|
|
|
|
|
cligen/global_flag.cr
|
|
|
|
<br/>
|
|
|
|
|
|
cligen/global_flag/add_global_flag.cr
|
|
|
|
<br/>
|
|
|
|
|
|
cligen/match_type.cr
|
|
|
|
<br/>
|
|
|
|
|
|
|
|
|
|
|
|
<h2>
|
|
<a id="constant-summary" class="anchor" href="#constant-summary">
|
|
<svg class="octicon-link" aria-hidden="true">
|
|
<use href="#octicon-link"/>
|
|
</svg>
|
|
</a>
|
|
Constant Summary
|
|
</h2>
|
|
|
|
<dl>
|
|
|
|
<dt class="entry-const" id="APPNAME">
|
|
<strong>APPNAME</strong> = <code><span class="t">File</span>.basename(<span class="t">PROGRAM_NAME</span>)</code>
|
|
</dt>
|
|
|
|
|
|
<dt class="entry-const" id="GLOBAL_FLAGS">
|
|
<strong>GLOBAL_FLAGS</strong> = <code><span class="o">[]</span> <span class="k">of</span> <span class="t">BaseFlag</span></code>
|
|
</dt>
|
|
|
|
|
|
<dt class="entry-const" id="MAX_COMMAND_DEPTH">
|
|
<strong>MAX_COMMAND_DEPTH</strong> = <code><span class="n">32</span></code>
|
|
</dt>
|
|
|
|
<dd class="entry-const-doc">
|
|
<h1><a id="cli-genmax-command-depth" class="anchor" href="#cli-genmax-command-depth"> <svg class="octicon-link" aria-hidden="true">
|
|
<use href="#octicon-link"/>
|
|
</svg>
|
|
</a>CliGen::MAX_COMMAND_DEPTH</h1>
|
|
<p>This exists to prevent the user from defining a command tree
|
|
that extends past the compile-time configured max via the
|
|
CliGen::MAX_COMMAND_DEPTH constant.</p>
|
|
<p>The reason this is a thing is because crystal macros don't allow for
|
|
unbounded while's/until's in macros, meaning it always has to be
|
|
deterministic. SO to deal with this and still allow for subcommand
|
|
defining you need either go with the default (32 command depth) or
|
|
define your own larger max (understand this will affect compile-time
|
|
due to this directly affecting loops in the Command macros).</p>
|
|
<p>So to still support this I had to make bounded for-loops usng</p>
|
|
<pre><code class="language-crystal"><span class="o">{%</span> <span class="k">for</span> i <span class="k">in</span> (<span class="n">1</span>..<span class="t">CliGen</span><span class="t">::</span><span class="t">MAX_COMMAND_DEPTH</span>) <span class="o">%}</span>
|
|
...<span class="k">do</span> checks...
|
|
<span class="o">{%</span> <span class="k">end</span> }</code></pre>
|
|
</dd>
|
|
|
|
|
|
<dt class="entry-const" id="VERSION">
|
|
<strong>VERSION</strong> = <code><span class="s">"0.2.0"</span></code>
|
|
</dt>
|
|
|
|
|
|
</dl>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h2>
|
|
<a id="macro-summary" class="anchor" href="#macro-summary">
|
|
<svg class="octicon-link" aria-hidden="true">
|
|
<use href="#octicon-link"/>
|
|
</svg>
|
|
</a>
|
|
Macro Summary
|
|
</h2>
|
|
<ul class="list-summary">
|
|
|
|
<li class="entry-summary">
|
|
<a href="#add_global_flag%28type%2C%2A%2Clong%2Cdescription%2Cenv_var%3D%22%22%2Cshort%3Dnil%2Cvalidation%3Dnil%2Cdefault%3Dnil%2Con_match%3Dnil%2Coptions%3Dnil%2Cformat%3Dnil%2Cinternal%3Dfalse%29-macro" class="signature"><strong>add_global_flag</strong>(type, *, long, description, env_var = <span class="s">""</span>, short = <span class="n">nil</span>, validation = <span class="n">nil</span>, default = <span class="n">nil</span>, on_match = <span class="n">nil</span>, options = <span class="n">nil</span>, format = <span class="n">nil</span>, internal = <span class="n">false</span>)</a>
|
|
|
|
<div class="summary"><p>This macro provides a user-friendly way to define a global flag for your project.</p></div>
|
|
|
|
</li>
|
|
|
|
<li class="entry-summary">
|
|
<a href="#override_help_template%28filepath%29-macro" class="signature"><strong>override_help_template</strong>(filepath)</a>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
<div class="methods-inherited">
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h2>
|
|
<a id="macro-detail" class="anchor" href="#macro-detail">
|
|
<svg class="octicon-link" aria-hidden="true">
|
|
<use href="#octicon-link"/>
|
|
</svg>
|
|
</a>
|
|
Macro Detail
|
|
</h2>
|
|
|
|
<div class="entry-detail" id="add_global_flag(type,*,long,description,env_var="",short=nil,validation=nil,default=nil,on_match=nil,options=nil,format=nil,internal=false)-macro">
|
|
<div class="signature">
|
|
|
|
macro <strong>add_global_flag</strong>(type, *, long, description, env_var = <span class="s">""</span>, short = <span class="n">nil</span>, validation = <span class="n">nil</span>, default = <span class="n">nil</span>, on_match = <span class="n">nil</span>, options = <span class="n">nil</span>, format = <span class="n">nil</span>, internal = <span class="n">false</span>)
|
|
|
|
<a class="method-permalink" href="#add_global_flag%28type%2C%2A%2Clong%2Cdescription%2Cenv_var%3D%22%22%2Cshort%3Dnil%2Cvalidation%3Dnil%2Cdefault%3Dnil%2Con_match%3Dnil%2Coptions%3Dnil%2Cformat%3Dnil%2Cinternal%3Dfalse%29-macro">#</a>
|
|
</div>
|
|
|
|
<div class="doc">
|
|
|
|
<p>This macro provides a user-friendly way to define a global flag for your
|
|
project.</p>
|
|
<h2><a id="what-does-this-do" class="anchor" href="#what-does-this-do">
|
|
<svg class="octicon-link" aria-hidden="true">
|
|
<use href="#octicon-link"/>
|
|
</svg>
|
|
</a>What does this do?</h2>
|
|
<p>This macro is used to help define & check a global flag to be used in the
|
|
all levels of commands.</p>
|
|
<p>When provided it will parse your values & serialize them into a Flag(T)
|
|
object & insert it in the CliGen::GLOBAL_FLAGS array after checking if
|
|
a flag using it's <code>--long</code> is already in use. In the case that that long
|
|
is already used it will raise at runtime and you'll need to choose another
|
|
long.</p>
|
|
<h2><a id="arguments" class="anchor" href="#arguments">
|
|
<svg class="octicon-link" aria-hidden="true">
|
|
<use href="#octicon-link"/>
|
|
</svg>
|
|
</a>Arguments</h2>
|
|
<h3><a id="type-type-node" class="anchor" href="#type-type-node">
|
|
<svg class="octicon-link" aria-hidden="true">
|
|
<use href="#octicon-link"/>
|
|
</svg>
|
|
</a>type: TypeNode</h3>
|
|
<p><strong>Required:</strong> true</p>
|
|
<p>This is the type of the flag (Bool, Int32, String, etc).</p>
|
|
<h3><a id="long-string-literal" class="anchor" href="#long-string-literal">
|
|
<svg class="octicon-link" aria-hidden="true">
|
|
<use href="#octicon-link"/>
|
|
</svg>
|
|
</a>long: StringLiteral</h3>
|
|
<p><strong>Required:</strong> true</p>
|
|
<p>This is the long form of the flag that will be matched at the command-line</p>
|
|
<h3><a id="description-string-literal" class="anchor" href="#description-string-literal">
|
|
<svg class="octicon-link" aria-hidden="true">
|
|
<use href="#octicon-link"/>
|
|
</svg>
|
|
</a>description: StringLiteral</h3>
|
|
<p><strong>Required:</strong> true</p>
|
|
<p>This is the full length description of the flag that will be presented in the
|
|
help text provided to the user.</p>
|
|
<h3><a id="env-var-string-literal" class="anchor" href="#env-var-string-literal">
|
|
<svg class="octicon-link" aria-hidden="true">
|
|
<use href="#octicon-link"/>
|
|
</svg>
|
|
</a>env_var: StringLiteral</h3>
|
|
<p><strong>Required:</strong> false</p>
|
|
<p>This is an ENV VAR that can be used to set this value without providing an
|
|
argument via the CLI. By default it will (unless explicitly disbled by
|
|
passing <code>env_var: nil</code> as an argument to disable the env_var entirely)
|
|
will parse your long flag and set the ENV VAR to the un "--" portion of it</p>
|
|
<p><strong>Warning:</strong> Incompatible ENV VAR formatting</p>
|
|
<p>When providing ENV VARs manually you cannot provide any whitespace or "-"
|
|
characters internally to it. As thse are both incompatible with ENV VARs.</p>
|
|
<p>If you provide an ENV VAR with these the framework will raise at
|
|
compile-time and tell you to change them.</p>
|
|
<p><strong>Note:</strong> Auto Generates ENV VAR from flag long</p>
|
|
<p>If you did not provide a ENV VAR manually (or disable it via setting it to
|
|
nil), the macro will use the long flag to create a ENV VAR that can be
|
|
matched. In this case if the flag has any internal "-" chars they will
|
|
be replaced with "_" so "--long--flag--name"/"--long-flag-name" ->
|
|
"LONG_FLAG_NAME".</p>
|
|
<p>When you provide a long: with a trailing ARGUMENT (ex: "--item ITEM",
|
|
"--item=ITEM") the flag will first be split on the whitespace or "="
|
|
prior to being used for the ENV_VAR.</p>
|
|
<h3><a id="short-string-literal" class="anchor" href="#short-string-literal">
|
|
<svg class="octicon-link" aria-hidden="true">
|
|
<use href="#octicon-link"/>
|
|
</svg>
|
|
</a>short: StringLiteral</h3>
|
|
<p><strong>Required:</strong> false</p>
|
|
<p>This is the short form of a flag ("--filename" -> "-f") that can be matched
|
|
during parsing.</p>
|
|
<p><strong>Note:</strong> Alphabetic characters only</p>
|
|
<p>Unlike some other frameworks that might support numeric flags, due to the
|
|
issues around supporting them & being able to discern if these are arguments
|
|
(-1/signed int's) or short flags ("--one" -> "-1"), I've determined that I
|
|
will not be supporting numeric flags as this causes a number of
|
|
complications/complexities around ARGV parsing.</p>
|
|
<h3><a id="default-t" class="anchor" href="#default-t">
|
|
<svg class="octicon-link" aria-hidden="true">
|
|
<use href="#octicon-link"/>
|
|
</svg>
|
|
</a>default: T</h3>
|
|
<p><strong>Required:</strong> ?false?</p>
|
|
<p>This is the default value of the flag (String -> "abc", Int32 -> 0, etc)
|
|
that will be returned if no direct (via parsing CLI args) or indirect
|
|
(by parsing ENV VAR values) arguments are provided.</p>
|
|
<p>While not technically required, it's advised to always set a default
|
|
when creating flags as if you don't and nothing is parsed/provided
|
|
when Flag(T)#value! is called it will raise a
|
|
CliGen::MissingRequiredFlagError exception at the call site.</p>
|
|
<h3><a id="options-array-literaltcall" class="anchor" href="#options-array-literaltcall">
|
|
<svg class="octicon-link" aria-hidden="true">
|
|
<use href="#octicon-link"/>
|
|
</svg>
|
|
</a>options: ArrayLiteral(T)|Call</h3>
|
|
<p><strong>Required:</strong> false</p>
|
|
<p>This argument sets a static list of accepted arguments to a specific subset
|
|
of values.</p>
|
|
<p>EX: Output format</p>
|
|
<pre><code class="language-crystal"><span class="t">CliGen</span>.add_global_flag(<span class="t">String</span>,
|
|
default: <span class="s">"ecr"</span>,
|
|
short: <span class="s">"-f"</span>,
|
|
long: <span class="s">"--format"</span>,
|
|
description: <span class="s">"Provide the preferred output format"</span>,
|
|
options: <span class="s">%w[ json yaml ecr ]</span>
|
|
)</code></pre>
|
|
<p><strong>Note:</strong> Support for runtime resolution</p>
|
|
<p>While the primary value of this is static arrays of values, you can also
|
|
delegate the discovery of values to a global method or helper method in
|
|
your codebase.</p>
|
|
<p>HOWEVER, when doing so ALWAYS ensure that you are providing a full path
|
|
to your method, as the the macro has no way of determining relative paths
|
|
in your modules. While, provided you are doing this in the same context as
|
|
the method you are running, this shouldn't be an issue, however best
|
|
practices dictate you provide a full path just to be careful.</p>
|
|
<p>EX: Delegated resolution</p>
|
|
<pre><code class="language-crystal"><span class="k">module</span> <span class="t">ABC</span>
|
|
<span class="k">def</span> <span class="m">self</span>.items
|
|
<span class="s">%w[ a b c d e f g taco ]</span>
|
|
<span class="k">end</span>
|
|
<span class="k">end</span>
|
|
|
|
<span class="t">CliGen</span>.add_global_flag(<span class="t">String</span>,
|
|
default: <span class="s">"a"</span>,
|
|
short: <span class="s">"-i"</span>,
|
|
long: <span class="s">"--item"</span>,
|
|
description: <span class="s">"Provide an item to print"</span>,
|
|
options: <span class="t">::</span><span class="t">ABC</span>.items
|
|
)</code></pre>
|
|
<h3><a id="format-regex-literal" class="anchor" href="#format-regex-literal">
|
|
<svg class="octicon-link" aria-hidden="true">
|
|
<use href="#octicon-link"/>
|
|
</svg>
|
|
</a>format: RegexLiteral</h3>
|
|
<p><strong>Required:</strong> false</p>
|
|
<p>This exists to handle (for String & Custom Data Types) filtering & checking
|
|
that an argument being provided by a user is being given in a specific
|
|
format.</p>
|
|
<p>This is something you use when you're only wanting to validate formatting,
|
|
if you plan to do more specific/extensive validation you should use the
|
|
validation: field.</p>
|
|
<p>EX: Hostname matching</p>
|
|
<pre><code class="language-crystal"><span class="t">CliGen</span>.add_global_flag(<span class="t">Array</span>(<span class="t">String</span>),
|
|
default: <span class="o">[]</span> <span class="k">of</span> <span class="t">String</span>,
|
|
short: <span class="s">"-H"</span>,
|
|
long: <span class="s">"--hostname"</span>,
|
|
description: <span class="s">"Provide a hostname to do remote work on"</span>,
|
|
format: <span class="s">/^[a-zA-Z]{3}[0-9]+node[0-9]$/</span>
|
|
)</code></pre>
|
|
<h3><a id="validation-proc-literalt-bool" class="anchor" href="#validation-proc-literalt-bool">
|
|
<svg class="octicon-link" aria-hidden="true">
|
|
<use href="#octicon-link"/>
|
|
</svg>
|
|
</a>validation: ProcLiteral(T, Bool)</h3>
|
|
<p><strong>Required:</strong> false</p>
|
|
<p>Here you can provide a ad-hoc proc for doing validations of a provided
|
|
argument that can't easily be done by providing a static <code>options:</code> value.</p>
|
|
<p><strong>Note:</strong> Explicit input & return type requirement</p>
|
|
<p>The explicit input <code>: T</code> & return <code>: Bool</code> turn types are required as the
|
|
macros I setup are trying to enforce that both the input & return types
|
|
are explicity to avoid truthy & falsey semantics.</p>
|
|
<p>EX: checking int range</p>
|
|
<pre><code class="language-crystal"><span class="t">CliGen</span>.add_global_flag(<span class="t">Int32</span>,
|
|
short: <span class="s">"-p"</span>,
|
|
long: <span class="s">"--port"</span>,
|
|
description: <span class="s">"Provide a single port to test against"</span>,
|
|
validation: <span class="o">-></span>(port : <span class="t">Int32</span>) : <span class="t">Bool</span> <span class="k">do</span>
|
|
(<span class="t">UInt16</span><span class="t">::</span><span class="t">MIN</span>..<span class="t">UInt16</span><span class="t">::</span><span class="t">MAX</span>).includes?(port)
|
|
<span class="k">end</span>
|
|
)</code></pre>
|
|
<p>EX: file existance check</p>
|
|
<pre><code class="language-crystal"><span class="t">CliGen</span>.add_global_flag(<span class="t">String</span>,
|
|
short: <span class="s">"-i"</span>,
|
|
long: <span class="s">"--filename"</span>,
|
|
description: <span class="s">"Provide a file that will serve as the input for this program"</span>,
|
|
validation: <span class="o">-></span>(file : <span class="t">String</span>) : <span class="t">Bool</span> <span class="k">do</span>
|
|
<span class="k">if</span> <span class="t">File</span>.exists?(file)
|
|
<span class="n">true</span>
|
|
<span class="k">else</span>
|
|
<span class="t">STDERR</span>.puts <span class="s">"ERROR : --filename : Provided file (</span><span class="i">#{</span>file<span class="i">}</span><span class="s">) does not exist"</span>
|
|
<span class="n">false</span>
|
|
<span class="k">end</span>
|
|
<span class="k">end</span>
|
|
)</code></pre>
|
|
<h3><a id="on-match-proc-literalt-nil" class="anchor" href="#on-match-proc-literalt-nil">
|
|
<svg class="octicon-link" aria-hidden="true">
|
|
<use href="#octicon-link"/>
|
|
</svg>
|
|
</a>on_match: ProcLiteral(T, Nil)</h3>
|
|
<p><strong>Required:</strong> false</p>
|
|
<p>This option is where you provide the proc for handling ad-hoc</p>
|
|
<p>EX: Configuring the stdlib log level</p>
|
|
<pre><code class="language-crystal"><span class="t">CliGen</span>.add_global_flag(<span class="t">String</span>,
|
|
long: <span class="s">"--log-level LEVEL"</span>,
|
|
short: <span class="s">"-l"</span>,
|
|
description: <span class="s">"Set the current log level of the stdlib Log library"</span>,
|
|
options: <span class="s">%w[ trace debug notice info warn error fatal ]</span>,
|
|
on_match: <span class="o">-></span>(level : <span class="t">String</span>) <span class="k">do</span>
|
|
<span class="t">::</span><span class="t">Log</span>.setup(level: <span class="t">::</span><span class="t">Log</span><span class="t">::</span><span class="t">Severity</span>.parse(level))
|
|
<span class="k">end</span>
|
|
)</code></pre>
|
|
<p>EX: Collecting arguments in a global array</p>
|
|
<pre><code class="language-crystal"><span class="k">module</span> <span class="t">MyModule</span>
|
|
<span class="t">MY_ARRAY</span> <span class="o">=</span> <span class="o">[]</span> <span class="k">of</span> <span class="t">String</span>
|
|
<span class="t">CliGen</span>.add_global_flag(<span class="t">String</span>,
|
|
long: <span class="s">"--filename FILE"</span>,
|
|
short: <span class="s">"-i"</span>,
|
|
description: <span class="s">"Provide a single file to check against (repeatable)"</span>,
|
|
validation: <span class="o">-></span>(file : <span class="t">String</span>) : <span class="t">Bool</span> <span class="k">do</span>
|
|
<span class="k">if</span> <span class="t">File</span>.exists?(file)
|
|
<span class="n">true</span>
|
|
<span class="k">else</span>
|
|
<span class="t">STDERR</span>.puts <span class="s">"ERROR : --filename : </span><span class="i">#{</span>file<span class="i">}</span><span class="s"> does not exist"</span>
|
|
<span class="n">false</span>
|
|
<span class="k">end</span>
|
|
<span class="k">end</span>,
|
|
on_match: <span class="o">-></span>(file : <span class="t">String</span>) <span class="k">do</span>
|
|
<span class="t">::</span><span class="t">MyModule</span><span class="t">::</span><span class="t">MY_ARRAY</span> <span class="o"><<</span> file
|
|
<span class="k">end</span>
|
|
)
|
|
<span class="k">end</span></code></pre>
|
|
<p>For more detailed documentation please visit the wiki in the repo. All topics are covered there in much greater detail than inline documentation here</p>
|
|
</div>
|
|
|
|
<br/>
|
|
<div>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<div class="entry-detail" id="override_help_template(filepath)-macro">
|
|
<div class="signature">
|
|
|
|
macro <strong>override_help_template</strong>(filepath)
|
|
|
|
<a class="method-permalink" href="#override_help_template%28filepath%29-macro">#</a>
|
|
</div>
|
|
|
|
<br/>
|
|
<div>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</div>
|
|
|
|
</body>
|
|
</html>
|