Added excerpt helper

src/Helpers.php

@@ -47,6 +47,7 @@ class Helpers extends BaseHelpers
         $this->add('repeat', new Text\RepeatHelper());
         $this->add('replace', new Text\ReplaceHelper());
         $this->add('truncate', new Text\TruncateHelper());
+        $this->add('excerpt', new Text\ExcerptHelper());
 
         // Layout helpers
         $storage = new Layout\BlockStorage();

src/Text/ExcerptHelper.php

@@ -0,0 +1,72 @@
+<?php
+/**
+* Excerpt
+* (c) Matteo Merola
+*
+*/
+
+namespace JustBlackBird\HandlebarsHelpers\Text;
+
+use Handlebars\Context;
+use Handlebars\Helper as HelperInterface;
+use Handlebars\Template;
+
+/**
+ * Truncates a string to specified length in words.
+ *
+ * Usage:
+ * ```handlebars
+ *   {{#excerpt string length append}}
+ * ```
+ *
+ * Arguments:
+ *  - "string": A string that must be truncated.
+ *  - "length": A number of words to limit the string.
+ *  - "append": A string to append if charaters are omitted. Default value is an
+ *    empty string.
+ *
+ * @author Matteo Merola <mattmezza@gmail.com>
+ */
+class ExcerptHelper 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(
+                '"excerpt" helper expects two or three arguments.'
+            );
+        }
+        $varContent = (string)$context->get($parsed_args[0]);
+        $limit = intval($context->get($parsed_args[1]));
+        $ellipsis = isset($parsed_args[2]) ? (string)$context->get($parsed_args[2]) : '';
+        if ($limit === 0) {
+            return $ellipsis;
+        }
+        if ($limit < 0) {
+            throw new \InvalidArgumentException(
+                'The second argument of "excerpt" helper has to be greater than or equal to 0.'
+            );
+        }
+        $words = str_word_count($varContent, 2);
+        $value = "";
+        if (count($words) > $limit) {
+            $permitted = array_slice($words, 0, $limit, true);
+            end($permitted);
+            $lastWordPosition = key($permitted);
+            $lastWord = $permitted[$lastWordPosition];
+            $lastWordLength = strlen($lastWord);
+            $realLimit = $lastWordPosition+$lastWordLength;
+            $value = substr($varContent, 0, $realLimit);
+        } else {
+            $value .= $varContent;
+        }
+        if ($ellipsis) {
+            $value .= $ellipsis;
+        }
+        return $value;
+    }
+}

src/Text/Helpers.php

@@ -31,5 +31,6 @@ class Helpers extends BaseHelpers
         $this->add('repeat', new RepeatHelper());
         $this->add('replace', new ReplaceHelper());
         $this->add('truncate', new TruncateHelper());
+        $this->add('excerpt', new ExcerptHelper());
     }
 }

tests/HelpersTest.php

@@ -59,6 +59,7 @@ class HelpersTest extends \PHPUnit_Framework_TestCase
             array('repeat', '\\JustBlackBird\\HandlebarsHelpers\\Text\\RepeatHelper'),
             array('replace', '\\JustBlackBird\\HandlebarsHelpers\\Text\\ReplaceHelper'),
             array('truncate', '\\JustBlackBird\\HandlebarsHelpers\\Text\\TruncateHelper'),
+            array('excerpt', '\\JustBlackBird\\HandlebarsHelpers\\Text\\ExcerptHelper'),
 
             // Layout helpers
             array('block', '\\JustBlackBird\\HandlebarsHelpers\\Layout\\BlockHelper'),

tests/Text/ExcerptHelperTest.php

@@ -0,0 +1,100 @@
+<?php
+/*
+ *
+ * (c) Matteo Merola <mattmezza@gmail.com>
+ *
+ */
+
+namespace JustBlackBird\HandlebarsHelpers\Tests\Text;
+
+use JustBlackBird\HandlebarsHelpers\Text\ExcerptHelper;
+
+/**
+ * Test class for "excerpt" helper.
+ *
+ * @author Matteo Merola <mattmezza@gmail.com>
+ */
+class ExcerptTest extends \PHPUnit_Framework_TestCase
+{
+    /**
+     * Tests that strings are repeated properly.
+     *
+     * @dataProvider truncateProvider
+     */
+    public function testExcerpt($template, $data, $result)
+    {
+        $helpers = new \Handlebars\Helpers(array('excerpt' => new ExcerptHelper()));
+        $engine = new \Handlebars\Handlebars(array('helpers' => $helpers));
+
+        $this->assertEquals($engine->render($template, $data), $result);
+    }
+
+    /**
+     * A data provider for testExcerpt method.
+     */
+    public function truncateProvider()
+    {
+        return array(
+            // No truncate
+            array('{{excerpt a len}}', array('a' => '123', 'len' => 5), '123'),
+            // Simple truncates
+            array('{{excerpt "prova matteo ciao" 2}}', array(), 'prova matteo'),
+            array('{{excerpt "prova merola hello" 0}}', array(), ''),
+            // Truncate with ellipsis
+            array('{{excerpt "prova matt" 1 "..."}}', array(), 'prova...'),
+        );
+    }
+
+    /**
+     * 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('excerpt' => new ExcerptHelper()));
+        $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('{{excerpt}}'),
+            array('{{excerpt "abc"}}'),
+            // Too much arguments
+            array('{{excerpt "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('excerpt' => new ExcerptHelper()));
+        $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('{{excerpt "abc" -10}}'),
+        );
+    }
+}

tests/Text/HelpersTest.php

@@ -43,6 +43,7 @@ class HelpersTest extends \PHPUnit_Framework_TestCase
             array('repeat', '\\JustBlackBird\\HandlebarsHelpers\\Text\\RepeatHelper'),
             array('replace', '\\JustBlackBird\\HandlebarsHelpers\\Text\\ReplaceHelper'),
             array('truncate', '\\JustBlackBird\\HandlebarsHelpers\\Text\\TruncateHelper'),
+            array('excerpt', '\\JustBlackBird\\HandlebarsHelpers\\Text\\ExcerptHelper'),
         );
     }
 }