From 8a3dbf1ffa025518e344392f2ea81494fd115b65 Mon Sep 17 00:00:00 2001
From: bzick <a.cobest@gmail.com>
Date: Wed, 18 Jun 2014 17:21:29 +0400
Subject: [PATCH] Update docs

---
 docs/configuration.md  |  36 +--------
 docs/ext/extend.md     | 163 +++++++++++++++++++++++++++++++++++++++++
 docs/operators.md      |   4 +-
 docs/readme.md         |  64 +++++++++-------
 src/Fenom/Provider.php |   1 -
 5 files changed, 205 insertions(+), 63 deletions(-)
 create mode 100644 docs/ext/extend.md

diff --git a/docs/configuration.md b/docs/configuration.md
index cf8e17d..83bed60 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -50,46 +50,12 @@ By default all options disabled
 
 ## Extends
 
-### Template providers [TRANSLATE]
+### Template providers
 
 Бывает так что шаблны не хранятся на файловой сиситеме, а хранятся в некотором хранилище, например, в базе данных MySQL.
 В этом случае шаблонизатору нужно описать как забирать шаблоны из хранилища, как проверять дату изменения шаблона и где хранить кеш шаблонов (опционально).
 Эту задачу берут на себя Providers, это объекты реальзующие интерфейс `Fenom\ProviderInterface`.
 
-### Cache providers [TRANSLATE]
-
-Изначально Fenom не расчитывался на то что кеш скомпиленых шаблонов может располагаться не на файловой системе.
-Однако, в теории, есть возможность реализовать свое кеширование для скомпиленых шаблонов без переопределения шаблонизатора.
-Речь идет о своем протоколе, отличным от `file://`, который [можно определить](http://php.net/manual/en/class.streamwrapper.php) в PHP.
-
-Ваш протол должени иметь класс реализации протокола как указан в документации [Stream Wrapper](http://www.php.net/manual/en/class.streamwrapper.php).
-Класс протокола может иметь не все указанные в документации методы. Вот список методов, необходимых шаблонизатору:
-
-* [CacheStreamWrapper::stream_open](http://www.php.net/manual/en/streamwrapper.stream-open.php)
-* [CacheStreamWrapper::stream_write](http://www.php.net/manual/en/streamwrapper.stream-write.php)
-* [CacheStreamWrapper::stream_close](http://www.php.net/manual/en/streamwrapper.stream-close.php)
-* [CacheStreamWrapper::rename](http://www.php.net/manual/en/streamwrapper.rename.php)
-
-For `include`:
-
-* [CacheStreamWrapper::stream_stat](http://www.php.net/manual/en/streamwrapper.stream-stat.php)
-* [CacheStreamWrapper::stream_read](http://www.php.net/manual/en/streamwrapper.stream-read.php)
-* [CacheStreamWrapper::stream_eof](http://www.php.net/manual/en/streamwrapper.stream-eof.php)
-
-**Note**
-(On 2014-05-13) Zend OpCacher doesn't support custom protocols except `file://` and `phar://`.
-
-For example,
-
-```php
-$this->setCacheDir("redis://hash/compiled/");
-```
-
-* `$cache = fopen("redis://hash/compiled/XnsbfeDnrd.php", "w");`
-* `fwrite($cache, "... <template content> ...");`
-* `fclose($cache);`
-* `rename("redis://hash/compiled/XnsbfeDnrd.php", "redis://hash/compiled/main.php");`
-
 ### Callbacks and filters
 
 #### Before compile callback
diff --git a/docs/ext/extend.md b/docs/ext/extend.md
new file mode 100644
index 0000000..5db18b3
--- /dev/null
+++ b/docs/ext/extend.md
@@ -0,0 +1,163 @@
+Extends Fenom
+=============
+
+*TODO*
+
+# Add tags
+
+В шаблонизаторе принято различать два типа тегов: _компиляторы_ и _функции_.
+Compilers invokes during compilation template to PHP source and have to
+Компиляторы вызываются во время преобразования кода шаблона в PHP код и возвращяю PHP код который будет вставлен вместо тега.
+А функции вызываются непременно в момент выполнения шаблона и возвращают непосредственно данные которые будут отображены.
+Среди тегов как и в HTML есть строчные и блоковые теги.
+
+## Inline function
+
+Примитивное добавление функции можно осуществить следующим образом:
+
+```php
+$fenom->addFunction(string $function_name, callable $callback[, callable $parser]);
+```
+
+В данном случае запускается стандартный парсер, который автоматически разберет аргументы тега, которые должны быть в формате HTML аттрибутов и отдаст их в функцию ассоциативным массивом:
+```php
+$fenom->addFunction("some_function", function (array $params) { /* ... */ });
+```
+При необходимости можно переопределить парсер на произвольный:
+```php
+$fenom->addFunction("some_function", $some_function, function (Fenom\Tokenizer $tokenizer, Fenom\Template $template) { /* parse tag */});
+```
+Существует более простой способ добавления произвольной функции:
+
+```php
+$fenom->addFunctionSmarty(string $function_name, callable $callback);
+```
+
+В данном случае парсер сканирует список аргументов коллбека и попробует сопоставить с аргументами тега.
+
+```php
+// ... class XYCalcs ..
+public static function calc($x, $y = 5) { /* ... */}
+// ...
+$fenom->addFunctionSmart('calc', 'XYCalcs::calc');
+```
+then
+```smarty
+{calc x=$top y=50} or {calc y=50 x=$top} is XYCalcs::calc($top, 50)
+{calc x=$top} or {calc $top} is XYCalcs::calc($top)
+```
+Таким образом вы успешно можете добавлять Ваши функции или методы.
+
+## Block function
+
+Добавление блоковой функции аналогичен добавлению строковой за исключением того что есть возможность указать парсер для закрывающего тега.
+
+```php
+$fenom->addBlockFunction(string $function_name, callable $callback[, callable $parser_open[, callable $parser_close]]);
+```
+
+Сам коллбек принимает первым аргументом контент между открывающим и закрывающим тегом, а вторым аргументом - ассоциативный массив из аргуметов тега:
+```php
+$fenom->addBlockFunction('some_block_function', function ($content, array $params) { /* ... */});
+```
+
+## Inline compiler
+
+Добавление строчного компилятора осуществляеться очень просто:
+
+```php
+$fenom->addCompiler(string $compiler, callable $parser);
+```
+
+Парсер должен принимать `Fenom\Tokenizer $tokenizer`, `Fenom\Template $template` и возвращать PHP код.
+Компилятор так же можно импортировать из класса автоматически
+
+```php
+$fenom->addCompilerSmart(string $compiler, $storage);
+```
+
+`$storage` может быть как классом так и объектом. В данном случае шаблонизатор будет искать метод `tag{$compiler}`, который будет взят в качестве парсера тега.
+
+## Block compiler
+
+Добавление блочного компилятора осуществяется двумя способами. Первый
+
+```php
+$fenom->addBlockCompiler(string $compiler, array $parsers, array $tags);
+```
+
+где `$parser` ассоциативный массив `["open" => parser, "close" => parser]`, сождержащий парсер на открывающий и на закрывающий тег, а `$tags` содержит список внутренних тегов в формате `["tag_name"] => parser`, которые могут быть использованы только с этим компилятором.
+Второй способ добавления парсера через импортирование из класса или объекта методов:
+
+```php
+$fenom->addBlockCompilerSmart(string $compiler, $storage, array $tags, array $floats);
+```
+
+# Add modifiers
+
+```
+$fenom->addModifier(string $modifier, callable $callback);
+```
+
+* `$modifier` - название модификатора, которое будет использоваться в шаблоне
+* `$callback` - коллбек, который будет вызван для изменения данных
+
+For example:
+
+```smarty
+{$variable|my_modifier:$param1:$param2}
+```
+
+```php
+$fenom->addModifier('my_modifier', function ($variable, $param1, $param2) {
+    // ...
+});
+```
+
+# Extends test operator
+
+```php
+$fenom->addTest($name, $code);
+?>
+
+# Add template provider
+
+Бывает так что шаблны не хранятся на файловой сиситеме, а хранятся в некотором хранилище, например, в базе данных MySQL.
+В этом случае шаблонизатору нужно описать как забирать шаблоны из хранилища, как проверять дату изменения шаблона и где хранить кеш шаблонов (опционально).
+Эту задачу берут на себя Providers, это объекты реальзующие интерфейс `Fenom\ProviderInterface`.
+
+# Extends accessor
+
+# Extends cache
+
+Изначально Fenom не расчитывался на то что кеш скомпиленых шаблонов может располагаться не на файловой системе.
+Однако, в теории, есть возможность реализовать свое кеширование для скомпиленых шаблонов без переопределения шаблонизатора.
+Речь идет о своем протоколе, отличным от `file://`, который [можно определить](http://php.net/manual/en/class.streamwrapper.php) в PHP.
+
+Ваш протол должени иметь класс реализации протокола как указан в документации [Stream Wrapper](http://www.php.net/manual/en/class.streamwrapper.php).
+Класс протокола может иметь не все указанные в документации методы. Вот список методов, необходимых шаблонизатору:
+
+* [CacheStreamWrapper::stream_open](http://www.php.net/manual/en/streamwrapper.stream-open.php)
+* [CacheStreamWrapper::stream_write](http://www.php.net/manual/en/streamwrapper.stream-write.php)
+* [CacheStreamWrapper::stream_close](http://www.php.net/manual/en/streamwrapper.stream-close.php)
+* [CacheStreamWrapper::rename](http://www.php.net/manual/en/streamwrapper.rename.php)
+
+For `include`:
+
+* [CacheStreamWrapper::stream_stat](http://www.php.net/manual/en/streamwrapper.stream-stat.php)
+* [CacheStreamWrapper::stream_read](http://www.php.net/manual/en/streamwrapper.stream-read.php)
+* [CacheStreamWrapper::stream_eof](http://www.php.net/manual/en/streamwrapper.stream-eof.php)
+
+**Note**
+(On 2014-05-13) Zend OpCacher doesn't support custom protocols except `file://` and `phar://`.
+
+For example,
+
+```php
+$this->setCacheDir("redis://hash/compiled/");
+```
+
+* `$cache = fopen("redis://hash/compiled/XnsbfeDnrd.php", "w");`
+* `fwrite($cache, "... <template content> ...");`
+* `fclose($cache);`
+* `rename("redis://hash/compiled/XnsbfeDnrd.php", "redis://hash/compiled/main.php");`
\ No newline at end of file
diff --git a/docs/operators.md b/docs/operators.md
index 579d772..22fa228 100644
--- a/docs/operators.md
+++ b/docs/operators.md
@@ -85,7 +85,7 @@ Operators
 
 * `$a ~ $b` - return concatenation of variables `$a` and `$b`
 
-### Ternary operator
+### Ternary operators
 
 * `$a ? $b : $c` - returns `$b` if `$a` is not empty, and `$c` otherwise
 * `$a ! $b : $c` - returns `$b` if `$a` is set, and `$c` otherwise
@@ -99,7 +99,7 @@ Operators
 {$a ? 5 : 10} {* outputs 10 *}
 ```
 
-### Check operator
+### Check operators
 
 * `$a?` - returns `TRUE` if `$a` is not empty
 * `$a!` - returns `TRUE` if `$a` is set
diff --git a/docs/readme.md b/docs/readme.md
index 3009957..8d5d478 100644
--- a/docs/readme.md
+++ b/docs/readme.md
@@ -15,26 +15,6 @@ Documentation
 
 ***
 
-### Modifiers
-
-[Usage](./syntax.md#modifiers)
-
-* [upper](./mods/upper.md) aka `up` — convert to uppercase a string
-* [lower](./mods/lower.md) aka `low` — convert to lowercase a string
-* [date_format](./mods/date_format.md) - format date, timestamp via strftime() function
-* [date](./mods/date.md) - format date, timestamp via date() function
-* [truncate](./mods/truncate.md) — truncate thee string to specified length
-* [escape](./mods/escape.md) aka `e` — escape the string
-* [unescape](./mods/unescape.md) — unescape the string
-* [strip](./mods/strip.md) — remove extra whitespaces
-* [length](./mods/length.md) — calculate length of string, array, object
-* [in](./mods/in.md) — find value in string or array
-* allowed functions: `json_encode`, `json_decode`, `count`, `is_string`, `is_array`, `is_numeric`, `is_int`, `is_object`,
-`strtotime`, `gettype`, `is_double`, `ip2long`, `long2ip`, `strip_tags`, `nl2br`
-* or [add](./ext/mods.md) yours
-
-***
-
 ### Tags
 
 [Usage](./syntax.md#tags)
@@ -52,13 +32,47 @@ Documentation
 * [macro](./tags/macro.md) and `import` — template functions
 * [autoescape](./tags/autoescape.md) — escape template fragment
 * [raw](./tags/raw.md) — unescape template fragment
-* or [add](./ext/tags.md) yours
+* or [add](./ext/extend.md#add-tags) yours
+
+
+***
+
+### Modifiers
+
+[Usage](./syntax.md#modifiers)
+
+* [upper](./mods/upper.md) aka `up` — convert to uppercase a string
+* [lower](./mods/lower.md) aka `low` — convert to lowercase a string
+* [date_format](./mods/date_format.md) - format date, timestamp via strftime() function
+* [date](./mods/date.md) - format date, timestamp via date() function
+* [truncate](./mods/truncate.md) — truncate thee string to specified length
+* [escape](./mods/escape.md) aka `e` — escape the string
+* [unescape](./mods/unescape.md) — unescape the string
+* [strip](./mods/strip.md) — remove extra whitespaces
+* [length](./mods/length.md) — calculate length of string, array, object
+* [in](./mods/in.md) — find value in string or array
+* allowed functions: `json_encode`, `json_decode`, `count`, `is_string`, `is_array`, `is_numeric`, `is_int`, `is_object`,
+`strtotime`, `gettype`, `is_double`, `ip2long`, `long2ip`, `strip_tags`, `nl2br`
+* or [add](./ext/extend.md#add-modifiers) yours
+
+***
+
+### Operators
+
+* [Arithmetic operators](./operators.md#arithmetic-operators) — `+`, `-`, `*`, `/`, `%`
+* [Logical operators](./operators.md#logical-operators) — `||`, `&&`, `!$var`, `and`, `or`, `xor`
+* [Comparison operators](./operators.md#comparison-operators) — `>`, `>=`, `<`, `<=`, `==`, `!=`, `!==`, `<>`
+* [Bitwise operators](./operators.md#bitwise-operators) — `|`, `&`, `^`, `~$var`, `>>`, `<<`
+* [Assignment operators](./operators.md#assignment-operators) — `=`, `+=`, `-=`, `*=`, `/=`, `%=`, `&=`, `|=`, `^=`, `>>=`, `<<=`
+* [String concatenation operator](./operators.md#string-operator) — `$str1 ~ $str2`
+* [Ternary operators](./operators.md#ternary-operators) — `$a ? $b : $c`, `$a ! $b : $c`, `$a ?: $c`, `$a !: $c`
+* [Check operators](./operators.md#check-operators) — `$var?`, `$var!`
+* [Test operator](./operators.md#test-operators) — `is`, `is not`
+* [Containment operator](./operators.md#containment-operators) — `in`, `not in`
 
 ***
 
 ### Extends
 
-* [Extensions](./ext/extensions.md)
-* [Add tags](./ext/tags.md)
-* [Add modifiers](./ext/mods.md)
-* [Parsing](./ext/parsing.md)
+* [Extend Fenom](./ext/extend.md)
+* [Add-ons](./ext/extensions.md)
diff --git a/src/Fenom/Provider.php b/src/Fenom/Provider.php
index bfbc359..6ea55db 100644
--- a/src/Fenom/Provider.php
+++ b/src/Fenom/Provider.php
@@ -147,7 +147,6 @@ class Provider implements ProviderInterface
     public function templateExists($tpl)
     {
         return ($path = realpath($this->_path . "/" . $tpl)) && strpos($path, $this->_path) === 0;
-//        return file_exists($this->_path . "/" . $tpl);
     }
 
     /**