Skip to content

Commit

Permalink
[#615] added Format Specifiers section to the user manual; mention fo…
Browse files Browse the repository at this point in the history 
…rmat specifiers in javadoc for relevant @command, @option and @parameters annotation attributes

Closes #615
  • Loading branch information
@remkop
remkop committed Feb 1, 2019
1 parent 52e6fb8 commit 71204dc
Show file tree
Hide file tree
Showing 2 changed files with 54 additions and 28 deletions.
28 changes: 21 additions & 7 deletions docs/index.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1309,7 +1309,7 @@ The markup will be rendered as ANSI escape codes on supported systems.

image:VersionInfoWithColors.png[Screenshot of version information containing markup with Ansi styles and colors]

From picocli v1.0, the `version` may contain https://docs.oracle.com/javase/7/docs/api/java/util/Formatter.html[format specifiers]:
From picocli v1.0, the `version` may contain <<Format Specifiers,format specifiers>>:

[source,java]
----
Expand Down Expand Up @@ -1432,10 +1432,10 @@ Some annotated fields in the below example class have a `paramLabel` attribute a
----
@Command()
class ParamLabels {
@Option(names = "-f", paramLabel = "FILE", description = "a file") File f;
@Option(names = "-n", description = "a number option") int number;
@Parameters(index = "0", paramLabel = "NUM", description = "number param") int n;
@Parameters(index = "1", description = "the host parameter") InetAddress host;
@Option(names = "-f", description = "a file", paramLabel = "FILE") File f;
@Option(names = "-n", description = "a number option") int number;
@Parameters(index = "0", description = "number param", paramLabel = "NUM") int n;
@Parameters(index = "1", description = "the host parameter") InetAddress host;
}
----
NOTE: For demonstration purposes the above example mixes the all-uppercase (e.g., `NUM`) style label and the fish bracket (e.g., `<number>`) style labels. For real applications, mixing these label styles should be avoided. An application should consistently use only one style.
Expand Down Expand Up @@ -1495,12 +1495,24 @@ class Ln { ... }
The `header` will be shown at the top of the usage help message (before the synopsis). The first header line is also the line shown in the subcommand list if your command has subcommands (see <<Usage Help for Subcommands>>).

Use the `footer` attribute to specify one or more lines to show below the generated usage help message.

Each element of the attribute String array is displayed on a separate line.

The `headerHeading` and `footerHeading` may contain format specifiers. See <<Section Headings>>.
=== Format Specifiers
All usage help message elements can have embedded line separator (`%n`) format specifiers.
These are converted to the platform-specific line separator when the usage help message is printed.

<<Static Version Information,Version help>> may have format specifiers that format additional arguments passed to the `printVersionHelp` method.

See the https://docs.oracle.com/javase/8/docs/api/java/util/Formatter.html[java.util.Formatter javadoc] for details.

IMPORTANT: Note that to show percent `'%'` characters in the usage help message, they need to be escaped with another `%`. For example: `@Parameters(description = "%%-age of the total")` is rendered as `%-age of the total`.

An alternative way to control the layout of the usage help message is that some sections (`header`, `footer`, and `description`) can be specified as an array of Strings,
where each element of the array is displayed on a separate line in the usage help message.

=== Section Headings
Section headers can be used to make usage message layout appear more spacious. Section headings may contain embedded line separator (`%n`) format specifiers:
Section headers can be used to make usage message layout appear more spacious. The example below demonstrates the use of embedded line separator (`%n`) format specifiers:
[source,java]
----
@Command(name = "commit",
Expand Down Expand Up @@ -2235,6 +2247,8 @@ The most commonly used git commands are:
tag Create, list, delete or verify a tag object signed with GPG.
----

The description of each subcommand in the command list is taken from the subcommand's first `header` line, or the first `description` line if it does not have a `header` defined.

The above usage help message is produced from the annotations on the class below:
[source,java]
----
Expand Down
54 changes: 33 additions & 21 deletions src/main/java/picocli/CommandLine.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2552,9 +2552,10 @@ private static class NoCompletionCandidates implements Iterable<String> {
boolean versionHelp() default false;

/**
* Description of this option, used when generating the usage documentation.
* <p>
* From picocli 3.2, the usage string may contain variables that are rendered when help is requested.
* Description of this option, used when generating the usage documentation. Each element of the array is rendered on a separate line.
* <p>May contain embedded {@linkplain java.util.Formatter format specifiers} like {@code %n} line separators. Literal percent {@code '%'} characters must be escaped with another {@code %}.
* </p><p>
* The description may contain variables that are rendered when help is requested.
* The string {@code ${DEFAULT-VALUE}} is replaced with the default value of the option. This is regardless of
* the command's {@link Command#showDefaultValues() showDefaultValues} setting or the option's {@link #showDefaultValue() showDefaultValue} setting.
* The string {@code ${COMPLETION-CANDIDATES}} is replaced with the completion candidates generated by
Expand Down Expand Up @@ -2774,9 +2775,10 @@ private static class NoCompletionCandidates implements Iterable<String> {
*/
String index() default "";

/** Description of the parameter(s), used when generating the usage documentation.
* <p>
* From picocli 3.2, the usage string may contain variables that are rendered when help is requested.
/** Description of the parameter(s), used when generating the usage documentation. Each element of the array is rendered on a separate line.
* <p>May contain embedded {@linkplain java.util.Formatter format specifiers} like {@code %n} line separators. Literal percent {@code '%'} characters must be escaped with another {@code %}.
* </p><p>
* The description may contain variables that are rendered when help is requested.
* The string {@code ${DEFAULT-VALUE}} is replaced with the default value of the positional parameter. This is regardless of
* the command's {@link Command#showDefaultValues() showDefaultValues} setting or the positional parameter's {@link #showDefaultValue() showDefaultValue} setting.
* The string {@code ${COMPLETION-CANDIDATES}} is replaced with the completion candidates generated by
Expand Down Expand Up @@ -3131,7 +3133,9 @@ private static class NoCompletionCandidates implements Iterable<String> {
String separator() default "=";

/** Version information for this command, to print to the console when the user specifies an
* {@linkplain Option#versionHelp() option} to request version help. This is not part of the usage help message.
* {@linkplain Option#versionHelp() option} to request version help. Each element of the array is rendered on a separate line.
* <p>May contain embedded {@linkplain java.util.Formatter format specifiers} like {@code %n} line separators. Literal percent {@code '%'} characters must be escaped with another {@code %}.</p>
* <p>This is not part of the usage help message.</p>
*
* @return a string or an array of strings with version information about this command (each string in the array is displayed on a separate line).
* @since 0.9.8
Expand Down Expand Up @@ -3167,21 +3171,22 @@ private static class NoCompletionCandidates implements Iterable<String> {
* @since 3.0 */
boolean helpCommand() default false;

/** Set the heading preceding the header section. May contain embedded {@linkplain java.util.Formatter format specifiers}.
/** Set the heading preceding the header section.
* <p>May contain embedded {@linkplain java.util.Formatter format specifiers} like {@code %n} line separators. Literal percent {@code '%'} characters must be escaped with another {@code %}.</p>
* @return the heading preceding the header section
* @see UsageMessageSpec#headerHeading()
* @see Help#headerHeading(Object...) */
String headerHeading() default "";

/** Optional summary description of the command, shown before the synopsis.
/** Optional summary description of the command, shown before the synopsis. Each element of the array is rendered on a separate line.
* <p>May contain embedded {@linkplain java.util.Formatter format specifiers} like {@code %n} line separators. Literal percent {@code '%'} characters must be escaped with another {@code %}.</p>
* @return summary description of the command
* @see UsageMessageSpec#header()
* @see Help#header(Object...) */
String[] header() default {};

/** Set the heading preceding the synopsis text. May contain embedded
* {@linkplain java.util.Formatter format specifiers}. The default heading is {@code "Usage: "} (without a line
* break between the heading and the synopsis text).
/** Set the heading preceding the synopsis text. The default heading is {@code "Usage: "} (without a line break between the heading and the synopsis text).
* <p>May contain embedded {@linkplain java.util.Formatter format specifiers} like {@code %n} line separators. Literal percent {@code '%'} characters must be escaped with another {@code %}.</p>
* @return the heading preceding the synopsis text
* @see Help#synopsisHeading(Object...) */
String synopsisHeading() default "Usage: ";
Expand All @@ -3193,27 +3198,32 @@ private static class NoCompletionCandidates implements Iterable<String> {
* @see Help#detailedSynopsis(Comparator, boolean) */
boolean abbreviateSynopsis() default false;

/** Specify one or more custom synopsis lines to display instead of an auto-generated synopsis.
/** Specify one or more custom synopsis lines to display instead of an auto-generated synopsis. Each element of the array is rendered on a separate line.
* <p>May contain embedded {@linkplain java.util.Formatter format specifiers} like {@code %n} line separators. Literal percent {@code '%'} characters must be escaped with another {@code %}.</p>
* @return custom synopsis text to replace the auto-generated synopsis
* @see Help#customSynopsis(Object...) */
String[] customSynopsis() default {};

/** Set the heading preceding the description section. May contain embedded {@linkplain java.util.Formatter format specifiers}.
/** Set the heading preceding the description section.
* <p>May contain embedded {@linkplain java.util.Formatter format specifiers} like {@code %n} line separators. Literal percent {@code '%'} characters must be escaped with another {@code %}.</p>
* @return the heading preceding the description section
* @see Help#descriptionHeading(Object...) */
String descriptionHeading() default "";

/** Optional text to display between the synopsis line(s) and the list of options.
/** Optional text to display between the synopsis line(s) and the list of options. Each element of the array is rendered on a separate line.
* <p>May contain embedded {@linkplain java.util.Formatter format specifiers} like {@code %n} line separators. Literal percent {@code '%'} characters must be escaped with another {@code %}.</p>
* @return description of this command
* @see Help#description(Object...) */
String[] description() default {};

/** Set the heading preceding the parameters list. May contain embedded {@linkplain java.util.Formatter format specifiers}.
/** Set the heading preceding the parameters list.
* <p>May contain embedded {@linkplain java.util.Formatter format specifiers} like {@code %n} line separators. Literal percent {@code '%'} characters must be escaped with another {@code %}.</p>
* @return the heading preceding the parameters list
* @see Help#parameterListHeading(Object...) */
String parameterListHeading() default "";

/** Set the heading preceding the options list. May contain embedded {@linkplain java.util.Formatter format specifiers}.
/** Set the heading preceding the options list.
* <p>May contain embedded {@linkplain java.util.Formatter format specifiers} like {@code %n} line separators. Literal percent {@code '%'} characters must be escaped with another {@code %}.</p>
* @return the heading preceding the options list
* @see Help#optionListHeading(Object...) */
String optionListHeading() default "";
Expand All @@ -3240,18 +3250,20 @@ private static class NoCompletionCandidates implements Iterable<String> {
* @return whether the default values for options and parameters should be shown in the description column */
boolean showDefaultValues() default false;

/** Set the heading preceding the subcommands list. May contain embedded {@linkplain java.util.Formatter format specifiers}.
* The default heading is {@code "Commands:%n"} (with a line break at the end).
/** Set the heading preceding the subcommands list. The default heading is {@code "Commands:%n"} (with a line break at the end).
* <p>May contain embedded {@linkplain java.util.Formatter format specifiers} like {@code %n} line separators. Literal percent {@code '%'} characters must be escaped with another {@code %}.</p>
* @return the heading preceding the subcommands list
* @see Help#commandListHeading(Object...) */
String commandListHeading() default "Commands:%n";

/** Set the heading preceding the footer section. May contain embedded {@linkplain java.util.Formatter format specifiers}.
/** Set the heading preceding the footer section.
* <p>May contain embedded {@linkplain java.util.Formatter format specifiers} like {@code %n} line separators. Literal percent {@code '%'} characters must be escaped with another {@code %}.</p>
* @return the heading preceding the footer section
* @see Help#footerHeading(Object...) */
String footerHeading() default "";

/** Optional text to display after the list of options.
/** Optional text to display after the list of options. Each element of the array is rendered on a separate line.
* <p>May contain embedded {@linkplain java.util.Formatter format specifiers} like {@code %n} line separators. Literal percent {@code '%'} characters must be escaped with another {@code %}.</p>
* @return text to display after the list of options
* @see Help#footer(Object...) */
String[] footer() default {};
Expand Down

0 comments on commit 71204dc

Please sign in to comment.