picocli

https://picocli.info/
Admin
picocli is a highly productive Java annotation processing framework for creating powerful...
Tokens:934,868
Snippets:7,904
Trust Score:9.3
Update:1 day ago
Show doc for...
Tokens:
Raw
### Example output of version info with variables

Source: https://picocli.info/

Shows a sample output of the version info with variables example.

```text
Versioned Command 1.0
Picocli 4.0.0
JVM: 1.8.0_202 (Oracle Corporation Substrate VM GraalVM 1.0.0-rc15 CE)
OS: Linux 4.4.0-17134-Microsoft amd64
```

--------------------------------

### Example properties resource bundle for usage help

Source: https://picocli.info/index.html

A complete properties file defining usage help section headings, option descriptions, exit codes, and special descriptions for picocli. Use numbered keys for multi-line sections and descriptions. Leading whitespace is removed by default; start with \u0020 to preserve it. Headings can contain %n for multi-line values.

```properties
# Usage Help Message Sections
# ---------------------------
# Numbered resource keys can be used to create multi-line sections.
usage.headerHeading = This is my app. It does stuff. Good stuff.%n
usage.header   = header first line
usage.header.0 = header second line
usage.descriptionHeading = Description:%n
usage.description.0 = first line
usage.description.1 = second line
usage.description.2 = third line
usage.synopsisHeading = Usage:\u0020

# Leading whitespace is removed by default.
# Start with \u0020 to keep the leading whitespace.
usage.customSynopsis.0 =      Usage: ln [OPTION]... [-T] TARGET LINK_NAME   (1st form)
usage.customSynopsis.1 = \u0020 or:  ln [OPTION]... TARGET                  (2nd form)
usage.customSynopsis.2 = \u0020 or:  ln [OPTION]... TARGET... DIRECTORY     (3rd form)

# Headings can contain the %n character to create multi-line values.
usage.parameterListHeading = %nPositional parameters:%n
usage.optionListHeading = %nOptions:%n
usage.commandListHeading = %nCommands:%n
usage.footerHeading = Powered by picocli%n
usage.footer = footer

# Option Descriptions
# -------------------
# Use numbered keys to create multi-line descriptions.

# Example description for an option `@Option(names = "-x")`
x = This is the description for the -x option

# Example multi-line description for an option `@Option(names = "-y")`
y.0 = This is the first line of the description for the -y option
y.1 = This is the second line of the description for the -y option

# Example descriptions for the standard help mixin options:
help = Show this help message and exit.
version = Print version information and exit.

# Exit Code Description
# ---------------------
usage.exitCodeListHeading = Exit Codes:%n
usage.exitCodeList.0 = \u00200:Successful program execution. (notice leading space '\u0020')
usage.exitCodeList.1 = 64:Usage error: user input for the command was incorrect.
usage.exitCodeList.2 = 70:An exception occurred when invoking the business logic of this command.

# @file Description
# -----------------
picocli.atfile=One or more argument files containing options, commands and positional parameters.

# End-of-Options (--) Delimiter Description
# -----------------------------------------
picocli.endofoptions = Separates options from positional parameters.

```

--------------------------------

### Example: Setting up PicocliCommands.ClearScreen with a Terminal

Source: https://picocli.info/apidocs-all/info.picocli.shell.jline3/picocli/shell/jline3/PicocliCommands.ClearScreen.html

Example from the documentation showing how to use the ClearScreen subcommand. It requires a JLine Terminal, which is set on a PicocliCommandsFactory before constructing the CommandLine. The example includes the @Command annotation, factory creation, and setting the terminal.

```java
 @Command(subcommands = PicocliCommands.ClearScreen.class)
 class MyApp //...

 PicocliCommandsFactory factory = new PicocliCommandsFactory();
 CommandLine cmd = new CommandLine(new MyApp(), factory);
 // create terminal
 factory.setTerminal(terminal);
```

--------------------------------

### JUnit 4/5 setup and teardown for output capturing

Source: https://picocli.info/

Shows how to use JUnit lifecycle annotations to set up and restore System.out and System.err. The example includes commented-out JUnit 4 annotations and active JUnit 5 annotations, with a test method that executes a picocli command and asserts the captured output.

```java
//import org.junit.After;  // JUnit 4
//import org.junit.Before; // JUnit 4
import org.junit.jupiter.api.AfterEach;  // JUnit 5
import org.junit.jupiter.api.BeforeEach; // JUnit 5
//...
class TestOutput {
    final PrintStream originalOut = System.out;
    final PrintStream originalErr = System.err;
    final ByteArrayOutputStream out = new ByteArrayOutputStream();
    final ByteArrayOutputStream err = new ByteArrayOutputStream();

    //@Before   // JUnit 4
    @BeforeEach // JUnit 5
    public void setUpStreams() {
        out.reset();
        err.reset();
        System.setOut(new PrintStream(out));
        System.setErr(new PrintStream(err));
    }

    //@After   // JUnit 4
    @AfterEach // JUnit 5
    public void restoreStreams() {
        System.setOut(originalOut);
        System.setErr(originalErr);
    }

    @Test
    public void test() {
        String[] args = "my command args".split(" ");
        new CommandLine(new MyApp()).execute(args);
        assertEquals("MY COMMAND OUTPUT", out.toString());
        assertEquals("", err.toString());
    }
}
```

--------------------------------

### Usage help output for ${DEFAULT-VALUE} example

Source: https://picocli.info/

The usage help produced by the ${DEFAULT-VALUE} examples, showing the default value in the description.

```text
Usage: <main class> [-f=<file>]
  -f, --file=<file>   the file to use (default: config.xml)
```

--------------------------------

### Usage help output for ${COMPLETION-CANDIDATES} example

Source: https://picocli.info/

The usage help produced by the ${COMPLETION-CANDIDATES} examples, showing the completion candidates in the descriptions.

```text
Usage: <main class> [-l=<lang>] [-o=<option>]
  -l=<lang>     Enum values: java, groovy, kotlin, javascript, frege, clojure
  -o=<option>   Candidates: A, B, C
```

--------------------------------

### Black Box and White Box Testing with CommandLine (Kotlin)

Source: https://picocli.info/

Kotlin version of the testing example, using the same setup and assertions. Uses Kotlin property syntax for setting the output writer and accessing application state.

```Kotlin
val app = MyApp()
val cmd = CommandLine(app)

val sw = StringWriter()
cmd.out = PrintWriter(sw)

// black box testing
val exitCode = cmd.execute("-x", "-y=123")
assertEquals(0, exitCode)
assertEquals("Your output is abc...", sw.toString())

// white box testing
assertEquals("expectedValue1", app.state1)
assertEquals("expectedValue2", app.state2)
```

--------------------------------

### Usage help output for @<filename> example

Source: https://picocli.info/

The usage help message produced by the example command, showing the @<filename> entry before the positional parameter.

```text
Usage: myapp [-hV] [@<filename>...] <file>
Example command.
      [@<filename>...]   One or more argument files containing options.
      <file>             A file.
  -h, --help             Show this help message and exit.
  -V, --version          Print version information and exit.
```

--------------------------------

### Command line: Multiple positional parameters example

Source: https://picocli.info/

Example invocation showing multiple positional parameters.

```text
<command> SECONDS HOURS DAYS
```

--------------------------------

### Return Value from Callable or Method - Before (Java)

Source: https://picocli.info/

Deprecated usage of CommandLine.call to get a result from a Callable. Replace with execute and getExecutionResult as shown in the 'After' example.

```java
class MyCallable implements Callable<MyResult> {
    public MyResult call() { /* ... */ }
}

MyResult result = CommandLine.call(new MyCallable(), args);
```

--------------------------------

### Example: Generate resource config with java -cp

Source: https://picocli.info/man/gen-resource-config.html

Command-line example showing how to run the ResourceConfigGenerator with the required classpath entries (myapp.jar, picocli-4.7.7.jar, picocli-codegen-4.7.7.jar) and a command class (my.pkg.MyClass).

```bash
java -cp "myapp.jar;picocli-4.7.7.jar;picocli-codegen-4.7.7.jar" picocli.codegen.aot.graalvm.ResourceConfigGenerator my.pkg.MyClass
```

--------------------------------

### Example usage of IExtensible.getExtension

Source: https://picocli.info/apidocs-all/info.picocli/picocli/CommandLine.Model.IExtensible.html

Shows how to use the IExtensible interface to get an extension instance. It checks if an IAnnotatedElement is an instance of IExtensible, then retrieves an InitialValueState extension and processes it if non-null.

```java
 // suppose we want to add a method `getInitialValueState` to `IAnnotatedElement`
 IAnnotatedElement element = getAnnotatedElement();
 if (element instanceof IExtensible) {
     InitialValueState state = ((IExtensible) element).getExtension(InitialValueState.class);
     if (state != null) {
         // ...
     }
 }

```

--------------------------------

### Example argument file contents

Source: https://picocli.info/

Shows the contents of an argument file at /home/foo/args. Lines starting with # are comments and ignored. Arguments can be space- or newline-separated; quoted values with spaces are allowed.

```text
# This line is a comment and is ignored.
ABC -option=123
'X Y Z'
```

--------------------------------

### void init(CommandLine helpCommandLine, CommandLine.Help.ColorScheme colorScheme, PrintWriter out, PrintWriter err)

Source: https://picocli.info/apidocs-all/info.picocli/picocli/CommandLine.HelpCommand.html

Initializes this object with the information needed to implement a help command that provides usage help for other commands.

```APIDOC
## void init(CommandLine helpCommandLine, CommandLine.Help.ColorScheme colorScheme, PrintWriter out, PrintWriter err)

### Description
Initializes this object with the information needed to implement a help command that provides usage help for other commands.

### Method
`void init(CommandLine helpCommandLine, CommandLine.Help.ColorScheme colorScheme, PrintWriter out, PrintWriter err)`

### Parameters
- **helpCommandLine** (CommandLine) - Required - The command line object for the help command.
- **colorScheme** (CommandLine.Help.ColorScheme) - Required - The color scheme to use for output.
- **out** (PrintWriter) - Required - The writer for standard output.
- **err** (PrintWriter) - Required - The writer for error output.

### Returns
void
```

--------------------------------

### CommandLine.IHelpFactory.create

Source: https://picocli.info/apidocs-all/info.picocli/picocli/class-use/CommandLine.Help.ColorScheme.html

Returns a Help instance to assist in rendering the usage help message.

```APIDOC
## CommandLine.IHelpFactory.create

### Description
Returns a Help instance to assist in rendering the usage help message.

### Method
create

### Signature
CommandLine.Help create(CommandLine.Model.CommandSpec commandSpec, CommandLine.Help.ColorScheme colorScheme)

### Parameters
- **commandSpec** (CommandLine.Model.CommandSpec) - Required - The command specification.
- **colorScheme** (CommandLine.Help.ColorScheme) - Required - The color scheme to use.

### Returns
- **CommandLine.Help** - A Help instance.
```

--------------------------------

### Kotlin: Define interface with @Option property

Source: https://picocli.info/

Kotlin equivalent of the Java interface example, using @get:Option on a val property. The annotation target is required for Kotlin properties.

```Kotlin
interface Counter {
    @get:Option(names = ["--count"])
    val count: Int
}
```

--------------------------------

### init(CommandLine, Help.ColorScheme, PrintWriter, PrintWriter)

Source: https://picocli.info/apidocs-all/info.picocli/picocli/CommandLine.HelpCommand.html

Initializes this object with the information needed to implement a help command that provides usage help for other commands.

```APIDOC
## init(CommandLine, Help.ColorScheme, PrintWriter, PrintWriter)

### Description
Initializes this object with the information needed to implement a help command that provides usage help for other commands.

### Method
init

### Signature
public void init(CommandLine helpCommandLine, CommandLine.Help.ColorScheme colorScheme, PrintWriter out, PrintWriter err)

### Parameters
- **helpCommandLine** (CommandLine) - Required - The CommandLine object associated with this help command. Implementors can use this to walk the command hierarchy and get access to the help command's parent and sibling commands.
- **colorScheme** (CommandLine.Help.ColorScheme) - Required - The color scheme to use when printing help, including whether to use Ansi colors or not
- **out** (PrintWriter) - Required - The output writer to print the usage help message to
- **err** (PrintWriter) - Required - The error writer to print any diagnostic messages to, in addition to the output from the exception handler

### Return Value
void

### Interface
CommandLine.IHelpCommandInitializable2
```

--------------------------------

### Kotlin: Combining explicit and automatic indexes

Source: https://picocli.info/

Kotlin version of the same example, showing automatic index assignment relative to explicit indexes. Automatic indexes start from the explicit index plus 1.

```kotlin
class ExplicitAndAutomaticIndexes {
    @Parameters(index = "0") lateinit var explicit0: String   // explicit index "0"
                                                              // at default anchor point
    @Parameters lateinit var pAuto1: String                   // assigned index "1",
                                                              // anchor point + 1
    @Parameters lateinit var pAuto2: String                   // assigned index "2"
    @Parameters(index = "1+") lateinit var pAnchored1: String // assigned index "1":
                                                              // no explicit index 1
    @Parameters(index = "1+") lateinit var pAnchored2: String // assigned index "2"
    @Parameters(index = "2") lateinit var explicit2: String   // explicit index "2",
                                                              // matching anchor for "2+"
    @Parameters(index = "2+") lateinit var pAnchored3: String // assigned index "3",
                                                              // anchor point + 1
    @Parameters(index = "2+") lateinit var pAnchored4: String // assigned index "4"
}
```

--------------------------------

### Custom converter implementation in Java

Source: https://picocli.info/

Example implementation of `ITypeConverter<Integer>` that maps `java.sql.Types` constant names to their integer values. Requires a public no-argument constructor unless a custom factory is installed.

```java
class SqlTypeConverter implements ITypeConverter<Integer> {
    public Integer convert(String value) throws Exception {
        switch (value) {
            case "ARRAY"  : return Types.ARRAY;
            case "BIGINT" : return Types.BIGINT;
            case "BINARY" : return Types.BINARY;
            case "BIT"    : return Types.BIT;
            case "BLOB"   : return Types.BLOB;
            // ...
        }
    }
}
```

--------------------------------

### Anchored Automatic Index Example (Kotlin)

Source: https://picocli.info/

Kotlin class demonstrating anchored automatic index using `index = "1+"` to start automatic index assignment from 1 instead of 0.

```kotlin
class Anchored {
    @Parameters(index = "1+") lateinit var p1: String  // assigned index = "1" or higher
    @Parameters(index = "1+") lateinit var p2: String  // assigned index = "2" or higher
}
```

--------------------------------

### Usage help with styles and colors (Kotlin)

Source: https://picocli.info/

Kotlin version of the usage help example, using arrays for header and description.

```kotlin
@Command(name = "commit",
        sortOptions = false,
        headerHeading = "@|bold,underline Usage|@:%n%n",
        synopsisHeading = "%n",
        descriptionHeading = "%n@|bold,underline Description|@:%n%n",
        parameterListHeading = "%n@|bold,underline Parameters|@:%n",
        optionListHeading = "%n@|bold,underline Options|@:%n",
        header = ["Record changes to the repository."],
        description = ["Stores the current contents of the index in a new commit " +
                "along with a log message from the user describing the changes."])
class GitCommit { /* ... */ }
```

--------------------------------

### init(CommandLine, ColorScheme, PrintWriter, PrintWriter)

Source: https://picocli.info/apidocs-all/info.picocli/picocli/CommandLine.IHelpCommandInitializable2.html

Initializes this object with the information needed to implement a help command that provides usage help for other commands.

```APIDOC
## init(CommandLine, ColorScheme, PrintWriter, PrintWriter)

### Description
Initializes this object with the information needed to implement a help command that provides usage help for other commands.

### Method
void init(CommandLine helpCommandLine, CommandLine.Help.ColorScheme colorScheme, PrintWriter outWriter, PrintWriter errWriter)

### Parameters
- **helpCommandLine** (CommandLine) - The CommandLine object associated with this help command. Implementors can use this to walk the command hierarchy and get access to the help command's parent and sibling commands.
- **colorScheme** (CommandLine.Help.ColorScheme) - The color scheme to use when printing help, including whether to use Ansi colors or not.
- **outWriter** (PrintWriter) - The output writer to print the usage help message to.
- **errWriter** (PrintWriter) - The error writer to print any diagnostic messages to, in addition to the output from the exception handler.

### Implementation Note
If an error occurs in the run or call method while processing the help request, it is recommended custom Help commands throw a ParameterException with a reference to the parent command. The default ParameterException handler will print the error message and the usage for the parent command.

### Since
4.0
```

--------------------------------

### Anchored Automatic Index Example (Java)

Source: https://picocli.info/

Java class demonstrating anchored automatic index using `index = "1+"` to start automatic index assignment from 1 instead of 0.

```java
class Anchored {
    @Parameters(index = "1+") String p1; // assigned index = "1" or higher
    @Parameters(index = "1+") String p2; // assigned index = "2" or higher
}
```

--------------------------------

### Java example: Foo with subcommands Bar and Baz

Source: https://picocli.info/

Defines a top-level command Foo with subcommand Bar, which itself has subcommand Baz. Uses Callable<Integer> and @Command annotations. The main method uses CommandLine.execute to run and get exit code.

```java
@Command(name = "foo", subcommands = Bar.class)
class Foo implements Callable<Integer> {
    @Option(names = "-x") int x;

    @Override public Integer call() {
        System.out.printf("hi from foo, x=%d%n", x);
        boolean ok = true;
        return ok ? 0 : 1; // exit code
    }

    public static void main(String... args) {
        int exitCode = new CommandLine(new Foo()).execute(args);
        System.exit(exitCode);
    }
}

@Command(name = "bar", description = "I'm a subcommand of `foo`")
class Bar implements Callable<Integer> {
    @Option(names = "-y") int y;

    @Override public Integer call() {
        System.out.printf("hi from bar, y=%d%n", y);
        return 23;
    }

    @Command(name = "baz", description = "I'm a subcommand of `bar`")
    int baz(@Option(names = "-z") int z) {
        System.out.printf("hi from baz, z=%d%n", z);
        return 45;
    }
}
```

--------------------------------

### DIY output capturing with ByteArrayOutputStream

Source: https://picocli.info/

Manually captures System.out and System.err by replacing them with PrintStream wrappers around ByteArrayOutputStream. The example shows setup, test execution, teardown in a finally block, and assertions. This approach is verbose but avoids external libraries.

```java
ByteArrayOutputStream err = new ByteArrayOutputStream();
ByteArrayOutputStream out = new ByteArrayOutputStream();
PrintStream oldErr = System.err;
PrintStream oldOut = System.out;
try {
    System.setErr(new PrintStream(err));           // setup
    System.setOut(new PrintStream(out));
    String[] args = "my command args".split(" ");  // test
    new CommandLine(new MyApp()).execute(args);
} finally {
    System.setErr(oldErr);                         // teardown
    System.setOut(oldOut);
}
assertEquals("MY COMMAND OUTPUT", out.toString()); // verify
assertEquals("", err.toString());
```

--------------------------------

### CommandLine.IHelpCommandInitializable2.init

Source: https://picocli.info/apidocs-all/info.picocli/picocli/class-use/CommandLine.Help.ColorScheme.html

Initializes this object with the information needed to implement a help command that provides usage help for other commands.

```APIDOC
## CommandLine.IHelpCommandInitializable2.init

### Description
Initializes this object with the information needed to implement a help command that provides usage help for other commands.

### Method
init

### Signature
void init(CommandLine helpCommandLine, CommandLine.Help.ColorScheme colorScheme, PrintWriter outWriter, PrintWriter errWriter)

### Parameters
- **helpCommandLine** (CommandLine) - Required - The command line for the help command.
- **colorScheme** (CommandLine.Help.ColorScheme) - Required - The color scheme to use.
- **outWriter** (PrintWriter) - Required - The output writer.
- **errWriter** (PrintWriter) - Required - The error writer.
```

--------------------------------

### Example usage of @PicocliScript with @Command

Source: https://picocli.info/apidocs-all/info.picocli.groovy/picocli/groovy/PicocliBaseScript.html

Shows how to install PicocliBaseScript via the @PicocliScript annotation and use the @Command annotation to define a command. The script body is executed after the base class parses the command line and initializes @Field variables annotated with @Option or @Parameters.

```groovy
 @Command(name = "myCommand", description = "does something special")
 @PicocliScript
 import picocli.groovy.PicocliScript
 import picocli.CommandLine.Command
 ...
 
```

--------------------------------

### void init(CommandLine helpCommandLine, CommandLine.Help.Ansi ansi, PrintStream out, PrintStream err)

Source: https://picocli.info/apidocs-all/info.picocli/picocli/CommandLine.HelpCommand.html

Deprecated. Initializes this object with the information needed to implement a help command. This method is deprecated and should not be used.

```APIDOC
## void init(CommandLine helpCommandLine, CommandLine.Help.Ansi ansi, PrintStream out, PrintStream err)

### Description
Deprecated. Initializes this object with the information needed to implement a help command. This method is deprecated and should not be used.

### Method
`void init(CommandLine helpCommandLine, CommandLine.Help.Ansi ansi, PrintStream out, PrintStream err)`

### Parameters
- **helpCommandLine** (CommandLine) - Required - The command line object for the help command.
- **ansi** (CommandLine.Help.Ansi) - Required - The ANSI style to use for output.
- **out** (PrintStream) - Required - The output stream for standard output.
- **err** (PrintStream) - Required - The output stream for error output.

### Returns
void
```

--------------------------------

### Java: Combining explicit and automatic indexes

Source: https://picocli.info/

Shows how automatic indexes are assigned when an explicit index is present at the anchor point. Automatic indexes start from the explicit index plus 1. The example includes explicit indexes '0' and '2', and anchored indexes '1+' and '2+'.

```java
class ExplicitAndAutomaticIndexes {
    @Parameters(index = "0" ) String explicit0;  // explicit index "0" at default anchor point
    @Parameters String pAuto1;                   // assigned index "1", anchor point + 1
    @Parameters String pAuto2;                   // assigned index "2"
    @Parameters(index = "1+") String pAnchored1; // assigned index "1": no explicit index 1
    @Parameters(index = "1+") String pAnchored2; // assigned index "2"
    @Parameters(index = "2" ) String explicit2;  // explicit index "2", matching anchor for "2+"
    @Parameters(index = "2+") String pAnchored3; // assigned index "3", anchor point + 1
    @Parameters(index = "2+") String pAnchored4; // assigned index "4"
}
```

--------------------------------

### Create example file for checksum

Source: https://picocli.info/

Creates a text file named hello.txt containing 'hello' to use as input for the CheckSum application.

```bash
echo "hello" > hello.txt
```

--------------------------------

### Kotlin: Version info with colors

Source: https://picocli.info/

Kotlin equivalent of the version info with colors example.

```kotlin
@Command(version = [
        "@|yellow Versioned Command 1.0|@",
        "@|blue Build 12345|@",
        "@|red,bg(white) (c) 2017|@"])
class VersionedCommand { /* */ }
```

--------------------------------

### Kotlin: Validate at least one of --xml, --csv, --json options

Source: https://picocli.info/

This Kotlin example is the equivalent of the Java version, showing a picocli command that validates at the start of the run() method that at least one of the --xml, --csv, or --json options is specified. It throws a ParameterException if none are present, using the injected CommandSpec.

```kotlin
@Command(name = "myapp", mixinStandardHelpOptions = true, version = ["myapp 0.1"])
class MultiOptionValidationExample : Runnable {
    @Option(names = ["--xml"])  var xmlFiles: List<File>? = null
    @Option(names = ["--csv"])  var csvFiles: List<File>? = null
    @Option(names = ["--json"]) var jsonFiles: List<File>? = null

    @Spec lateinit var spec : CommandSpec // injected by picocli

     override fun run() {
        validate()

        // remaining business logic here
    }

    private fun validate() {
        if (missing(xmlFiles) && missing(csvFiles) && missing(jsonFiles)) {
            throw ParameterException(spec.commandLine(),
                "Missing option: at least one of the " +
                "'--xml', '--csv', or '--json' options must be specified.")
        }
    }

    private fun missing(list: List<*>?): Boolean {
        return list == null || list.isEmpty()
    }
}

fun main(args: Array<String>) {
    exitProcess(CommandLine(MultiOptionValidationExample()).execute(*args))
}
```

--------------------------------

### Kotlin: Multi-line version info

Source: https://picocli.info/

Kotlin equivalent of the multi-line version info example.

```kotlin
@Command(version = ["Versioned Command 1.0", "Build 12345", "(c) 2017"])
class VersionedCommand { /* */ }
```

--------------------------------

### Java: Validate at least one of --xml, --csv, --json options

Source: https://picocli.info/

This Java example shows a picocli command that validates at the start of the run() method that at least one of the --xml, --csv, or --json options is specified. If none are present, it throws a ParameterException with a descriptive message. The command uses @Spec to inject the CommandSpec for error reporting.

```java
@Command(name = "myapp", mixinStandardHelpOptions = true, version = "myapp 0.1")
class MultiOptionValidationExample implements Runnable {
    @Option(names="--xml")  List<File> xmlFiles;
    @Option(names="--csv")  List<File> csvFiles;
    @Option(names="--json") List<File> jsonFiles;

    @Spec CommandSpec spec; // injected by picocli

    public static void main(String... args) {
        System.exit(new CommandLine(new MultiOptionValidationExample()).execute(args));
    }

    public void run() {
        validate();

        // remaining business logic here
    }

    private void validate() {
        if (missing(xmlFiles) && missing(csvFiles) && missing(jsonFiles)) {
            throw new ParameterException(spec.commandLine(),
                    "Missing option: at least one of the " +
                    "'--xml', '--csv', or '--json' options must be specified.");
        }
    }

    private boolean missing(List<?> list) {
        return list == null || list.isEmpty();
    }
}
```

--------------------------------

### Usage help output for End of Options example

Source: https://picocli.info/

The usage help message produced by the example command, showing the `--` delimiter entry at the end of the options list.

```text
Usage: myapp [-hV] [--] <file>
Example command.
      <file>      A file.
  -h, --help      Show this help message and exit.
  -V, --version   Print version information and exit.
  --              This option can be used to separate command-line options from
                    the list of positional parameters.
```

--------------------------------

### Abbreviated Synopsis Example (Kotlin)

Source: https://picocli.info/

Kotlin version of the abbreviated synopsis example.

```kotlin
@Command(abbreviateSynopsis = true)
class App {
    @Parameters lateinit var files: Array<File>
    @Option(names = ["--count", "-c"]) var count = 0
    // ...
}
```

--------------------------------

### Required parameters example in Kotlin

Source: https://picocli.info/

Kotlin version of the required parameters example.

```kotlin
class BothOptionAndParametersMandatory {
    @Parameters(arity = "1..*", description = ["at least one File"])
    lateinit var files: Array<File>

    @Option(names = ["-n"], required = true, description = ["mandatory number"])
    var number = 0
}
```

--------------------------------

### DOS option example

Source: https://picocli.info/apidocs-all/info.picocli/picocli/CommandLine.Option.html

Example of DOS-style options with slash prefix and colon-separated parameters.

```dos
DIR /S /A:D /T:C
```

--------------------------------

### Example properties resource bundle for usage help

Source: https://picocli.info/

A properties file with keys for usage help sections, option descriptions, exit codes, and other messages. Note the use of numbered keys for multi-line sections, %n for newlines, and \u0020 to preserve leading whitespace.

```properties
# Usage Help Message Sections
# ---------------------------
# Numbered resource keys can be used to create multi-line sections.
usage.headerHeading = This is my app. It does stuff. Good stuff.%n
usage.header   = header first line
usage.header.0 = header second line
usage.descriptionHeading = Description:%n
usage.description.0 = first line
usage.description.1 = second line
usage.description.2 = third line
usage.synopsisHeading = Usage:\u0020

# Leading whitespace is removed by default.
# Start with \u0020 to keep the leading whitespace.
usage.customSynopsis.0 =      Usage: ln [OPTION]... [-T] TARGET LINK_NAME   (1st form)
usage.customSynopsis.1 = \u0020 or:  ln [OPTION]... TARGET                  (2nd form)
usage.customSynopsis.2 = \u0020 or:  ln [OPTION]... TARGET... DIRECTORY     (3rd form)

# Headings can contain the %n character to create multi-line values.
usage.parameterListHeading = %nPositional parameters:%n
usage.optionListHeading = %nOptions:%n
usage.commandListHeading = %nCommands:%n
usage.footerHeading = Powered by picocli%n
usage.footer = footer

# Option Descriptions
# -------------------
# Use numbered keys to create multi-line descriptions.

# Example description for an option `@Option(names = "-x")`
x = This is the description for the -x option

# Example multi-line description for an option `@Option(names = "-y")`
y.0 = This is the first line of the description for the -y option
y.1 = This is the second line of the description for the -y option

# Example descriptions for the standard help mixin options:
help = Show this help message and exit.
version = Print version information and exit.

# Exit Code Description
# ---------------------
usage.exitCodeListHeading = Exit Codes:%n
usage.exitCodeList.0 = \u00200:Successful program execution. (notice leading space '\u0020')
usage.exitCodeList.1 = 64:Usage error: user input for the command was incorrect.
usage.exitCodeList.2 = 70:An exception occurred when invoking the business logic of this command.

# @file Description
# -----------------
picocli.atfile=One or more argument files containing options, commands and positional parameters.

# End-of-Options (--) Delimiter Description
# -----------------------------------------
picocli.endofoptions = Separates options from positional parameters.
```

--------------------------------

### Kotlin: Print version help after parsing

Source: https://picocli.info/

Kotlin equivalent of the Java version help printing example.

```kotlin
val commandLine = CommandLine(VersionedCommand())
commandLine.parseArgs(*args)
if (commandLine.isVersionHelpRequested) {
    commandLine.printVersionHelp(System.out)
    return
}
```

--------------------------------

### Example class with @Parameters paramLabel

Source: https://picocli.info/apidocs-all/info.picocli/picocli/CommandLine.Parameters.html

Java example demonstrating the use of the paramLabel attribute in a @Parameters annotation. The example shows a class with a File array field annotated with paramLabel="FILE" and a description.

```java
class Example {
     @Parameters(paramLabel="FILE", description="path of the input FILE(s)")
     private File[] inputFiles;
 }
```

--------------------------------

### CommandLine.HelpCommand.init

Source: https://picocli.info/apidocs-all/info.picocli/picocli/class-use/CommandLine.Help.ColorScheme.html

Initializes this object with the information needed to implement a help command that provides usage help for other commands.

```APIDOC
## CommandLine.HelpCommand.init

### Description
Initializes this object with the information needed to implement a help command that provides usage help for other commands.

### Method
init

### Signature
void init(CommandLine helpCommandLine, CommandLine.Help.ColorScheme colorScheme, PrintWriter out, PrintWriter err)

### Parameters
- **helpCommandLine** (CommandLine) - Required - The command line for the help command.
- **colorScheme** (CommandLine.Help.ColorScheme) - Required - The color scheme to use.
- **out** (PrintWriter) - Required - The output writer.
- **err** (PrintWriter) - Required - The error writer.
```

--------------------------------

### Custom Synopsis Example (Kotlin)

Source: https://picocli.info/

Kotlin example using customSynopsis with a raw string literal.

```kotlin
@Command(synopsisHeading = "", mixinStandardHelpOptions = true, customSynopsis = ["""
Usage: ln [OPTION]... [-T] TARGET LINK_NAME   (1st form)
   or: ln [OPTION]... TARGET                  (2nd form)
   or: ln [OPTION]... TARGET... DIRECTORY     (3rd form)
   or:  ln [OPTION]... -t DIRECTORY TARGET...  (4th form)"""])
class Ln { /* ... */ }
```

--------------------------------

### Main method using parseArgs and printHelpIfRequested

Source: https://picocli.info/apidocs-all/info.picocli/picocli/CommandLine.html

Shows how to use CommandLine to parse arguments, check for help requests, and handle ParameterException with usage output.

```java
 public static void main(String... args) {
     Encrypt encrypt = new Encrypt();
     try {
         ParseResult parseResult = new CommandLine(encrypt).parseArgs(args);
         if (!CommandLine.printHelpIfRequested(parseResult)) {
             runProgram(encrypt);
         }
     } catch (ParameterException ex) { // command line arguments could not be parsed
         System.err.println(ex.getMessage());
         ex.getCommandLine().usage(System.err);
     }
 }

```

--------------------------------

### Command line example for repeated options

Source: https://picocli.info/quick-guide.html

Shows how the user can specify the same option multiple times to provide multiple values.

```bash
<command> -option 111 -option 222 -option 333
```

--------------------------------

### Subcommand Method Example

Source: https://picocli.info/index.html

Example of a @Command-annotated method that is automatically added as a subcommand to the enclosing class command.

```APIDOC
## Subcommand Method Example

### Description
A @Command-annotated method inside a class annotated with @Command is automatically added as a subcommand to the class command, unless the class command has attribute `@Command(addMethodSubcommands = false)`.

### Method
N/A (Java/Kotlin method)

### Endpoint
N/A (Java/Kotlin method)

### Parameters
#### Method Parameters
- **commitMessage** (String) - Optional - Corresponds to option `-m, --message`.
- **squash** (String) - Optional - Corresponds to option `--squash` with paramLabel `<commit>`.
- **files** (File[]) - Required - Positional parameter with paramLabel `<file>`.

### Request Example
N/A (Java/Kotlin method)

### Response
N/A (Java/Kotlin method)

```

--------------------------------

### Usage help with styles and colors (Java)

Source: https://picocli.info/

Configures a @Command with headings and descriptions using markup for bold and underline styles, and shows how to set header and description text.

```java
@Command(name = "commit",
        sortOptions = false,
        headerHeading = "@|bold,underline Usage|@:%n%n",
        synopsisHeading = "%n",
        descriptionHeading = "%n@|bold,underline Description|@:%n%n",
        parameterListHeading = "%n@|bold,underline Parameters|@:%n",
        optionListHeading = "%n@|bold,underline Options|@:%n",
        header = "Record changes to the repository.",
        description = "Stores the current contents of the index in a new commit " +
                "along with a log message from the user describing the changes.")
class GitCommit { /* ... */ }
```

--------------------------------

### Example: Generate reflection config with gen-reflect-config

Source: https://picocli.info/man/gen-reflect-config.html

Command-line example showing how to run the ReflectionConfigGenerator with the required classpath and a class argument. The output is a JSON configuration file (or written to stdout if -o is not specified).

```bash
java -cp "myapp.jar;picocli-4.7.7.jar;picocli-codegen-4.7.7.jar" picocli.codegen.aot.graalvm.ReflectionConfigGenerator my.pkg.MyClass
```

--------------------------------

### Double Dash (--) - Kotlin parsing example

Source: https://picocli.info/

Kotlin version of the double dash parsing example.

```kotlin
val args = arrayOf("-v", "--", "-files", "file1", "file2")
val demo = DoubleDashDemo()
CommandLine(demo).parseArgs(*args)

assert(demo.verbose)
assert(demo.files == null)
assert(demo.params == Arrays.asList("-files", "file1", "file2"))
```

--------------------------------

### CommandLine.Help.optionList()

Source: https://picocli.info/apidocs-all/index-files/index-15.html

Returns a description of all options in this command, including any argument groups.

```APIDOC
## CommandLine.Help.optionList()

### Description
Returns a description of all options in this command, including any argument groups.

### Method
optionList()

### Returns
- **String** - A description of all options.
```

--------------------------------

### substring(int start)

Source: https://picocli.info/apidocs-all/info.picocli/picocli/CommandLine.Help.Ansi.Text.html

Returns a new Text instance that is a substring of this Text starting at the given index.

```APIDOC
## Method: substring(int start)

### Description
Returns a new Text instance that is a substring of this Text. Does not modify this instance!

### Parameters
- **start** (int) - Required - index in the plain text where to start the substring

### Returns
CommandLine.Help.Ansi.Text - a new Text instance that is a substring of this Text

```

--------------------------------

### init(CommandLine, CommandLine.Help.Ansi, PrintStream, PrintStream)

Source: https://picocli.info/apidocs-all/info.picocli/picocli/CommandLine.IHelpCommandInitializable.html

Initializes this object with the information needed to implement a help command that provides usage help for other commands. This method is called by CommandLine::printHelpIfRequested before the help command's run or call method is invoked.

```APIDOC
## init(CommandLine, CommandLine.Help.Ansi, PrintStream, PrintStream)

### Description
Initializes this object with the information needed to implement a help command that provides usage help for other commands. This method is called by CommandLine::printHelpIfRequested before the help command's run or call method is invoked.

### Method
init

### Signature
void init(CommandLine helpCommandLine, CommandLine.Help.Ansi ansi, PrintStream out, PrintStream err)

### Parameters
- **helpCommandLine** (CommandLine) - Required - The CommandLine object associated with this help command. Implementors can use this to walk the command hierarchy and get access to the help command's parent and sibling commands.
- **ansi** (CommandLine.Help.Ansi) - Required - Whether to use Ansi colors or not.
- **out** (PrintStream) - Required - The stream to print the usage help message to.
- **err** (PrintStream) - Required - The error stream to print any diagnostic messages to, in addition to the output from the exception handler.

### Deprecation
Deprecated. Use CommandLine.IHelpCommandInitializable2 instead.

### Since
3.0

### Implementation Note
If an error occurs in the run or call method while processing the help request, it is recommended custom Help commands throw a ParameterException with a reference to the parent command. The DefaultExceptionHandler will print the error message and the usage for the parent command, and will terminate with the exit code of the exception handler if one was set.
```
Tokens:
Raw