doc/index.org

   1 #+TITLE: CLI Helper - library to help implementing commandline interfaces
   2
   3 * General
   4 - This program is free software: released under Creative Commons Zero
   5   (CC0) license
   6
   7 - Program author:
   8   - Svjatoslav Agejenko
   9   - Homepage: https://svjatoslav.eu
  10   - Email: mailto://svjatoslav@svjatoslav.eu
  11
  12 - [[https://www.svjatoslav.eu/projects/][Other software projects hosted at svjatoslav.eu]]
  13
  14 ** Source code
  15 - [[https://www2.svjatoslav.eu/gitweb/?p=cli-helper.git;a=snapshot;h=HEAD;sf=tgz][Download latest snapshot in TAR GZ format]]
  16
  17 - [[https://www2.svjatoslav.eu/gitweb/?p=cli-helper.git;a=summary][Browse Git repository online]]
  18
  19 - Clone Git repository using command:
  20   : git clone https://www2.svjatoslav.eu/git/cli-helper.git
  21
  22 - See [[https://www3.svjatoslav.eu/projects/cli-helper/apidocs/][JavaDoc]]
  23
  24 * Library contents
  25 - See also: [[https://www3.svjatoslav.eu/projects/svjatoslav_commons/apidocs/][CLI Helper JavaDoc]].
  26
  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,
  30 such as:
  31
  32 - [[id:4fca35e4-fdf1-4675-a36f-6206d6fb72cb][Asking for user input]]
  33 - Handling application command-line arguments
  34
  35
  36 ** Ask for user input
  37 :PROPERTIES:
  38 :ID:       4fca35e4-fdf1-4675-a36f-6206d6fb72cb
  39 :END:
  40
  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.
  44
  45 ** Command-line application CLI arguments processing
  46 *** Theory
  47 **** Commands and Arguments
  48
  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.
  55
  56 In the example below, 'my-video-coder' is our command, and the rest
  57 are arguments:
  58
  59 #+BEGIN_SRC shell
  60 my-video-coder encode --input vid1.mp4 vid2.mp4 vid3.mp4 --quality 5
  61 #+END_SRC
  62
  63 To better understand how these concepts work together, let's break
  64 down our example command:
  65
  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                          |
  74
  75 **** Options
  76
  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.
  80
  81 **** Parameters
  82
  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.
  87
  88 **** Positional Parameters
  89
  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
  92 positional parameter.
  93
  94 **** Subcommands
  95
  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'.
  99
 100 *** Implementation
 101
 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.
 107
 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.).
 113
 114 - `ArgumentCount` class determines if a parameter can have any amount
 115   of arguments (MULTI), exactly one argument (SINGLE), or no arguments
 116   (NONE).
 117
 118 - `Parser` class takes all these parameters and checks whether all
 119   required arguments are provided and if they match the expected
 120   format.
 121
 122 **** Usage example
 123
 124 TODO:
 125
 126 * Getting the library
 127 Instructions to embed svjatoslav-commons library in your project:
 128
 129 Maven pom.xml file snippet:
 130
 131 #+BEGIN_SRC xml
 132 <dependencies>
 133     ...
 134     <dependency>
 135         <groupId>eu.svjatoslav</groupId>
 136         <artifactId>cli-helper</artifactId>
 137         <version>1.0</version>
 138     </dependency>
 139     ...
 140 </dependencies>
 141
 142
 143 <repositories>
 144     ...
 145     <repository>
 146         <id>svjatoslav.eu</id>
 147         <name>Svjatoslav repository</name>
 148         <url>http://www3.svjatoslav.eu/maven/</url>
 149     </repository>
 150     ...
 151 </repositories>
 152 #+END_SRC