doc/CLI arguments processing.org

   1 :PROPERTIES:
   2 :ID:       46115263-ed3d-4acc-9ec5-523d7acf87b8
   3 :END:
   4 #+TITLE: Commandline interface arguments processing
   5 #+AUTHOR: Svjatoslav Agejenko
   6 #+LANGUAGE: en
   7
   8 - [[id:bb4f96cd-458c-495b-a605-313b2e3e28d2][Back to CLI Helper - library main page]]
   9
  10 * Theory
  11 ** Commands and Arguments
  12
  13 Every command-line application has a way of receiving input from
  14 users, usually in the form of command-line arguments. A command-line
  15 argument is a piece of information provided to the command-line
  16 application when it's invoked. These arguments are provided as an
  17 array of strings. The first element of the array (argument 0) is
  18 typically the name of the command itself.
  19
  20 In the example below, 'my-video-coder' is our command, and the rest
  21 are arguments:
  22
  23 #+BEGIN_SRC shell
  24 my-video-coder encode --input vid1.mp4 vid2.mp4 vid3.mp4 --quality 5
  25 #+END_SRC
  26
  27 To better understand how these concepts work together, let's break
  28 down our example command:
  29
  30 | argument # | value(s)                   | type                          |
  31 |------------+----------------------------+-------------------------------|
  32 |          0 | my-video-coder             | command                       |
  33 |          1 | encode                     | [[id:94242e8a-c59b-42fd-8cc7-ba3df1938119][subcommand]]                    |
  34 |          2 | --input                    | [[id:ffedf388-4d23-41eb-98d0-83fd3940b24d][option1]]                       |
  35 |    3, 4, 5 | vid1.mp4 vid2.mp4 vid3.mp4 | [[id:8a39d20c-421f-4bc7-94e4-8e561e58bea0][parameters for --input option]] |
  36 |          6 | --quality                  | [[id:ffedf388-4d23-41eb-98d0-83fd3940b24d][option2]]                       |
  37 |          7 | 5                          | [[id:8a39d20c-421f-4bc7-94e4-8e561e58bea0][option for --quaily option]] |
  38
  39 ** Subcommand
  40 :PROPERTIES:
  41 :ID:       94242e8a-c59b-42fd-8cc7-ba3df1938119
  42 :END:
  43
  44 Subcommands are more specific actions that a command can perform. They
  45 are often used with commands that have multiple functions. In our
  46 example, *encode* is a subcommand of *my-video-coder*.
  47
  48 ** Option
  49 :PROPERTIES:
  50 :ID:       ffedf388-4d23-41eb-98d0-83fd3940b24d
  51 :END:
  52
  53 Options are arguments that change the behavior of a command or
  54 subcommand. They usually start with a dash (-) or double dash
  55 (--). For instance, *--input* and *--quality* are options in our
  56 example command.
  57
  58 ** Parameter
  59 :PROPERTIES:
  60 :ID:       8a39d20c-421f-4bc7-94e4-8e561e58bea0
  61 :END:
  62
  63 Parameter provides additional information to a command, subcommand or
  64 option.
  65
  66 For instance, in our example:
  67 - 'vid1.mp4 vid2.mp4 vid3.mp4' are parameters for the *--input* option.
  68 - '5' is a parameter for the *--quality* option.
  69
  70 * Implementation                                                   :noexport:
  71
  72 Parsing Command-line Arguments:
  73 - `Parameter` class is used for defining parameters with their
  74   descriptions, types, and aliases. It also keeps track of whether the
  75   specific option was present in the command line or not. This
  76   information is used later in the processing.
  77
  78   - `DirectoryParameter`, `FileParameter`, `IntegerParameter`,
  79     `StringParameter`, `NullParameter`, and `StringParameters` are
  80     examples of Parameter classes, each one having unique
  81     characteristics for handling specific types of parameters
  82     (directories, files, integers, strings, etc.).
  83
  84 - `ArgumentCount` class determines if a option can have any amount
  85   of arguments (MULTI), exactly one argument (SINGLE), or no arguments
  86   (NONE).
  87
  88 - `Parser` class takes all these parameters and checks whether all
  89   required arguments are provided and if they match the expected
  90   format.
  91
  92 ** Usage example
  93
  94 TODO: