test php fenced block only by default

Author: mathroc

.gitignore

@@ -1,3 +1,4 @@
+/composer.lock
 /vendor/
 /phpstan.neon
 /.phpunit.result.cache

.phpactor.json

@@ -0,0 +1,6 @@
+{
+    "$schema": "/phpactor.schema.json",
+    "language_server_phpstan.enabled": true,
+    "php_code_sniffer.enabled": true,
+    "prophecy.enabled": false
+}

README.md

@@ -15,7 +15,7 @@ example will be marked as failed.
 /**
  * Compute the factorial of a non-negative $n
  *
- * ```
+ * ```php
  * assert(factorial(0) === 1);
  * assert(factorial(5) === 120);
  * ```
@@ -105,4 +105,3 @@ $ ./bin/doctest examples/factorial.php
 # TODO
 
 * Junit output
-* Find PHP examples in markdown

composer.json

@@ -30,7 +30,6 @@
     },
     "require-dev": {
         "phpunit/phpunit": "^10.0|^11.0|^12.0",
-        "phpspec/prophecy-phpunit": "^2.0",
         "squizlabs/php_codesniffer": "^3.6",
         "slevomat/coding-standard": "^8.0",
         "phpstan/phpstan": "^2.0",

examples/Ratio.php

@@ -1,20 +1,20 @@
 <?php
 
 /**
- * ```
+ * ```php
  * $ratio = new Ratio(0.3);
  * echo $ratio->formatPercentage(); // @prints 30%
  * ```
  *
- * ```
+ * ```php
  * $ratio = new Ratio(0.9);
  * $ratio->value = 0.1; // @throws Error Cannot modify readonly property Ratio::$value
  * ```
  */
 final class Ratio
 {
     /**
-     * ```
+     * ```php
      * new Ratio(log(0)); // @throws InvalidArgumentException Ratio only accepts finite values. Got -INF
      * ```
      */
@@ -27,7 +27,7 @@ public function __construct(
     }
 
     /**
-     * ```
+     * ```php
      * assert(Ratio::fromPercentage(80)->value === 0.8);
      * ```
      */
@@ -37,7 +37,7 @@ public static function fromPercentage(float $percentage): Ratio
     }
 
     /**
-     * ```
+     * ```php
      * $ratio = new Ratio(0.167);
      * self::assertEq($ratio->formatPercentage(2), "16.70%");
      * ```

examples/factorial.php

@@ -3,43 +3,43 @@
 /**
  * Compute the factorial of a non-negative $n
  *
- * ```
+ * ```php
  * assert(factorial(0) === 1);
  * assert(factorial(1) === 1);
  * assert(factorial(2) === 2);
  * assert(factorial(3) === 6);
  * ```
  *
- * ```
+ * ```php
  * // You can use `self::assert*` to call `Webmozart\Assert\Assert::*` assertion helpers
  * self::assertEq(factorial(4), 24);
  * self::assertEq(factorial(5), 120);
  * ```
  *
- * ```
+ * ```php
  * // This example will fail because of unexpected output
  * echo factorial(6);
  * ```
  *
- * ```
+ * ```php
  * // You can check for expected output with one or more `@prints [text]` inline comments
  * echo factorial(6); // @prints 720
  * ```
  *
- * ```
+ * ```php
  * // This example will fail with InvalidArgumentException unexpected negative integer: -10
  * factorial(-10);
  * ```
  *
- * ```
+ * ```php
  * // You can check for Exception with a `@throws [Exception class] [Exception message]` inline comment
  * factorial(-10); // @throws InvalidArgumentException unexpected negative integer: -10
  *
  * // Everything after the exception will be ignored. So this won't fail:
  * assert(1 === 2);
  * ```
  *
- * ```
+ * ```php
  * // This example will fail with the message : "Expected a value equal to 3628890. Got: 3628800"
  * self::assertEq(factorial(10), 3628890);
  * ```

phpcs.xml.dist

@@ -5,9 +5,7 @@
 
     <file>src</file>
     <file>tests</file>
-    <exclude-pattern>tests/data/examples/</exclude-pattern>
-
-    <exclude-pattern>tests/examples.php</exclude-pattern>
+    <exclude-pattern>tests/data/</exclude-pattern>
 
     <rule ref="PSR12">
         <exclude name="PSR12.Files.FileHeader" />

phpstan.neon.dist

@@ -12,4 +12,4 @@ parameters:
 		uncheckedExceptionClasses:
 			- RuntimeException
 	excludePaths:
-		- tests/data/examples
+		- tests/data/code-blocs/

src/Application.php

@@ -11,6 +11,7 @@
 #[AsCommand("doctest")]
 final class Application extends SingleCommandApplication
 {
+    // phpcs:disable SlevomatCodingStandard.Functions.FunctionLength.FunctionLength
     protected function configure(): void
     {
         $this
@@ -27,8 +28,16 @@ protected function configure(): void
                 "filter",
                 "f",
                 Input\InputOption::VALUE_REQUIRED,
-                "Ony run code blocks whose names matche the filter",
+                "Ony run code blocks whose names match the filter",
                 default: "",
+            )
+            ->addOption(
+                "languages",
+                "l",
+                Input\InputOption::VALUE_REQUIRED | Input\InputOption::VALUE_IS_ARRAY,
+                "Ony run code blocks whose language match." . PHP_EOL
+                    . "(\"*\" to match any language, \"\" to match unspecified language)",
+                default: ["php"],
             );
     }
 
@@ -37,6 +46,7 @@ protected function execute(Input\InputInterface $input, Output\OutputInterface $
         $testSuite = TestSuite::fromPaths(
             $input->getArgument("paths"),
             $input->getOption("filter"),
+            $this->getLanguages($input),
         );
 
         $testSuite->addSubscriber(new Subscriber\ProgressBar($input, $output));
@@ -49,4 +59,24 @@ protected function execute(Input\InputInterface $input, Output\OutputInterface $
             ? Command::SUCCESS
             : Command::FAILURE;
     }
+
+    /**
+     * @return list<string>|null
+     */
+    private function getLanguages(Input\InputInterface $input): ?array
+    {
+        $languages = [];
+
+        foreach ($input->getOption("languages") as $lang) {
+            if ($lang === '*') {
+                $languages = null;
+
+                break;
+            }
+
+            $languages[] = $lang;
+        }
+
+        return $languages;
+    }
 }

src/Iterator/AllExamples.php

@@ -7,10 +7,13 @@
 
 final class AllExamples implements Examples
 {
+    /**
+     * @param list<string>|null $acceptedLanguages Use empty string for unspecified language, and null for any languages
+     */
     public function __construct(
-        private Comments $comments,
-    ) {
-    }
+        private readonly Comments $comments,
+        private readonly ?array $acceptedLanguages,
+    ) {}
 
     /**
      * @return \Traversable<Example>
@@ -24,17 +27,25 @@ public function getIterator(): \Traversable
 
     /**
      * @param array<string> $paths paths to files and folder to look for PHP comments code examples in
+     * @param list<string>|null $acceptedLanguages Use empty string for unspecified language, and null for any languages
      */
-    public static function fromPaths(array $paths): self
-    {
-        return new self(Comments::fromPaths($paths));
+    public static function fromPaths(
+        array $paths,
+        ?array $acceptedLanguages,
+    ): self {
+        return new self(
+            SourceComments::fromPaths($paths),
+            $acceptedLanguages,
+        );
     }
 
     /**
      * @return \Traversable<Example>
      */
-    private function iterateComment(string $comment, Location $location): \Traversable
-    {
+    private function iterateComment(
+        string $comment,
+        Location $location,
+    ): \Traversable {
         $lines = new \ArrayIterator(\explode(PHP_EOL, $comment));
         $index = 1;
 
@@ -46,30 +57,41 @@ private function iterateComment(string $comment, Location $location): \Traversab
     /**
      * @param \ArrayIterator<int,string> $lines
      */
-    private function nextExample(\ArrayIterator $lines, Location $location, int $index): ?Example
-    {
-        $codeblockStartedAt = $this->findFencedCodeBlockStart($lines);
+    private function nextExample(
+        \ArrayIterator $lines,
+        Location $location,
+        int $index,
+    ): ?Example {
+        $codeblockStartedAt = $this->findFencedPHPCodeBlockStart($lines);
 
         if ($codeblockStartedAt === null) {
             return null;
         }
 
-        return $this->readExample($lines, $location->startingAt($codeblockStartedAt, $index));
+        return $this->readExample(
+            $lines,
+            $location->startingAt($codeblockStartedAt, $index),
+        );
     }
 
     /**
      * @param \ArrayIterator<int,string> $lines
      */
-    private function readExample(\ArrayIterator $lines, Location $location): ?Example
-    {
+    private function readExample(
+        \ArrayIterator $lines,
+        Location $location,
+    ): ?Example {
         $buffer = [];
 
         while ($lines->valid()) {
             $line = $lines->current();
             $lines->next();
 
-            if ($this->endOfAPHPFencedCodeBlock($line)) {
-                return new Example(\implode(PHP_EOL, $buffer), $location->ofLength($lines->key()));
+            if ($this->endOfAFencedCodeBlock($line)) {
+                return new Example(
+                    \implode(PHP_EOL, $buffer),
+                    $location->ofLength($lines->key()),
+                );
             }
 
             $buffer[] = \preg_replace("/^\s*\*( ?)/", "", $line);
@@ -80,28 +102,60 @@ private function readExample(\ArrayIterator $lines, Location $location): ?Exampl
 
     /**
      * @param \ArrayIterator<int,string> $lines
+     * phpcs:disable SlevomatCodingStandard.Complexity.Cognitive.ComplexityTooHigh
      */
-    private function findFencedCodeBlockStart(\ArrayIterator $lines): ?int
+    private function findFencedPHPCodeBlockStart(\ArrayIterator $lines): ?int
     {
+        $insideAFencedCodeBlock = false;
+
         while ($lines->valid()) {
             $line = $lines->current();
             $lines->next();
 
-            if ($this->startOfAPHPFencedCodeBlock($line)) {
-                return $lines->key();
+            if ($insideAFencedCodeBlock) {
+                if ($this->endOfAFencedCodeBlock($line)) {
+                    $insideAFencedCodeBlock = false;
+                }
+            } else {
+                $lang = $this->startOfAFencedCodeBlock($line);
+
+                if ($lang === false) {
+                    continue;
+                }
+
+                if ($this->isAcceptedLanguage($lang)) {
+                    return $lines->key();
+                }
+
+                $insideAFencedCodeBlock = true;
             }
         }
 
         return null;
     }
 
-    private function endOfAPHPFencedCodeBlock(string $line): bool
+    private function isAcceptedLanguage(string $lang): bool
+    {
+        if ($this->acceptedLanguages === null) {
+            return true;
+        }
+
+        return \in_array(needle: $lang, haystack: $this->acceptedLanguages, strict: true);
+    }
+
+    private function endOfAFencedCodeBlock(string $line): bool
     {
         return \ltrim($line) === "* ```";
     }
 
-    private function startOfAPHPFencedCodeBlock(string $line): bool
+    private function startOfAFencedCodeBlock(string $line): false|string
     {
-        return \in_array(\ltrim($line), ["* ```", "* ```php"], strict: true);
+        $line = \trim($line);
+
+        if (!\str_starts_with($line, "* ```")) {
+            return false;
+        }
+
+        return \substr($line, 5);
     }
 }