Reformat documentation

This commit is contained in:
bzick 2014-08-02 00:24:14 +04:00
parent 5972884c80
commit 0ff3ffc27f
60 changed files with 168 additions and 161 deletions

View File

@ -9,7 +9,7 @@ Fenom - Template Engine for PHP
[![Coverage Status](https://coveralls.io/repos/bzick/fenom/badge.png?branch=master)](https://coveralls.io/r/bzick/fenom?branch=master)
[![Code Climate](https://codeclimate.com/github/bzick/fenom.png)](https://codeclimate.com/github/bzick/fenom)
[![Total Downloads](https://poser.pugx.org/fenom/fenom/downloads.png)](https://packagist.org/packages/fenom/fenom)
## [Quick start](./docs/start.md) :: [Documentation](./docs/readme.md) :: [Benchmark](./docs/benchmark.md)
## [Quick start](./docs/en/start.md) :: [Documentation](./docs/readme.md) [en](./docs/en/readme.md)/[ru](./docs/ru/readme.md) :: [Benchmark](./docs/en/benchmark.md)
<!-- :: [Articles](./docs/articles.md) -->
### What is it
@ -18,13 +18,13 @@ Fenom - Template Engine for PHP
It means:
* Known Smarty-like [syntax](./docs/syntax.md) with improvements.
* Very [fast](./docs/benchmark.md).
* [Lightweight](./docs/benchmark.md).
* Very [flexible](./docs/configuration.md#extends).
* Known Smarty-like [syntax](./docs/en/syntax.md) with improvements.
* Very [fast](./docs/en/benchmark.md).
* [Lightweight](./docs/en/benchmark.md).
* Very [flexible](./docs/en/configuration.md#extends).
* Progressive parser without regular expressions.
* High [code coverage](https://coveralls.io/r/bzick/fenom?branch=master).
* Easy to understand [how it works](./docs/dev/readme.md).
* Easy to [use](./docs/start.md).
* Maximum [protection](./docs/configuration.md#configure).
* Easy to understand [how it works](./docs/en/dev/readme.md).
* Easy to [use](./docs/en/start.md).
* Maximum [protection](./docs/en/configuration.md#configure).

86
docs/en/readme.md Normal file
View File

@ -0,0 +1,86 @@
Documentation
=============
**Please, help translate documentation to english or fix typos. [Read more](./helpme.md).**
### Fenom
* [Quick start](./start.md)
* [Usage](./start.md#install-fenom)
* [Framework adapters](./adapters.md)
* [For developers](./dev/readme.md)
* [Configuration](./configuration.md)
* [Syntax](./syntax.md)
* [Operators](./operators.md)
***
### Tags
[Usage](./syntax.md#tags)
* [var](./tags/var.md) — define variable
* [if](./tags/if.md), `elseif` and `else` — conditional statement
* [foreach](./tags/foreach.md), `foreaelse`, `break` and `continue` — traversing items in an array or object
* [for](./tags/for.md), `forelse`, `break` and `continue` — loop statement
* [switch](./tags/switch.md), `case`, `default`
* [cycle](./tags/cycle.md) — cycles on an array of values
* [include](./tags/include.md), `insert` — includes and evaluates the specified template
* [extends](./tags/extends.md), `use`, `block` and `parent` — 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
* [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
***
### 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
* [match](./mods/match.md) — match string against a pattern.
* [ematch](./mods/ematch.md) — perform a regular expression match.
* [replace](./mods/replace.md) — replace all occurrences of the search string with the replacement string.
* [ereplace](./mods/ereplace.md) — perform a regular expression search and replace.
* [split](./mods/split.md) — split a string by string.
* [esplit](./mods/esplit.md) — split string by a regular expression.
* [join](./mods/join.md) — join array elements with a string.
* 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-operator) — `is`, `is not`
* [Containment operator](./operators.md#containment-operator) — `in`, `not in`
***
### Extends
* [Extend Fenom](./ext/extend.md)
* [Add-ons](./ext/extensions.md)

View File

@ -1,86 +1,5 @@
Documentation
=============
Languages
=========
**Please, help translate documentation to english or fix typos. [Read more](./helpme.md).**
### Fenom
* [Quick start](./start.md)
* [Usage](./start.md#install-fenom)
* [Framework adapters](./adapters.md)
* [For developers](./dev/readme.md)
* [Configuration](./configuration.md)
* [Syntax](./syntax.md)
* [Operators](./operators.md)
***
### Tags
[Usage](./syntax.md#tags)
* [var](./tags/var.md) — define variable
* [if](./tags/if.md), `elseif` and `else` — conditional statement
* [foreach](./tags/foreach.md), `foreaelse`, `break` and `continue` — traversing items in an array or object
* [for](./tags/for.md), `forelse`, `break` and `continue` — loop statement
* [switch](./tags/switch.md), `case`, `default`
* [cycle](./tags/cycle.md) — cycles on an array of values
* [include](./tags/include.md), `insert` — includes and evaluates the specified template
* [extends](./tags/extends.md), `use`, `block` and `parent` — 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
* [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
***
### 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
* [match](./mods/match.md) — match string against a pattern.
* [ematch](./mods/ematch.md) — perform a regular expression match.
* [replace](./mods/replace.md) — replace all occurrences of the search string with the replacement string.
* [ereplace](./mods/ereplace.md) — perform a regular expression search and replace.
* [split](./mods/split.md) — split a string by string.
* [esplit](./mods/esplit.md) — split string by a regular expression.
* [join](./mods/join.md) — join array elements with a string.
* 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-operator) — `is`, `is not`
* [Containment operator](./operators.md#containment-operator) — `in`, `not in`
***
### Extends
* [Extend Fenom](./ext/extend.md)
* [Add-ons](./ext/extensions.md)
* [English](./en/readme.md)
* [Russian](./ru/readme.md)

View File

@ -1,8 +1,8 @@
Adapters
Адаптеры
========
* [Fenom + Yii](https://bitbucket.org/RSol/rfenomviewrender)
* [Fenom + Kohana](https://github.com/2bj/kofenom) — Kofenom
* Fenom + Symphony
* Fenom + Symphony2
* Fenom + Zend Framework
* Fenom + Zend Framework 2

View File

@ -1,52 +1,55 @@
Setup
=====
Настройка
=========
## Configure
### Template cache
### Кеш шаблонов
```php
$fenom->setCompileDir($dir);
```
This method set the name of the directory where template caches are stored. By default this is `/tmp`. This directory must be writeable.
Задает имя каталога, в котором хранятся компилированные шаблоны. По умолчанию это `/tmp`. Каталог дожен быть доступен на запись.
### Template settings
### Параметры обработчика
Установка параметров через фабрику
```php
// set options using factory
$fenom = Fenom::factory($tpl_dir, $compile_dir, $options);
// or inline using method setOptions
$fenom->setOptions($options);
```
Options may by associative array like `'option_name' => true` or bitwise mask.
Установка параметров через метод
```php
$fenom->setOptions($options);
```
В обоих случаях аргумет `$options` может быть массивом или битовой маской.
В массиве ключем должно быть название параметра, а ключем — булевый флаг `true` (активировать) или `false` (деактивировать).
Битавая маска должна состоять из занчений констант из таблице ниже
| Option name | Constant | Description | Affect |
| Название параметра | Константа | Описание | Эффект |
| ---------------------- | ------------------------- | ------------ | ------- |
| *disable_methods* | `Fenom::DENY_METHODS` | disable calling methods of objects in templates. | |
| *disable_native_funcs* | `Fenom::DENY_NATIVE_FUNCS`| disable calling native function in templates, except allowed. | |
| *auto_reload* | `Fenom::AUTO_RELOAD` | reload template if source will be changed | decreases performance |
| *force_compile* | `Fenom::FORCE_COMPILE` | recompile template every time when the template renders | very decreases performance |
| *disable_cache* | `Fenom::DISABLE_CACHE` | disable compile cache | greatly decreases performance |
| *force_include* | `Fenom::FORCE_INCLUDE` | paste template body instead of include-tag | increases performance, increases cache size |
| *auto_escape* | `Fenom::AUTO_ESCAPE` | html-escape each variables outputs | decreases performance |
| *force_verify* | `Fenom::FORCE_VERIFY` | check existence every used variable | decreases performance |
<!-- | *auto_trim* | `Fenom::AUTO_TRIM` | remove space-characters before and after tags | | -->
| *disable_statics* | `Fenom::DENY_STATICS` | disable calling static methods in templates. | |
| *strip* | `Fenom::AUTO_STRIP` | strip all whitespaces in templates. | decrease cache size |
| *disable_methods* | `Fenom::DENY_METHODS` | отключает воззможность вызова методов в шаблоне | |
| *disable_native_funcs* | `Fenom::DENY_NATIVE_FUNCS`| отключает возможность использования фунций PHP, за исключением разрешенных | |
| *auto_reload* | `Fenom::AUTO_RELOAD` | автоматически пересобирать кеш шаблона если шаблон изменился | понижает производительность |
| *force_compile* | `Fenom::FORCE_COMPILE` | каждый раз пересобирать кеш шаблонов (рекоммендуется только для отладки)| очень сильно понижает производительность |
| *disable_cache* | `Fenom::DISABLE_CACHE` | не кешировать компилированный шаблон | эпично понижает производительность |
| *force_include* | `Fenom::FORCE_INCLUDE` | стараться по возможности вставить код дочернего шаблона в родительский при подключении шаблона | повышает производительность, увеличивает размер файлов в кеше, уменьшает количество файлов в кеше |
| *auto_escape* | `Fenom::AUTO_ESCAPE` | автоматически экранировать HTML сущности при выводе переменных в шаблон | понижает производительность |
| *force_verify* | `Fenom::FORCE_VERIFY` | автоматически проверять существование переменной перед использованием в шаблоне | понижает производительность |
| *disable_statics* | `Fenom::DENY_STATICS` | отключает воззможность вызова статических методов в шаблоне | |
| *strip* | `Fenom::AUTO_STRIP` | удаляет лишиние пробелы в шаблоне | уменьшает размер кеша |
```php
$fenom->setOptions(array(
"compile_check" => true,
"force_include" => true
));
// same
// тоже самое что и
$fenom->setOptions(Fenom::AUTO_RELOAD | Fenom::FORCE_INCLUDE);
```
**Note**
By default all options disabled
**Замечание**
По умолчанию все параметры деактивированы.
## Extends

View File

@ -1,9 +0,0 @@
Требуется помощь в переводе документации
========================================
Принимаю любую помощь в переводе статей документации. Вносить правки в документацию можете любым удобным способом:
* Сделать merge request (нажав `Edit` вверху файла)
* Прислать адрес статьи и что на что заменить. В письме лучше укажите `Fenom docs`.
Заранее благодарен!

View File

@ -1,55 +1,63 @@
Operators
Операторы
=========
### Arithmetic operators
### Арифметические операторы
* `$a + $b` - addition
* `$a - $b` - subtraction
* `$a * $b` - multiplication
* `$a / $b` - division
* `$a % $b` - modulus
Все же помнят арифметику?
* `-$a` - отрицание знака, смена знака `$a`.
* `$a + $b` - сложение, сумма `$a` и `$b`.
* `$a - $b` - вычитаение, разность `$a` и `$b`.
* `$a * $b` - умножение, произведение `$a` и `$b`.
* `$a / $b` - деление, частное от деления `$a` на `$b`.
* `$a % $b` - деление по модулю, целочисленный остаток от деления `$a` на `$b`.
```smarty
{$a + $b * $c/$d - $e*5 + 1e3}
```
### Logical operators
### Логические операторы
* `$a || $b` - or
* `$a && $b` - and
* `!$a` - not, unary operator
* `$a and $b` - and
* `$a or $b` - or
* `$a xor $b` - xor
* `$a || $b` - логичесое ИЛИ
* `$a && $b` - лигическое И
* `!$a` - отрицание, унарный оператор
* `$a or $b` - логическое ИЛИ
* `$a and $b` - логическое И
* `$a xor $b` - xor, логическое сложение
```smarty
{if $b && $c} ... {/if}
```
### Comparison operators
### Операторы сравнения
* `$a < $b` - less than
* `$a > $b` - greater than
* `$a <= $b` - less than or equal to
* `$a >= $b` - greater than or equal to
* `$a == $b` - equal
* `$a === $b` - identical
* `$a !== $b` - not identical
* `$a != $b` - not equal
* `$a <> $b` - not equal
* `$a < $b` - строгое неравество, `$a` меньше `$b`
* `$a > $b` - строгое неравество, `$a` больше `$b`
* `$a <= $b` - не строгое не равество, `$a` меньше или равно `$b`
* `$a >= $b` - не строгое не равество, `$a` больше или равно `$b`
* `$a == $b` - Равно, `$a` равно `$b`
* `$a === $b` - Тождественно равно, `$a` иденично `$b`. Отличается от равества тем что проверяет так же тип значений; если '0' == 0 — истина, то уже '0' === 0 — ложно.
* `$a !== $b` - не иденично, `$a` отличается от `$b`
* `$a != $b` - неравенство, `$a` отличается от `$b`
* `$a <> $b` - неравенство
```smarty
{if $b >= 5} ... {/if}
```
### Bitwise operators
В случае, если вы сравниваете число со строкой или две строки, содержащие числа, каждая строка будет преобразована в число, и сравниваться они будут как числа.
Преобразование типов не происходит при использовании `===` или `!==` так как в этом случае кроме самих значений сравниваются еще и типы.
* `$a | $b` - or
* `$a & $b` - and
* `$a ^ $b` - xor
* `~$a` - not, unary operator
* `$a << $b` - shift left
* `$a >> $b` - shift right
### Побитовые операторы
Побитовые операторы позволяют считывать и устанавливать конкретные биты целых чисел.
* `$a | $b` - битовое ИЛИ, устанавливаются те биты, которые установлены в `$a` или в `$b`.
* `$a & $b` - битовое И, устанавливаются только те биты, которые установлены и в `$a`, и в `$b`.
* `$a ^ $b` - битовое исключающее ИЛИ, устанавливаются только те биты, которые установлены либо только в `$a`, либо только в `$b`, но не в обоих одновременно.
* `~$a` - битовое отрицание, устанавливаются те биты, которые не установлены в `$a`, и наоборот.
* `$a << $b` - битовый сдвиг влево, все биты переменной `$a` сдвигаются на `$b` позиций влево (каждая позиция подразумевает "умножение на 2")
* `$a >> $b` - битовый сдвиг вправо, все биты переменной `$a` сдвигаются на `$b` позиций вправо (каждая позиция подразумевает "деление на 2")
```smarty
{if $a & 1} {var $b = 4 | $flags} {/if}

View File

@ -21,7 +21,7 @@ Documentation
* [if](./tags/if.md), `elseif` и `else` — условный оператор
* [foreach](./tags/foreach.md), `foreaelse`, `break` and `continue` — перебор элементов массива или объекта
* [for](./tags/for.md), `forelse`, `break` and `continue` — цикл
* [switch](./tags/switch.md), `case`, `default`
* [switch](./tags/switch.md), `case`, `default` груповой условный оператор
* [cycle](./tags/cycle.md) — циклицеский перебор массива значений
* [include](./tags/include.md), `insert` — вставляет и испольняет указанный шаблон
* [extends](./tags/extends.md), `use`, `block` и `parent` — наследование шаблонов

View File

@ -205,7 +205,7 @@ but if use single quote any template expressions will be on display as it is
{var $c = 7E-10}
```
### Операции над переменными
### Операции
Как и любой другой язык программирования/шаблонизации Fenom поддерживает множество различных операторов: