Generators/Text: don't print title if there is no content

This refactors the class to _retrieve_ the intended output, instead of echo-ing it out directly and validates whether it makes sense to print anything at all about a sniff before sending the output to screen.

It deprecates the following methods, which will be removed in PHPCS 4.0:
* `printTitle()` in favour of `getFormattedTitle()`
* `printTextBlock()` in favour of `getFormattedTextBlock()`
* `printCodeComparisonBlock()` in favour of `getFormattedCodeComparisonBlock()`

Author: jrfnl

src/Generators/Text.php

@@ -30,16 +30,19 @@ class Text extends Generator
      */
     public function processSniff(DOMNode $doc)
     {
-        $this->printTitle($doc);
-
+        $content = '';
         foreach ($doc->childNodes as $node) {
             if ($node->nodeName === 'standard') {
-                $this->printTextBlock($node);
+                $content .= $this->getFormattedTextBlock($node);
             } else if ($node->nodeName === 'code_comparison') {
-                $this->printCodeComparisonBlock($node);
+                $content .= $this->getFormattedCodeComparisonBlock($node);
             }
         }
 
+        if (trim($content) !== '') {
+            echo $this->getFormattedTitle($doc), $content;
+        }
+
     }//end processSniff()
 
 
@@ -50,32 +53,76 @@ public function processSniff(DOMNode $doc)
      *                      It represents the "documentation" tag in the XML
      *                      standard file.
      *
+     * @deprecated 3.12.0 Use Text::getFormattedTitle() instead.
+     *
+     * @codeCoverageIgnore
+     *
      * @return void
      */
     protected function printTitle(DOMNode $doc)
+    {
+        echo $this->getFormattedTitle($doc);
+
+    }//end printTitle()
+
+
+    /**
+     * Format the title area for a single sniff.
+     *
+     * @param \DOMNode $doc The DOMNode object for the sniff.
+     *                      It represents the "documentation" tag in the XML
+     *                      standard file.
+     *
+     * @since 3.12.0 Replaces the deprecated Text::printTitle() method.
+     *
+     * @return string
+     */
+    protected function getFormattedTitle(DOMNode $doc)
     {
         $title        = $this->getTitle($doc);
         $standard     = $this->ruleset->name;
         $displayTitle = "$standard CODING STANDARD: $title";
         $titleLength  = strlen($displayTitle);
 
-        echo PHP_EOL;
-        echo str_repeat('-', ($titleLength + 4));
-        echo strtoupper(PHP_EOL."| $displayTitle |".PHP_EOL);
-        echo str_repeat('-', ($titleLength + 4));
-        echo PHP_EOL.PHP_EOL;
+        $output  = PHP_EOL;
+        $output .= str_repeat('-', ($titleLength + 4));
+        $output .= strtoupper(PHP_EOL."| $displayTitle |".PHP_EOL);
+        $output .= str_repeat('-', ($titleLength + 4));
+        $output .= PHP_EOL.PHP_EOL;
 
-    }//end printTitle()
+        return $output;
+
+    }//end getFormattedTitle()
 
 
     /**
      * Print a text block found in a standard.
      *
      * @param \DOMNode $node The DOMNode object for the text block.
      *
+     * @deprecated 3.12.0 Use Text::getFormattedTextBlock() instead.
+     *
+     * @codeCoverageIgnore
+     *
      * @return void
      */
     protected function printTextBlock(DOMNode $node)
+    {
+        echo $this->getFormattedTextBlock($node);
+
+    }//end printTextBlock()
+
+
+    /**
+     * Format a text block found in a standard.
+     *
+     * @param \DOMNode $node The DOMNode object for the text block.
+     *
+     * @since 3.12.0 Replaces the deprecated Text::printTextBlock() method.
+     *
+     * @return string
+     */
+    protected function getFormattedTextBlock(DOMNode $node)
     {
         $text = trim($node->nodeValue);
         $text = str_replace('<em>', '*', $text);
@@ -117,19 +164,39 @@ protected function printTextBlock(DOMNode $node)
             }
         }//end foreach
 
-        echo implode(PHP_EOL, $lines).PHP_EOL.PHP_EOL;
+        return implode(PHP_EOL, $lines).PHP_EOL.PHP_EOL;
 
-    }//end printTextBlock()
+    }//end getFormattedTextBlock()
 
 
     /**
      * Print a code comparison block found in a standard.
      *
      * @param \DOMNode $node The DOMNode object for the code comparison block.
      *
+     * @deprecated 3.12.0 Use Text::getFormattedCodeComparisonBlock() instead.
+     *
+     * @codeCoverageIgnore
+     *
      * @return void
      */
     protected function printCodeComparisonBlock(DOMNode $node)
+    {
+        echo $this->getFormattedCodeComparisonBlock($node);
+
+    }//end printCodeComparisonBlock()
+
+
+    /**
+     * Format a code comparison block found in a standard.
+     *
+     * @param \DOMNode $node The DOMNode object for the code comparison block.
+     *
+     * @since 3.12.0 Replaces the deprecated Text::printCodeComparisonBlock() method.
+     *
+     * @return string
+     */
+    protected function getFormattedCodeComparisonBlock(DOMNode $node)
     {
         $codeBlocks = $node->getElementsByTagName('code');
         $first      = trim($codeBlocks->item(0)->nodeValue);
@@ -205,9 +272,9 @@ protected function printCodeComparisonBlock(DOMNode $node)
         $maxCodeLines  = max(count($firstLines), count($secondLines));
         $maxTitleLines = max(count($firstTitleLines), count($secondTitleLines));
 
-        echo str_repeat('-', 41);
-        echo ' CODE COMPARISON ';
-        echo str_repeat('-', 42).PHP_EOL;
+        $output  = str_repeat('-', 41);
+        $output .= ' CODE COMPARISON ';
+        $output .= str_repeat('-', 42).PHP_EOL;
 
         for ($i = 0; $i < $maxTitleLines; $i++) {
             if (isset($firstTitleLines[$i]) === true) {
@@ -222,14 +289,14 @@ protected function printCodeComparisonBlock(DOMNode $node)
                 $secondLineText = '';
             }
 
-            echo '| ';
-            echo $firstLineText.str_repeat(' ', (46 - strlen($firstLineText)));
-            echo ' | ';
-            echo $secondLineText.str_repeat(' ', (47 - strlen($secondLineText)));
-            echo ' |'.PHP_EOL;
+            $output .= '| ';
+            $output .= $firstLineText.str_repeat(' ', (46 - strlen($firstLineText)));
+            $output .= ' | ';
+            $output .= $secondLineText.str_repeat(' ', (47 - strlen($secondLineText)));
+            $output .= ' |'.PHP_EOL;
         }//end for
 
-        echo str_repeat('-', 100).PHP_EOL;
+        $output .= str_repeat('-', 100).PHP_EOL;
 
         for ($i = 0; $i < $maxCodeLines; $i++) {
             if (isset($firstLines[$i]) === true) {
@@ -244,16 +311,18 @@ protected function printCodeComparisonBlock(DOMNode $node)
                 $secondLineText = '';
             }
 
-            echo '| ';
-            echo $firstLineText.str_repeat(' ', max(0, (47 - strlen($firstLineText))));
-            echo '| ';
-            echo $secondLineText.str_repeat(' ', max(0, (48 - strlen($secondLineText))));
-            echo '|'.PHP_EOL;
+            $output .= '| ';
+            $output .= $firstLineText.str_repeat(' ', max(0, (47 - strlen($firstLineText))));
+            $output .= '| ';
+            $output .= $secondLineText.str_repeat(' ', max(0, (48 - strlen($secondLineText))));
+            $output .= '|'.PHP_EOL;
         }//end for
 
-        echo str_repeat('-', 100).PHP_EOL.PHP_EOL;
+        $output .= str_repeat('-', 100).PHP_EOL.PHP_EOL;
 
-    }//end printCodeComparisonBlock()
+        return $output;
+
+    }//end getFormattedCodeComparisonBlock()
 
 
 }//end class

tests/Core/Generators/Expectations/ExpectedOutputStructureDocs.txt

@@ -1,9 +1,4 @@
 
----------------------------------------------
-| GENERATORTEST CODING STANDARD: NO CONTENT |
----------------------------------------------
-
-
 -------------------------------------------------------------------------------
 | GENERATORTEST CODING STANDARD: CODE COMPARISON ONLY, MISSING STANDARD BLOCK |
 -------------------------------------------------------------------------------

tests/Core/Generators/Expectations/ExpectedOutputUnsupportedElementAtWrongLevel.txt

@@ -175,7 +175,7 @@ public static function dataDocSpecifics()
             ],
             'Unsupported: <code> element at the wrong level'   => [
                 'sniffs'         => 'StandardWithDocs.Unsupported.ElementAtWrongLevel',
-                'pathToExpected' => __DIR__.'/Expectations/ExpectedOutputUnsupportedElementAtWrongLevel.txt',
+                'pathToExpected' => __DIR__.'/Expectations/ExpectedOutputEmpty.txt',
             ],
             'Unsupported: one correct elm, one at wrong level' => [
                 'sniffs'         => 'StandardWithDocs.Unsupported.OneElmAtWrongLevel',
@@ -187,7 +187,7 @@ public static function dataDocSpecifics()
             ],
             'Unsupported: unknown element'                     => [
                 'sniffs'         => 'StandardWithDocs.Unsupported.UnknownElement',
-                'pathToExpected' => __DIR__.'/Expectations/ExpectedOutputUnsupportedUnknownElement.txt',
+                'pathToExpected' => __DIR__.'/Expectations/ExpectedOutputEmpty.txt',
             ],
         ];