From 432e03085bbf5e4685d68e006bfee99ccbcd26ae Mon Sep 17 00:00:00 2001 From: Svjatoslav Agejenko Date: Mon, 9 Oct 2023 00:16:22 +0300 Subject: [PATCH] Updating documentation --- doc/index.org | 107 ++++++++++++++++-- .../parameter_parser/ArgumentCount.java | 15 ++- .../parameter_parser/Parameter.java | 3 + 3 files changed, 115 insertions(+), 10 deletions(-) diff --git a/doc/index.org b/doc/index.org index ea82e8d..4dde3c1 100644 --- a/doc/index.org +++ b/doc/index.org @@ -22,16 +22,109 @@ - See [[https://www3.svjatoslav.eu/projects/cli-helper/apidocs/][JavaDoc]] * Library contents -- See [[https://www3.svjatoslav.eu/projects/svjatoslav_commons/apidocs/][JavaDoc]]. +- See also: [[https://www3.svjatoslav.eu/projects/svjatoslav_commons/apidocs/][CLI Helper JavaDoc]]. -- Commandline Interface helper - : eu.svjatoslav.commons.cli_helper.CLIHelper +This library is a collection of command-line interface (CLI) helper +functions that simplifies the process of building and maintaining CLI +applications. The library provides several different functionalities, +such as: -- Commandline arguments parser and validator. - : eu.svjatoslav.commons.cli_helper.parameter_parser +- [[id:4fca35e4-fdf1-4675-a36f-6206d6fb72cb][Asking for user input]] +- Handling application command-line arguments -* Usage -Instructions to embed svjatoslav-commons in your project as a library: + +** Ask for user input +:PROPERTIES: +:ID: 4fca35e4-fdf1-4675-a36f-6206d6fb72cb +:END: + +- askBoolean() :: Asks the user to enter a boolean value (yes/no). +- 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: Maven pom.xml file snippet: diff --git a/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/ArgumentCount.java b/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/ArgumentCount.java index 1d830a3..3d8ed7f 100755 --- a/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/ArgumentCount.java +++ b/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/ArgumentCount.java @@ -6,8 +6,17 @@ package eu.svjatoslav.commons.cli_helper.parameter_parser; public enum ArgumentCount { - NONE, // parameter has no arguments - SINGLE, // parameter has one argument - MULTI // parameter can have multiple arguments + /** + * Parameter has no arguments. + */ + NONE, + /** + * Parameter has exactly one argument. + */ + SINGLE, + /** + * Parameter can have any amount of arguments. + */ + MULTI } diff --git a/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/Parameter.java b/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/Parameter.java index 92c5c81..f360ddc 100755 --- a/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/Parameter.java +++ b/src/main/java/eu/svjatoslav/commons/cli_helper/parameter_parser/Parameter.java @@ -17,6 +17,9 @@ public abstract class Parameter { */ public final String description; + /** + * List of arguments for this parameter. + */ public final List arguments = new ArrayList<>(); final ArgumentCount argumentCount; private final List aliases = new ArrayList<>(); -- 2.20.1