Rename the term "template" to "renderer"

Signed-off-by: Jack Cherng <jfcherng@gmail.com>

Author: jfcherng

README.md

@@ -49,8 +49,8 @@ $newFile = __DIR__ . '/example/new_file.txt';
 $old = 'This is the old string.';
 $new = 'And this is the new one.';
 
-// template class name: Unified, Context, Json, Inline, SideBySide
-$template = 'Unified';
+// renderer class name: Unified, Context, Json, Inline, SideBySide
+$rendererName = 'Unified';
 
 // the Diff class options
 $differOptions = [
@@ -62,35 +62,35 @@ $differOptions = [
     'ignoreWhitespace' => false,
 ];
 
-// the template class options
-$templateOptions = [
+// the renderer class options
+$rendererOptions = [
     // how detailed the rendered HTML in-line diff is? (none, line, word, char)
     'detailLevel' => 'line',
-    // template language: eng, cht, chs, jpn, ...
+    // renderer language: eng, cht, chs, jpn, ...
     // or an array which has the same keys with a language file
     'language' => 'eng',
-    // show a separator between different diff hunks in HTML templates
+    // show a separator between different diff hunks in HTML renderers
     'separateBlock' => true,
     // the frontend HTML could use CSS "white-space: pre;" to visualize consecutive whitespaces
     // but if you want to visualize them in the backend with " ", you can set this to true
     'spacesToNbsp' => false,
-    // HTML template tab width (negative = do not convert into spaces)
+    // HTML renderer tab width (negative = do not convert into spaces)
     'tabSize' => 4,
     // internally, ops (tags) are all int type but this is not good for human reading.
     // set this to "true" to convert them into string form before outputting.
     'outputTagAsString' => true,
 ];
 
 // one-line simply compare two files
-$result = DiffHelper::calculateFiles($oldFile, $newFile, $differOptions, $templateOptions);
+$result = DiffHelper::calculateFiles($oldFile, $newFile, $rendererName, $differOptions, $rendererOptions);
 // one-line simply compare two strings
-$result = DiffHelper::calculate($old, $new, $template, $differOptions, $templateOptions);
+$result = DiffHelper::calculate($old, $new, $rendererName, $differOptions, $rendererOptions);
 // or even shorter if you are happy with default options
-$result = DiffHelper::calculate($old, $new, $template);
+$result = DiffHelper::calculate($old, $new, $rendererName);
 
 // custom usage
 $differ = new Differ(explode("\n", $old), explode("\n", $new), $differOptions);
-$renderer = RendererFactory::make($template, $templateOptions); // or your own renderers
+$renderer = RendererFactory::make($rendererName, $rendererOptions); // or your own renderers
 $result = $renderer->render($differ);
 ```
 

UPGRADING/UPGRADING_v6.md

@@ -12,6 +12,13 @@ there is no breaking change for you so you do not have to do anything.
 - The `Diff` class has been renamed to `Differ`.
   It's easy to adapt to this by changing the class name.
 
+- The term `template` has been renamed to `renderer`. Some examples are:
+
+  - Method `DiffHelper::getRenderersInfo()`
+  - Method `DiffHelper::getAvailableRenderers()`
+  - Constant `RendererConstant::RENDERER_TYPES`
+  - Constant `AbstractRenderer::IS_TEXT_RENDERER`
+
 - Now a `Renderer` has `render()` API, but a `Differ` does not.
   But if you use those classes by yourself, it should be written like below.
 
@@ -20,7 +27,7 @@ there is no breaking change for you so you do not have to do anything.
   use Jfcherng\Diff\Factory\RendererFactory;
 
   $differ = new Differ(explode("\n", $old), explode("\n", $new), $diffOptions);
-  $renderer = RendererFactory::make($template, $templateOptions);
+  $renderer = RendererFactory::make($renderer, $rendererOptions);
   $result = $renderer->render($differ); // <-- this has been changed
   ```
 

example/demo.php

@@ -31,19 +31,19 @@
                 'ignoreWhitespace' => false,
             ];
 
-            // options for template class
-            $templateOptions = [
+            // options for renderer class
+            $rendererOptions = [
                 // how detailed the rendered HTML is? (line, word, char)
                 'detailLevel' => 'line',
-                // template language: eng, cht, chs, jpn, ...
+                // renderer language: eng, cht, chs, jpn, ...
                 // or an array which has the same keys with a language file
                 'language' => 'eng',
-                // show a separator between different diff hunks in HTML templates
+                // show a separator between different diff hunks in HTML renderers
                 'separateBlock' => true,
                 // the frontend HTML could use CSS "white-space: pre;" to visualize consecutive whitespaces
                 // but if you want to visualize them in the backend with " ", you can set this to true
                 'spacesToNbsp' => false,
-                // HTML template tab width (negative = do not convert into spaces)
+                // HTML renderer tab width (negative = do not convert into spaces)
                 'tabSize' => 4,
                 // internally, ops (tags) are all int type but this is not good for human reading.
                 // set this to "true" to convert them into string form before outputting.
@@ -61,7 +61,7 @@
                 $newFile,
                 'Inline',
                 $diffOptions,
-                ['detailLevel' => 'none'] + $templateOptions
+                ['detailLevel' => 'none'] + $rendererOptions
             );
 
             echo $result;
@@ -77,7 +77,7 @@
                 $newFile,
                 'Inline',
                 $diffOptions,
-                ['detailLevel' => 'line'] + $templateOptions
+                ['detailLevel' => 'line'] + $rendererOptions
             );
 
             echo $result;
@@ -93,7 +93,7 @@
                 $newFile,
                 'Inline',
                 $diffOptions,
-                ['detailLevel' => 'word'] + $templateOptions
+                ['detailLevel' => 'word'] + $rendererOptions
             );
 
             echo $result;
@@ -109,7 +109,7 @@
                 $newFile,
                 'Inline',
                 $diffOptions,
-                ['detailLevel' => 'char'] + $templateOptions
+                ['detailLevel' => 'char'] + $rendererOptions
             );
 
             echo $result;
@@ -125,7 +125,7 @@
                 $newFilePath,
                 'SideBySide',
                 $diffOptions,
-                $templateOptions
+                $rendererOptions
             );
 
             echo $result;
@@ -141,7 +141,7 @@
                 $newFilePath,
                 'Inline',
                 $diffOptions,
-                $templateOptions
+                $rendererOptions
             );
 
             echo $result;
@@ -157,7 +157,7 @@
                 $newFilePath,
                 'Unified',
                 $diffOptions,
-                $templateOptions
+                $rendererOptions
             );
 
             echo \htmlspecialchars($result);
@@ -173,7 +173,7 @@
                 $newFilePath,
                 'Context',
                 $diffOptions,
-                $templateOptions
+                $rendererOptions
             );
 
             echo \htmlspecialchars($result);
@@ -189,7 +189,7 @@
                 $newFilePath,
                 'Json',
                 $diffOptions,
-                ['outputTagAsString' => true] + $templateOptions
+                ['outputTagAsString' => true] + $rendererOptions
             );
 
             $beautified = \json_encode(

src/DiffHelper.php

@@ -29,11 +29,11 @@ public static function getProjectDirectory(): string
     }
 
     /**
-     * Get the information about available templates.
+     * Get the information about available renderers.
      *
      * @return array
      */
-    public static function getTemplatesInfo(): array
+    public static function getRenderersInfo(): array
     {
         static $info;
 
@@ -45,7 +45,7 @@ public static function getTemplatesInfo(): array
             static::getProjectDirectory(),
             'src',
             'Renderer',
-            '{' . \implode(',', RendererConstant::TEMPLATE_TYPES) . '}',
+            '{' . \implode(',', RendererConstant::RENDERER_TYPES) . '}',
             '*.php',
         ]);
 
@@ -58,7 +58,7 @@ function (string $file): string {
             \glob($glob, \GLOB_BRACE)
         );
 
-        $templates = \array_filter(
+        $renderers = \array_filter(
             $fileNames,
             // only normal class files are wanted
             function (string $fileName): bool {
@@ -70,25 +70,25 @@ function (string $fileName): bool {
         );
 
         $info = [];
-        foreach ($templates as $template) {
-            $info[$template] = RendererFactory::resolveTemplate($template)::INFO;
+        foreach ($renderers as $renderer) {
+            $info[$renderer] = RendererFactory::resolveRenderer($renderer)::INFO;
         }
 
         return $info;
     }
 
     /**
-     * Get the available templates.
+     * Get the available renderers.
      *
-     * @return string[] the available templates
+     * @return string[] the available renderers
      */
-    public static function getAvailableTemplates(): array
+    public static function getAvailableRenderers(): array
     {
-        return \array_keys(self::getTemplatesInfo());
+        return \array_keys(self::getRenderersInfo());
     }
 
     /**
-     * Get the content of the CSS style sheet for HTML templates.
+     * Get the content of the CSS style sheet for HTML renderers.
      *
      * @throws \LogicException   path is a directory
      * @throws \RuntimeException path cannot be opened
@@ -115,25 +115,25 @@ public static function getStyleSheet(): string
      *
      * @param string|string[] $old             the old string (or array of lines)
      * @param string|string[] $new             the new string (or array of lines)
-     * @param string          $template        the template name
+     * @param string          $renderer        the renderer name
      * @param array           $differOptions   the options for Differ object
-     * @param array           $templateOptions the options for template object
+     * @param array           $rendererOptions the options for renderer object
      *
      * @return string the rendered differences
      */
     public static function calculate(
         $old,
         $new,
-        string $template = 'Unified',
+        string $renderer = 'Unified',
         array $differOptions = [],
-        array $templateOptions = []
+        array $rendererOptions = []
     ): string {
         // always convert into array form
         \is_string($old) && ($old = \explode("\n", $old));
         \is_string($new) && ($new = \explode("\n", $new));
 
-        return RendererFactory::getInstance($template)
-            ->setOptions($templateOptions)
+        return RendererFactory::getInstance($renderer)
+            ->setOptions($rendererOptions)
             ->render(
                 Differ::getInstance()
                     ->setOldNew($old, $new)
@@ -146,9 +146,9 @@ public static function calculate(
      *
      * @param string $old             the path of the old file
      * @param string $new             the path of the new file
-     * @param string $template        the template name
+     * @param string $renderer        the renderer name
      * @param array  $differOptions   the options for Differ object
-     * @param array  $templateOptions the options for template object
+     * @param array  $rendererOptions the options for renderer object
      *
      * @throws \LogicException   path is a directory
      * @throws \RuntimeException path cannot be opened
@@ -158,9 +158,9 @@ public static function calculate(
     public static function calculateFiles(
         string $old,
         string $new,
-        string $template = 'Unified',
+        string $renderer = 'Unified',
         array $differOptions = [],
-        array $templateOptions = []
+        array $rendererOptions = []
     ): string {
         // we want to leave the line-ending problem to static::calculate()
         // so do not set SplFileObject::DROP_NEW_LINE flag
@@ -171,9 +171,9 @@ public static function calculateFiles(
         return static::calculate(
             $oldFile->fread($oldFile->getSize()),
             $newFile->fread($newFile->getSize()),
-            $template,
+            $renderer,
             $differOptions,
-            $templateOptions
+            $rendererOptions
         );
     }
 }