Add CLI arguments processing documentation

[cli-helper.git] / doc / CLI arguments processing.org

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: