From: Robert Gruendler <robert@play.fm>
Date: Mon, 18 Jul 2011 11:32:46 +0000 (+0200)
Subject: added phpDocs for TokenParsers, filters and tests
X-Git-Url: http://git.silmor.de/gitweb/?a=commitdiff_plain;h=2b7e8d9da95d4f6cc07dac5cb36d551b8e413ce3;p=konrad%2Ftwig.git

added phpDocs for TokenParsers, filters and tests
---

diff --git a/lib/Twig/Extension/Core.php b/lib/Twig/Extension/Core.php
index 9211291..3771f48 100644
--- a/lib/Twig/Extension/Core.php
+++ b/lib/Twig/Extension/Core.php
@@ -191,6 +191,18 @@ function twig_cycle($values, $i)
     return $values[$i % count($values)];
 }
 
+/**
+ * 
+ * The date filter is able to format a date to a given format:
+ * 
+ * <pre>
+ *   {{ post.published_at|date("m/d/Y") }}
+ * </pre>
+ * 
+ * @param DateTime|string $date
+ * @param string $format
+ * @param string $timezone
+ */
 function twig_date_format_filter($date, $format = 'F j, Y H:i', $timezone = null)
 {
     if (!$date instanceof DateTime) {
@@ -213,6 +225,12 @@ function twig_date_format_filter($date, $format = 'F j, Y H:i', $timezone = null
     return $date->format($format);
 }
 
+/**
+ * The url_encode filter URL encodes a given string.
+ *
+ * @param string $url
+ * @param bool $raw if true uses rawurlencode() instead of urlencode
+ */
 function twig_urlencode_filter($url, $raw = false)
 {
     if ($raw) {
@@ -222,6 +240,12 @@ function twig_urlencode_filter($url, $raw = false)
     return urlencode($url);
 }
 
+/**
+ * The json_encode filter returns the JSON representation of a string.
+ *
+ * @param string $value The value being encoded. Can be any type except a resource. 
+ * @param integer options Bitmask consisting of JSON_HEX_QUOT, JSON_HEX_TAG, JSON_HEX_AMP, JSON_HEX_APOS, JSON_NUMERIC_CHECK, JSON_PRETTY_PRINT, JSON_UNESCAPED_SLASHES, JSON_FORCE_OBJECT. 
+ */
 function twig_jsonencode_filter($value, $options = 0)
 {
     if ($value instanceof Twig_Markup) {
@@ -240,6 +264,20 @@ function _twig_markup2string(&$value)
     }
 }
 
+/**
+ * The merge filter merges an array or a hash with the value:
+ *
+ * <pre>
+ * {% set items = { 'apple': 'fruit', 'orange': 'fruit' } %}
+ * 
+ *  {% set items = items|merge({ 'peugeot': 'car' }) %}
+ * 
+ *  {# items now contains { 'apple': 'fruit', 'orange': 'fruit', 'peugeot': 'car' } #}
+ * </pre>
+ * 
+ * @param array $arr1
+ * @param array $arr2
+ */
 function twig_array_merge($arr1, $arr2)
 {
     if (!is_array($arr1) || !is_array($arr2)) {
@@ -249,16 +287,55 @@ function twig_array_merge($arr1, $arr2)
     return array_merge($arr1, $arr2);
 }
 
+/**
+ * The join filter returns a string which is the concatenation of the strings in the sequence. The separator between elements is an empty string per default, you can define it with the optional parameter:
+ *
+ * <pre>
+ *  {{ [1, 2, 3]|join('|') }}
+ *  {# returns 1|2|3 #}
+ *
+ *  {{ [1, 2, 3]|join }}
+ *  {# returns 123 #}
+ * </pre>
+ *
+ * @param array $value
+ * @param string $glue
+ */
 function twig_join_filter($value, $glue = '')
 {
     return implode($glue, (array) $value);
 }
 
+/**
+ *
+ * The default filter returns the passed default value if the value is undefined or empty, otherwise the value of the variable
+ * 
+ * <pre>
+ * 
+ *  {{ var.foo|default('foo item on var is not defined') }}
+ *
+ * </pre>
+ * 
+ * @param mixed $value
+ * @param string $default
+ */
 function twig_default_filter($value, $default = '')
 {
     return twig_test_empty($value) ? $default : $value;
 }
 
+/**
+ * The keys filter returns the keys of an array. It is useful when you want to iterate over the keys of an array: 
+ *
+ * <pre>
+ * {% for key in array|keys %}
+ *      ...
+ *  {% endfor %}
+ * </pre>
+ *
+ * @param array $array
+ *
+ */
 function twig_get_array_keys_filter($array)
 {
     if (is_object($array) && $array instanceof Traversable) {
@@ -272,6 +349,11 @@ function twig_get_array_keys_filter($array)
     return array_keys($array);
 }
 
+/**
+ * The reverse filter reverses an array or an object if it implements the Iterator interface.
+ *
+ * @param array $array
+ */
 function twig_reverse_filter($array)
 {
     if (is_object($array) && $array instanceof Traversable) {
@@ -285,6 +367,11 @@ function twig_reverse_filter($array)
     return array_reverse($array);
 }
 
+/**
+ * The sort filter sorts an array using PHPs asort().
+ * 
+ * @param array $array
+ */
 function twig_sort_filter($array)
 {
     asort($array);
@@ -305,6 +392,16 @@ function twig_in_filter($value, $compare)
     return false;
 }
 
+/**
+ * The replace filter formats a given string by replacing the placeholders (placeholders are free-form):
+ *
+ * <pre>
+ *  {{ "I like %this% and %that%."|replace({'%this%': foo, '%that%': "bar"}) }}
+ * </pre>
+ *
+ * @param string $pattern
+ * @param string $replacements
+ */
 function twig_strtr($pattern, $replacements)
 {
     return str_replace(array_keys($replacements), array_values($replacements), $pattern);
@@ -362,6 +459,12 @@ function twig_escape_filter(Twig_Environment $env, $string, $type = 'html', $cha
     }
 }
 
+/**
+ * The escape filter converts the characters &, <, >, ', and " in strings to HTML-safe sequences. Use this if you need to display text that might contain such characters in HTML.
+ * It uses the PHP function htmlspecialchars() internally.
+ *
+ * @param Twig_Node $filterArgs
+ */
 function twig_escape_filter_is_safe(Twig_Node $filterArgs)
 {
     foreach ($filterArgs as $arg) {
@@ -411,11 +514,23 @@ function _twig_escape_js_callback($matches)
 
 // add multibyte extensions if possible
 if (function_exists('mb_get_info')) {
+    /**
+     * The length filters returns the number of items of a sequence or mapping, or the length of a string.
+     * 
+     * @param Twig_Environment $env
+     * @param mixed $thing
+     */
     function twig_length_filter(Twig_Environment $env, $thing)
     {
         return is_scalar($thing) ? mb_strlen($thing, $env->getCharset()) : count($thing);
     }
 
+    /**
+     * The upper filter converts a value to uppercase.
+     *
+     * @param Twig_Environment $env
+     * @param string $string
+     */
     function twig_upper_filter(Twig_Environment $env, $string)
     {
         if (null !== ($charset = $env->getCharset())) {
@@ -425,6 +540,12 @@ if (function_exists('mb_get_info')) {
         return strtoupper($string);
     }
 
+    /**
+     * The lower filter converts a value to lowercase.
+     *
+     * @param Twig_Environment $env
+     * @param string $string
+     */
     function twig_lower_filter(Twig_Environment $env, $string)
     {
         if (null !== ($charset = $env->getCharset())) {
@@ -434,6 +555,12 @@ if (function_exists('mb_get_info')) {
         return strtolower($string);
     }
 
+    /**
+     * The title filter returns a titlecased version of the value. I.e. words will start with uppercase letters, all remaining characters are lowercase.
+     *
+     * @param Twig_Environment $env
+     * @param string $string
+     */
     function twig_title_string_filter(Twig_Environment $env, $string)
     {
         if (null !== ($charset = $env->getCharset())) {
@@ -443,6 +570,12 @@ if (function_exists('mb_get_info')) {
         return ucwords(strtolower($string));
     }
 
+    /**
+     * The capitalize filter capitalizes a value. The first character will be uppercase, all others lowercase. 
+     *
+     * @param Twig_Environment $env
+     * @param string $string
+     */
     function twig_capitalize_string_filter(Twig_Environment $env, $string)
     {
         if (null !== ($charset = $env->getCharset())) {
@@ -456,16 +589,34 @@ if (function_exists('mb_get_info')) {
 // and byte fallback
 else
 {
+   /**
+    * The length filters returns the number of items of a sequence or mapping, or the length of a string.
+    * 
+    * @param Twig_Environment $env
+    * @param mixed $thing
+    */
     function twig_length_filter(Twig_Environment $env, $thing)
     {
         return is_scalar($thing) ? strlen($thing) : count($thing);
     }
 
+    /**
+     * The title filter returns a titlecased version of the value. I.e. words will start with uppercase letters, all remaining characters are lowercase.
+     *
+     * @param Twig_Environment $env
+     * @param string $string
+     */
     function twig_title_string_filter(Twig_Environment $env, $string)
     {
         return ucwords(strtolower($string));
     }
 
+    /**
+     * The capitalize filter capitalizes a value. The first character will be uppercase, all others lowercase. 
+     *
+     * @param Twig_Environment $env
+     * @param string $string
+     */
     function twig_capitalize_string_filter(Twig_Environment $env, $string)
     {
         return ucfirst(strtolower($string));
@@ -481,41 +632,127 @@ function twig_ensure_traversable($seq)
     }
 }
 
+/**
+ * sameas checks if a variable points to the same memory address than another variable:
+ * 
+ * <pre> 
+ * {% if foo.attribute is sameas(false) %}
+ *    the foo attribute really is the ``false`` PHP value
+ * {% endif %} 
+ * </pre>
+ * 
+ * @param mixed $value
+ * @param mixed $test
+ */
 function twig_test_sameas($value, $test)
 {
     return $value === $test;
 }
 
+/**
+ * none returns true if the variable is none:
+ * 
+ * <pre> 
+ *  {{ var is none }}
+ * </pre>
+ * 
+ * @param mixed $value
+ */
 function twig_test_none($value)
 {
     return null === $value;
 }
 
+/**
+ * divisibleby checks if a variable is divisible by a number:
+ * 
+ * <pre> 
+ *  {% if loop.index is divisibleby(3) %} 
+ * </pre>
+ * 
+ * @param integer $value
+ * @param integer $num
+ */
 function twig_test_divisibleby($value, $num)
 {
     return 0 == $value % $num;
 }
 
+/**
+* even returns true if the given number is even:
+*
+* <pre>
+*  {{ var is even }}
+* </pre>
+*
+* @param integer $value
+*/
 function twig_test_even($value)
 {
     return $value % 2 == 0;
 }
 
+/**
+* odd returns true if the given number is odd:
+*
+* <pre>
+*  {{ var is odd }}
+* </pre>
+*
+* @param integer $value
+*/
 function twig_test_odd($value)
 {
     return $value % 2 == 1;
 }
 
+/**
+* constant checks if a variable has the exact same value as a constant. You can use either global constants or class constants:
+*
+* <pre>
+*  {% if post.status is constant('Post::PUBLISHED') %}
+*    the status attribute is exactly the same as Post::PUBLISHED
+*  {% endif %}
+* </pre>
+*
+* @param mixed $value
+* @param mixed $constant
+*/
 function twig_test_constant($value, $constant)
 {
     return constant($constant) === $value;
 }
 
+/**
+* defined checks if a variable is defined in the current context. This is very useful if you use the strict_variables option:
+*
+* <pre>
+* {# defined works with variable names #}
+* {% if foo is defined %}
+*     ...
+* {% endif %}
+* </pre>
+*
+* @param mixed $name value to check.
+* @param array $context An array with keys to check.
+*/
 function twig_test_defined($name, $context)
 {
     return array_key_exists($name, $context);
 }
 
+/**
+* empty checks if a variable is empty:
+*
+* <pre>
+* {# evaluates to true if the foo variable is null, false, or the empty string #}
+* {% if foo is empty %}
+*     ...
+* {% endif %}
+* </pre>
+*
+* @param mixed $value
+*/
 function twig_test_empty($value)
 {
     return false === $value || (empty($value) && '0' != $value);
diff --git a/lib/Twig/TokenParser/AutoEscape.php b/lib/Twig/TokenParser/AutoEscape.php
index 59180c1..75c6c5e 100644
--- a/lib/Twig/TokenParser/AutoEscape.php
+++ b/lib/Twig/TokenParser/AutoEscape.php
@@ -8,6 +8,26 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
+/**
+ *  
+ * You can mark a section of a template to be escaped or not by using the autoescape tag:
+ * 
+ * <pre>
+ * {% autoescape true %}
+ *   Everything will be automatically escaped in this block
+ * {% endautoescape %}
+ *
+ * {% autoescape false %}
+ *   Everything will be outputed as is in this block
+ * {% endautoescape %}
+ *
+ * {% autoescape true js %}
+ *   Everything will be automatically escaped in this block
+ *   using the js escaping strategy
+ * {% endautoescape %}
+ * </pre>
+ *
+ */
 class Twig_TokenParser_AutoEscape extends Twig_TokenParser
 {
     /**
diff --git a/lib/Twig/TokenParser/Block.php b/lib/Twig/TokenParser/Block.php
index 92028a1..54ee61f 100644
--- a/lib/Twig/TokenParser/Block.php
+++ b/lib/Twig/TokenParser/Block.php
@@ -9,6 +9,20 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
+/**
+ * 
+ * Blocks are used for inheritance and act as placeholders and replacements at the same time.
+ *
+ * 
+ * <pre>
+ *  {% block head %}
+ *    <link rel="stylesheet" href="style.css" />
+ *    <title>{% block title %}{% endblock %} - My Webpage</title>
+ *  {% endblock %}
+ * </pre>
+ * 
+ *
+ */ 
 class Twig_TokenParser_Block extends Twig_TokenParser
 {
     /**
diff --git a/lib/Twig/TokenParser/Extends.php b/lib/Twig/TokenParser/Extends.php
index 8115aa7..4582077 100644
--- a/lib/Twig/TokenParser/Extends.php
+++ b/lib/Twig/TokenParser/Extends.php
@@ -9,6 +9,19 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
+/**
+ * 
+ * The extends tag can be used to extend a template from another one. 
+ * You can have multiple of them in a file but only one of them may be executed at the time. 
+ * There is no support for multiple inheritance. 
+ *
+ * 
+ * <pre>
+ *  {% extends "base.html" %}
+ * </pre>
+ * 
+ *
+ */ 
 class Twig_TokenParser_Extends extends Twig_TokenParser
 {
     /**
diff --git a/lib/Twig/TokenParser/Filter.php b/lib/Twig/TokenParser/Filter.php
index b15d375..2117eaa 100644
--- a/lib/Twig/TokenParser/Filter.php
+++ b/lib/Twig/TokenParser/Filter.php
@@ -8,6 +8,19 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
+/**
+ * 
+ * Filter sections allow you to apply regular Twig filters on a block of template data. Just wrap the code in the special filter section:
+ *
+ * 
+ * <pre>
+ * {% filter upper %}
+ *  This text becomes uppercase
+ * {% endfilter %}
+ * </pre>
+ * 
+ *
+ */
 class Twig_TokenParser_Filter extends Twig_TokenParser
 {
     /**
diff --git a/lib/Twig/TokenParser/For.php b/lib/Twig/TokenParser/For.php
index 20740d4..3cc7c59 100644
--- a/lib/Twig/TokenParser/For.php
+++ b/lib/Twig/TokenParser/For.php
@@ -9,6 +9,21 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
+/**
+ * 
+ * Loop over each item in a sequence. For example, to display a list of users provided in a variable called users:
+ *
+ * 
+ * <pre>
+ * <ul>
+ *  {% for user in users %}
+ *    <li>{{ user.username|e }}</li>
+ *  {% endfor %}
+ * </ul> 
+ * </pre>
+ * 
+ *
+ */ 
 class Twig_TokenParser_For extends Twig_TokenParser
 {
     /**
diff --git a/lib/Twig/TokenParser/If.php b/lib/Twig/TokenParser/If.php
index 59c5773..17a6a9a 100644
--- a/lib/Twig/TokenParser/If.php
+++ b/lib/Twig/TokenParser/If.php
@@ -9,6 +9,22 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
+/**
+ * 
+ * The if statement in Twig is comparable with the if statements of PHP. In the simplest form you can use it to test if a variable is not empty:
+ *
+ * <pre>
+ * {% if users %}
+ *  <ul>
+ *    {% for user in users %}
+ *      <li>{{ user.username|e }}</li>
+ *    {% endfor %}
+ *  </ul>
+ * {% endif %}
+ * </pre>
+ * 
+ *
+ */
 class Twig_TokenParser_If extends Twig_TokenParser
 {
     /**
diff --git a/lib/Twig/TokenParser/Import.php b/lib/Twig/TokenParser/Import.php
index e791138..6a9ad6f 100644
--- a/lib/Twig/TokenParser/Import.php
+++ b/lib/Twig/TokenParser/Import.php
@@ -8,6 +8,18 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
+/**
+ * 
+ * Twig supports putting often used code into macros. 
+ * These macros can go into different templates and get imported from there.
+ *
+ * 
+ * <pre>
+ *   {% import 'forms.html' as forms %}
+ * </pre>
+ * 
+ *
+ */
 class Twig_TokenParser_Import extends Twig_TokenParser
 {
     /**
diff --git a/lib/Twig/TokenParser/Include.php b/lib/Twig/TokenParser/Include.php
index cd44803..0a983da 100644
--- a/lib/Twig/TokenParser/Include.php
+++ b/lib/Twig/TokenParser/Include.php
@@ -9,6 +9,19 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
+/**
+ * 
+ * The include statement is useful to include a template and return the rendered content of that file into the current namespace:
+ *
+ * 
+ * <pre>
+ *   {% include 'header.html' %}
+ *     Body
+ *   {% include 'footer.html' %}
+ * </pre>
+ * 
+ *
+ */
 class Twig_TokenParser_Include extends Twig_TokenParser
 {
     /**
diff --git a/lib/Twig/TokenParser/Macro.php b/lib/Twig/TokenParser/Macro.php
index 1f2210d..e25c3a8 100644
--- a/lib/Twig/TokenParser/Macro.php
+++ b/lib/Twig/TokenParser/Macro.php
@@ -8,6 +8,21 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
+/**
+ * 
+ * Macros are comparable with functions in regular programming languages. 
+ * They are useful to put often used HTML idioms into reusable elements to not repeat yourself.
+ * Here is a small example of a macro that renders a form element:
+ *
+ * 
+ * <pre>
+ * {% macro input(name, value, type, size) %}
+ *    <input type="{{ type|default('text') }}" name="{{ name }}" value="{{ value|e }}" size="{{ size|default(20) }}" />
+ * {% endmacro %}
+ * </pre>
+ * 
+ *
+ */
 class Twig_TokenParser_Macro extends Twig_TokenParser
 {
     /**
diff --git a/lib/Twig/TokenParser/Sandbox.php b/lib/Twig/TokenParser/Sandbox.php
index 964fe6f..90971d3 100644
--- a/lib/Twig/TokenParser/Sandbox.php
+++ b/lib/Twig/TokenParser/Sandbox.php
@@ -8,6 +8,19 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
+/**
+ * The sandbox extension can be used to evaluate untrusted code. Access to unsafe attributes and methods is prohibited. 
+ *
+ *
+ * <pre>
+ * {% sandbox %}
+ *     {% include 'user.html' %}
+ * {% endsandbox %}
+ * </pre>
+ *
+ * @see http://www.twig-project.org/doc/api.html#sandbox-extension for details
+ *
+ */
 class Twig_TokenParser_Sandbox extends Twig_TokenParser
 {
     /**
diff --git a/lib/Twig/TokenParser/Set.php b/lib/Twig/TokenParser/Set.php
index eb5e5fe..6d294d5 100644
--- a/lib/Twig/TokenParser/Set.php
+++ b/lib/Twig/TokenParser/Set.php
@@ -8,6 +8,26 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
+/**
+ * 
+ * Inside code blocks you can also assign values to variables. Assignments use the set tag and can have multiple targets:
+ * 
+ * <pre>
+ *  {% set foo = 'foo' %}
+ *
+ *  {% set foo = [1, 2] %}
+ *
+ *  {% set foo = {'foo': 'bar'} %}
+ *
+ *  {% set foo = 'foo' ~ 'bar' %}
+ *
+ *  {% set foo, bar = 'foo', 'bar' %}
+ *
+ *  {% set foo %}Some content{% endset %}
+ * </pre>
+ * 
+ *
+ */
 class Twig_TokenParser_Set extends Twig_TokenParser
 {
     /**
diff --git a/lib/Twig/TokenParser/Spaceless.php b/lib/Twig/TokenParser/Spaceless.php
index ac20439..064f54f 100644
--- a/lib/Twig/TokenParser/Spaceless.php
+++ b/lib/Twig/TokenParser/Spaceless.php
@@ -8,6 +8,20 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
+/**
+ * Use the spaceless tag to remove whitespace between HTML tags:
+ *
+ * <pre>
+ * {% spaceless %}
+ *      <div>
+ *          <strong>foo</strong>
+ *      </div>
+ * {% endspaceless %}
+ * 
+ * {# output will be <div><strong>foo</strong></div> #}
+ * </pre>
+ *
+ */
 class Twig_TokenParser_Spaceless extends Twig_TokenParser
 {
     /**
diff --git a/lib/Twig/TokenParser/Use.php b/lib/Twig/TokenParser/Use.php
index 7c1cbee..c7ff6fe 100644
--- a/lib/Twig/TokenParser/Use.php
+++ b/lib/Twig/TokenParser/Use.php
@@ -8,6 +8,20 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
+/**
+ * The use statement tells Twig to import the blocks defined in another template into the current template (it’s like macros, but for blocks):
+ *
+ * <pre>
+ * {% extends "base.html" %}
+ *
+ * {% use "blocks.html" %}
+ *
+ * {% block title %}{% endblock %}
+ * {% block content %}{% endblock %}
+ * </pre>
+ *
+ * @see http://www.twig-project.org/doc/templates.html#horizontal-reuse for details.
+ */
 class Twig_TokenParser_Use extends Twig_TokenParser
 {
     /**