Update docs

docs/main.md

@@ -8,10 +8,11 @@ Documentation
 * [Syntax](./syntax.md)
 * [Settings](./settings.md)
 * [Callbacks and filters](./callbacks.md)
+* [Operators](./operators.md)
 
 **Modifiers**
 
-Conversation about [modifiers](./modifiers.md)
+Conversation about [modifiers](./syntax.md#modifiers)
 
 * [upper](./mods/upper.md) aka `up`
 * [lower](./mods/lower.md) aka `low`
@@ -26,7 +27,7 @@ Conversation about [modifiers](./modifiers.md)
 
 **Tags**
 
-Conversation about [tags](./tags.md)
+Conversation about [tags](./syntax.md#tags)
 
 * [var](./tags/var.md)
 * [if](./tags/if.md), `elseif` and `else`

docs/settings.md

@@ -1,48 +1,36 @@
 Настройка
 =========
 
-### Параметры
+### Параметры шаблонизатора
 
-#### Исходные шаблоны
+Что бы установить папку для хранения кеша собранных шаблонов
-
-Добавить папку с шаблонами:
-
-```php
-$aspect->addTemplateDir($dir);
-```
-
-Шаблонизатор последовательно будет перебирать папки и искать указанный шаблон.
-
-#### Сборки шаблонов
-
-Задаёт папку в которую будут сохранятся преобразованные в PHP шаблоны
 
 ```php
 $aspect->setCompileDir($dir);
 ```
 
-#### Опции
+### Пакаметры компилятора
 
 ```php
+// set options using factory
+$aspect = Aspect::factory($tpl_dir, $compile_dir, $options);
+// or inline using method setOptions
 $aspect->setOptions($options);
 ```
 
-Массив `'option_name' => boolean` (если ключ не указан автоматически задаётся false)
+Параметры могут быть массивом `'option_name' => true` (если ключ не указан автоматически задаётся false) или битовой маской.
 
-* **disable_methods**, `boolean`, запретить вызов методов у объектов
+* **disable_methods**, `Aspect::DENY_METHODS`, запретить вызов методов у объектов
-* **disable_native_funcs**, `boolean`, запретить использование PHP функций, кроме разрешенных
+* **disable_native_funcs**, `Aspect::DENY_INLINE_FUNCS`, запретить использование PHP функций, кроме разрешенных
-* **disable_set_vars**, `boolean`, запретить изменять или задавать переменные
+* **auto_reload**, `Aspect::AUTO_RELOAD`, пересобирать шаблон если его оригинал был изменён (замедляет работу шаблонизатора).
-* **include_sources**, `boolean`, вставлять исходный код шаблона в его сборку
+* **force_compile**, `Aspect::FORCE_COMPILE`, пересобирать шаблон при каждом вызове (сильно замедляет работу шаблонизатора).
-* **compile_check**, `boolean`, сравнивать mtime у исходного шаблона и его сборки. При изменении исходного шаблона будет производится его пересборка (замедляет работу шаблонизатора).
+* **force_include**, `Aspect::FORCE_INCLUDE`, оптимизировать вставку шаблона в шаблон. Это увеличит производительность и размер собранного шаблона.
-* **force_compile**, `boolean`, пересобирать шаблон при каждом вызове (сильно замедляет работу шаблонизатора).
-* **force_include**, `boolean`.
 
-или битовая маска из флагов:
+```php
-
+$aspect->setOptions(array(
-* `Aspect::DENY_METHODS` то же что и **disable_methods**
+    "compile_check" => true,
-* `Aspect::DENY_INLINE_FUNCS` то же что и **disable_native_funcs**
+    "force_include" => true
-* `Aspect::DENY_SET_VARS` то же что и **disable_set_vars**
+));
-* `Aspect::INCLUDE_SOURCES` то же что и **include_sources**
+// same
-* `Aspect::CHECK_MTIME` то же что и **compile_check**
+$aspect->setOptions(Aspect::AUTO_RELOAD | Aspect::FORCE_INCLUDE);
-* `Aspect::FORCE_COMPILE` то же что и **force_compile**
+```
-* `Aspect::FORCE_INCLUDE` то же что и **force_include**

docs/syntax.md

@@ -1,7 +1,7 @@
 Синтаксис
 =========
 
-### Вывод переменной
+### Переменные
 
 Вывод значений переменных в шаблонизаторе Aspect идентичен правилам вывода шаблонизатора Smarty
 
@@ -36,13 +36,22 @@
 ### Математические операции
 
 ```smarty
-{$x+$y}                   // will output the sum of x and y.
+{$x+$y}
-{$foo[$x+3]}              // as array index
+{$foo[$x+3]}
 {$foo[$x+3]*$x+3*$y % 3}
 ```
 
+[Список всех операторов](./operators.md)
+
 ### Объявление переменных
 
+```smarty
+{var $foo = "bar"}
+{var $foo = 5}
+```
+
+в качестве значения так же допускаются математические, логические операции и результаты функций
+
 ```smarty
 {var $foo = $x + $y}
 {var $foo = $x.y[z] + $y}
@@ -51,12 +60,22 @@
 {var $foo.bar.baz = 1}
 ```
 
+Подробнее смотрите [{var}](./tags/var.md)
+
 #### Объявление массивов
 
 ```smarty
 {var $foo=[1,2,3]}
-{var $foo=['y'=>'yellow','b'=>'blue']}
+{var $foo=['y'=>'yellow','b'=>'blue']}  can be associative
-{var $foo=[1,[9,8],3]}   // can be nested
+{var $foo=[1,[9,8],3]}   can be nested
+```
+
+в качестве ключа и значения так же допускаются математические, логические операции и результаты функций
+
+```smarty
+{var $foo=[$a, $d.c, $a + $f]}
+{var $foo=['y'=>'yellow', $color=>$colors[ $color ]}  can be associative
+{var $foo=[1,[$parent ,$a + $e],3]}   can be nested
 ```
 
 ### Работа с объектами
@@ -66,22 +85,42 @@
 {var $foo=$object->item->method($y, 'named')}
 ```
 
+Вызов метода в шаблоне можно запретить [настройками](./settings.md)
 
-### Работа со строками
+### Работа со скалярными значениями
 
 Строки в Aspect обрабатываются идентично правилам подстановки переменных в строки в PHP, т.е. в двойных кавычках переменная заменяется на её значение, в одинарных замены не происходит.
-В отличие от Smarty в строках не обрабатываются управляющие конструкции, например "if", но работают модификаторы.
 
 ```smarty
-{var $foo="Ivan"}
+{var $foo="Username"}
-{var $user.name="Ivan"}
+{var $user.name="Username"}
-{"Hi, $foo"}          выведет "Hi, Ivan"
+{"Hi, $foo"}          выведет "Hi, Username"
-{"Hi, {$foo}"}        выведет "Hi, Ivan"
+{"Hi, {$foo}"}        выведет "Hi, Username"
-{"Hi, {$user.name}"}  выведет "Hi, Ivan"
+{"Hi, {$user.name}"}  выведет "Hi, Username"
+{var $message = "Hi, {$user.name}"}
 {'Hi, $foo'}          выведет 'Hi, $foo'
 {'Hi, {$foo}'}        выведет 'Hi, {$foo}'
 ```
 
+Переменные в строках так же поддерживают [модификаторы](#modifiers)
+
+```smarty
+{"Hi, {$user.name|up}"} outputs Hi, USERNAME
+```
+
+Поддерживается вызов методов
+
+```smarty
+{"Hi, {$user->getName(true)}"} outputs Hi, Username
+```
+
+Числовые значение обрабатывается как есть
+
+```smarty
+{2|pow:10}
+{var $magick = 5381|calc}
+```
+
 ### Модификаторы
 
 * Модификаторы позволяют изменить значение переменной перед выводом или использованием в выражении
@@ -92,30 +131,31 @@
 * Модификаторы могут составлять цепочки. В этом случае они применяются к переменной последовательно слева направо
 
 ```smarty
-{var $foo="Ivan"}
+{var $foo="User"}
-{$foo|upper}     выведет "IVAN"
+{$foo|upper}     выведет "USER"
-{$foo|lower}     выведет "ivan"
+{$foo|lower}     выведет "user"
+{"{$foo|lower}"}     выведет "user"
+{"User"|lower}}     выведет "user"
 {$looong_text|truncate:80:"..."}  обрежет текст до 80 символов и добавит "..." в конец текста
 {$looong_text|lower|truncate:$settings.count:$settings.etc}
-{var $foo="Ivan"|upper}    переменная $foo будет содержать "IVAN"
+{var $foo="Ivan"|upper}    переменная $foo будет содержать "USER"
 ```
 
-Подробнее модификаторы описаны в разделе [модификаторы](./docs/modifiers.md)
+[Список модификаторов](./main.md#modifiers)
 
-### Функции
+### Теги
 
-Каждый тэг шаблонизатора либо выводит переменную, либо вызывает какую-либо функцию.
+Каждый тэг шаблонизатора либо выводит переменную, либо вызывает какую-либо функцию. (переписать)
 Тег вызова функции начинается с названия функции и содержит список аргументов:
 
 ```smarty
 {FUNCNAME attr1 = "val1" attr2 = $val2}
 ```
 
-Это общий формат функций, но могут быть исключения, например функция {var}, использовавшаяся выше.
+Это общий формат функций, но могут быть исключения, например функция [{var}](./tags/var.md), использованная выше.
 
 ```smarty
 {include file="my.tpl"}
-{mailto address="bzick@megagroup.ru" text="Article's author"}
 {var $foo=5}
 {if $user.loggined}
     Welcome, <span style="color: red">{$user.name}!</span>
@@ -124,9 +164,7 @@
 {/if}
 ```
 
-Аргументы
+В общем случае аргументы принимают любой формат переменных, в том числе результаты арифметических операций и модификаторов.
-
-Аргументы принимают любой формат переменных, в том числе результаты арифметических операций и модификаторов.
 
 ```smarty
 {funct arg=true}
@@ -150,15 +188,13 @@
 {funct arg=($a.d.c|count+4)/3}
 ```
 
+### Игнорирование разделителя
 
-
+В шаблонизаторе Aspect используются фигурные скобки для отделения HTML от кода Aspect.
-###
-
-Как и в Smarty, в шаблонизаторе Aspect используются фигурные скобки для отделения HTML от кода Aspect.
 Если требуется вывести текст, содержащий фигурные скобки помните о следующих возможностях:
 
-1. Использование блочного тега `{ignore}{/ignore}`. Текст внутри этого тега не компилируется шаблонизатором и выводится "как есть".
+1. Использование блочного тега `{ignore}{/ignore}`. Текст внутри этого тега текст не компилируется шаблонизатором и выводится как есть.
-2. Если после открывающей фигурной скобки есть пробельный символ, то она не воспринимается как разделитель Aspect и код после неё выводится "как есть".
+2. Если после открывающей фигурной скобки есть пробельный символ (пробел или `\t`) или перенос строки (`\r` или `\n`), то она не воспринимается как разделитель rкода Aspect и код после неё выводится как есть.
 
 Пример:
 
@@ -191,3 +227,25 @@
 	})('test');
 </script>
 ```
+
+### Пробелы и переносы строк
+
+Шаблонизатор допускает любое количество пробелов или переносов строк в своём коде
+
+```smarty
+{include 'control.tpl'
+    options=$list
+    name=$cp.name
+    type='select'
+}
+
+{foreach [
+    "one"   => 1,
+    "two"   => 2,
+    "three" => 3
+] as $key => $val}
+
+    {$key}: {$val}
+
+{/foreach}
+```

docs/tags/capture.md

@@ -1,3 +1,15 @@
 Tag {capture}
 =============
 
+```smarty
+{capture $var}
+This content will be captured into variable $var
+{/capture}
+```
+
+
+```smarty
+{capture|stip_tags $var}
+This content will be captured into variable $var and all tags will be stripped
+{/capture}
+```

docs/tags/cycle.md

@@ -1,3 +1,13 @@
 Tag {cycle}
 ===========
 
+```smarty
+{for $i=$a.c..}
+    <div class="{cycle ["odd", "even"]}">
+{/for}
+
+
+{for $i=$a.c..}
+    <div class="{cycle ["odd", "even"] index=$i}">
+{/for}
+```

docs/tags/extends.md

@@ -1,18 +1,61 @@
 Tag {extends}
 =============
 
+Тег {extends} реализует наследование шаблонов
 
 ### {extends}
 
+```smarty
+{extends 'parent.tpl'}
+```
+
+```smarty
+{extends $parent_tpl}
+```
+
+```smarty
+{if $theme?}
+    {extends $theme.template}
+{/if}
+```
 
 ### {block}
 
+```smarty
+{block bk1}content 1{/block}
+
+{block 'bk2'}content 2{/block}
+
+{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}
 
 
+```smarty
+{use 'blocks.tpl'}
+
+{if $theme.extended?}
+    {use $theme.extended}
+{/if}
+```
+
+
 ### {parent}
 
+```smarty
+{block 'block1'}
+  content ...
+  {parent}
+  content ...
+{/block}
+```
 
-### Dynamic vs. static inheritance
+### Perfomance
 

docs/tags/filter.md

@@ -4,7 +4,7 @@ Tags {filter}
 Позволяет применить модификаторы на фрагмент шаблона
 
 ```smarty
-{filter|strip_tags|truncate:80}
+{filter|strip_tags|truncate:20}
-Remove all HTML <b>tags</b> and truncate text to 80 symbols
+Remove all HTML <b>tags</b> and truncate text to 20 symbols
 {/filter}
 ```

docs/tags/foreach.md

@@ -57,7 +57,6 @@ Tag {foreach}
 ```
 
 Переменная `$last` будет иметь значение **TRUE**, если текущая итерация является последней.
-Использование last замедляет работу цикла и требует от `$list` быть **countable**. Если есть возможность используйте **first** параметр.
 
 ### {break}
 
@@ -81,3 +80,7 @@ Tag {foreach}
 ```
 
 В блоке `{foreachelse}...{/foreach}` использование `{break}`, `{continue}` выбросит исключение `Aspect\CompileException` при компиляции
+
+### Perfomance
+
+Использование last замедляет работу цикла и требует от `$list` быть **countable**. Если есть возможность используйте **first** параметр.

docs/tags/ignore.md

@@ -6,5 +6,10 @@ Tag {ignore}
 ```smarty
 {ignore}
     var data = {"time": obj.ts};
-{ignore}
+{/ignore}
+```
+
+You may ignore delimiters without tag `{ignore}`
+```smarty
+var data = { "time": obj.ts };
 ```