Port docs

README.md

@@ -183,4 +183,119 @@ Aspect templater
 {funct arg=1+2}
 {funct arg=$a.d.c+4}
 {funct arg=($a.d.c|count+4)/3}
+```
+
+
+
+### Вывод текста с фигурными скобками
+
+Как и в Smarty, в шаблонизаторе Aspect используются фигурные скобки для отделения HTML от кода Aspect.
+Если требуется вывести текст, содержащий фигурные скобки помните о следующих возможностях:
+
+1. Использование блочного тега @{literal}{/literal}@. Текст внутри этого тега не компилируется шаблонизатором и выводится "как есть".
+2. Если после открывающей фигурной скобки есть пробельный символ, то она не воспринимается как разделитель Aspect и код после неё выводится "как есть".
+
+Пример:
+
+```smarty
+{literal}
+<style>
+	h1 {font-size: 24px; color: #F00;}
+</style>
+{/literal}
+<script>
+	(function (text) {
+		var e = document.createElement('P');
+		e.innerHTML = text;
+		document.body.appendChild(e);
+	})('test');
+</script>
+```
+
+Выведет
+
+```html
+<style>
+	h1 {font-size: 24px; color: #F00;}
+</style>
+<script>
+	(function (text) {
+		var e = document.createElement('P');
+		e.innerHTML = text;
+		document.body.appendChild(e);
+	})('test');
+</script>
+```
+
+## Настройка
+
+### Параметры
+
+#### Исходные шаблоны
+
+Добавить папку с шаблонами:
+
+```php
+  $aspect->addTemplateDir($dir);
+```
+
+Шаблонизатор последовательно будет перебирать папки и искать указанный шаблон.
+
+#### Сборки шаблонов
+
+Задаёт папку в которую будут сохранятся преобразованные в PHP шаблоны
+```php
+  $aspect->setCompileDir($dir);
+```
+
+#### Опции
+
+```php
+  $aspect->setOptions($options);
+```
+
+Массив `'option_name' => boolean` (если ключ не указан автоматически задаётся false)
+
+* **disable_methods**, `boolean`, запретить вызов методов у объектов
+* **disable_native_funcs**, `boolean`, запретить использование PHP функций, кроме разрешенных
+* **disable_set_vars**, `boolean`, запретить изменять или задавать переменные
+* **include_sources**, `boolean`, вставлять исходный код шаблона в его сборку
+* **compile_check**, `boolean`, сравнивать mtime у исходного шаблона и его сборки. При изменении исходного шаблона будет производится его пересборка (замедляет работу шаблонизатора).
+* **force_compile**, `boolean`, пересобирать шаблон при каждом вызове (сильно замедляет работу шаблонизатора).
+
+или битовая маска из флагов:
+
+* `Aspect::DENY_METHODS` то же что и **disable_methods**
+* `Aspect::DENY_INLINE_FUNCS` то же что и **disable_native_funcs**
+* `Aspect::DENY_SET_VARS` то же что и **disable_set_vars**
+* `Aspect::INCLUDE_SOURCES` то же что и **include_sources**
+* `Aspect::CHECK_MTIME` то же что и **compile_check**
+* `Aspect::FORCE_COMPILE` то же что и **force_compile**
+
+### Модификаторы
+
+Добавить модификатор:
+```php
+  $aspect->addModifier($modifier, $callback);
+```
+
+* `$modifier` - имя модификатора
+* `$callback` - строка с именем функции
+
+### Теги
+
+Теги делятся на компилеры и функции.
+Компилеры формируют синтаксис языка шаблона, добавляя такой функционал как foreach, if, while и т.д. В то время как функции - обычный вызов некоторой именованной функции
+
+Добавить компилер:
+```php
+  $aspect->addCompiler($compiler, $parser);
+```
+
+* `$compiler` - имя модификатора
+* `$parser`  - функция разбора тега в формате function (MF\Tokenizer $tokens, MF\Aspect\Template $tpl) {}
+
+Добавить блочный компилер:
+```php
+  $aspect->addBlockCompiler($compiler, $parsers, $tags);
 ```

docs/modifiers.md

@@ -1,3 +1,113 @@
 Модификаторы
 ============
 
+## Оператор if
+
+Реализация "оператора if":http://php.net/if из PHP
+
+```smarty
+{if <expresion>}
+   {*...some code...*}
+{/if}
+```
+
+Код, расположенный в теге `if` будет выполнен/выведен если выражение @<expression>@ возвращает значение приводимое к `TRUE`
+Использование блока `elseif`
+
+```smarty
+{if <expresion1>}
+   {*...some code...*}
+{elseif <expresion2>}
+   {*...some code...*}
+{/if}
+```
+
+Код, расположенный после тега `elseif` будет выполнен/выведен, если выражение @<expression1>@ вернуло значение приводимое к `FALSE`, **<expression2>** - приводимое к `TRUE`
+
+Использование блока `else`
+
+```smarty
+{if <expresion>}
+   {*...some code...*}
+{else}
+   {*...some code...*}
+{/if}
+```
+
+Код, расположенный после тега `else` будет выполнен/выведен, если выражение **<expression>** вернуло значение приводимое к `FALSE`
+
+В тестируемых выражениях могут быть использованы "логические операторы":http://www.php.net/manual/en/language.operators.logical.php , что позволяет обрабатывать сочетания нескольких условий.
+
+## Оператор foreach
+
+Реализация оператора [foreach в PHP](http://docs.php.net/foreach)
+Общий синтаксис:
+
+```smarty
+{foreach <array> as <key_var> => <value_var> index=<index_var> first=<first_flag> last=<last_flag>}
+    {*...some code...*}
+    {if <expression1>}
+        {break}
+    {/if}
+    {*...some code...*}
+    {if <expression2>}
+        {continue}
+    {/if}
+    {*...some code...*}
+{foreachelse}
+    {*...some code...*}
+{/foreach}
+```
+
+(!) <index_var>, <first_flag>, <last_flag>, <key_var> и <value_var> могут быть только переменные (допускаются вложенности на подобие $a.b.c, но массив $a.b должен быть объявлен).
+
+Перебор значений массива $list
+
+```smarty
+{foreach $list as $value}
+ <div>{$value}</div>
+{/foreach}
+```
+
+Перебор ключей и значений массива $list
+
+```smarty
+{foreach $list as $key => $value}
+ <div>{$key}: {$value}</div>
+{/foreach}
+```
+
+Получение номера (индекса) итерации
+
+```smarty
+{foreach $list as $value index=$index}
+ <div>№{$index}: {$value}</div>
+{/foreach}
+```
+
+Определение первого элемента
+
+```smarty
+{foreach $list as $value first=$first}
+ <div>{if $first} first item {/if} {$value}</div>
+{/foreach}
+```
+
+Переменная `$first` будет иметь значение `TRUE`, если текущая итерация является первой.
+
+Определение последнего элемента
+
+```smarty
+{foreach $list as $value last=$last}
+ <div>{if $last} last item {/if} {$value}</div>
+{/foreach}
+```
+
+Переменная `$last` будет иметь значение `TRUE`, если текущая итерация является последней.
+Использование @last@ замедляет работу цикла и требует от `$list` быть *countable*. Если есть возможность используйте `first` параметр.
+
+### Вложенные теги
+
+* `{break}` используется для выхода из цикла до достижения последней итерации. Если в цикле встречается тег `{break}`, цикл завершает свою работу, и далее выполняется код, следующий сразу за блоком цикла
+* `{continue}` используется для прерывания текущей итерации. Если в цикле встречается тег `{continue}`, часть цикла, следующая после тега, не выполняется, и начинается следующая итерация. Если текущая итерация была последней, цикл завершается.
+* `{foreachelse}` ограничивает код, который должен быть выполнен, если итерируемый объект пуст.