Added support for a --skip-text option.

AlexSkrypnyk · May 26, 2023 · 5c6d12c · 5c6d12c
1 parent ef66072
commit 5c6d12c
Show file tree

Hide file tree

Showing 5 changed files with 64 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -261,6 +261,7 @@ like so: `--exclude-prefix=VAR1 --exclude-prefix=VAR2` etc.
 | Name                               | Description                                                                          | Default value |
 |------------------------------------|--------------------------------------------------------------------------------------|---------------|
 | `paths`                            | File or directory to scan. Multiple files separated by space.                        |               |
+| `--skip-text=SKIP`                 | Skip variable extraction if the comment has this specified text.                     | `@skip`       |
 | `--skip-description-prefix=PREFIX` | Skip description lines that start with the provided prefix. Multiple values allowed. |               |
 
 ### Filtering

diff --git a/src/Extractor/AbstractExtractor.php b/src/Extractor/AbstractExtractor.php
@@ -48,6 +48,12 @@ public static function getConsoleArguments(): array {
    */
   public static function getConsoleOptions(): array {
     return [
+      new InputOption(
+        name: 'skip-text',
+        mode: InputOption::VALUE_REQUIRED,
+        description: 'Skip variable extraction if the comment has this specified text.',
+        default: '@skip'
+      ),
       new InputOption(
         name: 'skip-description-prefix',
         mode: InputOption::VALUE_IS_ARRAY | InputOption::VALUE_REQUIRED,
@@ -62,6 +68,7 @@ public static function getConsoleOptions(): array {
    */
   protected function processConfig(Config $config): void {
     $config->set('paths', $this->scanPaths(Utils::resolvePaths($config->get('paths', []))));
+    $config->set('skip-text', $config->get('skip-text', '@skip'));
   }
 
   /**

diff --git a/src/Extractor/ShellExtractor.php b/src/Extractor/ShellExtractor.php
@@ -43,6 +43,7 @@ public function extract(): array {
    * {@inheritdoc}
    */
   protected function extractVariablesFromFile($file): void {
+    $skip = $this->config->get('skip-text');
     $lines = Utils::getLinesFromFiles([$file]);
 
     foreach ($lines as $num => $line) {
@@ -64,6 +65,10 @@ protected function extractVariablesFromFile($file): void {
 
       $description = $this->extractVariableDescription($lines, $num, $this->config->get('skip-description-prefix'));
       if ($description) {
+        if ($skip && str_contains($description, $skip)) {
+          continue;
+        }
+
         $var->setDescription($description);
       }
 

diff --git a/tests/Fixtures/test-data-skip-text.sh b/tests/Fixtures/test-data-skip-text.sh
@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+##
+# Test data file for variables extraction script.
+#
+# shellcheck disable=SC2034,SC2154
+
+# @skip
+VAR1=val1
+
+# Description from bash without a leading space that goes on
+# multiple lines.
+# @docs-skip
+VAR2=val2
+
diff --git a/tests/Functional/MarkdownBlocksFormatterFunctionalTest.php b/tests/Functional/MarkdownBlocksFormatterFunctionalTest.php
@@ -578,6 +578,43 @@ public function dataProviderFormatter() {
 
         EOD,
       ],
+
+      // Skip - default.
+      [
+        [
+          '--exclude-local',
+          '--sort',
+          '--format=md-blocks',
+          $this->fixtureFile('test-data-skip-text.sh'),
+        ],
+        <<<'EOD'
+        ### `VAR2`
+
+        Description from bash without a leading space that goes on<br />multiple lines.<br />@docs-skip
+
+        Default value: `val2`
+
+        EOD,
+      ],
+
+      // Skip - custom.
+      [
+        [
+          '--exclude-local',
+          '--sort',
+          '--format=md-blocks',
+          '--skip-text=docs-skip',
+          $this->fixtureFile('test-data-skip-text.sh'),
+        ],
+        <<<'EOD'
+        ### `VAR1`
+
+        @skip
+
+        Default value: `val1`
+
+        EOD,
+      ],
     ];
   }