v5.0.0

CHANGELOG.md

@@ -1,5 +1,100 @@
 # BEM-XJST Changelog
 
+# 2016-01-29, [v5.0.0](https://github.com/bem/bem-xjst/compare/v4.3.3...v5.0.0), @miripiruni
+**BEMHTML breaking changes**: behavior mods and elemMods BEMJSON fields are changed. 
+
+BEM-XJST now should not treat mods as elemMods if block exist.
+```js
+// BEMJSON
+{
+  block: 'b',
+  elem: 'e',
+  mods: { m: 'v' } // will be ignored because of elem
+}
+
+// Result with v4.3.3
+'v class="b__e b__e_m_v"></div>'
+
+// Result with v5.0.0
+'<div class="b1__e1"></div>'
+```
+
+BEM-XJST should not treat elemMods as mods.
+```js
+// BEMJSON
+{
+  block: 'b1',
+  elemMods: { m1: 'v1' }
+}
+
+// Result with v4.3.3
+'<div class="b1 b1_m1_v1"></div>'
+
+// Result with v5.0.0
+'<div class="b1"></div>'
+```
+
+**BEM-XJST breaking changes**: BEM-XJST now supports two template engines — BEMHTML for getting HTML output and BEMTREE for getting BEMJSON. By default BEM-XJST will use BEMHTML engine.
+Usage example:
+
+```js
+var bemxjst = require('bem-xjst');
+var bemhtml = bemxjst.bemhtml;
+
+// Add templates
+bemhtml.compile(function() {
+  block('b').content()('yay');
+});
+
+// Apply templates to data context in BEMJSON format and get result as HTML string
+bemhtml.apply({ block: 'b' });
+// Result: <div class="b">yay</div>
+```
+
+```js
+var bemxjst = require('bem-xjst');
+var bemtree = bemxjst.bemtree;
+
+// Add templates
+bemtree.compile(function() {
+  block('b').content()('yay');
+});
+
+// Apply templates to data context in BEMJSON format and get result as BEMJSON
+bemtree.apply({ block: 'b' });
+// Result: { block: 'b1', content: 'yay' }
+```
+
+
+Now supports changing elemMods in runtime. Example:
+```js
+// Template
+block('b1').elem('e1').def()(function() {
+  this.elemMods.a = 'b';
+  return applyNext();
+});
+// BEMJSON
+{ block: 'b1', elem: 'e1' }
+// Result:
+'<div class="b1__e1 b1__e1_a_b"</div>'
+```
+
+BEMTREE will return Boolean as is. Example:
+```js
+// Input BEMJSON
+[
+  true,
+  { block: 'b1', content: true },
+  [ { elem: 'e1', content: true }, true ]
+]
+// Output BEMJSON
+[
+  true,
+  { block: 'b1', content: true },
+  [ { elem: 'e1', content: true }, true ]
+]
+```
+
 ## 2016-01-22, [v4.3.3](https://github.com/bem/bem-xjst/compare/v4.3.2...v4.3.3), @miripiruni
 Should properly render attr values:
 ```js

README.md

@@ -16,22 +16,36 @@ Install it by [npm](https://npmjs.org): `npm install bem-xjst`.
 ### As a node.js module
 
 ```js
-var bem = require('bem-xjst');
-var template = bem.compile('... your source code ...');
+var bemxjst = require('bem-xjst');
+var bemhtml = bemxjst.bemhtml;
 
-template.apply(/* ... your input data here ... */);
+// Add templates
+bemhtml.compile(function() {
+  block('b').content()('yay');
+});
+
+// Apply templates to data context in BEMJSON format and get result as HTML string
+bemhtml.apply({ block: 'b' });
+// Result: <div class="b">yay</div>
+```
 
-// Or even better:
+```js
+var bemxjst = require('bem-xjst');
+var bemtree = bemxjst.bemtree;
 
-template = bem.compile(function() {
-  block('b1').content()('yay');
+// Add templates
+bemtree.compile(function() {
+  block('b').content()('yay');
 });
-template.apply({ block: 'b1' });
+
+// Apply templates to data context in BEMJSON format and get result as BEMJSON
+bemtree.apply({ block: 'b' });
+// Result: { block: 'b1', content: 'yay' }
 ```
 
 ### As a CLI tool
 
-```
+```bash
 $ bem-xjst --help
 
 Usage:
@@ -41,7 +55,7 @@ Usage:
 Options:
   -h, --help : Help
   -v, --version : Version
-  -d, --dev-mode : Dev mode
+  -e, --engine : Engine name (default: bemhtml, supported: bemhtml | bemtree)
   -i INPUT, --input=INPUT : Input file (default: stdin)
   -o OUTPUT, --output=OUTPUT : Output file (default: stdout)
 ```
@@ -71,17 +85,50 @@ Run compiled templates on specified input context. Return resulting HTML output.
 Add more BEM templates to the `templates` instance. Might be called in runtime
 to deliver more blocks declarations to the client.
 
+```js
+var bemxjst = require('bem-xjst');
+var templates = bemxjst.bemhtml.compile(function() {
+    block('b').tag()('a');
+  });
+
+templates.apply({ block: 'b' });
+// Return '<a class="b"></a>'
+
+templates.compile(function() {
+  block('b').content()('Hi, folks!');
+});
+
+templates.apply({ block: 'b' });
+// Return '<a class="b">Hi, folks!</a>'
+```
+
 #### `.BEMContext`
 
 Constructor of the `this` object available in template bodies. Might be amended
 to expose some functionality to the templates, or to add [_flush][1] method.
 
+```js
+var bemxjst = require('bem-xjst');
+var templates = bemxjst.bemhtml.compile('');
+
+templates.BEMContext.prototype.myField = 'opa';
+
+templates.compile(function() {
+  block('b').content()(function() {
+    return this.myField;
+  });
+});
+
+templates.apply({ block: 'b' });
+// Return '<div class="b">opa</div>'
+```
+
 ### Benchmarks
 
 To run benchmarks:
 
 ```bash
-cd benchmarks/
+cd bench/
 npm install
 node run.js -h
 node run.js
@@ -97,7 +144,7 @@ See [wiki][0]
 
 #### License
 
-Code and documentation copyright 2015 YANDEX LLC. Code released under the
+Code and documentation copyright 2016 YANDEX LLC. Code released under the
 [Mozilla Public License 2.0](LICENSE.txt).
 
 [0]: https://github.com/bem/bem-xjst/wiki/Notable-changes-between-bem-xjst@1.x-and-bem-xjst@2.x

README.ru.md

@@ -9,22 +9,43 @@
 
 ## Установка
 
-Устанавливается с помощью [npm](https://npmjs.org): `npm install bem`.
+Устанавливается с помощью [npm](https://npmjs.org): `npm install bem-xjst`.
 
 ## Использование
 
-### В качестве js-модуля
+### В качестве node.js модуля
 
 ```js
-var BEM_XJST = require('bem-xjst'),
-    template = BEM_XJST.compile('... your source code ...');
+var bemxjst = require('bem-xjst');
+var bemhtml = bemxjst.bemhtml;
 
-template.apply(/* ... your input data here ... */);
+// Add templates
+bemhtml.compile(function() {
+  block('b').content()('yay');
+});
+
+// Apply templates to data context in BEMJSON format and get result as HTML string
+bemhtml.apply({ block: 'b' });
+// Result: <div class="b">yay</div>
 ```
 
-### В виде программы
+```js
+var bemxjst = require('bem-xjst');
+var bemtree = bemxjst.bemtree;
+
+// Add templates
+bemtree.compile(function() {
+  block('b').content()('yay');
+});
 
+// Apply templates to data context in BEMJSON format and get result as BEMJSON
+bemtree.apply({ block: 'b' });
+// Result: { block: 'b1', content: 'yay' }
 ```
+
+### В виде CLI-утилиты
+
+```bash
 $ bem-xjst --help
 
 Usage:
@@ -34,7 +55,98 @@ Usage:
 Options:
   -h, --help : Help
   -v, --version : Version
-  -d, --dev-mode : Dev mode
+  -e, --engine : Engine name (default: bemhtml, supported: bemhtml | bemtree)
   -i INPUT, --input=INPUT : Input file (default: stdin)
   -o OUTPUT, --output=OUTPUT : Output file (default: stdout)
 ```
+
+## API
+
+### Compiler
+
+#### `.compile(string or function)`
+
+Компилирует шаблоны и возвращает объект `templates`.
+(Смотри документацию его методов ниже).
+
+#### `.generate(string or function)`
+
+Генерирует JS-код, который может быть передан и выполнен в браузере для
+получения объекта `templates`.
+
+### templates
+
+#### `.apply(context)`
+
+Применяет скомпилированные шаблоны к переданному BEMJSON в аргументе context.
+В зависимости от `engine` возвращает BEMJSON или HTML.
+
+#### `.compile(string or function)`
+
+Добавляет шаблоны к экземпляру `templates`. Может быть вызван в рантайме.
+
+```js
+var bemxjst = require('bem-xjst');
+var templates = bemxjst.bemhtml.compile(function() {
+    block('b').tag()('a');
+  });
+
+templates.apply({ block: 'b' });
+// Return '<a class="b"></a>'
+
+templates.compile(function() {
+  block('b').content()('Hi, folks!');
+});
+
+templates.apply({ block: 'b' });
+// Return '<a class="b">Hi, folks!</a>'
+```
+
+#### `.BEMContext`
+
+Конструктор `this` доступного в теле шаблонов. Может быть расширен для
+предоставления дополнительной функциональности в шаблонах.
+
+```js
+var bemxjst = require('bem-xjst');
+var templates = bemxjst.bemhtml.compile('');
+
+templates.BEMContext.prototype.myField = 'opa';
+
+templates.compile(function() {
+  block('b').content()(function() {
+    return this.myField;
+  });
+});
+
+templates.apply({ block: 'b' });
+// Return '<div class="b">opa</div>'
+```
+
+### Тесты на производительность
+
+Чтобы запустить тесты:
+
+```bash
+cd bench/
+npm install
+node run.js -h
+node run.js
+```
+
+Тесты на производительность могут быть запущены с параметром `--compare`
+для отслеживания регрессий и сравнения с предыдущей версией BEM-XJST. Не забудьте
+ убедиться, что в `benchmarks/package.json` указан правильный hash коммита
+ `bem-xjst`.
+
+### Миграция с v1.x
+
+Смотри [wiki][0] (English)
+
+#### Лицензия
+
+Права на код и документацию принадлежат 2016 YANDEX LLC.
+[Mozilla Public License 2.0](LICENSE.txt).
+
+[0]: https://github.com/bem/bem-xjst/wiki/Notable-changes-between-bem-xjst@1.x-and-bem-xjst@2.x
+[1]: https://github.com/bem/bem-xjst/wiki/Notable-changes-between-bem-xjst@1.x-and-bem-xjst@2.x#this_str-is-gone

package.json

@@ -1,6 +1,6 @@
 {
   "name": "bem-xjst",
-  "version": "4.3.3",
+  "version": "5.0.0",
   "bin": {
     "bem-xjst": "bin/bem-xjst"
   },