Resolve #52 and fixes.

- HTML renderer Inline, SideBySide and Unified return false when there's nothing to render. - Text renderer Context, InlineCli and Unified return false when there's nothing to render. Main renderer returns false when there's nothing to render. - Text renderer InlineCli renders line-ending `\n` instead of `PHP_EOL`. - Added missing docBlock content. - Updated docBlock of the SubRenderer Interface. - Added method Diff::isIdentical(). - Updated README.md to reflect Diff::isIdentical().
JBlond · Jul 22, 2020 · fda4852 · fda4852
1 parent 10986ac
commit fda4852
Show file tree

Hide file tree

Showing 12 changed files with 125 additions and 98 deletions.
diff --git a/README.md b/README.md
@@ -7,7 +7,7 @@
 ## Introduction
 
 A comprehensive library for generating differences between two hashable objects (strings or arrays).
-Generated differences can be rendered in all of the standard formats including:
+Generated differences can be rendered in all the standard formats including:
 
 * Unified
 * Context
@@ -35,8 +35,8 @@ use jblond\Diff\Renderer\Html\SideBySide;
 // Installed via composer...
 require 'vendor/autoload.php';
 
-$a = file_get_contents(dirname(__FILE__).'/a.txt');
-$b = file_get_contents(dirname(__FILE__).'/b.txt');
+$sampleA = file_get_contents(dirname(__FILE__).'/a.txt');
+$sampleB = file_get_contents(dirname(__FILE__).'/b.txt');
 
 // Options for generating the diff.
 $options = [
@@ -47,20 +47,26 @@ $options = [
 ];
 
 // Initialize the diff class.
-$diff = new Diff($a, $b /*, $options */);
+$diff = new Diff($sampleA, $sampleB /*, $options */);
 
 // Choose Renderer.
 $renderer = new SideBySide([
-    'title1' => 'Custom title for OLD version',
-    'title2' => 'Custom title for NEW version',
+    'title1' => 'Custom title for sample A',
+    'title2' => 'Custom title for sample B',
 ]);
 
-// Show it.
+// Show the output of the difference renderer.
 echo $diff->Render($renderer);
+
+// Alternative
+// Show the differences or a message.
+echo $diff->isIdentical() ? 'No differences found.' : '<pre>' . htmlspecialchars($diff->render($renderer)) . '</pre>' ;
+
 ```
 
 ### Example Output
-A quick usage example can be found in the `example/` directory and under example.php. Included is a light theme and a dark theme.
+File `example.php` contains a quick demo and can be found in the `example/` directory.
+Included is a light and a dark theme.
 
 #### HTML Side By Side Example
 

diff --git a/example/example.php b/example/example.php
@@ -23,73 +23,73 @@
 ];
 
 // Choose one of the initializations.
-$diff = new Diff($sampleA, $sampleB);       // Initialize the diff class with default options.
-//$diff = new Diff($a, $b, $customOptions); // Initialize the diff class with custom options.
+$diff = new Diff($sampleA, $sampleB);                   // Initialize the diff class with default options.
+//$diff = new Diff($sampleA, $sampleB, $customOptions); // Initialize the diff class with custom options.
 ?><!DOCTYPE html>
 <html lang="en">
-    <head>
-        <meta charset="utf-8"/>
-        <title>PHP LibDiff - Examples</title>
-        <link rel="stylesheet" type="text/css" href="styles.css" />
-        <script>
-            function changeCSS(cssFile, cssLinkIndex) {
-
-                const oldLink = document.getElementsByTagName('link').item(cssLinkIndex);
-
-                const newLink = document.createElement('link');
-                newLink.setAttribute('rel', 'stylesheet');
-                newLink.setAttribute('type', 'text/css');
-                newLink.setAttribute('href', cssFile);
-
-                document.getElementsByTagName('head').item(0).replaceChild(newLink, oldLink);
-            }
-        </script>
-    </head>
-    <body>
-        <h1>PHP LibDiff - Examples</h1>
-        <aside>
-            <h2>Change Theme</h2>
-            <a href="#" onclick="changeCSS('styles.css', 0);">Light Theme</a>
-            <a href="#" onclick="changeCSS('dark-theme.css', 0);">Dark Theme</a>
-        </aside>
-        <hr>
-
-        <h2>HTML Side by Side Diff</h2>
-
-        <?php
+<head>
+    <meta charset="utf-8"/>
+    <title>PHP LibDiff - Examples</title>
+    <link rel="stylesheet" type="text/css" href="styles.css"/>
+    <script>
+        function changeCSS(cssFile, cssLinkIndex) {
+
+            const oldLink = document.getElementsByTagName('link').item(cssLinkIndex);
+
+            const newLink = document.createElement('link');
+            newLink.setAttribute('rel', 'stylesheet');
+            newLink.setAttribute('type', 'text/css');
+            newLink.setAttribute('href', cssFile);
+
+            document.getElementsByTagName('head').item(0).replaceChild(newLink, oldLink);
+        }
+    </script>
+</head>
+<body>
+    <h1>PHP LibDiff - Examples</h1>
+    <aside>
+        <h2>Change Theme</h2>
+        <a href="#" onclick="changeCSS('styles.css', 0);">Light Theme</a>
+        <a href="#" onclick="changeCSS('dark-theme.css', 0);">Dark Theme</a>
+    </aside>
+    <hr>
+
+    <h2>HTML Side by Side Diff</h2>
+
+    <?php
         // Generate a side by side diff.
         $renderer = new SideBySide();
-        echo $diff->Render($renderer);
-        ?>
-
-        <h2>HTML Inline Diff</h2>
-
-        <?php
+        echo $diff->isIdentical() ? 'No differences found.' : $diff->Render($renderer);
+    ?>
 
+    <h2>HTML Inline Diff</h2>
+    <?php
         // Generate an inline diff.
         $renderer = new Inline();
-        echo $diff->render($renderer);
-        ?>
+        echo $diff->isIdentical() ? 'No differences found.' : $diff->Render($renderer);
+    ?>
 
-        <h2>HTML Unified Diff</h2>
-        <?php
+    <h2>HTML Unified Diff</h2>
+    <?php
         // Generate a unified diff.
         $renderer = new HtmlUnified();
-        echo "<pre>{$diff->render($renderer)}</pre>";
-        ?>
+        echo $diff->isIdentical() ? 'No differences found.' : '<pre>' . $diff->Render($renderer) . '</pre>';
+    ?>
 
-        <h2>Text Unified Diff</h2>
-        <?php
+    <h2>Text Unified Diff</h2>
+    <?php
         // Generate a unified diff.
         $renderer = new Unified();
-        echo '<pre>' . htmlspecialchars($diff->render($renderer)) . '</pre>';
-        ?>
+        echo $diff->isIdentical() ?
+            'No differences found.' : '<pre>' . htmlspecialchars($diff->render($renderer)) . '</pre>';
+    ?>
 
-        <h2>Text Context Diff</h2>
-        <?php
+    <h2>Text Context Diff</h2>
+    <?php
         // Generate a context diff.
         $renderer = new Context();
-        echo '<pre>' . htmlspecialchars($diff->render($renderer)) . '</pre>';
-        ?>
-    </body>
+        echo $diff->isIdentical() ?
+            'No differences found.' : '<pre>' . htmlspecialchars($diff->render($renderer)) . '</pre>';
+    ?>
+</body>
 </html>
diff --git a/lib/jblond/Diff.php b/lib/jblond/Diff.php
@@ -21,14 +21,14 @@
  *
  * PHP version 7.2 or greater
  *
- * @package     jblond
- * @author      Chris Boulton <[email protected]>
- * @author      Mario Brandt <[email protected]>
- * @author      Ferry Cools <[email protected]>
+ * @package         jblond
+ * @author          Chris Boulton <[email protected]>
+ * @author          Mario Brandt <[email protected]>
+ * @author          Ferry Cools <[email protected]>
  * @copyright   (c) 2020 Mario Brandt
- * @license     New BSD License http://www.opensource.org/licenses/bsd-license.php
- * @version     2.1.1
- * @link        https://github.com/JBlond/php-diff
+ * @license         New BSD License http://www.opensource.org/licenses/bsd-license.php
+ * @version         2.1.1
+ * @link            https://github.com/JBlond/php-diff
  */
 class Diff
 {
@@ -73,6 +73,10 @@ class Diff
      * @see Diff::setOptions()
      */
     private $options = [];
+    /**
+     * @var bool True when compared versions are identical, False otherwise.
+     */
+    private $identical;
 
     /**
      * The constructor.
@@ -169,9 +173,9 @@ public function getVersion2(): array
      * Render a diff-view using a rendering class and get its results.
      *
      * @param object|Context|Unified|UnifiedHtml|Inline|SideBySide $renderer An instance of the rendering object,
-     * used for generating the diff-view.
+     *                                                                       used for generating the diff-view.
      *
-     * @return mixed The generated diff-view. The type of the return value depends on the applied rendereder.
+     * @return mixed The generated diff-view. The type of the return value depends on the applied renderer.
      */
     public function render(object $renderer)
     {
@@ -221,6 +225,20 @@ public function getArrayRange(array $array, int $start = 0, $end = null): array
         return array_slice($array, $start, $length);
     }
 
+    /**
+     * Get if the compared versions are identical or have differences.
+     *
+     * @return bool True when identical.
+     */
+    public function isIdentical(): bool
+    {
+        if ($this->getGroupedOpCodes() === null) {
+            $this->getGroupedOpCodes();
+        }
+
+        return $this->identical;
+    }
+
     /**
      * Generate a list of the compiled and grouped op-codes for the differences between two strings.
      *
@@ -240,6 +258,8 @@ public function getGroupedOpCodes(): array
         //Get and cache the grouped op-codes.
         $sequenceMatcher    = new SequenceMatcher($this->version1, $this->version2, $this->options);
         $this->groupedCodes = $sequenceMatcher->getGroupedOpCodes();
+        $opCodes            = $sequenceMatcher->getOpCodes();
+        $this->identical    = count($opCodes) == 1 && $opCodes[0][0] == 'equal';
 
         return $this->groupedCodes;
     }

diff --git a/lib/jblond/Diff/Renderer/Html/Inline.php b/lib/jblond/Diff/Renderer/Html/Inline.php
@@ -57,9 +57,9 @@ public function __construct(array $options = [])
     /**
      * Render and return a diff-view with changes between the two sequences displayed inline (under each other).
      *
-     * @return string The generated inline diff-view.
+     * @return string|false The generated diff-view or false when there's no difference.
      */
-    public function render(): string
+    public function render()
     {
         $changes = parent::renderSequences();
 

diff --git a/lib/jblond/Diff/Renderer/Html/SideBySide.php b/lib/jblond/Diff/Renderer/Html/SideBySide.php
@@ -57,9 +57,9 @@ public function __construct(array $options = [])
     /**
      * Render a and return diff-view with changes between the two sequences displayed side by side.
      *
-     * @return string The generated side by side diff-view.
+     * @return string|false The generated diff-view or false when there's no difference.
      */
-    public function render(): string
+    public function render()
     {
         $changes = parent::renderSequences();
 

diff --git a/lib/jblond/Diff/Renderer/Html/Unified.php b/lib/jblond/Diff/Renderer/Html/Unified.php
@@ -57,9 +57,9 @@ public function __construct(array $options = [])
     /**
      * Render a and return diff-view with changes between the two sequences (under each other).
      *
-     * @return string The generated unified diff-view.
+     * @return string|false The generated diff-view or false when there's no difference.
      */
-    public function render(): string
+    public function render()
     {
         $changes = parent::renderSequences();
 

diff --git a/lib/jblond/Diff/Renderer/MainRenderer.php b/lib/jblond/Diff/Renderer/MainRenderer.php
@@ -21,7 +21,7 @@
 class MainRenderer extends MainRendererAbstract
 {
     /**
-     * @var int
+     * @var int Character count of the line marker with the most characters.
      */
     protected $maxLineMarkerWidth = 0;
     /**
@@ -31,20 +31,20 @@ class MainRenderer extends MainRendererAbstract
     private $lastTag;
 
     /**
-     * Generate a string representation of changes between the "old and "new" sequences.
+     * Generate a string representation of changes between version1 and version2.
      *
      * This method is called by the renderers which extends this class.
      *
-     * @param array  $changes     Contains the op-codes about the differences between "old and "new".
+     * @param array  $changes     Contains the op-codes about the differences between version1 and version2.
      * @param object $subRenderer Renderer which is subClass of this class.
      *
-     * @return string Representation of the differences.
+     * @return string|false String representation of the differences or false when versions are identical.
      */
-    public function renderOutput(array $changes, object $subRenderer): string
+    public function renderOutput(array $changes, object $subRenderer)
     {
         if (!$changes) {
-            //No changes between "old" and "new"
-            return 'No differences found.';
+            //No changes between version1 and version2
+            return false;
         }
 
         $output = $subRenderer->generateDiffHeader();

diff --git a/lib/jblond/Diff/Renderer/SubRendererInterface.php b/lib/jblond/Diff/Renderer/SubRendererInterface.php
@@ -21,9 +21,9 @@ interface SubRendererInterface
     /**
      * Render and return a diff-view with changes between two sequences.
      *
-     * @return string The generated diff-view.
+     * @return string|false The generated diff-view or false when there's no difference.
      */
-    public function render(): string;
+    public function render();
 
     /**
      * Generate a string representation of the start of a diff view.

diff --git a/lib/jblond/Diff/Renderer/Text/Context.php b/lib/jblond/Diff/Renderer/Text/Context.php
@@ -37,11 +37,11 @@ class Context extends MainRendererAbstract
      *
      * @link https://www.gnu.org/software/diffutils/manual/html_node/Detailed-Context.html#Detailed-Context
      *
-     * @return string The generated context diff-view.
+     * @return string|false The generated diff-view or false when there's no difference.
      */
-    public function render(): string
+    public function render()
     {
-        $diff    = '';
+        $diff    = false;
         $opCodes = $this->diff->getGroupedOpCodes();
 
         foreach ($opCodes as $group) {