diff --git a/docs/A-Whirlwind-Tour-of-Picocli.adoc b/docs/A-Whirlwind-Tour-of-Picocli.adoc index b109a26f1..93c6824b0 100644 --- a/docs/A-Whirlwind-Tour-of-Picocli.adoc +++ b/docs/A-Whirlwind-Tour-of-Picocli.adoc @@ -2,6 +2,10 @@ :author: Remko Popma :source-highlighter: coderay :icons: font +ifdef::env-github[] +:note-caption: :information_source: +:tip-caption: :bulb: +endif::[] //:imagesdir: http://picocli.info diff --git a/docs/autocomplete.adoc b/docs/autocomplete.adoc index 241bc21dc..ada2252c3 100644 --- a/docs/autocomplete.adoc +++ b/docs/autocomplete.adoc @@ -10,6 +10,9 @@ :source-highlighter: coderay :icons: font :imagesdir: images +ifdef::env-github[] +:tip-caption: :bulb: +endif::[] [link=https://github.com/remkop/picocli] image::https://s3.amazonaws.com/github/ribbons/forkme_right_red_aa0000.png[Fork me on GitHub,float="right"] diff --git a/docs/build-great-native-cli-apps-in-java-with-graalvm-and-picocli.adoc b/docs/build-great-native-cli-apps-in-java-with-graalvm-and-picocli.adoc index ee805c9f6..371013aed 100644 --- a/docs/build-great-native-cli-apps-in-java-with-graalvm-and-picocli.adoc +++ b/docs/build-great-native-cli-apps-in-java-with-graalvm-and-picocli.adoc @@ -7,6 +7,9 @@ //:toclevels: 3 //:imagesdir: https://picocli.info/images/ :imagesdir: images/ +ifdef::env-github[] +:tip-caption: :bulb: +endif::[] // create variables for some link text used in article to prevent link mangling in PDF :ms-cpp-2015-redist: Microsoft Visual C++ 2015 Redistributable Update 3 RC :ms-cpp-2010-redist: Microsoft Visual C++ 2010 SP1 Redistributable Package (x64) diff --git a/docs/groovy-2.5-clibuilder-renewal-part1.adoc b/docs/groovy-2.5-clibuilder-renewal-part1.adoc index 8cc01e359..401061d23 100644 --- a/docs/groovy-2.5-clibuilder-renewal-part1.adoc +++ b/docs/groovy-2.5-clibuilder-renewal-part1.adoc @@ -9,6 +9,9 @@ :source-highlighter: coderay :icons: font :imagesdir: images +ifdef::env-github[] +:note-caption: :information_source: +endif::[] The `CliBuilder` class for quickly and concisely building command line applications has been renewed in Apache Groovy 2.5. This two-part article highlights what is new. diff --git a/docs/groovy-2.5-clibuilder-renewal-part2.adoc b/docs/groovy-2.5-clibuilder-renewal-part2.adoc index c6e10dd4b..baa430690 100644 --- a/docs/groovy-2.5-clibuilder-renewal-part2.adoc +++ b/docs/groovy-2.5-clibuilder-renewal-part2.adoc @@ -9,6 +9,9 @@ :source-highlighter: coderay :icons: font :imagesdir: images +ifdef::env-github[] +:note-caption: :information_source: +endif::[] The `CliBuilder` class for quickly and concisely building command line applications has been renewed in Apache Groovy 2.5. This is the second of a two-part article series that highlights what is new. diff --git a/docs/index.adoc b/docs/index.adoc index 70a8c73ed..fd2c5e5bd 100644 --- a/docs/index.adoc +++ b/docs/index.adoc @@ -6,13 +6,20 @@ :toc: left :numbered: :toclevels: 2 -:toc-title: Features +:toc-title: Table of contents :source-highlighter: coderay //:source-highlighter: highlightjs //:highlightjs-theme: darkula :icons: font :imagesdir: images :sectanchors: +ifdef::env-github[] +:caution-caption: :fire: +:important-caption: :heavy_exclamation_mark: +:note-caption: :information_source: +:tip-caption: :bulb: +:warning-caption: :warning: +endif::[] [link=https://github.com/remkop/picocli] image::https://s3.amazonaws.com/github/ribbons/forkme_right_red_aa0000.png[Fork me on GitHub,float="right"] @@ -28,31 +35,29 @@ image:logo/horizontal.png[picocli the Mighty Tiny Command Line Interface,width=8 The user manual for the latest release is at http://picocli.info. For the busy and impatient: there is also a link:quick-guide.html[Quick Guide]. -== Introduction +== Introducing Picocli +Picocli is a one-file framework for creating Java command line applications with almost zero code. Picocli aims to be the easiest way to create rich command line applications that can run on and off the JVM. -Picocli is a one-file framework for creating Java command line applications with almost zero code. -Supports a variety of command line syntax styles including POSIX, GNU, MS-DOS and more. -Generates highly customizable usage help messages with <>. +=== Features +Picocli supports a variety of command line syntax styles including POSIX, GNU, MS-DOS and more and generates highly customizable usage help messages with <>. Picocli-based applications can have link:autocomplete.html[command line TAB completion] showing available options, option parameters and subcommands, for any level of nested subcommands. Picocli-based applications can be ahead-of-time compiled to a image:https://www.graalvm.org/resources/img/logo-colored.svg[GraalVM] <>, with extremely fast startup time and lower memory requirements, which can be distributed as a single executable file. - -image:checksum-usage-help.png[Screenshot of usage help with Ansi codes enabled] - Picocli <> for your application (HTML, PDF and Unix man pages). Another distinguishing feature of picocli is how it aims to let users run picocli-based applications without requiring picocli as an external dependency: all the source code lives in a single file, to encourage application authors to include it _in source form_. -How it works: annotate your class and picocli initializes it from the command line arguments, -converting the input to strongly typed values in the fields of your class. +=== Sample application +Let's get started by looking at minimal picocli-based command line application. This fully working sample app may be used to calculate the checksum(s) of one or more file(s) given as command line parameter(s): -TIP: picocli also provides a <>, separately from the annotations API. +.Synopsis of sample application +image:checksum-usage-help.png[Screenshot of usage help with Ansi codes enabled] -.A full working example picocli-based command line application +.Source code of sample application [[CheckSum-application]] [source,java] ---- @@ -67,25 +72,25 @@ import java.nio.file.Files; import java.security.MessageDigest; import java.util.concurrent.Callable; -@Command(name = "checksum", mixinStandardHelpOptions = true, version = "checksum 4.0", +@Command(name = "checksum", mixinStandardHelpOptions = true, version = "checksum 4.0", // <8> description = "Prints the checksum (MD5 by default) of a file to STDOUT.") -class CheckSum implements Callable { +class CheckSum implements Callable { // <1> - @Parameters(index = "0", description = "The file whose checksum to calculate.") - private File file; + @Parameters(index = "0", description = "The file whose checksum to calculate.") // <2> + private File file; // <4> - @Option(names = {"-a", "--algorithm"}, description = "MD5, SHA-1, SHA-256, ...") - private String algorithm = "MD5"; + @Option(names = {"-a", "--algorithm"}, description = "MD5, SHA-1, SHA-256, ...") // <3> + private String algorithm = "MD5"; // <4> // this example implements Callable, so parsing, error handling and handling user // requests for usage help or version help can be done with one line of code. public static void main(String... args) { - int exitCode = new CommandLine(new CheckSum()).execute(args); - System.exit(exitCode); + int exitCode = new CommandLine(new CheckSum()).execute(args); // <5> + System.exit(exitCode); // <7> } @Override - public Integer call() throws Exception { // your business logic goes here... + public Integer call() throws Exception { // your business logic // <6> byte[] fileContents = Files.readAllBytes(file.toPath()); byte[] digest = MessageDigest.getInstance(algorithm).digest(fileContents); System.out.printf("%0" + (digest.length*2) + "x%n", new BigInteger(1, digest)); @@ -94,15 +99,11 @@ class CheckSum implements Callable { } ---- -Implement `Runnable` or `Callable`, and your command can be <> in one line of code. -The example above uses the `CommandLine.execute` method -to parse the command line, handle errors, handle requests for usage and version help, and invoke the business logic. -Applications can call `System.exit` with the returned exit code to signal success or failure to their caller. - -The <> attribute adds `--help` and `--version` options to your application. +_This is how it works_: Create a class ➊ that represents your command and annotate this class with @Command ➑. Let this class implement `Runnable` or `Callable` and picocli will kick off your application after parsing is successfully completed. Then, annotate the fields or methods of the command class with @Parameters ➋ and/or @Option ➌ to declare what positional parameters and/or options your application expects. Picocli will convert the command line arguments given to your app to strongly typed values in the fields ➍ of your class. In the `main` method of your class, use the `CommandLine.execute` method ➎ to parse the command line, handle errors, handle requests for usage and version help, and invoke the business logic ➏. Once your business logic finished, you may call `System.exit` ➐ to return an exit code to your caller, indicating success or failure of your business logic. Additionally, you may make use of the <> attribute ➑ which adds `--help` and `--version` options to your application. +TIP: Picocli also provides a <>, separately from the annotations API. -== Getting Started +== Setting up your picocli based project You can add picocli as an external dependency to your project, or you can include it as source. === Add as External Dependency diff --git a/docs/picocli-on-graalvm.adoc b/docs/picocli-on-graalvm.adoc index e6b19ed1e..a2f8a83ce 100644 --- a/docs/picocli-on-graalvm.adoc +++ b/docs/picocli-on-graalvm.adoc @@ -1,6 +1,9 @@ = Picocli on GraalVM: Blazingly Fast Command Line Apps :source-highlighter: highlightjs :highlightjs-theme: darkula +ifdef::env-github[] +:tip-caption: :bulb: +endif::[] image::https://picocli.info/images/picocli-on-graalvm.png[] diff --git a/docs/picocli-programmatic-api.adoc b/docs/picocli-programmatic-api.adoc index 4f4f37c34..99541ee89 100644 --- a/docs/picocli-programmatic-api.adoc +++ b/docs/picocli-programmatic-api.adoc @@ -9,6 +9,10 @@ :source-highlighter: coderay :icons: font :imagesdir: images +ifdef::env-github[] +:caution-caption: :fire: +:tip-caption: :bulb: +endif::[] TIP: For most applications the annotations API is a better fit than the programmatic API: the annotation syntax is more compact, easier to read, and easier to maintain. See this https://picocli.info/quick-guide.html[quick guide] and for more details, the http://picocli.info[user manual]. @@ -38,16 +42,16 @@ When used as a library, the application calls the `CommandLine.parseArgs` method public class ProgrammaticCommand { public static void main(String[] args) { - CommandSpec spec = CommandSpec.create(); + CommandSpec spec = CommandSpec.create(); // <1> spec.mixinStandardHelpOptions(true); // usageHelp and versionHelp options spec.addOption(OptionSpec.builder("-c", "--count") .paramLabel("COUNT") .type(int.class) - .description("number of times to execute").build()); + .description("number of times to execute").build()); // <2> spec.addPositional(PositionalParamSpec.builder() .paramLabel("FILES") .type(List.class).auxiliaryTypes(File.class) // List - .description("The files to process").build()); + .description("The files to process").build()); // <3> CommandLine commandLine = new CommandLine(spec); // set an execution strategy (the run(ParseResult) method) that will be called @@ -74,16 +78,19 @@ public class ProgrammaticCommand { } } ---- +<1> `CommandSpec` +<2> `OptionSpec` +<3> `PositionalParamSpec` == Configuration The following classes are the main model classes used to configure the parser: -* `CommandSpec` -* `OptionSpec` -* `PositionalParamSpec` +* <> +* <> +* <> -=== `CommandSpec` +=== CommandSpec ==== Command Name and Version `CommandSpec` models a command. It has a name and a version, both of which may be empty. For example: @@ -163,7 +170,7 @@ CommandSpec cmd = CommandSpec.create() .addSubcommand("help", helpSubcommand); ---- -=== `OptionSpec` +=== OptionSpec `OptionSpec` models a command option. An `OptionSpec` must have at least one name, which is used during parsing to match command line arguments. Other attributes can be left empty and picocli will give them a reasonable default value. This defaulting is why `OptionSpec` objects are created with a builder: this allows you to specify only some attributes and let picocli initialise the other attributes. For example, if only the option’s name is specified, picocli assumes the option takes no parameters (arity = 0), and is of type `boolean`. Another example, if arity is larger than `1`, picocli sets the type to `List` and the `auxiliary type` to `String`. Once an `OptionSpec` is constructed, its configuration becomes immutable, but its `value` can still be modified. Usually the value is set during command line parsing when a command line argument matches one of the option names. @@ -172,7 +179,7 @@ The value is set via the getter and setter _bindings_. We’ll come back to bind Similar to the annotation API, `OptionSpec` objects have `help`, `usageHelp` and `versionHelp` attributes. When the parser matches an option that was marked with any of these attributes, it will no longer validate that all required arguments exist. See the section below on the `parseWithHandler(s)` methods that automatically print help when requested. -=== `PositionalParamSpec` +=== PositionalParamSpec `PositionalParamSpec` objects don’t have names, but have an index range instead. A single `PositionalParamSpec` object can capture multiple positional parameters. The default index range is set to `0..*` (all indices). A command may have multiple `PositionalParamSpec` objects to capture positional parameters at different index ranges. This can be useful if positional parameters at different index ranges have different data types. @@ -491,4 +498,4 @@ public class MyApp { } ---- -For more detail, see the https://picocli.info/#execute[Executing Commands] section of the user manual. \ No newline at end of file +For more details, see the https://picocli.info/#execute[Executing Commands] section of the user manual. \ No newline at end of file diff --git a/docs/quick-guide.adoc b/docs/quick-guide.adoc index 2a64cff07..69b4b4427 100644 --- a/docs/quick-guide.adoc +++ b/docs/quick-guide.adoc @@ -10,6 +10,11 @@ :source-highlighter: coderay :icons: font :imagesdir: images +ifdef::env-github[] +:caution-caption: :fire: +:important-caption: :heavy_exclamation_mark: +:note-caption: :information_source: +endif::[] This is the Quick Guide. For more detail, see the full user manual at http://picocli.info[http://picocli.info]. diff --git a/picocli-codegen/README.adoc b/picocli-codegen/README.adoc index 2a7838058..de3553cf2 100644 --- a/picocli-codegen/README.adoc +++ b/picocli-codegen/README.adoc @@ -8,6 +8,10 @@ //:source-highlighter: highlightjs //:highlightjs-theme: darkula :icons: font +ifdef::env-github[] +:caution-caption: :fire: +:tip-caption: :bulb: +endif::[] image::https://picocli.info/images/logo/horizontal-400x150.png[picocli,height="150px"]