Add CLI arguments processing documentation

A new document has been added that details the process of command-line arguments processing. It provides information on commands, subcommands, options and parameters, and how they function. A breakdown of example command is provided for a better understanding of the process. Addition of this document helps in providing clarity for any user engaging with the application. Furthermore, it was moved from the 'index.org' to a new stand-alone document in order to improve the document structure and readability.

diff --git a/doc/CLI arguments processing.org b/doc/CLI arguments processing.org
new file mode 100644 (file)
index 0000000..2a38bee
--- /dev/null
+++ b/doc/CLI arguments processing.org
@@ -0,0 +1,94 @@
+:PROPERTIES:
+:ID:       46115263-ed3d-4acc-9ec5-523d7acf87b8
+:END:
+#+TITLE: Commandline interface arguments processing
+#+AUTHOR: Svjatoslav Agejenko
+#+LANGUAGE: en
+
+- [[id:bb4f96cd-458c-495b-a605-313b2e3e28d2][Back to CLI Helper - library main page]]
+
+* 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 # | value(s)                   | type                          |
+|------------+----------------------------+-------------------------------|
+|          0 | my-video-coder             | command                       |
+|          1 | encode                     | [[id:94242e8a-c59b-42fd-8cc7-ba3df1938119][subcommand]]                    |
+|          2 | --input                    | [[id:ffedf388-4d23-41eb-98d0-83fd3940b24d][option1]]                       |
+|    3, 4, 5 | vid1.mp4 vid2.mp4 vid3.mp4 | [[id:8a39d20c-421f-4bc7-94e4-8e561e58bea0][parameters for --input option]] |
+|          6 | --quality                  | [[id:ffedf388-4d23-41eb-98d0-83fd3940b24d][option2]]                       |
+|          7 | 5                          | [[id:8a39d20c-421f-4bc7-94e4-8e561e58bea0][option for --quaily option]] |
+
+** Subcommand
+:PROPERTIES:
+:ID:       94242e8a-c59b-42fd-8cc7-ba3df1938119
+:END:
+
+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*.
+
+** Option
+:PROPERTIES:
+:ID:       ffedf388-4d23-41eb-98d0-83fd3940b24d
+:END:
+
+Options are arguments that change the behavior of a command or
+subcommand. They usually start with a dash (-) or double dash
+(--). For instance, *--input* and *--quality* are options in our
+example command.
+
+** Parameter
+:PROPERTIES:
+:ID:       8a39d20c-421f-4bc7-94e4-8e561e58bea0
+:END:
+
+Parameter provides additional information to a command, subcommand or
+option.
+
+For instance, in our example:
+- 'vid1.mp4 vid2.mp4 vid3.mp4' are parameters for the *--input* option.
+- '5' is a parameter for the *--quality* option.
+
+* Implementation                                                   :noexport:
+
+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 option 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 option 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:

diff --git a/doc/index.org b/doc/index.org
index 4dde3c1..dde84b2 100644 (file)
--- a/doc/index.org
+++ b/doc/index.org
@@ -1,3 +1,6 @@
+:PROPERTIES:
+:ID:       bb4f96cd-458c-495b-a605-313b2e3e28d2
+:END:
 #+TITLE: CLI Helper - library to help implementing commandline interfaces
 
 * General
@@ -22,6 +25,9 @@
 - See [[https://www3.svjatoslav.eu/projects/cli-helper/apidocs/][JavaDoc]]
 
 * Library contents
+:PROPERTIES:
+:ID:       fef7ebc3-0f00-4b82-a926-c0cfdf709762
+:END:
 - See also: [[https://www3.svjatoslav.eu/projects/svjatoslav_commons/apidocs/][CLI Helper JavaDoc]].
 
 This library is a collection of command-line interface (CLI) helper
@@ -30,8 +36,7 @@ applications. The library provides several different functionalities,
 such as:
 
 - [[id:4fca35e4-fdf1-4675-a36f-6206d6fb72cb][Asking for user input]]
-- Handling application command-line arguments
-
+- [[id:46115263-ed3d-4acc-9ec5-523d7acf87b8][Commandline interface arguments processing]]
 
 ** Ask for user input
 :PROPERTIES:
@@ -42,87 +47,6 @@ such as:
 - 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: