#+TITLE: CLI Helper - library to help implementing commandline interfaces

* General
- This program is free software: released under Creative Commons Zero
  (CC0) license

- Program author:
  - Svjatoslav Agejenko
  - Homepage: https://svjatoslav.eu
  - Email: mailto://svjatoslav@svjatoslav.eu

- [[https://www.svjatoslav.eu/projects/][Other software projects hosted at svjatoslav.eu]]

** Source code
- [[https://www2.svjatoslav.eu/gitweb/?p=cli-helper.git;a=snapshot;h=HEAD;sf=tgz][Download latest snapshot in TAR GZ format]]

- [[https://www2.svjatoslav.eu/gitweb/?p=cli-helper.git;a=summary][Browse Git repository online]]

- Clone Git repository using command:
  : git clone https://www2.svjatoslav.eu/git/cli-helper.git

- See [[https://www3.svjatoslav.eu/projects/cli-helper/apidocs/][JavaDoc]]

* Library contents
- See also: [[https://www3.svjatoslav.eu/projects/svjatoslav_commons/apidocs/][CLI Helper JavaDoc]].

This library is a collection of command-line interface (CLI) helper
functions that simplifies the process of building and maintaining CLI
applications. The library provides several different functionalities,
such as:

- [[id:4fca35e4-fdf1-4675-a36f-6206d6fb72cb][Asking for user input]]
- Handling application command-line arguments


** Ask for user input
:PROPERTIES:
:ID:       4fca35e4-fdf1-4675-a36f-6206d6fb72cb
:END:

- askBoolean() :: Asks the user to enter a boolean value (yes/no).
- askLong() :: Asks the user to enter an integer.
- askString() :: Asks the user to enter a string.

** Command-line application CLI arguments processing
*** Theory
**** Commands and Arguments

Every command-line application has a way of receiving input from
users, usually in the form of command-line arguments. A command-line
argument is a piece of information provided to the command-line
application when it's invoked. These arguments are provided as an
array of strings. The first element of the array (argument 0) is
typically the name of the command itself.

In the example below, 'my-video-coder' is our command, and the rest
are arguments:

#+BEGIN_SRC shell
my-video-coder encode --input vid1.mp4 vid2.mp4 vid3.mp4 --quality 5
#+END_SRC

To better understand how these concepts work together, let's break
down our example command:

| argument # | type                   | values                     |
|------------+------------------------+----------------------------|
|          0 | command                | my-video-coder             |
|          1 | subcommand             | encode                     |
|          2 | option1                | --input                    |
|    3, 4, 5 | parameters for option1 | vid1.mp4 vid2.mp4 vid3.mp4 |
|          6 | option2                | --quality                  |
|          7 | parameters for option2 | 5                          |

**** Options

Options are arguments that change the behavior of a command. They
usually start with a dash (-) or double dash (--). For instance,
'--input' and '--quality' are options in our example command.

**** Parameters

A parameter provides additional information to a command or
option. For instance, 'vid1.mp4 vid2.mp4 vid3.mp4' are parameters for
the '--input' option, and '5' is a parameter for the '--quality'
option in our example command.

**** Positional Parameters

These are the arguments that follow the command and are usually
required for the command to execute. In our example, 'encode' is a
positional parameter.

**** Subcommands

Subcommands are more specific actions that a command can perform. They
are often used with commands that have multiple functions. In our
example, 'encode' is a subcommand of 'my-video-coder'.

*** Implementation

Parsing Command-line Arguments:
- `Parameter` class is used for defining parameters with their
  descriptions, types, and aliases. It also keeps track of whether the
  specific parameter was present in the command line or not. This
  information is used later in the processing.

  - `DirectoryParameter`, `FileParameter`, `IntegerParameter`,
    `StringParameter`, `NullParameter`, and `StringParameters` are
    examples of Parameter classes, each one having unique
    characteristics for handling specific types of parameters
    (directories, files, integers, strings, etc.).

- `ArgumentCount` class determines if a parameter can have any amount
  of arguments (MULTI), exactly one argument (SINGLE), or no arguments
  (NONE).

- `Parser` class takes all these parameters and checks whether all
  required arguments are provided and if they match the expected
  format.

**** Usage example

TODO:

* Getting the library
Instructions to embed svjatoslav-commons library in your project:

Maven pom.xml file snippet:

#+BEGIN_SRC xml
<dependencies>
    ...
    <dependency>
        <groupId>eu.svjatoslav</groupId>
        <artifactId>cli-helper</artifactId>
        <version>1.0</version>
    </dependency>
    ...
</dependencies>


<repositories>
    ...
    <repository>
        <id>svjatoslav.eu</id>
        <name>Svjatoslav repository</name>
        <url>http://www3.svjatoslav.eu/maven/</url>
    </repository>
    ...
</repositories>
#+END_SRC