From 4b29e666b06762b4b36438c9370c38bc43121f78 Mon Sep 17 00:00:00 2001 From: Kasimir Cash Date: Wed, 28 Feb 2024 12:23:28 +0000 Subject: Command Line Parser Concept (#6099) * Adds logic for validation * Adds validation to do-install * Adds help to do-install * Adds validation & help to reconfigure * Adds validation to check.translation * Adds validation to manipulate.translation * Small fixes to help texts * Refactors language option validation * Adds default options to validation * Fixes validation with regex * Refactors readAs functions * Updates to new regex validation format * Fixes typing around default values * Adds file extension validation * Restandardises validation & parsing typing around array of strings * Adds NotOneOf validation * Adds ArrayOfString read as * Refactors existing validation * Adds validation throughout cli * Removes unused file * Adds new CL parser with goal of wrapping CLI behaviour * Hides parsing and validation * Rewites CL parser to make better use of classes * Rolls out new parser across CL * Fixes error during unknown option check * Fixes misnamed property calls * Seperates validations into more appropriate locations * Adds common boolean forms to validation * Moves CommandLineParser and Option classes into their own files * Fixes error when validating Int type * Rewrites appendTypedValues -> appendTypedValidValues now filters invalid values from output * Renames -> for clarity * Adds some docs clarifying option defaults and value taking behaviour * Refactors getUsageMessage for readability * Minor formatting changes * Adds tests for CommandLineParser * Adds more tests * Adds minor fixs * Reconfigure now correctly updates config * More fixes to reconfigure * Fixes required files for CommandLineParserTest * Use .php extension for PHP file * PHPStan ignore instead of wrong typing * Refactors to support php 7.4 * Moves away from dynamic properties by adding 'Definintions' to all commands * Renames target to definition for clarity * Stops null from being returned as a valid value in a certain edge case * Adds PHPStan ignore instead of incorrect typing * Refactors tests to take account of new typing solution * Marks file as executable * Draft CLI rework * Finish rewrite as object-oriented * Fix PHPStan ignore and make more strongly typed * Rename class Option to CliOption * Light renaming + anonymous classes --------- Co-authored-by: Alexandre Alapetite --- cli/CliOptionsParser.php | 247 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 247 insertions(+) create mode 100644 cli/CliOptionsParser.php (limited to 'cli/CliOptionsParser.php') diff --git a/cli/CliOptionsParser.php b/cli/CliOptionsParser.php new file mode 100644 index 000000000..be325bd91 --- /dev/null +++ b/cli/CliOptionsParser.php @@ -0,0 +1,247 @@ + */ + private array $options = []; + /** @var array */ + private array $inputs = []; + /** @var array $errors */ + public array $errors = []; + public string $usage = ''; + + public function __construct() { + global $argv; + + $this->usage = $this->getUsageMessage($argv[0]); + + $this->parseInput(); + $this->appendUnknownAliases($argv); + $this->appendInvalidValues(); + $this->appendTypedValidValues(); + } + + private function parseInput(): void { + $getoptInputs = $this->getGetoptInputs(); + $this->getoptOutputTransformer(getopt($getoptInputs['short'], $getoptInputs['long'])); + $this->checkForDeprecatedAliasUse(); + } + + /** Adds an option that produces an error message if not set. */ + protected function addRequiredOption(string $name, CliOption $option): void { + $this->inputs[$name] = [ + 'defaultInput' => null, + 'required' => true, + 'aliasUsed' => null, + 'values' => null, + ]; + $this->options[$name] = $option; + } + + /** + * Adds an optional option. + * @param string $defaultInput If not null this value is received as input in all cases where no + * user input is present. e.g. set this if you want an option to always return a value. + */ + protected function addOption(string $name, CliOption $option, string $defaultInput = null): void { + $this->inputs[$name] = [ + 'defaultInput' => is_string($defaultInput) ? [$defaultInput] : $defaultInput, + 'required' => null, + 'aliasUsed' => null, + 'values' => null, + ]; + $this->options[$name] = $option; + } + + private function appendInvalidValues(): void { + foreach ($this->options as $name => $option) { + if ($this->inputs[$name]['required'] && $this->inputs[$name]['values'] === null) { + $this->errors[$name] = 'invalid input: ' . $option->getLongAlias() . ' cannot be empty'; + } + } + + foreach ($this->inputs as $name => $input) { + foreach ($input['values'] ?? $input['defaultInput'] ?? [] as $value) { + switch ($this->options[$name]->getTypes()['type']) { + case 'int': + if (!ctype_digit($value)) { + $this->errors[$name] = 'invalid input: ' . $input['aliasUsed'] . ' must be an integer'; + } + break; + case 'bool': + if (filter_var($value, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE) === null) { + $this->errors[$name] = 'invalid input: ' . $input['aliasUsed'] . ' must be a boolean'; + } + break; + } + } + } + } + + private function appendTypedValidValues(): void { + foreach ($this->inputs as $name => $input) { + $values = $input['values'] ?? $input['defaultInput'] ?? null; + $types = $this->options[$name]->getTypes(); + if ($values) { + $validValues = []; + $typedValues = []; + + switch ($types['type']) { + case 'string': + $typedValues = $values; + break; + case 'int': + $validValues = array_filter($values, static fn($value) => ctype_digit($value)); + $typedValues = array_map(static fn($value) => (int) $value, $validValues); + break; + case 'bool': + $validValues = array_filter($values, static fn($value) => filter_var($value, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE) !== null); + $typedValues = array_map(static fn($value) => (bool) filter_var($value, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE), $validValues); + break; + } + + if (!empty($typedValues)) { + // @phpstan-ignore-next-line (change to `@phpstan-ignore property.dynamicName` when upgrading to PHPStan 1.11+) + $this->$name = $types['isArray'] ? $typedValues : array_pop($typedValues); + } + } + } + } + + /** @param array|false $getoptOutput */ + private function getoptOutputTransformer($getoptOutput): void { + $getoptOutput = is_array($getoptOutput) ? $getoptOutput : []; + + foreach ($getoptOutput as $alias => $value) { + foreach ($this->options as $name => $data) { + if (in_array($alias, $data->getAliases(), true)) { + $this->inputs[$name]['aliasUsed'] = $alias; + $this->inputs[$name]['values'] = $value === false + ? [$data->getOptionalValueDefault()] + : (is_array($value) + ? $value + : [$value]); + } + } + } + } + + /** + * @param array $userInputs + * @return array + */ + private function getAliasesUsed(array $userInputs, string $regex): array { + $foundAliases = []; + + foreach ($userInputs as $input) { + preg_match($regex, $input, $matches); + + if(!empty($matches['short'])) { + $foundAliases = array_merge($foundAliases, str_split($matches['short'])); + } + if(!empty($matches['long'])) { + $foundAliases[] = $matches['long']; + } + } + + return $foundAliases; + } + + /** + * @param array $input List of user command-line inputs. + */ + private function appendUnknownAliases(array $input): void { + $valid = []; + foreach ($this->options as $option) { + $valid = array_merge($valid, $option->getAliases()); + } + + $sanitizeInput = $this->getAliasesUsed($input, $this->makeInputRegex()); + $unknownAliases = array_diff($sanitizeInput, $valid); + if (empty($unknownAliases)) { + return; + } + + foreach ($unknownAliases as $unknownAlias) { + $this->errors[$unknownAlias] = 'unknown option: ' . $unknownAlias; + } + } + + /** + * Checks for presence of deprecated aliases. + * @return bool Returns TRUE and generates a deprecation warning if deprecated aliases are present, FALSE otherwise. + */ + private function checkForDeprecatedAliasUse(): bool { + $deprecated = []; + $replacements = []; + + foreach ($this->inputs as $name => $data) { + if ($data['aliasUsed'] !== null && $data['aliasUsed'] === $this->options[$name]->getDeprecatedAlias()) { + $deprecated[] = $this->options[$name]->getDeprecatedAlias(); + $replacements[] = $this->options[$name]->getLongAlias(); + } + } + + if (empty($deprecated)) { + return false; + } + + fwrite(STDERR, "FreshRSS deprecation warning: the CLI option(s): " . implode(', ', $deprecated) . + " are deprecated and will be removed in a future release. Use: " . implode(', ', $replacements) . + " instead\n"); + return true; + } + + /** @return array{long:array,short:string}*/ + private function getGetoptInputs(): array { + $getoptNotation = [ + 'none' => '', + 'required' => ':', + 'optional' => '::', + ]; + + $long = []; + $short = ''; + + foreach ($this->options as $option) { + $long[] = $option->getLongAlias() . $getoptNotation[$option->getValueTaken()]; + $long[] = $option->getDeprecatedAlias() ? $option->getDeprecatedAlias() . $getoptNotation[$option->getValueTaken()] : ''; + $short .= $option->getShortAlias() ? $option->getShortAlias() . $getoptNotation[$option->getValueTaken()] : ''; + } + + return [ + 'long' => array_filter($long), + 'short' => $short + ]; + } + + private function getUsageMessage(string $command): string { + $required = ['Usage: ' . basename($command)]; + $optional = []; + + foreach ($this->options as $name => $option) { + $shortAlias = $option->getShortAlias() ? '-' . $option->getShortAlias() . ' ' : ''; + $longAlias = '--' . $option->getLongAlias() . ($option->getValueTaken() === 'required' ? '=<' . strtolower($name) . '>' : ''); + if ($this->inputs[$name]['required']) { + $required[] = $shortAlias . $longAlias; + } else { + $optional[] = '[' . $shortAlias . $longAlias . ']'; + } + } + + return implode(' ', $required) . ' ' . implode(' ', $optional); + } + + private function makeInputRegex() : string { + $shortWithValues = ''; + foreach ($this->options as $option) { + if (($option->getValueTaken() === 'required' || $option->getValueTaken() === 'optional') && $option->getShortAlias()) { + $shortWithValues .= $option->getShortAlias(); + } + } + + return $shortWithValues === '' + ? "/^--(?'long'[^=]+)|^-(?\w+)/" + : "/^--(?'long'[^=]+)|^-(?(?(?=\w*[$shortWithValues])[^$shortWithValues]*[$shortWithValues]|\w+))/"; + } +} -- cgit v1.2.3