Docs++

docs/en/readme.md

@@ -23,22 +23,26 @@ Documentation
 
 [Usage](./syntax.md#tags)
 
-* [set](./tags/var.md), `add` and `var` — define variables
+* [set](./tags/set.md), [add](./tags/set.md#add) and `var` — define variables
-* [if](./tags/if.md), `elseif` and `else` — conditional statement
+* [if](./tags/if.md), [elseif](./tags/if.md#elseif) and [else](./tags/if.md#else) — conditional statement
-* [foreach](./tags/foreach.md), `foreaelse`, `break` and `continue` — traversing items in an array or object
+* [foreach](./tags/foreach.md), [foreaelse](./tags/foreach.md#foreaelse),
-* [for](./tags/for.md), `forelse`, `break` and `continue` — loop statement
+  [break](./tags/foreach.md#break) and [continue](./tags/foreach.md#continue) — traversing items in an array or object
-* [switch](./tags/switch.md), `case`, `default` —
+* [switch](./tags/switch.md), [case](./tags/switch.md#case) — complex condition statement
 * [cycle](./tags/cycle.md) — cycles on an array of values
-* [include](./tags/include.md), `insert` —  includes and evaluates the specified template
+* [include](./tags/include.md), [insert](./tags/include.md#insert) —  includes and evaluates the specified template
-* [extends](./tags/extends.md), `use`, `block` and `parent` — template inheritance
+* [extends](./tags/extends.md), [use](./tags/extends.md#use),
+  [block](./tags/extends.md#block), [parent](./tags/extends.md#parent) and [paste](./tags/extends.md#paste) — template inheritance
 * [filter](./tags/filter.md) — apply modifier on a block of template data
 * [ignore](./tags/ignore.md) — ignore Fenom syntax
-* [macro](./tags/macro.md) and `import` — template functions
+* [macro](./tags/macro.md) and [import](./tags/macro.md#import) — template functions
 * [autoescape](./tags/autoescape.md) — escape template fragment
 * [raw](./tags/raw.md) — unescape template fragment
 * [unset](./tags/unset.md) — unset a given variables
 * or [add](./ext/extend.md#add-tags) yours
 
+Deprecated tags
+
+* [for](./tags/for.md), `forelse`, `break` and `continue` — loop statement
 
 ***
 

docs/en/tags/cycle.md

@@ -1,13 +1,15 @@
 Tag {cycle}
 ===========
 
+`{cycle}` is used to alternate a set of values.
+
 ```smarty
-{for $i=$a.c..}
+{foreach 1..10}
     <div class="{cycle ["odd", "even"]}">
-{/for}
+{/foreach}
 
 
-{for $i=$a.c..}
+{foreach 1..10}
     <div class="{cycle ["odd", "even"] index=$i}">
-{/for}
+{/foreach}
 ```

docs/en/tags/extends.md

@@ -1,82 +1,68 @@
-Tag {extends} [RU]
+Tag {extends}]
-==================
+=============
 
-Тег `{extends}` реализует наследование шаблонов, иерархия, обратная {include}. То есть шаблон сам выбирает своего родителя.
+`{extends}` tags are used in child templates in template inheritance for extending parent templates.
+The `{extends}` tag must be on before any block.
+Also if a child template extends a parent template with the `{extends}` tag it may contain only `{block}` tags. Any other template content is ignored.
 
 ### {extends}
 
-Родительский шаблон можно задать единожды и до объявления какого-либо блока.
-
 ```smarty
 {extends 'parent.tpl'}
 ```
 
-Имя родительского шаблона может быть задан динамически, в этом случае производительность отрисовки может снизиться.
-
-```smarty
-{extends $parent_tpl}
-```
-
 ### {block}
 
-Блок указывает фрагмент шаблона, который будет передан родителю. Имя блока может быть задано как явно
-
 ```smarty
-{block bk1}content 1{/block}
-...
 {block 'bk2'}content 2{/block}
 ```
 
-так и не явно, но в данном случае пострадает производительность
-
-```smarty
-{block "bk{$number}"}content {$number}{/block}
-...
-{if $condition}
-    {block "bk-if"}content, then 'if' is true{/block}
-{else}
-    {block "bk{$fail}"}content, then 'if' is false{/block}
-{/if}
-```
-
 ### {use}
 
 Что бы импортировать блоки из другого шаблона используйте тег {use}:
 
 ```smarty
-{use 'blocks.tpl'}
+{use 'blocks.tpl'} merge blocks from blocks.tpl template
-```
 
+{block 'alpha'} rewrite block alpha from blocks.tpl template, if it exists
+   ...
+{/block}
+```
 
 ### {parent}
 
-Planned. Not supported yet. Feature #5.
-
 ```smarty
-{block 'block1'}
+{extends 'parent.tpl'}
+
+{block 'header'}
   content ...
-  {parent}
+  {parent}  pase code from block 'header' from parent.tpl
   content ...
 {/block}
 ```
 
-### Performance
+### {paste}
 
-Алгоритм реализации наследования шаблонов может работать в разных режимах, в зависимости от условий.
+Paste code of any block
-Каждый режим имеет свою производительность.
 
-1. **Максимальная** производительность:
+```smarty
-    * Имена шаблонов в теге {extends } заданы явно, без использования переменных и условий.
+{block 'b1'}
-    * Имена блоков заданы явно, без использования переменных, условий и не вложены ни в какой другой тег.
+    ...
-2. **Средняя** производительность:
+{/block}
-    * Имена шаблонов в теге {extends } заданы явно, без использования переменных и условий.
-    * Имена блоков заданы **не** явно, с использованием переменныч, условий или могут быть вложенные в другие теги.
-3. **Низкая** производительность:
-    * Имена шаблонов в теге {extends } заданы **не** явно, с использованием переменных и условий.
-    * Имена блоков заданы явно, без использования переменных, условий и не вложены ни в какой другой тег.
-4. **Минимальная** производительность:
-    * Имена шаблонов в теге {extends } заданы **не** явно, с использованием переменных и условий.
-    * Имена блоков заданы **не** явно, с использованием переменных, условий или могут быть вложенные в другие теги.
 
-Режим может идти только на понижение, при изменении условий во время прохождения по иерархии шаблонов.
+{block 'b2'}
-При любом режиме работы не используется буферизация данных, то есть данные выводятся сразу.
+    ...
+    {paste 'b1'} paste code from b1
+{/block}
+
+```
+
+### {$.block}
+
+Checks if clock exists
+
+```smarty
+{if $.block.header}
+    block header exists
+{/if}
+```

docs/en/tags/filter.md

@@ -1,10 +1,12 @@
 Tags {filter}
 =============
 
-Позволяет применить модификаторы на фрагмент шаблона
+Apply modifier to template area.
 
 ```smarty
 {filter|strip_tags|truncate:20}
 Remove all HTML <b>tags</b> and truncate {$text} to 20 symbols
 {/filter}
-```
+```
+
+**Note**: output buffering used. May be used a lot of memory if you output a lot of data.

docs/en/tags/foreach.md

@@ -1,5 +1,7 @@
-Tag {foreach} [RU]
+Tag {foreach}
-==================
+=============
+
+The tag `{foreach}` construct provides an easy way to iterate over arrays and ranges.
 
 ```smarty
 {foreach $list as [$key =>] $value [index=$index] [first=$first] [last=$last]}
@@ -15,7 +17,8 @@ Tag {foreach} [RU]
 
 ### {foreach}
 
-Перебор значений массива $list
+On each iteration, the value of the current element is assigned to `$value` and the internal array pointer is
+advanced by one (so on the next iteration, you'll be looking at the next element).
 
 ```smarty
 {foreach $list as $value}
@@ -23,7 +26,7 @@ Tag {foreach} [RU]
 {/foreach}
 ```
 
-Перебор ключей и значений массива $list
+The next form will additionally assign the current element's key to the `$key` variable on each iteration.
 
 ```smarty
 {foreach $list as $key => $value}
@@ -31,7 +34,7 @@ Tag {foreach} [RU]
 {/foreach}
 ```
 
-Получение номера (индекса) итерации
+Gets the current array index, starting with zero.
 
 ```smarty
 {foreach $list as $value index=$index}
@@ -39,7 +42,7 @@ Tag {foreach} [RU]
 {/foreach}
 ```
 
-Определение первого элемента
+Detect first iteration:
 
 ```smarty
 {foreach $list as $value first=$first}
@@ -47,8 +50,9 @@ Tag {foreach} [RU]
 {/foreach}
 ```
 
-Переменная `$first` будет иметь значение **TRUE**, если текущая итерация является первой.
+`$first` is `TRUE` if the current `{foreach}` iteration is the initial one.
-Определение последнего элемента
+
+Detect last iteration:
 
 ```smarty
 {foreach $list as $value last=$last}
@@ -56,22 +60,22 @@ Tag {foreach} [RU]
 {/foreach}
 ```
 
-Переменная `$last` будет иметь значение **TRUE**, если текущая итерация является последней.
+`$last` is set to `TRUE` if the current `{foreach}` iteration is the final one.
 
 ### {break}
 
-Тег `{break}` используется для выхода из цикла до достижения последней итерации. Если в цикле встречается тег `{break}`, цикл завершает свою работу, и далее, выполняется код, следующий сразу за блоком цикла
+Tag `{break}` aborts the iteration.
 
 ### {continue}
 
-Тег `{continue}` используется для прерывания текущей итерации. Если в цикле встречается тег `{continue}`, часть цикла, следующая после тега, не выполняется, и начинается следующая итерация. Если текущая итерация была последней, цикл завершается.
+Tag `{continue}` leaves the current iteration and begins with the next iteration.
 
 ### {foreachelse}
 
-Тег {foreachelse} ограничивает код, который должен быть выполнен, если итерируемый объект пуст.
+`{foreachelse}` is executed when there are no values in the array variable.
 
 ```smarty
-{var $list = []}
+{set $list = []}
 {foreach $list as $value}
  <div>{if $last} last item {/if} {$value}</div>
 {foreachelse}
@@ -79,8 +83,4 @@ Tag {foreach} [RU]
 {/foreach}
 ```
 
-В блоке `{foreachelse}...{/foreach}` использование `{break}`, `{continue}` выбросит исключение `Fenom\CompileException` при компиляции
+`{foreachelse}` does not support tags `{break}` and `{continue}`.
-
-### Notice
-
-Использование last требует от `$list` быть **countable**.

docs/en/tags/if.md

@@ -1,7 +1,9 @@
-Tag {if} [RU]
+Tag {if}
-=============
+========
 
-Реализация оператора [if](http://docs.php.net/if) из PHP
+Tag {if}  have much the same flexibility as PHP [if](http://docs.php.net/if) statements,
+with a few added features for the template engine.
+All operators, allowed functions and variables are recognized in conditions.
 
 ```smarty
 {if <expression>}
@@ -21,8 +23,6 @@ Tag {if} [RU]
 {/if}
 ```
 
-Код, расположенный в теге `{if}` будет выполнен/выведен если выражение *<expression>* возвращает значение приводимое к **TRUE**
-
 ### {elseif}
 
 ```smarty
@@ -33,8 +33,6 @@ Tag {if} [RU]
 {/if}
 ```
 
-Код, расположенный после тега `{elseif}` будет выполнен/выведен, если выражение <expression1> вернуло значение приводимое к **FALSE**, <expression2> - приводимое к **TRUE**
-
 ### {else}
 
 ```smarty
@@ -43,7 +41,4 @@ Tag {if} [RU]
 {else}
     {*...some code...*}
 {/if}
-```
+```
-
-Код, расположенный после тега `{else}` будет выполнен/выведен, если выражение <expression> вернуло значение приводимое к **FALSE**
-В тестируемых выражениях могут быть использованы логические операторы , что позволяет обрабатывать сочетания нескольких условий.

docs/en/tags/macro.md

@@ -1,12 +1,12 @@
-Tag {macro} [RU]
+Tag {macro}
-================
+===========
 
-Макросы - фрагмент шаблона который можно повторить сколь угодно раз и в каком угодно месте.
+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.
 
 ### {macro}
 
-Обявление макроса происходит при помощи блочного тега `{macro}`
+Macros can be defined in any template using tag `{macro}`.
 
 ```smarty
 {macro plus($x, $y, $z=0)}
@@ -14,14 +14,10 @@ Tag {macro} [RU]
 {/macro}
 ```
 
-Вызов макроса происходит при помощи строкового тега `{macro}`. Аргументы передаются стандартно, как атрибуты в HTML тегах
-
 ```smarty
 {macro.plus x=$num y=100}
 ```
 
-Во время рекурсивного вызова используйте суффикс macro что бы обратиться к текущему макросу:
-
 ```smarty
 {macro plus($x, $y, $z=0)}
     ...
@@ -32,13 +28,17 @@ Tag {macro} [RU]
 
 ### {import}
 
-Для использования маросов в другом шаблоне необходимо их импортировать при помощи тега `{import}`
+Macros can be defined in any template, and need to be "imported" before being used.
+The above import call imports the "math.tpl" file (which can contain only macros, or a template and some macros),
+and import the functions as items of the `macro` namespace.
 
 ```smarty
 {import 'math.tpl'}
+
+{macro.plus x=1 y=3}
 ```
 
-При импорте можно указать дргое пространство имен что бы можно было использовать одноименные макросы из разных шаблонов
+Use another namespace instead of `macro`
 
 ```smarty
 {import 'math.tpl' as math}
@@ -46,9 +46,6 @@ Tag {macro} [RU]
 {math.plus x=5 y=100}
 ```
 
-Пространство имен макросов может совпадать с названием какого-либо тега, в данном случае ничего плохого не произойдет: будет вызван макрос, а тег не исчезнит
-При необходимости можно импортировать только необходимые макросы, явно указав в теге `{import}`
-
 ```smarty
 {import [plus, minus, exp] from 'math.tpl' as math}
 ```

docs/en/tags/set.md

@@ -0,0 +1,84 @@
+Tag {set}
+=========
+
+The tag {set} is used for assigning template variables during the execution of a template.
+
+```smarty
+{set $var=EXPR}
+```
+
+```smarty
+{set $var}
+  ... any content ...
+{/set}
+```
+
+```smarty
+{set $var|modifiers}
+  ... any content ...
+{/set}
+```
+
+Variable names follow the same rules as other labels in PHP. 
+A valid variable name starts with a letter or underscore, followed by any number of letters, numbers, or underscores.
+
+```smarty
+{set $v = 5}
+{set $v = "value"}
+
+{set $v = $x+$y}
+{set $v = 4}
+{set $v = $z++ + 1}
+{set $v = --$z}
+{set $v = $y/$x}
+{set $v = $y-$x}
+{set $v = $y*$x-2}
+{set $v = ($y^$x)+7}
+```
+
+Works this array too
+
+```smarty
+{set $v = [1,2,3]}
+{set $v = []}
+{set $v = ["one"|upper => 1, 4 => $x, "three" => 3]}
+{set $v = ["key1" => $y*$x-2, "key2" => ["z" => $z]]}
+```
+
+Getting function result into variable
+
+```smarty
+{set $v = count([1,2,3])+7}
+```
+
+Fetch the output of the template into variable
+
+```smarty
+{set $v}
+    Some long {$text|trim}
+{/set}
+
+{set $v|escape} {* apply modifier to variable*}
+    Some long {$text|trim}
+{/set}
+```
+
+### {add}
+
+The tag {add} the same tag as {set} except that sets the value of the variable if it does not exist.
+
+```smarty
+{add $var = 'value'}
+```
+
+instead of
+
+```smarty
+{if $var is not set}
+    {set $var = 'value'}
+{/if}
+```
+
+### {var}
+
+Old name of tag {set}. Currently tag {var} the same tag as {set}.

docs/en/tags/var.md

@@ -1,64 +0,0 @@
-Tag {var}
-=========
-
-The tag {var} is used for assigning template variables during the execution of a template.
-
-```smarty
-{var $var=EXPR}
-```
-
-```smarty
-{var $var}
-  ... any content ...
-{/var}
-```
-
-```smarty
-{var $var|modifiers}
-  ... any content ...
-{/var}
-```
-
-Variable names follow the same rules as other labels in PHP. 
-A valid variable name starts with a letter or underscore, followed by any number of letters, numbers, or underscores.
-
-```smarty
-{var $v = 5}
-{var $v = "value"}
-
-{var $v = $x+$y}
-{var $v = 4}
-{var $v = $z++ + 1}
-{var $v = --$z}
-{var $v = $y/$x}
-{var $v = $y-$x}
-{var $v = $y*$x-2}
-{var $v = ($y^$x)+7}
-```
-
-Creating array
-
-```smarty
-{var $v = [1,2,3]}
-{var $v = []}
-{var $v = ["one"|upper => 1, 4 => $x, "three" => 3]}
-{var $v = ["key1" => $y*$x-2, "key2" => ["z" => $z]]}
-```
-
-Getting function result into variable
-
-```smarty
-{var $v = count([1,2,3])+7}
-```
-
-Collect the output of the template into a variable 
-
-```smarty
-{var $v}
-    Some long {$text|trim}
-{/var}
-
-{var $v|escape} {* apply modifier to variable*}
-    Some long {$text|trim}
-{/var}
-```

docs/ru/operators.md

@@ -135,9 +135,21 @@ Fenom поддерживает префиксные и постфиксные о
 * `$a ~~ $b` - возвращает результат объединения сток `$a` и `$b` через пробел
 * `$a ~= $b` - присвоение с объединением
 
+Примеры
+
+```smarty
+{"A" ~ "B"}     -> AB
+
+{"A" ~~ "B"}    -> A B
+
+{add $v = "A"}
+{set $v ~= "B"}
+{$v}            -> AB
+```
+
 ### Оператор интервала
 
-Оператор `..` позволяет создать массив данных, не выходящие за указанные ограничения.
+Оператор `..` позволяет создать массив данных, не выходящие за указанные пределы.
 
 ```smarty
 {set $a = 1..4}

docs/ru/readme.md

@@ -47,6 +47,7 @@
 Устаревшие теги
 
 * [for](./tags/for.md), `forelse`, `break` and `continue` — цикл
+
 ***
 
 ### Модификаторы

docs/ru/syntax.md

@@ -102,7 +102,7 @@
   если такой констатнты нет будет взята константа `Storage\FS\DIR_SEPARATOR`.
 * `$.call` обращение к статическомому методу. `$.call.Storage.FS::put($filename, $data)` обращение к методу `Storage\FS::put($filename, $data)`.
   Настройка `disable_call` отключает возможность обращения к `$.call`. Так же можно ограничить и указать список доступных к вызову классов и функций.
-* `$.blocks` проверка на сущестование блоков которые были определены до момента обращения к акцессору. Например, `{$.blocks.BLOCK_NAME}`.
+* `$.block` проверка на сущестование блоков которые были определены до момента обращения к акцессору. Например, `{$.blocks.BLOCK_NAME}`.
 * так же вы можете [добавить](./ext/extend.md#Расширение-глобальной-переменной) свои или [удалить](./ext/extend.md#Расширение-глобальной-переменной) существующие системные переменные и функции
  
 
@@ -157,7 +157,7 @@
 {"Hi, {$user.name}!"}        выводит: Hi, Username!
 {"Hi, {$user->name}!"}       выводит: Hi, Username!
 {"Hi, {$user->getName()}!"}  выводит: Hi, Username!
-{"Hi, {\$user->name}!"}      выводит: Hi, {\$user->name}!
+{"Hi, {\$user->name}!"}      выводит: Hi, {$user->name}!
 ```
 
 Допускаются также различные операции и модификаторы:

docs/ru/tags/foreach.md

@@ -5,7 +5,7 @@
 `Foreach` работает только с массивами, объектами и интервалами.
 
 ```smarty
-{foreach $list as [$key =>] $value [index=$index] [first=$first] [last=$last]}
+{foreach $list [as [$key =>] $value] [index=$index] [first=$first] [last=$last]}
    {* ...code... *}
    {break}
    {* ...code... *}

src/Fenom.php

@@ -387,7 +387,7 @@ class Fenom
         'call'    => 'Fenom\Accessor::call',
         'tag'     => 'Fenom\Accessor::Tag',
         'fetch'   => 'Fenom\Accessor::fetch',
-        'blocks'  => 'Fenom\Accessor::blocks',
+        'block'   => 'Fenom\Accessor::block',
     );
 
     /**

src/Fenom/Accessor.php

@@ -194,42 +194,17 @@ class Accessor {
     }
 
     /**
-     * Accessor {$.blocks.name}
+     * Accessor {$.block.NAME}
-     * Accessor {$.blocks.name.from}
-     * Accessor {$.blocks.name.code}
-     * Accessor {$.blocks.name.use_parent}
-     * Accessor {$.blocks.name.import}
-     * Accessor {$.blocks}
      * @param Tokenizer $tokens
      * @param Template $tpl
      * @return mixed
      */
-    public static function blocks(Tokenizer $tokens, Template $tpl)
+    public static function block(Tokenizer $tokens, Template $tpl)
     {
         if($tokens->is('.')) {
             $name = $tokens->next()->get(Tokenizer::MACRO_STRING);
-            if($tokens->isNext('.')) {
+            $tokens->next();
-                $part = $tokens->next()->next()->get(Tokenizer::MACRO_STRING);
+            return isset($tpl->blocks[$name]) ? 'true' : 'false';
-                $tokens->next();
-                if(!isset($tpl->blocks[$name])) {
-                    return 'NULL';
-                }
-                switch($part) {
-                    case 'code':
-                        return var_export($tpl->blocks[$name]["block"], true);
-                    case 'from':
-                        return var_export($tpl->blocks[$name]["from"], true);
-                    case 'use_parent':
-                        return var_export($tpl->blocks[$name]["use_parent"], true);
-                    case 'import':
-                        return var_export($tpl->blocks[$name]["import"], true);
-                    default:
-                        throw new UnexpectedTokenException($tokens->back());
-                }
-            } else {
-                $tokens->next();
-                return isset($tpl->blocks[$name]) ? 'true' : 'false';
-            }
         } else {
             return "array(".implode(",", array_keys($tpl->blocks)).")";
         }