blob: 30703cbbba17829d2fc808f3bfd1cab4022a4bc4 [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!-- NewPage -->
<html lang="en">
<head>
<!-- Generated by javadoc (1.8.0_144) on Sat Apr 25 12:11:40 MST 2020 -->
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>CommandLine.Parameters (Apache Log4j Core 2.13.2 API)</title>
<meta name="date" content="2020-04-25">
<link rel="stylesheet" type="text/css" href="../../../../../../../stylesheet.css" title="Style">
<script type="text/javascript" src="../../../../../../../script.js"></script>
</head>
<body>
<script type="text/javascript"><!--
try {
if (location.href.indexOf('is-external=true') == -1) {
parent.document.title="CommandLine.Parameters (Apache Log4j Core 2.13.2 API)";
}
}
catch(err) {
}
//-->
</script>
<noscript>
<div>JavaScript is disabled on your browser.</div>
</noscript>
<!-- ========= START OF TOP NAVBAR ======= -->
<div class="topNav"><a name="navbar.top">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.top" title="Skip navigation links">Skip navigation links</a></div>
<a name="navbar.top.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../../../../../overview-summary.html">Overview</a></li>
<li><a href="package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</li>
<li><a href="class-use/CommandLine.Parameters.html">Use</a></li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../../../../../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../../../../../../index-all.html">Index</a></li>
<li><a href="../../../../../../../help-doc.html">Help</a></li>
</ul>
</div>
<div class="subNav">
<ul class="navList">
<li><a href="../../../../../../../org/apache/logging/log4j/core/tools/picocli/CommandLine.ParameterIndexGapException.html" title="class in org.apache.logging.log4j.core.tools.picocli"><span class="typeNameLink">Prev&nbsp;Class</span></a></li>
<li><a href="../../../../../../../org/apache/logging/log4j/core/tools/picocli/CommandLine.PicocliException.html" title="class in org.apache.logging.log4j.core.tools.picocli"><span class="typeNameLink">Next&nbsp;Class</span></a></li>
</ul>
<ul class="navList">
<li><a href="../../../../../../../index.html?org/apache/logging/log4j/core/tools/picocli/CommandLine.Parameters.html" target="_top">Frames</a></li>
<li><a href="CommandLine.Parameters.html" target="_top">No&nbsp;Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_top">
<li><a href="../../../../../../../allclasses-noframe.html">All&nbsp;Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_top");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<div>
<ul class="subNavList">
<li>Summary:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Required&nbsp;|&nbsp;</li>
<li><a href="#annotation.type.optional.element.summary">Optional</a></li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li><a href="#annotation.type.element.detail">Element</a></li>
</ul>
</div>
<a name="skip.navbar.top">
<!-- -->
</a></div>
<!-- ========= END OF TOP NAVBAR ========= -->
<!-- ======== START OF CLASS DATA ======== -->
<div class="header">
<div class="subTitle">org.apache.logging.log4j.core.tools.picocli</div>
<h2 title="Annotation Type CommandLine.Parameters" class="title">Annotation Type CommandLine.Parameters</h2>
</div>
<div class="contentContainer">
<div class="description">
<ul class="blockList">
<li class="blockList">
<hr>
<br>
<pre><a href="https://docs.oracle.com/javase/8/docs/api/java/lang/annotation/Retention.html?is-external=true" title="class or interface in java.lang.annotation">@Retention</a>(<a href="https://docs.oracle.com/javase/8/docs/api/java/lang/annotation/Retention.html?is-external=true#value--" title="class or interface in java.lang.annotation">value</a>=<a href="https://docs.oracle.com/javase/8/docs/api/java/lang/annotation/RetentionPolicy.html?is-external=true#RUNTIME" title="class or interface in java.lang.annotation">RUNTIME</a>)
<a href="https://docs.oracle.com/javase/8/docs/api/java/lang/annotation/Target.html?is-external=true" title="class or interface in java.lang.annotation">@Target</a>(<a href="https://docs.oracle.com/javase/8/docs/api/java/lang/annotation/Target.html?is-external=true#value--" title="class or interface in java.lang.annotation">value</a>=<a href="https://docs.oracle.com/javase/8/docs/api/java/lang/annotation/ElementType.html?is-external=true#FIELD" title="class or interface in java.lang.annotation">FIELD</a>)
public static @interface <a href="../../../../../../../src-html/org/apache/logging/log4j/core/tools/picocli/CommandLine.html#line.1347">CommandLine.Parameters</a></pre>
<div class="block"><p>
Fields annotated with <code>@Parameters</code> will be initialized with positional parameters. By specifying the
<a href="../../../../../../../org/apache/logging/log4j/core/tools/picocli/CommandLine.Parameters.html#index--"><code>index()</code></a> attribute you can pick which (or what range) of the positional parameters to apply. If no index
is specified, the field will get all positional parameters (so it should be an array or a collection).
</p><p>
When parsing the command line arguments, picocli first tries to match arguments to <a href="../../../../../../../org/apache/logging/log4j/core/tools/picocli/CommandLine.Option.html" title="annotation in org.apache.logging.log4j.core.tools.picocli"><code>Options</code></a>.
Positional parameters are the arguments that follow the options, or the arguments that follow a "--" (double
dash) argument on the command line.
</p><p>
For example:
</p>
<pre>import static picocli.CommandLine.*;
public class MyCalcParameters {
&#064;Parameters(type = BigDecimal.class, description = "Any number of input numbers")
private List&lt;BigDecimal&gt; files = new ArrayList&lt;BigDecimal&gt;();
&#064;Option(names = { "-h", "--help", "-?", "-help"}, help = true, description = "Display this help and exit")
private boolean help;
}
</pre><p>
A field cannot be annotated with both <code>@Parameters</code> and <code>@Option</code> or a <code>ParameterException</code>
is thrown.</p></div>
</li>
</ul>
</div>
<div class="summary">
<ul class="blockList">
<li class="blockList">
<!-- =========== ANNOTATION TYPE OPTIONAL MEMBER SUMMARY =========== -->
<ul class="blockList">
<li class="blockList"><a name="annotation.type.optional.element.summary">
<!-- -->
</a>
<h3>Optional Element Summary</h3>
<table class="memberSummary" border="0" cellpadding="3" cellspacing="0" summary="Optional Element Summary table, listing optional elements, and an explanation">
<caption><span>Optional Elements</span><span class="tabEnd">&nbsp;</span></caption>
<tr>
<th class="colFirst" scope="col">Modifier and Type</th>
<th class="colLast" scope="col">Optional Element and Description</th>
</tr>
<tr class="altColor">
<td class="colFirst"><code><a href="https://docs.oracle.com/javase/8/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a></code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../../../../org/apache/logging/log4j/core/tools/picocli/CommandLine.Parameters.html#arity--">arity</a></span></code>
<div class="block">Specifies the minimum number of required parameters and the maximum number of accepted parameters.</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><code><a href="https://docs.oracle.com/javase/8/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a>[]</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../../../../org/apache/logging/log4j/core/tools/picocli/CommandLine.Parameters.html#description--">description</a></span></code>
<div class="block">Description of the parameter(s), used when generating the usage documentation.</div>
</td>
</tr>
<tr class="altColor">
<td class="colFirst"><code>boolean</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../../../../org/apache/logging/log4j/core/tools/picocli/CommandLine.Parameters.html#hidden--">hidden</a></span></code>
<div class="block">Set <code>hidden=true</code> if this parameter should not be included in the usage message.</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><code><a href="https://docs.oracle.com/javase/8/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a></code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../../../../org/apache/logging/log4j/core/tools/picocli/CommandLine.Parameters.html#index--">index</a></span></code>
<div class="block">Specify an index ("0", or "1", etc.) to pick which of the command line arguments should be assigned to this
field.</div>
</td>
</tr>
<tr class="altColor">
<td class="colFirst"><code><a href="https://docs.oracle.com/javase/8/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a></code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../../../../org/apache/logging/log4j/core/tools/picocli/CommandLine.Parameters.html#paramLabel--">paramLabel</a></span></code>
<div class="block">Specify a <code>paramLabel</code> for the parameter to be used in the usage help message.</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><code><a href="https://docs.oracle.com/javase/8/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a></code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../../../../org/apache/logging/log4j/core/tools/picocli/CommandLine.Parameters.html#split--">split</a></span></code>
<div class="block">Specify a regular expression to use to split positional parameter values before applying them to the field.</div>
</td>
</tr>
<tr class="altColor">
<td class="colFirst"><code><a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Class.html?is-external=true" title="class or interface in java.lang">Class</a>&lt;?&gt;[]</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../../../../org/apache/logging/log4j/core/tools/picocli/CommandLine.Parameters.html#type--">type</a></span></code>
<div class="block">
Optionally specify a <code>type</code> to control exactly what Class the positional parameter should be converted
to.</div>
</td>
</tr>
</table>
</li>
</ul>
</li>
</ul>
</div>
<div class="details">
<ul class="blockList">
<li class="blockList">
<!-- ============ ANNOTATION TYPE MEMBER DETAIL =========== -->
<ul class="blockList">
<li class="blockList"><a name="annotation.type.element.detail">
<!-- -->
</a>
<h3>Element Detail</h3>
<a name="index--">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>index</h4>
<pre>public abstract&nbsp;<a href="https://docs.oracle.com/javase/8/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a>&nbsp;<a href="../../../../../../../src-html/org/apache/logging/log4j/core/tools/picocli/CommandLine.Parameters.html#line.1353">index</a></pre>
<div class="block">Specify an index ("0", or "1", etc.) to pick which of the command line arguments should be assigned to this
field. For array or Collection fields, you can also specify an index range ("0..3", or "2..*", etc.) to assign
a subset of the command line arguments to this field. The default is "*", meaning all command line arguments.</div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>an index or range specifying which of the command line arguments should be assigned to this field</dd>
</dl>
<dl>
<dt>Default:</dt>
<dd>"*"</dd>
</dl>
</li>
</ul>
</li>
</ul>
<ul class="blockList">
<li class="blockList"><a name="description--">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>description</h4>
<pre>public abstract&nbsp;<a href="https://docs.oracle.com/javase/8/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a>[]&nbsp;<a href="../../../../../../../src-html/org/apache/logging/log4j/core/tools/picocli/CommandLine.Parameters.html#line.1358">description</a></pre>
<div class="block">Description of the parameter(s), used when generating the usage documentation.</div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the description of the parameter(s)</dd>
</dl>
<dl>
<dt>Default:</dt>
<dd>{}</dd>
</dl>
</li>
</ul>
</li>
</ul>
<ul class="blockList">
<li class="blockList"><a name="arity--">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>arity</h4>
<pre>public abstract&nbsp;<a href="https://docs.oracle.com/javase/8/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a>&nbsp;<a href="../../../../../../../src-html/org/apache/logging/log4j/core/tools/picocli/CommandLine.Parameters.html#line.1368">arity</a></pre>
<div class="block">Specifies the minimum number of required parameters and the maximum number of accepted parameters. If a
positive arity is declared, and the user specifies an insufficient number of parameters on the command line,
<a href="../../../../../../../org/apache/logging/log4j/core/tools/picocli/CommandLine.MissingParameterException.html" title="class in org.apache.logging.log4j.core.tools.picocli"><code>CommandLine.MissingParameterException</code></a> is thrown by the <a href="../../../../../../../org/apache/logging/log4j/core/tools/picocli/CommandLine.html#parse-java.lang.String...-"><code>CommandLine.parse(String...)</code></a> method.
<p>The default depends on the type of the parameter: booleans require no parameters, arrays and Collections
accept zero to any number of parameters, and any other type accepts one parameter.</p></div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the range of minimum and maximum parameters accepted by this command</dd>
</dl>
<dl>
<dt>Default:</dt>
<dd>""</dd>
</dl>
</li>
</ul>
</li>
</ul>
<ul class="blockList">
<li class="blockList"><a name="paramLabel--">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>paramLabel</h4>
<pre>public abstract&nbsp;<a href="https://docs.oracle.com/javase/8/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a>&nbsp;<a href="../../../../../../../src-html/org/apache/logging/log4j/core/tools/picocli/CommandLine.Parameters.html#line.1383">paramLabel</a></pre>
<div class="block">Specify a <code>paramLabel</code> for the parameter to be used in the usage help message. If omitted,
picocli uses the field name in fish brackets (<code>'&lt;'</code> and <code>'&gt;'</code>) by default. Example:
<pre>class Example {
&#064;Parameters(paramLabel="FILE", description="path of the input FILE(s)")
private File[] inputFiles;
}</pre>
<p>By default, the above gives a usage help message like the following:</p><pre>
Usage: &lt;main class&gt; [FILE...]
[FILE...] path of the input FILE(s)
</pre></div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>name of the positional parameter used in the usage help message</dd>
</dl>
<dl>
<dt>Default:</dt>
<dd>""</dd>
</dl>
</li>
</ul>
</li>
</ul>
<ul class="blockList">
<li class="blockList"><a name="type--">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>type</h4>
<pre>public abstract&nbsp;<a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Class.html?is-external=true" title="class or interface in java.lang">Class</a>&lt;?&gt;[]&nbsp;<a href="../../../../../../../src-html/org/apache/logging/log4j/core/tools/picocli/CommandLine.Parameters.html#line.1413">type</a></pre>
<div class="block"><p>
Optionally specify a <code>type</code> to control exactly what Class the positional parameter should be converted
to. This may be useful when the field type is an interface or an abstract class. For example, a field can
be declared to have type <code>java.lang.Number</code>, and annotating <code>@Parameters(type=Short.class)</code>
ensures that the positional parameter value is converted to a <code>Short</code> before setting the field value.
</p><p>
For array fields whose <em>component</em> type is an interface or abstract class, specify the concrete <em>component</em> type.
For example, a field with type <code>Number[]</code> may be annotated with <code>@Parameters(type=Short.class)</code>
to ensure that positional parameter values are converted to <code>Short</code> before adding an element to the array.
</p><p>
Picocli will use the <a href="../../../../../../../org/apache/logging/log4j/core/tools/picocli/CommandLine.ITypeConverter.html" title="interface in org.apache.logging.log4j.core.tools.picocli"><code>CommandLine.ITypeConverter</code></a> that is
<a href="../../../../../../../org/apache/logging/log4j/core/tools/picocli/CommandLine.html#registerConverter-java.lang.Class-org.apache.logging.log4j.core.tools.picocli.CommandLine.ITypeConverter-">registered</a> for the specified type to convert
the raw String values before modifying the field value.
</p><p>
Prior to 2.0, the <code>type</code> attribute was necessary for <code>Collection</code> and <code>Map</code> fields,
but starting from 2.0 picocli will infer the component type from the generic type's type arguments.
For example, for a field of type <code>Map&lt;TimeUnit, Long&gt;</code> picocli will know the positional parameter
should be split up in key=value pairs, where the key should be converted to a <code>java.util.concurrent.TimeUnit</code>
enum value, and the value should be converted to a <code>Long</code>. No <code>@Parameters(type=...)</code> type attribute
is required for this. For generic types with wildcards, picocli will take the specified upper or lower bound
as the Class to convert to, unless the <code>@Parameters</code> annotation specifies an explicit <code>type</code> attribute.
</p><p>
If the field type is a raw collection or a raw map, and you want it to contain other values than Strings,
or if the generic type's type arguments are interfaces or abstract classes, you may
specify a <code>type</code> attribute to control the Class that the positional parameter should be converted to.</div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the type(s) to convert the raw String values</dd>
</dl>
<dl>
<dt>Default:</dt>
<dd>{}</dd>
</dl>
</li>
</ul>
</li>
</ul>
<ul class="blockList">
<li class="blockList"><a name="split--">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>split</h4>
<pre>public abstract&nbsp;<a href="https://docs.oracle.com/javase/8/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a>&nbsp;<a href="../../../../../../../src-html/org/apache/logging/log4j/core/tools/picocli/CommandLine.Parameters.html#line.1421">split</a></pre>
<div class="block">Specify a regular expression to use to split positional parameter values before applying them to the field.
All elements resulting from the split are added to the array or Collection. Ignored for single-value fields.</div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>a regular expression to split operand values or <code>""</code> if the value should not be split</dd>
<dt><span class="seeLabel">See Also:</span></dt>
<dd><a href="https://docs.oracle.com/javase/8/docs/api/java/lang/String.html?is-external=true#split-java.lang.String-" title="class or interface in java.lang"><code>String.split(String)</code></a></dd>
</dl>
<dl>
<dt>Default:</dt>
<dd>""</dd>
</dl>
</li>
</ul>
</li>
</ul>
<ul class="blockList">
<li class="blockList"><a name="hidden--">
<!-- -->
</a>
<ul class="blockListLast">
<li class="blockList">
<h4>hidden</h4>
<pre>public abstract&nbsp;boolean&nbsp;<a href="../../../../../../../src-html/org/apache/logging/log4j/core/tools/picocli/CommandLine.Parameters.html#line.1427">hidden</a></pre>
<div class="block">Set <code>hidden=true</code> if this parameter should not be included in the usage message.</div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>whether this parameter should be excluded from the usage message</dd>
</dl>
<dl>
<dt>Default:</dt>
<dd>false</dd>
</dl>
</li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div>
<!-- ========= END OF CLASS DATA ========= -->
<!-- ======= START OF BOTTOM NAVBAR ====== -->
<div class="bottomNav"><a name="navbar.bottom">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.bottom" title="Skip navigation links">Skip navigation links</a></div>
<a name="navbar.bottom.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../../../../../overview-summary.html">Overview</a></li>
<li><a href="package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</li>
<li><a href="class-use/CommandLine.Parameters.html">Use</a></li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../../../../../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../../../../../../index-all.html">Index</a></li>
<li><a href="../../../../../../../help-doc.html">Help</a></li>
</ul>
</div>
<div class="subNav">
<ul class="navList">
<li><a href="../../../../../../../org/apache/logging/log4j/core/tools/picocli/CommandLine.ParameterIndexGapException.html" title="class in org.apache.logging.log4j.core.tools.picocli"><span class="typeNameLink">Prev&nbsp;Class</span></a></li>
<li><a href="../../../../../../../org/apache/logging/log4j/core/tools/picocli/CommandLine.PicocliException.html" title="class in org.apache.logging.log4j.core.tools.picocli"><span class="typeNameLink">Next&nbsp;Class</span></a></li>
</ul>
<ul class="navList">
<li><a href="../../../../../../../index.html?org/apache/logging/log4j/core/tools/picocli/CommandLine.Parameters.html" target="_top">Frames</a></li>
<li><a href="CommandLine.Parameters.html" target="_top">No&nbsp;Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_bottom">
<li><a href="../../../../../../../allclasses-noframe.html">All&nbsp;Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_bottom");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<div>
<ul class="subNavList">
<li>Summary:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li>Required&nbsp;|&nbsp;</li>
<li><a href="#annotation.type.optional.element.summary">Optional</a></li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li><a href="#annotation.type.element.detail">Element</a></li>
</ul>
</div>
<a name="skip.navbar.bottom">
<!-- -->
</a></div>
<!-- ======== END OF BOTTOM NAVBAR ======= -->
<p class="legalCopy"><small><p align="center">Copyright &#169; 1999-2020 <a href="https://www.apache.org/">The Apache Software Foundation</a>. All Rights Reserved.<br /> Apache Logging, Apache Log4j, Log4j, Apache, the Apache feather logo, the Apache Logging project logo, and the Apache Log4j logo are trademarks of The Apache Software Foundation.</p></small></p>
</body>
</html>