1 #+TITLE: CLI Helper - library to help implementing commandline interfaces
4 - This program is free software: released under Creative Commons Zero
9 - Homepage: https://svjatoslav.eu
10 - Email: mailto://svjatoslav@svjatoslav.eu
12 - [[https://www.svjatoslav.eu/projects/][Other software projects hosted at svjatoslav.eu]]
15 - [[https://www2.svjatoslav.eu/gitweb/?p=cli-helper.git;a=snapshot;h=HEAD;sf=tgz][Download latest snapshot in TAR GZ format]]
17 - [[https://www2.svjatoslav.eu/gitweb/?p=cli-helper.git;a=summary][Browse Git repository online]]
19 - Clone Git repository using command:
20 : git clone https://www2.svjatoslav.eu/git/cli-helper.git
22 - See [[https://www3.svjatoslav.eu/projects/cli-helper/apidocs/][JavaDoc]]
25 - See also: [[https://www3.svjatoslav.eu/projects/svjatoslav_commons/apidocs/][CLI Helper JavaDoc]].
27 This library is a collection of command-line interface (CLI) helper
28 functions that simplifies the process of building and maintaining CLI
29 applications. The library provides several different functionalities,
32 - [[id:4fca35e4-fdf1-4675-a36f-6206d6fb72cb][Asking for user input]]
33 - Handling application command-line arguments
38 :ID: 4fca35e4-fdf1-4675-a36f-6206d6fb72cb
41 - askBoolean() :: Asks the user to enter a boolean value (yes/no).
42 - askLong() :: Asks the user to enter an integer.
43 - askString() :: Asks the user to enter a string.
45 ** Command-line application CLI arguments processing
47 **** Commands and Arguments
49 Every command-line application has a way of receiving input from
50 users, usually in the form of command-line arguments. A command-line
51 argument is a piece of information provided to the command-line
52 application when it's invoked. These arguments are provided as an
53 array of strings. The first element of the array (argument 0) is
54 typically the name of the command itself.
56 In the example below, 'my-video-coder' is our command, and the rest
60 my-video-coder encode --input vid1.mp4 vid2.mp4 vid3.mp4 --quality 5
63 To better understand how these concepts work together, let's break
64 down our example command:
66 | argument # | type | values |
67 |------------+------------------------+----------------------------|
68 | 0 | command | my-video-coder |
69 | 1 | subcommand | encode |
70 | 2 | option1 | --input |
71 | 3, 4, 5 | parameters for option1 | vid1.mp4 vid2.mp4 vid3.mp4 |
72 | 6 | option2 | --quality |
73 | 7 | parameters for option2 | 5 |
77 Options are arguments that change the behavior of a command. They
78 usually start with a dash (-) or double dash (--). For instance,
79 '--input' and '--quality' are options in our example command.
83 A parameter provides additional information to a command or
84 option. For instance, 'vid1.mp4 vid2.mp4 vid3.mp4' are parameters for
85 the '--input' option, and '5' is a parameter for the '--quality'
86 option in our example command.
88 **** Positional Parameters
90 These are the arguments that follow the command and are usually
91 required for the command to execute. In our example, 'encode' is a
96 Subcommands are more specific actions that a command can perform. They
97 are often used with commands that have multiple functions. In our
98 example, 'encode' is a subcommand of 'my-video-coder'.
102 Parsing Command-line Arguments:
103 - `Parameter` class is used for defining parameters with their
104 descriptions, types, and aliases. It also keeps track of whether the
105 specific parameter was present in the command line or not. This
106 information is used later in the processing.
108 - `DirectoryParameter`, `FileParameter`, `IntegerParameter`,
109 `StringParameter`, `NullParameter`, and `StringParameters` are
110 examples of Parameter classes, each one having unique
111 characteristics for handling specific types of parameters
112 (directories, files, integers, strings, etc.).
114 - `ArgumentCount` class determines if a parameter can have any amount
115 of arguments (MULTI), exactly one argument (SINGLE), or no arguments
118 - `Parser` class takes all these parameters and checks whether all
119 required arguments are provided and if they match the expected
126 * Getting the library
127 Instructions to embed svjatoslav-commons library in your project:
129 Maven pom.xml file snippet:
135 <groupId>eu.svjatoslav</groupId>
136 <artifactId>cli-helper</artifactId>
137 <version>1.0</version>
146 <id>svjatoslav.eu</id>
147 <name>Svjatoslav repository</name>
148 <url>http://www3.svjatoslav.eu/maven/</url>