You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
*[#1168][#1169] DOC: Ensure `org.jline.terminal.Terminal` is closed when done. Thanks to [David Walluck](https://github.com/dwalluck) for the pull request.
30
30
*[#1167] DOC: Fix broken links in Quick Guide. Thanks to [Andreas Deininger](https://github.com/deining) for the pull request.
31
31
*[#1171] DOC: Various documentation improvements. Thanks to [Andreas Deininger](https://github.com/deining) for the pull request.
32
+
*[#1173] DOC: Improve example applications for the user manual and Quick Guide. Thanks to [Andreas Deininger](https://github.com/deining) for the pull request.
32
33
*[#1170] TEST: Ensure ANSI is disabled in `ManPageGeneratorTest` regardless of environment. Thanks to [David Walluck](https://github.com/dwalluck) for the pull request.
33
34
*[#1166][#1103] TEST: Ensure ANSI is disabled in `TracerTest` regardless of environment. Thanks to [David Walluck](https://github.com/dwalluck) for the pull request.
Copy file name to clipboardExpand all lines: docs/index.adoc
+14-15Lines changed: 14 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -47,19 +47,20 @@ Picocli-based applications can be ahead-of-time compiled to a image:https://www.
47
47
48
48
Picocli <<Generate Man Page Documentation,generates beautiful documentation>> for your application (HTML, PDF and Unix man pages).
49
49
50
-
Another distinguishing feature of picocli is how it aims
51
-
to let users run picocli-based applications without requiring picocli as an external dependency:
50
+
.An example usage help message with ANSI colors and styles
51
+
image:checksum-usage-help.png[Screenshot of usage help with Ansi codes enabled]
52
+
53
+
Another distinguishing feature of picocli is how it aims to let users run picocli-based applications without requiring picocli as an external dependency:
52
54
all the source code lives in a single file, to encourage application authors to include it _in source form_.
53
55
54
-
This is how it works: you 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. If your class implements `Runnable` or `Callable`, you can let picocli kick off your application after parsing is successfully completed.
56
+
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.
55
57
56
-
=== Sample application
57
-
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):
58
+
TIP: Picocli also provides a <<Programmatic API,programmatic API>>, separately from the annotations API.
58
59
59
-
.Synopsis of sample application
60
-
image:checksum-usage-help.png[Screenshot of usage help with Ansi codes enabled]
60
+
=== Example application
61
+
The example below shows a short but fully functional picocli-based `checksum` command line application:
61
62
62
-
.Source code of sample application
63
+
.A full working example picocli-based command line application
@@ -101,13 +102,11 @@ class CheckSum implements Callable<Integer> {
101
102
}
102
103
----
103
104
104
-
Create a class that represents your command and annotate this class with `@Command`. Let this class implement `Runnable` or `Callable` and your command can be <<Executing Commands,executed>> in one line of code. Annotate the fields of the command class with `@Option` or `@Parameters` to declare the options and positional parameters of your application. Use the `CommandLine.execute` method to parse the command line, handle errors, handle requests for usage and version help, and invoke the business logic. Eventually, your application may call `System.exit` with the returned exit code to signal success or failure to their caller.
105
-
106
-
The <<Mixin Standard Help Options,mixinStandardHelpOptions>> attribute adds --help and --version options to your application.
105
+
Implement `Runnable` or `Callable` and your command can be <<Executing Commands,executed>> in one line of code. The example `main` method calls `CommandLine.execute` 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.
107
106
108
-
TIP: Picocli also provides a <<Programmatic API,programmatic API>>, separately from the annotations API.
107
+
The <<Mixin Standard Help Options,mixinStandardHelpOptions>> attribute adds `--help` and `--version` options to your application.
109
108
110
-
== Setting up your picocli based project
109
+
== Getting Started
111
110
You can add picocli as an external dependency to your project, or you can include it as source.
112
111
113
112
=== Add as External Dependency
@@ -6845,7 +6844,7 @@ The generated AsciiDoc files can be converted to HTML, PDF and unix man pages wi
6845
6844
6846
6845
See the link:https://github.com/remkop/picocli/tree/master/picocli-codegen#generate-documentation[Generate Documentation] section of the link:https://github.com/remkop/picocli/tree/master/picocli-codegen[picocli-codegen README] for details on how to generate and customize this documentation.
6847
6846
6848
-
The man pages for the picocli built-in tools were created with this tool:
6847
+
To see some examples, the man pages for the picocli built-in tools were created with this tool:
<p>Picocli is a one-file framework for creating Java command line applications with almost zero code.
861
-
Supports a variety of command line syntax styles including POSIX, GNU, MS-DOS and more.
862
-
Generates highly customizable usage help messages with <a href="#_ansi_colors_and_styles">ANSI colors and styles</a>.
868
+
<p>Picocli supports a variety of command line syntax styles including POSIX, GNU, MS-DOS and more and generates highly customizable usage help messages with <a href="#_ansi_colors_and_styles">ANSI colors and styles</a>.
863
869
Picocli-based applications can have <a href="autocomplete.html">command line TAB completion</a> showing available options, option parameters and subcommands, for any level of nested subcommands.
864
870
Picocli-based applications can be ahead-of-time compiled to a <span class="image"><img src="https://www.graalvm.org/resources/img/logo-colored.svg" alt="GraalVM"></span>
865
871
<a href="#_graalvm_native_image">native image</a>, with extremely fast startup time and lower memory requirements, which can be distributed as a single executable file.</p>
866
872
</div>
867
873
<div class="paragraph">
868
-
<p><span class="image"><img src="images/checksum-usage-help.png" alt="Screenshot of usage help with Ansi codes enabled"></span></p>
874
+
<p>Picocli <a href="#_generate_man_page_documentation">generates beautiful documentation</a> for your application (HTML, PDF and Unix man pages).</p>
869
875
</div>
870
876
<div class="paragraph">
871
-
<p>Picocli <a href="#_generate_man_page_documentation">generates beautiful documentation</a> for your application (HTML, PDF and Unix man pages).</p>
877
+
<div class="title">An example usage help message with ANSI colors and styles</div>
878
+
<p><span class="image"><img src="images/checksum-usage-help.png" alt="Screenshot of usage help with Ansi codes enabled"></span></p>
872
879
</div>
873
880
<div class="paragraph">
874
-
<p>Another distinguishing feature of picocli is how it aims
875
-
to let users run picocli-based applications without requiring picocli as an external dependency:
881
+
<p>Another distinguishing feature of picocli is how it aims to let users run picocli-based applications without requiring picocli as an external dependency:
876
882
all the source code lives in a single file, to encourage application authors to include it <em>in source form</em>.</p>
877
883
</div>
878
884
<div class="paragraph">
879
-
<p>How it works: annotate your class and picocli initializes it from the command line arguments,
880
-
converting the input to strongly typed values in the fields of your class.</p>
885
+
<p>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.</p>
<p>Implement <code>Runnable</code> or <code>Callable</code>, and your command can be <a href="#execute">executed</a> in one line of code.
937
-
The example above uses the <code>CommandLine.execute</code> method
938
-
to parse the command line, handle errors, handle requests for usage and version help, and invoke the business logic.
939
-
Applications can call <code>System.exit</code> with the returned exit code to signal success or failure to their caller.</p>
947
+
<p>Implement <code>Runnable</code> or <code>Callable</code> and your command can be <a href="#execute">executed</a> in one line of code. The example <code>main</code> method calls <code>CommandLine.execute</code> to parse the command line, handle errors, handle requests for usage and version help, and invoke the business logic. Applications can call <code>System.exit</code> with the returned exit code to signal success or failure to their caller.</p>
940
948
</div>
941
949
<div class="paragraph">
942
950
<p>The <a href="#_mixin_standard_help_options">mixinStandardHelpOptions</a> attribute adds <code>--help</code> and <code>--version</code> options to your application.</p>
<p>Annotate a field or method with <code>@ArgGroup(exclusive = false)</code> to create a group of dependent options and positional parameters that must co-occur. For example:</p>
<p>See the <a href="https://github.com/remkop/picocli/tree/master/picocli-codegen#generate-documentation">Generate Documentation</a> section of the <a href="https://github.com/remkop/picocli/tree/master/picocli-codegen">picocli-codegen README</a> for details on how to generate and customize this documentation.</p>
10191
10200
</div>
10192
10201
<div class="paragraph">
10193
-
<p>The man pages for the picocli built-in tools were created with this tool:</p>
10202
+
<p>To see some examples, the man pages for the picocli built-in tools were created with this tool:</p>
0 commit comments