From 903de64c152e7eeb53dc092f4180f726f599cb81 Mon Sep 17 00:00:00 2001 From: Rayan Levert Date: Sat, 17 Aug 2024 08:01:08 +0200 Subject: [PATCH] Re-adding deleted README.md by accident --- src/README.md | 202 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 202 insertions(+) create mode 100644 src/README.md diff --git a/src/README.md b/src/README.md new file mode 100644 index 0000000..caa4a2f --- /dev/null +++ b/src/README.md @@ -0,0 +1,202 @@ +## Dependency-free command line interface (CLI) handling arguments and easily personalizing output in the PHP userland + +[![Packagist Version](https://img.shields.io/packagist/v/rayanlevert/command-line-interface)](https://packagist.org/packages/rayanlevert/command-line-interface) +[![PHP from Packagist](https://img.shields.io/packagist/php-v/rayanlevert/command-line-interface)](https://packagist.org/packages/rayanlevert/command-line-interface) +[![codecov](https://codecov.io/gh/rayanlevert/command-line-interface/branch/main/graph/badge.svg)](https://codecov.io/gh/rayanlevert/command-line-interface) + +### **RayanLevert\Cli\Arguments\Argument** defines what is an Argument +An argument has a name and different options and can only be of type `integer`, `double` ou `string` (if the option `noValue` is used, it will be `bool`) + +```php +new \RayanLevert\Cli\Arguments\Argument(string $name, array $options = []) +``` + +``` +- description (string) Description of the argument +- defaultValue (float|int|string) Default value if the argument is not handled +- required (bool) If the argument must be present and parsed +- castTo (string) PHP type - If the argument has a type other than string, its value will be casted +- noValue (bool) If a prefixed argument doesn't need a value -> boolean cast +- prefix (string) Short prefix (-u) +- longPrefix (string) Long prefix (--user) +``` + +A `RayanLevert\Cli\Arguments\Exception` can be thrown if options are not compliant (see `__construct()`) + +### **RayanLevert\Cli\Arguments** is a collection of Argument capable of parsing values from `argv` (array of strings) + +```php +new \RayanLevert\Cli\Arguments(\RayanLevert\Cli\Arguments\Argument ...$oArguments) +``` + +> Required arguments must be declared first, before not required ones + +#### Recovery of parsed values is done via the method `parse(string ...$arguments): void` +> To parse arguments from the actual CLI, use `parse(...$argv)` (with declaring `global $argv;` if you are not in the global scope) + +Associates each parsed value to its Argument in the collection + +The parsed value of an argument is recoverable by `::get(string $argumentName)` + +By default, `NULL` is returned; `integer`, `float` or `string` can be returned if the argument has been parsed and option `castTo` has been set + +- If castTo is `integer` or `float`, the value must be a numeric string (asserts with `is_numeric()`) +- Si castTo is `string` (by default), the value will be the one parsed + +### Implementation +```php +$oArguments = new Arguments(new Argument('arg1')); +$oArguments->get('arg1') // NULL + +$oArguments = new Arguments(new Argument('arg1', ['defaultValue' => 'test'])); +$oArguments->get('arg1') // test + +$oArguments = new Arguments(new Argument('arg1', ['castTo' => 'float', 'defaultValue' => 14.3])); +$oArguments->get('arg1') // 14.3 + +$oArguments = new Arguments(new Argument('arg1', ['required' => true])); +$oArguments->parse(); // ParseException arg1 is required +$oArguments->parse('test'); // OK $oArguments->get('arg1') = test + +// Parsing optional arguments +$oArguments = new Arguments(new Argument('arg1'), new Argument('arg2')); +$oArguments->parse('test1'); // $oArguments->get('arg1') = test1, $oArguments->get('arg1') = NULL +$oArguments->parse('test1', 'test2'); // $oArguments->get('arg1') = test1, $oArguments->get('arg1') = test2 + +// Parsing prefixed arguments +$oArguments = new Arguments(new Argument('arg1', ['prefix' => 'a', 'longPrefix' => 'arg'])); +$oArguments->parse('-a=testValue'); // $oArguments->get('arg1') = testValue +$oArguments->parse('-a="test Value"'); // $oArguments->get('arg1') = test Value +$oArguments->parse('--arg=testValue'); // $oArguments->get('arg1') = testValue +$oArguments->parse('--arg="test Value"'); // $oArguments->get('arg1') = test Value +``` + +### Multiple methods are available + +- Adds an argument - `set(Argument $oArgument): void` +- Removes one - `remove(string $argumentName): void` +- Returns the number of arguments `count(): int` +- Prints a clean display about the informations of arguments `printArguments(): void` + ``` + Required arguments: + arg1 (type: string) + arg2 (type: integer) + + Optional arguments: + arg3 --arg3=arg3 (type: integer) + arg4 -arg4 + ``` + +## Personalizes the command line interface by changing the color and formatting displayed text + +### **RayanLevert\Cli\Style** is a class that only has static methods + +3 enumerations are available to stylize the output: + +- `RayanLevert\Cli\Style\Background`: Background colors +- `RayanLevert\Cli\Style\Foreground`: Text colors +- `RayanLevert\Cli\Style\Attributes`: Text attributes + +2 main methods are used to display formatted text + +```php +/** + * Prints a string of a background color, text color and/or an attribute +*/ +public static function inline(string $string, Background $bg = null, Foreground $fg = null, Attribute $at = null): void; + +/** + * Prints a string and breaks a line of a background color, text color and/or an attribute +*/ +public static function outline(string $string, Background $bg = null, Foreground $fg = null, Attribute $at = null): void; +``` + +And one to return the formatted string instead of printing it +```php +public static function stylize(string $string, Background $bg = null, Foreground $fg = null, Attribute $at = null): string; +``` + +Other useful methods are available: + +```php +/** + * Prints a formatted string thanks to its tags of ANSI codes (Foreground, Background and Attribute) + * + * Useful is you want to use multiple styles in one single method call + * + * Tags to use are in the three enumerations thanks to the 'tryFromTag' method +*/ +public static function tag(string $tag): void + +==================================== +｡◕‿◕｡ This is a title ｡◕‿◕｡ +==================================== +public static function title(string $title): void; + +--- Flanked message ---\n +public static function flank(string $message, string $char = '-', int $length = 3): void; + + (◍•﹏•) Warning message\n +public static function warning(string $message): void; // colored text in yellow + + (◍•﹏•) Error message\n +public static function error(string $message): void; // colored text in red + +public static function red(string $message): void; // displays a red colored text and breaks a line +public static function green(string $message): void; // displays a green colored text and breaks a line +public static function yellow(string $message): void; // displays a yellow colored text and breaks a line + +// Displays according to a boolean status, a red or green text colored message and breaks a line +public static function outlineWithBool(bool $status, string $ifTrue, string $ifFalse, string $toPrecede = ''): void; + +// Prints the details of an exception in red + its trace in white +public static function exception(\Exception $e, bool $withoutTrace = false): void; +``` + +### **RayanLevert\Cli\ProgressBar displays progression output through a progress bar** + +```php +/** + * @param int $max Maximum value of iterations + * @param int $numberOfSymbols Number of symbols added after each iteration +*/ +$oProgressBar = new ProgressBar(int $max, int $numberOfSymbols = 50); + +/** + * @param string $title Title to add above the progress bar + * @param Style\Foreground $fg Text color +*/ +$oProgressBar->setTitle(string $title = '', Style\Foreground $fg = Style\Foreground::BLUE); + +/** + * Starts the progress bar (or restarts it, if not breaks two lines) +*/ +$oProgressBar->start(); + +/** + * Advances the progress bar of `$toAdvance` iterations updating the progression +*/ +$oProgressBar->advance(int $toAdvance = 1); + +// Finishes the progress bar (advances to the max value) +$oProgressBar->finish(); +``` + +### Simple implementation + +```php +// 10 is the max value -> a new symbol every new iteration +$oProgressBar = new ProgressBar(10); +$oProgressBar->start('My progress bar'); + +// Advances to 1 each iteration +foreach (range(1, 10) as $range) { + $oProgressBar->advance(); +} + + My progress bar + 1 / 10 [# ] + 2 / 10 [## ] + ... + 10 / 10 [##########] +``` \ No newline at end of file