From 2c29a140b3ff6f0f60ac838437c4bd9b8fd6dad7 Mon Sep 17 00:00:00 2001 From: Svjatoslav Agejenko Date: Thu, 12 Oct 2023 22:36:14 +0300 Subject: [PATCH] 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. --- doc/CLI arguments processing.org | 94 ++++++++++++++++++++++++++++++++ doc/index.org | 90 +++--------------------------- 2 files changed, 101 insertions(+), 83 deletions(-) create mode 100644 doc/CLI arguments processing.org diff --git a/doc/CLI arguments processing.org b/doc/CLI arguments processing.org new file mode 100644 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 --- 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: -- 2.20.1