Skip to content

Commit

Permalink
Revert "[remkop#1307][remkop#1308] DOC: update rendered HTML, RELEASE…
Browse files Browse the repository at this point in the history 
…-NOTES"

This reverts commit 7498040.
  • Loading branch information
@MarkoMackic
MarkoMackic committed Oct 17, 2021
1 parent 02c38a0 commit df0498c
Show file tree
Hide file tree
Showing 2 changed files with 25 additions and 91 deletions.
1 change: 0 additions & 1 deletion RELEASE-NOTES.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,6 @@ Picocli follows [semantic versioning](http://semver.org/).
* [#1304] DOC: Manual, chapter '17.9 Inherited Command Attributes': added Kotlin version of code sample. Thanks to [Andreas Deininger](https://github.com/deining) for the pull request.
* [#1305] DOC: Document use of `IParameterConsumer` as n-ary type converter. Thanks to [Martin](https://github.com/martlin2cz) for raising this.
* [#1307] DOC: Added CAUTION admonitions, Kotlin code sample. Thanks to [Andreas Deininger](https://github.com/deining) for the pull request.
* [#1308] DOC: Add example for Option `converter`.

## <a name="4.6.2-deprecated"></a> Deprecations
No features were deprecated in this release.
Expand Down
115 changes: 25 additions & 90 deletions docs/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3629,44 +3629,39 @@ <h4 id="_single_parameter_type_converters"><a class="anchor" href="#_single_para
</div>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="java"><span class="kn">import</span> <span class="nn">javax.crypto.Cipher</span><span class="o">;</span>

<span class="kd">class</span> <span class="nc">CipherConverter</span> <span class="kd">implements</span> <span class="nc">ITypeConverter</span><span class="o">&lt;</span><span class="nc">Cipher</span><span class="o">&gt;</span> <span class="o">{</span>
<span class="kd">public</span> <span class="nc">Cipher</span> <span class="nf">convert</span><span class="o">(</span><span class="nc">String</span> <span class="n">value</span><span class="o">)</span> <span class="kd">throws</span> <span class="nc">Exception</span> <span class="o">{</span>
<span class="k">return</span> <span class="nc">Cipher</span><span class="o">.</span><span class="na">getInstance</span><span class="o">(</span><span class="n">value</span><span class="o">);</span>
<span class="o">}</span>
<span class="o">}</span></code></pre>
</div>
<p>Custom type converters can be registered with the <code>CommandLine.registerConverter(Class&lt;K&gt; cls, ITypeConverter&lt;K&gt; converter)</code> method. All options and positional parameters with the specified type will be converted by the specified converter.</p>
</div>
<div class="paragraph">
<p>Custom type converters can be specified for a specific option or positional parameter with the <code>converter</code> annotation attribute.
This is described in more detail in the <a href="#_option_specific_type_converters">Option-specific Type Converters</a> section, but here is a quick example:</p>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Java 8 lambdas make it easy to register custom converters:
</td>
</tr>
</table>
</div>
<div class="listingblock primary">
<div class="title">Java</div>
<div class="content">
<pre class="rouge highlight"><code data-lang="java"><span class="kd">class</span> <span class="nc">App</span> <span class="o">{</span>
<span class="nd">@Option</span><span class="o">(</span><span class="n">names</span> <span class="o">=</span> <span class="s">"-a"</span><span class="o">,</span> <span class="n">converter</span> <span class="o">=</span> <span class="nc">CipherConverter</span><span class="o">.</span><span class="na">class</span><span class="o">)</span>
<span class="n">javax</span><span class="o">.</span><span class="na">crypto</span><span class="o">.</span><span class="na">Cipher</span> <span class="n">cipher</span><span class="o">;</span>
<span class="o">}</span></code></pre>
<pre class="rouge highlight"><code data-lang="java"><span class="nc">CommandLine</span> <span class="n">cl</span> <span class="o">=</span> <span class="k">new</span> <span class="nc">CommandLine</span><span class="o">(</span><span class="n">app</span><span class="o">);</span>
<span class="n">cl</span><span class="o">.</span><span class="na">registerConverter</span><span class="o">(</span><span class="nc">Locale</span><span class="o">.</span><span class="na">class</span><span class="o">,</span> <span class="n">s</span> <span class="o">-&gt;</span> <span class="k">new</span> <span class="nc">Locale</span><span class="o">.</span><span class="na">Builder</span><span class="o">().</span><span class="na">setLanguageTag</span><span class="o">(</span><span class="n">s</span><span class="o">).</span><span class="na">build</span><span class="o">());</span>
<span class="n">cl</span><span class="o">.</span><span class="na">registerConverter</span><span class="o">(</span><span class="nc">Cipher</span><span class="o">.</span><span class="na">class</span><span class="o">,</span> <span class="n">s</span> <span class="o">-&gt;</span> <span class="nc">Cipher</span><span class="o">.</span><span class="na">getInstance</span><span class="o">(</span><span class="n">s</span><span class="o">));</span></code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">Kotlin</div>
<div class="content">
<pre class="rouge highlight"><code data-lang="kotlin"><span class="kd">class</span> <span class="nc">App</span> <span class="p">{</span>
<span class="nd">@Option</span><span class="p">(</span><span class="n">names</span> <span class="p">=</span> <span class="p">[</span><span class="s">"-a"</span><span class="p">],</span> <span class="n">converter</span> <span class="p">=</span> <span class="p">[</span><span class="nc">CipherConverter</span><span class="o">::</span><span class="k">class</span><span class="p">])</span>
<span class="k">lateinit</span> <span class="kd">var</span> <span class="py">cipher</span><span class="p">:</span> <span class="n">javax</span><span class="p">.</span><span class="n">crypto</span><span class="p">.</span><span class="nc">Cipher</span>
<span class="p">}</span></code></pre>
</div>
<pre class="rouge highlight"><code data-lang="java"><span class="n">val</span> <span class="n">cl</span> <span class="o">=</span> <span class="nc">CommandLine</span><span class="o">(</span><span class="n">app</span><span class="o">)</span>
<span class="n">cl</span><span class="o">.</span><span class="na">registerConverter</span><span class="o">(</span><span class="nl">Locale:</span><span class="o">:</span><span class="kd">class</span><span class="err">.</span><span class="nc">java</span><span class="o">)</span> <span class="o">{</span>
<span class="nl">s:</span> <span class="nc">String</span><span class="o">?</span> <span class="o">-&gt;</span> <span class="nc">Locale</span><span class="o">.</span><span class="na">Builder</span><span class="o">().</span><span class="na">setLanguageTag</span><span class="o">(</span><span class="n">s</span><span class="o">).</span><span class="na">build</span><span class="o">()</span>
<span class="o">}</span>
<span class="n">cl</span><span class="o">.</span><span class="na">registerConverter</span><span class="o">(</span><span class="nl">Cipher:</span><span class="o">:</span><span class="kd">class</span><span class="err">.</span><span class="nc">java</span><span class="o">)</span> <span class="o">{</span>
<span class="nc">Cipher</span><span class="o">.</span><span class="na">getInstance</span><span class="o">(</span><span class="n">it</span><span class="o">)</span>
<span class="o">}</span></code></pre>
</div>
<div class="paragraph">
<p>Alternatively, custom type converters can be registered <em>per type</em> in each command with the <code>CommandLine.registerConverter(Class&lt;K&gt; cls, ITypeConverter&lt;K&gt; converter)</code> method.
All options and positional parameters with the specified type will be converted by the specified converter.</p>
</div>
<div class="paragraph">
<p>After registering custom converters, call the <code>execute(String&#8230;&#8203;)</code> or <code>parseArgs(String&#8230;&#8203;)</code> method on the <code>CommandLine</code> instance where the converters are registered. (The static <code>populateCommand</code> method cannot be used.) For example:</p>
Expand Down Expand Up @@ -3696,18 +3691,6 @@ <h4 id="_single_parameter_type_converters"><a class="anchor" href="#_single_para
<span class="p">}</span></code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Java 8 lambdas make it easy to register custom converters:
</td>
</tr>
</table>
</div>
<div class="listingblock primary">
<div class="title">Java</div>
<div class="content">
Expand Down Expand Up @@ -3784,30 +3767,6 @@ <h4 id="_multi_parameter_type_converters"><a class="anchor" href="#_multi_parame
<span class="o">}</span></code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">Kotlin</div>
<div class="content">
<pre class="rouge highlight"><code data-lang="kotlin"><span class="nd">@Command</span><span class="p">(</span><span class="n">name</span> <span class="p">=</span> <span class="s">"set-position"</span><span class="p">)</span>
<span class="kd">class</span> <span class="nc">SetPositionCommand</span> <span class="p">{</span>
<span class="nd">@Parameters</span><span class="p">(</span><span class="n">parameterConsumer</span> <span class="p">=</span> <span class="nc">PointConverter</span><span class="o">::</span><span class="k">class</span><span class="p">)</span>
<span class="k">private</span> <span class="k">lateinit</span> <span class="kd">var</span> <span class="py">position</span><span class="p">:</span> <span class="nc">Point</span>

<span class="kd">class</span> <span class="nc">PointConverter</span> <span class="p">:</span> <span class="nc">IParameterConsumer</span> <span class="p">{</span>
<span class="k">override</span> <span class="k">fun</span> <span class="nf">consumeParameters</span><span class="p">(</span><span class="n">args</span><span class="p">:</span> <span class="nc">Stack</span><span class="p">&lt;</span><span class="nc">String</span><span class="p">&gt;,</span>
<span class="n">argSpec</span><span class="p">:</span> <span class="nc">ArgSpec</span><span class="p">,</span>
<span class="n">commandSpec</span><span class="p">:</span> <span class="nc">CommandSpec</span><span class="p">)</span> <span class="p">{</span>
<span class="k">if</span> <span class="p">(</span><span class="n">args</span><span class="p">.</span><span class="n">size</span> <span class="p">&lt;</span> <span class="mi">2</span><span class="p">)</span> <span class="p">{</span>
<span class="k">throw</span> <span class="nc">ParameterException</span><span class="p">(</span><span class="n">commandSpec</span><span class="p">.</span><span class="nf">commandLine</span><span class="p">(),</span>
<span class="s">"Missing coordinates for Point. Please specify 2 coordinates."</span><span class="p">)</span>
<span class="p">}</span>
<span class="kd">val</span> <span class="py">x</span> <span class="p">=</span> <span class="n">args</span><span class="p">.</span><span class="nf">pop</span><span class="p">().</span><span class="nf">toInt</span><span class="p">()</span>
<span class="kd">val</span> <span class="py">y</span> <span class="p">=</span> <span class="n">args</span><span class="p">.</span><span class="nf">pop</span><span class="p">().</span><span class="nf">toInt</span><span class="p">()</span>
<span class="n">argSpec</span><span class="p">.</span><span class="nf">setValue</span><span class="p">(</span><span class="nc">Point</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">))</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>See the sections on <a href="#_custom_parameter_processing">Custom Parameter Processing</a> for more details.</p>
</div>
Expand Down Expand Up @@ -3966,18 +3925,6 @@ <h3 id="_option_specific_type_converters"><a class="anchor" href="#_option_speci
<div class="paragraph">
<p>Type converters declared with the <code>converter</code> attribute need to have a public no-argument constructor to be instantiated, unless a <a href="#_custom_factory">Custom Factory</a> is installed to instantiate classes.</p>
</div>
<div class="admonitionblock caution">
<table>
<tr>
<td class="icon">
<i class="fa icon-caution" title="Caution"></i>
</td>
<td class="content">
If your type converter is declared as nested class, make sure you mark this class as <code>static</code>, or picocli will not be able to instantiate your nested converter class without a <a href="#_custom_factory">Custom Factory</a>.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="_arrays_collections_maps"><a class="anchor" href="#_arrays_collections_maps"></a>4.5. Arrays, Collections, Maps</h3>
Expand Down Expand Up @@ -12036,7 +11983,7 @@ <h3 id="_inherited_command_attributes"><a class="anchor" href="#_inherited_comma
<span class="n">description</span> <span class="p">=</span> <span class="p">[</span><span class="s">"App description"</span><span class="p">],</span>
<span class="n">footerHeading</span> <span class="p">=</span> <span class="s">"Copyright%n"</span><span class="p">,</span> <span class="n">footer</span> <span class="p">=</span> <span class="p">[</span><span class="s">"(c) Copyright by the authors"</span><span class="p">],</span>
<span class="n">showAtFileInUsageHelp</span> <span class="p">=</span> <span class="k">true</span><span class="p">)</span>
<span class="kd">class</span> <span class="nc">App</span> <span class="p">:</span> <span class="nc">Runnable</span> <span class="p">{</span>
<span class="kd">class</span> <span class="nc">AppKt</span> <span class="p">:</span> <span class="nc">Runnable</span> <span class="p">{</span>
<span class="nd">@Option</span><span class="p">(</span><span class="n">names</span> <span class="p">=</span> <span class="p">[</span><span class="s">"-x"</span><span class="p">])</span> <span class="kd">var</span> <span class="py">x</span> <span class="p">=</span> <span class="mi">0</span>

<span class="k">override</span> <span class="k">fun</span> <span class="nf">run</span><span class="p">()</span> <span class="p">{</span> <span class="nf">println</span><span class="p">(</span><span class="s">"Hello from app!\nx = $x"</span><span class="p">)</span> <span class="p">}</span>
Expand Down Expand Up @@ -14841,18 +14788,6 @@ <h3 id="_model_transformations"><a class="anchor" href="#_model_transformations"
<div class="paragraph">
<p>All transformers are called once, after the full command hierarchy is constructed, and before any command line arguments are parsed.</p>
</div>
<div class="admonitionblock caution">
<table>
<tr>
<td class="icon">
<i class="fa icon-caution" title="Caution"></i>
</td>
<td class="content">
If your model transformer is declared as nested class, make sure you mark this class as <code>static</code>, or picocli will not be able to instantiate your transformer class without a <a href="#_custom_factory">Custom Factory</a>.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="_automatic_parameter_indexes"><a class="anchor" href="#_automatic_parameter_indexes"></a>21.7. Automatic Parameter Indexes</h3>
Expand Down Expand Up @@ -15550,7 +15485,7 @@ <h3 id="_spring_boot_example"><a class="anchor" href="#_spring_boot_example"></a
<p>This will bring in the <code>info.picocli:picocli</code> and the <code>info.picocli:picocli-spring-boot-starter</code> dependencies.</p>
</div>
<div class="paragraph">
<p>Now open the pre-authored source file <code>SpringBootDemoApplication.java</code>, rename it to <code>MySpringMailer.java</code> and edit and extend it so that it looks like this:</p>
<p>Now open the pre-authored source file <code>SpringBootDemoApplication.java</code>, rename it to MySpringMailer.java and edit and extend it so that it looks like this:</p>
</div>
<div class="listingblock primary">
<div class="title">Java</div>
Expand Down Expand Up @@ -15686,7 +15621,7 @@ <h3 id="_spring_boot_example"><a class="anchor" href="#_spring_boot_example"></a
<table>
<tr>
<td><i class="conum" data-value="1"></i><b>1</b></td>
<td>We annotate our command with the <code>@org.springframework.stereotype.Component</code> annotation so that Spring can autodetect it for dependency injection.</td>
<td>We annotate our command with the <code>@org.springframework.stereotype.Component</code> annontation so that Spring can autodetect it for dependency injection.</td>
</tr>
<tr>
<td><i class="conum" data-value="2"></i><b>2</b></td>
Expand Down

0 comments on commit df0498c

Please sign in to comment.