tristan/cligen
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Committing before help rework

Browse Source
This commit is contained in:
Tristan Ancelet
2026-09-05 13:19:55 -05:00
parent 4cce5cc45c
commit 3fa77f5707
105 changed files with 22505 additions and 684 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/CliGen/Argument.html
+345 -8
View File
@@ -62,11 +62,6 @@
<ul>
<li class=" " data-id="CliGenerator/CliGen/AdditionalDefaultFlag" data-name="cligen::additionaldefaultflag">
<a href="../CliGen/AdditionalDefaultFlag.html">AdditionalDefaultFlag</a>
</li>
<li class=" " data-id="CliGenerator/CliGen/App" data-name="cligen::app">
<a href="../CliGen/App.html">App</a>
@@ -77,16 +72,31 @@
</li>
<li class=" " data-id="CliGenerator/CliGen/ArgReprocessedError" data-name="cligen::argreprocessederror">
<a href="../CliGen/ArgReprocessedError.html">ArgReprocessedError</a>
</li>
<li class=" current" 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>
@@ -97,13 +107,33 @@
</li>
<li class=" " data-id="CliGenerator/CliGen/CommandNode" data-name="cligen::commandnode">
<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/DefaultFlag" data-name="cligen::defaultflag">
<a href="../CliGen/DefaultFlag.html">DefaultFlag</a>
<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>
@@ -112,16 +142,86 @@
</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/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>
@@ -132,6 +232,26 @@
</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/Selection" data-name="cligen::selection">
<a href="../CliGen/Selection.html">Selection</a>
@@ -142,11 +262,56 @@
</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>
@@ -171,6 +336,178 @@
<h2>
<a id="overview" class="anchor" href="#overview">
<svg class="octicon-link" aria-hidden="true">
<use href="#octicon-link"/>
</svg>
</a>
Overview
</h2>
<p>This is used for annotating instance variables for the CliGen framework can know how to create your <code><a href="../CliGen/Flag.html">CliGen::Flag</a>(T)</code> objects</p>
<p>WHILE this is usually being handled by the <code><a href="../CliGen/Command.html#argument%28variable%2Cdescription%2Clong%3Dnil%2Cshort%3Dnil%2Cvalidation%3Dnil%2Con_match%3Dnil%2Cdef_setter%3Dfalse%2Cdef_getter%3Dfalse%2Coptions%3Dnil%2Cdelimiter%3D%22%2C%22%2Cformat%3Dnil%2Callow_no_verification%3Dfalse%2Cenv_var%3Dnil%29-macro">CliGen::Command.argument</a></code> macro
inside of the class body.</p>
<p>EX:</p>
<pre><code class="language-crystal"><span class="k">class</span> <span class="t">MyCmd</span> <span class="o">&lt;</span> <span class="t">CliGen</span><span class="t">::</span><span class="t">Command</span>
argument(myvar : <span class="t">String</span> <span class="o">=</span> <span class="s">&quot;test&quot;</span>,
short: <span class="s">&quot;-m&quot;</span>,
long: <span class="s">&quot;--myvar&quot;</span>,
description: <span class="s">&quot;This is my test flag&quot;</span>,
options: <span class="s">%w[ test test2 test3 ]</span>
)
<span class="k">def</span> <span class="m">main</span>
puts <span class="s">&quot;@myvar was </span><span class="i">#{</span>@myvar<span class="i">}</span><span class="s">&quot;</span>
<span class="k">end</span>
<span class="k">end</span></code></pre>
<p>However, this can also be done manually if you don't want to use the macros
you will make me sad, but otherwise it's understandable if you want do it
manually. Just understand that the macros are there for doing all of the
validations for user-friendly implementation.</p>
<h2><a id="expected-metadata" class="anchor" href="#expected-metadata">
<svg class="octicon-link" aria-hidden="true">
<use href="#octicon-link"/>
</svg>
</a>Expected Metadata:</h2>
<h3><a id="short" class="anchor" href="#short">
<svg class="octicon-link" aria-hidden="true">
<use href="#octicon-link"/>
</svg>
</a>short:</h3>
<p>Type: StringLiteral</p>
<p>Required: false</p>
<p>This represents the short form of the flag bring provided. it is optional as
not all flags have to have a short form flag.</p>
<h3><a id="long" class="anchor" href="#long">
<svg class="octicon-link" aria-hidden="true">
<use href="#octicon-link"/>
</svg>
</a>long:</h3>
<p>Type: StringLiteral</p>
<p>Required: true</p>
<p>This represents the long-form of the flag. It is required in order to generate
the <code><a href="../CliGen/Flag.html">Flag</a>(T)</code>.</p>
<h3><a id="description" class="anchor" href="#description">
<svg class="octicon-link" aria-hidden="true">
<use href="#octicon-link"/>
</svg>
</a>description:</h3>
<p>Type: StringLiteral
Required: true</p>
<p>This is the description of your flag and is required for <code><a href="../CliGen/Flag.html">Flag</a>(T)</code> creation</p>
<h3><a id="delimiter" class="anchor" href="#delimiter">
<svg class="octicon-link" aria-hidden="true">
<use href="#octicon-link"/>
</svg>
</a>delimiter:</h3>
<p>Type: StringLiteral</p>
<p>Required: false</p>
<p>For <code><a href="../CliGen/Flag.html">Flag</a></code>(Array(T)) flags this is the delimiter that will seperate any inline
args (ex: &quot;,&quot; will split &quot;a,b,c&quot;) provided at the commandline. If nil/not
provided, the framework will default to ',' as this is the usual choice.</p>
<h3><a id="env-var" class="anchor" href="#env-var">
<svg class="octicon-link" aria-hidden="true">
<use href="#octicon-link"/>
</svg>
</a>env_var:</h3>
<p>Type: StringLiteral</p>
<p>Required: false</p>
<p>This is the ENV VAR that can be used to specify your flag value when not
provided by the user.</p>
<h3><a id="validation" class="anchor" href="#validation">
<svg class="octicon-link" aria-hidden="true">
<use href="#octicon-link"/>
</svg>
</a>validation:</h3>
<p>Type: ProcLiteral</p>
<p>Required: false</p>
<p>This is a proc that can be used to provide an ad-hoc way of verifying the
value provided by a user.</p>
<p>EX: Int Validator</p>
<pre><code class="language-crystal">validation: <span class="o">-&gt;</span>(i : <span class="t">Int32</span>) : <span class="t">Bool</span> <span class="k">do</span>
(<span class="n">1</span>..<span class="n">23</span>).includes?(i)
<span class="k">end</span></code></pre>
<p>This is used as a fallback to where the options: key doesn't cleanly
provide enough of a check for the provided values.</p>
<p>Note:
The input value MUST be the same as the value type as the instance
variable. Otherwise CliGen will not compile. IF requested I can
add a raw_validation: key as well to do the same but for just the
String variable provided by the user.</p>
<h3><a id="on-match" class="anchor" href="#on-match">
<svg class="octicon-link" aria-hidden="true">
<use href="#octicon-link"/>
</svg>
</a>on_match:</h3>
<p>Type: ProcLiteral</p>
<p>Required: false</p>
<p>Much like validation, this is used as a hook for doing arbitrary actions
with the parsed value from the user (very useful for global flags).</p>
<p>EX: Log level setter</p>
<pre><code class="language-crystal">on_match: <span class="o">-&gt;</span>(arg : <span class="t">String</span>) <span class="k">do</span>
<span class="k">begin</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(arg))
<span class="k">rescue</span> e : <span class="t">ArgumentError</span>
<span class="t">STDERR</span>.puts <span class="s">&quot;ERROR : Failed to set to </span><span class="i">#{</span>arg<span class="i">}</span><span class="s"> log level: (</span><span class="i">#{</span>e.<span class="k">class</span><span class="i">}</span><span class="s">: </span><span class="i">#{</span>e.message<span class="i">}</span><span class="s">)&quot;</span>
<span class="k">end</span>
<span class="k">end</span></code></pre>
<p>In this way you can use on_match: to hook a global flag and have it call some
arbitrary method elsewhere in the codebase to help setup the environment
before the main command is run.</p>
<h3><a id="options" class="anchor" href="#options">
<svg class="octicon-link" aria-hidden="true">
<use href="#octicon-link"/>
</svg>
</a>options:</h3>
<p>Type: ArrayLiteral(T)|Call</p>
<p>Required: false</p>
<p>CURRENTLY this is being as a way of providing a static set of values that we
are to use when doing a provided argument.</p>
<p>EX: Options for string var</p>
<pre><code class="language-crystal">options: <span class="s">%w[ a b c ]</span></code></pre>
<p>Howver, this currently also
supports delegating the retrieval of values (in array format) to be learned
at runtime by providing a call to a global methods/class method/util
method/etc</p>
<p>EX: Deletgating to runtime</p>
<pre><code class="language-crystal"><span class="k">module</span> <span class="t">MyModule</span>
<span class="k">def</span> <span class="m">self</span>.my_method : <span class="t">Array</span>(<span class="t">String</span>)
<span class="k">if</span> <span class="t">File</span>.exists?(<span class="s">&quot;/etc/valid_things.txt&quot;</span>)
<span class="t">File</span>.read(<span class="s">&quot;/etc/valid_things.txt&quot;</span>).split(<span class="s">&quot;,&quot;</span>)
<span class="k">else</span>
<span class="s">%w[ a b c ]</span>
<span class="k">end</span>
<span class="k">end</span>
<span class="t">CliGen</span>.add_global_flag(<span class="t">String</span>,
short: <span class="s">&quot;-t&quot;</span>,
long: <span class="s">&quot;--test&quot;</span>,
description: <span class="s">&quot;This does things. I promise&quot;</span>,
options: <span class="t">::</span><span class="t">MyModule</span>.my_method,
on_match: <span class="o">-&gt;</span>(t : <span class="t">String</span>) <span class="k">do</span>
puts <span class="s">&quot;Matched </span><span class="i">#{</span>t<span class="i">}</span><span class="s">&quot;</span>
<span class="k">end</span>
)
<span class="k">end</span></code></pre>
<p>Doing things this way gives you some runtime flexibility, but makes you
responsible for ensuring that it doesn't crash or provide incorrect data
at runtime. As (unfortunately) the framework doesn't account for developer
error at runtime like it can at compile-time with a static array of
values.</p>
<h3><a id="format" class="anchor" href="#format">
<svg class="octicon-link" aria-hidden="true">
<use href="#octicon-link"/>
</svg>
</a>format:</h3>
<p>Type: RegexLiteral</p>
<p>Required: false</p>
<p>This metadata is used to provide (mostly for strings when you don't have a
statically known list of values that can be provided at runtime, but you
want to filter out invalid options.</p>
<p>EX: filtering for csv formatted info</p>
<pre><code class="language-crystal">format: <span class="s">/^([a-z0-9]+)(,?[a-z0-9]+)+$/</span></code></pre>