Add "truncate" helper

src/Helpers.php

@@ -40,5 +40,6 @@ class Helpers extends BaseHelpers
         $this->add('lowercase', new String\LowercaseHelper());
         $this->add('uppercase', new String\UppercaseHelper());
         $this->add('repeat', new String\RepeatHelper());
+        $this->add('truncate', new String\TruncateHelper());
     }
 }

src/String/Helpers.php

@@ -29,5 +29,6 @@ class Helpers extends BaseHelpers
         $this->add('lowercase', new LowercaseHelper());
         $this->add('uppercase', new UppercaseHelper());
         $this->add('repeat', new RepeatHelper());
+        $this->add('truncate', new TruncateHelper());
     }
 }

src/String/TruncateHelper.php

@@ -0,0 +1,69 @@
+<?php
+/*
+ * This file is part of Handlebars.php Helpers Set
+ *
+ * (c) Dmitriy Simushev <simushevds@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace JustBlackBird\HandlebarsHelpers\String;
+
+use Handlebars\Context;
+use Handlebars\Helper as HelperInterface;
+use Handlebars\Template;
+
+/**
+ * Truncates a string to specified length.
+ *
+ * Usage:
+ * ```handlebars
+ *   {{truncate string length append}}
+ * ```
+ *
+ * Arguments:
+ *  - "string": A string that must be truncated.
+ *  - "length": A number of characters to limit the string.
+ *  - "append": A string to append if charaters are omitted. Default value is an
+ *    empty string.
+ *
+ * @author Dmitriy Simushev <simushevds@gmail.com>
+ */
+class TruncateHelper implements HelperInterface
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function execute(Template $template, Context $context, $args, $source)
+    {
+        $parsed_args = $template->parseArguments($args);
+        if (count($parsed_args) < 2 || count($parsed_args) > 3) {
+            throw new \InvalidArgumentException(
+                '"truncate" helper expects two or three arguments.'
+            );
+        }
+
+        $string = (string)$context->get($parsed_args[0]);
+        $length = intval($context->get($parsed_args[1]));
+        $append = isset($parsed_args[2]) ? (string)$context->get($parsed_args[2]) : '';
+
+        if ($length < 0) {
+            throw new \InvalidArgumentException(
+                'The second argument of "truncate" helper has to be greater than or equal to 0.'
+            );
+        }
+
+        if ($append && strlen($append) > $length) {
+            throw new \InvalidArgumentException(
+                'Cannot truncate string. Length of append value is greater than target length.'
+            );
+        }
+
+        if (strlen($string) > $length) {
+            return substr($string, 0, $length - strlen($append)) . $append;
+        } else {
+            return $string;
+        }
+    }
+}

tests/HelpersTest.php

@@ -52,6 +52,7 @@ class HelpersTest extends \PHPUnit_Framework_TestCase
             array('lowercase', '\\JustBlackBird\\HandlebarsHelpers\\String\\LowercaseHelper'),
             array('uppercase', '\\JustBlackBird\\HandlebarsHelpers\\String\\UppercaseHelper'),
             array('repeat', '\\JustBlackBird\\HandlebarsHelpers\\String\\RepeatHelper'),
+            array('truncate', '\\JustBlackBird\\HandlebarsHelpers\\String\\TruncateHelper'),
         );
     }
 }

tests/String/HelpersTest.php

@@ -41,6 +41,7 @@ class HelpersTest extends \PHPUnit_Framework_TestCase
             array('lowercase', '\\JustBlackBird\\HandlebarsHelpers\\String\\LowercaseHelper'),
             array('uppercase', '\\JustBlackBird\\HandlebarsHelpers\\String\\UppercaseHelper'),
             array('repeat', '\\JustBlackBird\\HandlebarsHelpers\\String\\RepeatHelper'),
+            array('truncate', '\\JustBlackBird\\HandlebarsHelpers\\String\\TruncateHelper'),
         );
     }
 }

tests/String/TruncateHelperTest.php

@@ -0,0 +1,105 @@
+<?php
+/*
+ * This file is part of Handlebars.php Helpers Set
+ *
+ * (c) Dmitriy Simushev <simushevds@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace JustBlackBird\HandlebarsHelpers\Tests\String;
+
+use JustBlackBird\HandlebarsHelpers\String\TruncateHelper;
+
+/**
+ * Test class for "truncate" helper.
+ *
+ * @author Dmitriy Simushev <simushevds@gmail.com>
+ */
+class TruncateTest extends \PHPUnit_Framework_TestCase
+{
+    /**
+     * Tests that strings are repeated properly.
+     *
+     * @dataProvider truncateProvider
+     */
+    public function testTruncate($template, $data, $result)
+    {
+        $helpers = new \Handlebars\Helpers(array('truncate' => new TruncateHelper()));
+        $engine = new \Handlebars\Handlebars(array('helpers' => $helpers));
+
+        $this->assertEquals($engine->render($template, $data), $result);
+    }
+
+    /**
+     * A data provider for testTruncate method.
+     */
+    public function truncateProvider()
+    {
+        return array(
+            // No truncate
+            array('{{truncate a len}}', array('a' => '123', 'len' => 5), '123'),
+            // Simple truncates
+            array('{{truncate "0123456789" 5}}', array(), '01234'),
+            array('{{truncate "0123456789" 0}}', array(), ''),
+            // Truncate with ellipsis
+            array('{{truncate "0123456789" 5 "..."}}', array(), '01...'),
+        );
+    }
+
+    /**
+     * Tests that exception is thrown if wrong number of arguments is used.
+     *
+     * @expectedException InvalidArgumentException
+     * @dataProvider wrongArgumentsSetProvider
+     */
+    public function testArgumentsCount($template)
+    {
+        $helpers = new \Handlebars\Helpers(array('truncate' => new TruncateHelper()));
+        $engine = new \Handlebars\Handlebars(array('helpers' => $helpers));
+
+        $engine->render($template, array());
+    }
+
+    /**
+     * A data provider for testArgumentsCount method.
+     */
+    public function wrongArgumentsSetProvider()
+    {
+        return array(
+            // Not enough arguments
+            array('{{truncate}}'),
+            array('{{truncate "abc"}}'),
+            // Too much arguments
+            array('{{truncate "abc" 30 "..." "xyz"}}'),
+        );
+    }
+
+    /**
+     * Tests that exception is thrown if arguments are invalid.
+     *
+     * @expectedException InvalidArgumentException
+     * @dataProvider invalidArgumentsProvider
+     */
+    public function testInvalidArguments($template)
+    {
+        $helpers = new \Handlebars\Helpers(array('truncate' => new TruncateHelper()));
+        $engine = new \Handlebars\Handlebars(array('helpers' => $helpers));
+
+        $engine->render($template, array());
+    }
+
+    /**
+     * A data provider for testInvalidArguments method.
+     */
+    public function invalidArgumentsProvider()
+    {
+        return array(
+            // Negative target length.
+            array('{{truncate "abc" -10}}'),
+            // Length of ellipsis is greater than target length.
+            array('{{truncate "abc" 2 "..."}}')
+        );
+    }
+}