Merge pull request #11 from adriendupuis/feature/intro

Exercise Introduction
adriendupuis · May 11, 2020 · a132a6d · a132a6d
2 parents 9008fbd + 3762764
commit a132a6d
Show file tree

Hide file tree

Showing 3 changed files with 54 additions and 4 deletions.
diff --git a/README.md b/README.md
@@ -89,11 +89,21 @@ When `<step_number>` is **smaller than** the wanted step number, **execute** one
 
 `<threshold_step_number>` must be greater than `<step_number>`.
 
+#### Intro Keyword
+
+Previous tags can contain keyword `INTRO` anywhere after their step number.
+
+- `TRAINING EXERCISE STOP STEP <step_number> INTRO [...]`
+
+With `INTRO`, when `<step_number>` is **equal to** the wanted step number, **keep** inside content in both **exercise and solution**.
+
 #### Placeholder Tag
 
 - `TRAINING EXERCISE STEP PLACEHOLDER`
 
-A line containing this tag will be kept with this tag removed if found between step tags which's step number equals to the wanted step number.
+When `<step_number>` is **equal to** the wanted step number:
+* **keep** line containing this tag into **exercise** with this tag removed
+* **remove** line containing this tag from **solution
 
 #### Examples
 
@@ -308,7 +318,7 @@ done;
 * Version string as step numbers
 * Config file to name and describe steps
 * Dedicated file extension for original files
-* Placeholder: When $step === $targetStep, have an optional placeholder (to give instructions, clues, resources, etc.)
+* Find a better mechanism and wording for `INTRO` and `PLACEHOLDER` (more understandable, more consistent)
 * Handle just `TRAINING EXERCISE START STEP <step_number> <action_b> UNTIL <threshold_step_number>` (with default/implicit `THEN REMOVE`)
 * Handle just `TRAINING EXERCISE START STEP <step_number> UNTIL <threshold_step_number>` (with default/implicit `KEEP UNTIL <n> THEN REMOVE`)
 * More unit tests

diff --git a/src/ExerciseCleaner.php b/src/ExerciseCleaner.php
@@ -107,11 +107,16 @@ public function cleanCodeLines(array $lines, float $targetStep = 1, bool $soluti
                 if (null === $commentPattern && false !== strpos($action, 'COMMENT')) {
                     trigger_error("Unsupported COMMENT action at line $lineNumber", E_USER_WARNING);
                 }
+                $intro = false !== strpos($action, 'INTRO');
+                if ($intro) {
+                    $action = trim(str_replace('  ', ' ', str_replace('INTRO', '', $action)));
+                }
 
                 $startedTag = [
                     'step' => $step,
                     'action' => $action,
                     'name' => $this->getStepName($step) ?? '',
+                    'intro' => $intro,
                 ];
                 if ('' !== trim($action) && false !== strpos($action, ' ')) {
                     $matches = [];
@@ -159,9 +164,10 @@ public function cleanCodeLines(array $lines, float $targetStep = 1, bool $soluti
                             $keptLines[] = $line;
                     }
                 } elseif ($step === $targetStep) {
-                    if ($solution && false === strpos($line, $this->placeHolderTagConstant)) {
+                    $intro = $currentTag['intro'];
+                    if (($solution || $intro) && false === strpos($line, $this->placeHolderTagConstant)) {
                         $keptLines[] = $line;
-                    } elseif (!$solution && false !== strpos($line, $this->placeHolderTagConstant)) {
+                    } elseif ((!$solution || $intro) && false !== strpos($line, $this->placeHolderTagConstant)) {
                         $keptLines[] = preg_replace("@ *{$this->placeHolderTagConstant}@", '', $line);
                     }
                 }

diff --git a/tests/ExerciseCleanerTest.php b/tests/ExerciseCleanerTest.php
@@ -273,6 +273,40 @@ public function testThresholdActionTag(): void
         ], $cleanedCodeLines);
     }
 
+    public function testIntroKeyword(): void
+    {
+        $code = <<<'CODE'
+TRAINING EXERCISE START STEP 1 INTRO REMOVE
+Step 1 Introduction
+TRAINING EXERCISE STOP STEP 1
+TRAINING EXERCISE START STEP 1 KEEP INTRO UNTIL 2 THEN REMOVE
+Steps 1 & 2 Introduction
+TRAINING EXERCISE STOP STEP 1
+TRAINING EXERCISE START STEP 1 REMOVE
+Step 1 Solution
+TRAINING EXERCISE STOP STEP 1
+TRAINING EXERCISE START STEP 2 INTRO
+Step 2+ Introduction
+TRAINING EXERCISE STOP STEP 2
+TRAINING EXERCISE START STEP 2
+Step 2+ Solution
+TRAINING EXERCISE STOP STEP 2
+TRAINING EXERCISE START STEP 3
+Step 3 Solution
+TRAINING EXERCISE STOP STEP 3
+CODE;
+        $codeLines = explode(PHP_EOL, $code);
+
+        $this->assertEquals(['Step 1 Introduction', 'Steps 1 & 2 Introduction'], $this->exerciseCleaner->cleanCodeLines($codeLines, 1, false));
+        $this->assertEquals(['Step 1 Introduction', 'Steps 1 & 2 Introduction', 'Step 1 Solution'], $this->exerciseCleaner->cleanCodeLines($codeLines, 1, true));
+
+        $this->assertEquals(['Steps 1 & 2 Introduction', 'Step 2+ Introduction'], $this->exerciseCleaner->cleanCodeLines($codeLines, 2, false, false, '.php'));
+        $this->assertEquals(['Steps 1 & 2 Introduction', 'Step 2+ Introduction', 'Step 2+ Solution'], $this->exerciseCleaner->cleanCodeLines($codeLines, 2, true, false, '.php'));
+
+        $this->assertEquals(['Step 2+ Introduction', 'Step 2+ Solution'], $this->exerciseCleaner->cleanCodeLines($codeLines, 3, false));
+        $this->assertEquals(['Step 2+ Introduction', 'Step 2+ Solution', 'Step 3 Solution'], $this->exerciseCleaner->cleanCodeLines($codeLines, 3, true));
+    }
+
     public function testPlaceholderTags(): void
     {
         $code = <<<'CODE'