Add basic usage documentation generation

Author: cracksalad

psalm.baseline.xml

@@ -1,8 +1,13 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<files psalm-version="5.18.0@b113f3ed0259fd6e212d87c3df80eec95a6abf19">
+<files psalm-version="6.13.1@1e3b7f0a8ab32b23197b91107adc0a7ed8a05b51">
   <file src="src/CLIParser.php">
     <InvalidPropertyAssignmentValue>
-      <code>$allowedOptions</code>
+      <code><![CDATA[$allowedOptions]]></code>
     </InvalidPropertyAssignmentValue>
+    <RiskyTruthyFalsyComparison>
+      <code><![CDATA[empty($opt['value'])]]></code>
+      <code><![CDATA[empty($option['value'])]]></code>
+      <code><![CDATA[empty($this->allowedOptions)]]></code>
+    </RiskyTruthyFalsyComparison>
   </file>
 </files>

rector.php

@@ -4,6 +4,7 @@
 use Rector\Config\RectorConfig;
 use Rector\ValueObject\PhpVersion;
 use Rector\Set\ValueObject\LevelSetList;
+use Rector\Php80\Rector\Class_\ClassPropertyAssignToConstructorPromotionRector;
 
 return static function (RectorConfig $rectorConfig): void {
   $rectorConfig->paths([
@@ -16,4 +17,8 @@
   $rectorConfig->sets([
     LevelSetList::UP_TO_PHP_80
   ]);
+  
+  $rectorConfig->skip([
+    ClassPropertyAssignToConstructorPromotionRector::class
+  ]);
 };

src/CLIParser.php

@@ -10,17 +10,24 @@ final class CLIParser {
 
   /**
    * @var string[]
+   * @readonly
    * @psalm-var list<string>
    */
   private array $args;
+  /**
+   * @readonly
+   */
+  private string $optionsString;
   /**
    * @psalm-var null|list<string>|array<string, array{
    *    filter: int,
    *    flags?: int,
    *    options?: array{
    *      default?: scalar,
    *      ...
-   *    }
+   *    },
+   *    value_label?: string,
+   *    description?: string
    *  }>
    */
   private ?array $allowedOptions = null;
@@ -52,10 +59,11 @@ final class CLIParser {
   /**
    * @param string[] $args e.g. $_SERVER['argv']
    * @psalm-param list<string> $args
+   * @param string $optionsString will be printed inside usage documentation right after the script name and should contain e.g. `--in=<file> [--out=<file>]` 
    */
-  public function __construct(array $args) {
-    array_shift($args);
+  public function __construct(array $args, string $optionsString = '') {
     $this->args = $args;
+    $this->optionsString = $optionsString;
   }
 
   /**
@@ -68,7 +76,9 @@ public function __construct(array $args) {
    *    options?: array{
    *      default?: scalar,
    *      ...
-   *    }
+   *    },
+   *    value_label?: string,
+   *    description?: string
    *  }> $allowedOptions
    * @see https://www.php.net/manual/en/function.filter-var-array.php
    */
@@ -109,6 +119,61 @@ public function setStrictMode(bool $strictMode): void {
     $this->strictMode = $strictMode;
   }
 
+  public function printUsage(): void {
+    $usage = "\e[33mUsage:\e[0m".PHP_EOL;
+    $script = $_SERVER['argv'][0] ?? 'script.php';
+    $usage .= 'php '.$script.' '.$this->optionsString.PHP_EOL.PHP_EOL;
+    if(!empty($this->allowedOptions)){
+      $usage .= "\e[33mOptions:\e[0m".PHP_EOL;
+      $isList = array_is_list($this->allowedOptions);
+      $options = [];
+      foreach($this->allowedOptions as $key => $option){
+        if($isList){
+          /**
+           * @var string $option
+           * @var string|false $flag
+           */
+          $flag = array_search($option, $this->allowedFlags ?? [], true);
+          $options[] = [
+            'name' => $option,
+            'flag' => $flag,
+            'value' => '',
+            'description' => '',
+            'default' => null
+          ];
+        } else {
+          /**
+           * @var string $key
+           * @var string|false $flag
+           */
+          $flag = array_search($key, $this->allowedFlags ?? [], true);
+          $options[] = [
+            'name' => $key,
+            'flag' => $flag,
+            'value' => $option['value_label'] ?? '',
+            'description' => $option['description'] ?? '',
+            'default' => $option['options']['default'] ?? null
+          ];
+        }
+      }
+      $maxLength = 0;
+      foreach($options as $key => $opt){
+        $len = strlen(($opt['flag'] === false ? '' : '-'.$opt['flag'].', ').'--'.$opt['name'].(empty($opt['value']) ? '' : '=<'.$opt['value'].'>'));
+        $options[$key]['length'] = $len;
+        if($maxLength < $len){
+          $maxLength = $len;
+        }
+      }
+      foreach($options as $option){
+        $padding = str_pad(' ', $maxLength + 2 - $option['length']);
+        $usage .= "  \e[32m".($option['flag'] === false ? '' : '-'.$option['flag'].', ').'--'.$option['name']."\e[0m".(empty($option['value']) ? '' : "=<\e[34m".$option['value']."\e[0m>").
+            $padding.$option['description'].($option['default'] === null ? '' : " DEFAULT: \e[34m".strval($option['default'])."\e[0m").PHP_EOL;
+      }
+      $usage .= PHP_EOL;
+    }
+    echo $usage;
+  }
+  
   private function validateOption(string $option, ?string $value): bool {
     if($this->allowedOptions === null || (array_is_list($this->allowedOptions) && in_array($option, $this->allowedOptions))){
       $this->options[$option] = $value ?? true;
@@ -171,7 +236,9 @@ public function parse(): bool {
     }
 
     $endofoptions = false;
-    while(($arg = array_shift($this->args)) !== null){
+    $args = $this->args;
+    array_shift($args);
+    while(($arg = array_shift($args)) !== null){
       if($endofoptions){    // if we have reached end of options, we cast all remaining argvs as arguments
         $this->arguments[] = $arg;
 
@@ -186,12 +253,12 @@ public function parse(): bool {
           if($equalPos !== false){    // is it the syntax '--option=value'?
             $value = mb_substr($option, $equalPos + 1);
             $option = mb_substr($option, 0, $equalPos);
-          } else if(($this->args[0][0] ?? '-') !== '-'){  // is the option not followed by another option/flag but by arguments
-            while(($this->args[0][0] ?? '-') !== '-'){
+          } else if(($args[0][0] ?? '-') !== '-'){  // is the option not followed by another option/flag but by arguments
+            while(($args[0][0] ?? '-') !== '-'){
               /**
                * @psalm-suppress PossiblyNullOperand
                */
-              $value .= array_shift($this->args).' ';
+              $value .= array_shift($args).' ';
             }
             $value = rtrim($value, ' ');
           }
@@ -222,13 +289,13 @@ public function parse(): bool {
           $value = null;
           if($chr === '='){    // is it the syntax '-f=value'?
             $value = mb_substr($arg, $i + 1);
-          } else if(($this->args[0][0] ?? '-') !== '-'){  // is the flag not followed by another option/flag but by arguments
+          } else if(($args[0][0] ?? '-') !== '-'){  // is the flag not followed by another option/flag but by arguments
             $value = '';
-            while(($this->args[0][0] ?? '-') !== '-'){
+            while(($args[0][0] ?? '-') !== '-'){
               /**
                * @psalm-suppress PossiblyNullOperand
                */
-              $value .= array_shift($this->args).' ';
+              $value .= array_shift($args).' ';
             }
             $value = rtrim($value, ' ');
           }