From 1de675dc4cee20aabaacfbdf22bae549f34ccc0a Mon Sep 17 00:00:00 2001 From: Sergei Bocharov Date: Sun, 29 Jan 2017 15:50:30 +0300 Subject: [PATCH 1/6] review --- README.md | 198 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 148 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index 28c900b..76194e5 100644 --- a/README.md +++ b/README.md @@ -18,12 +18,13 @@ Library with a couple of methods to work with sets of BEM entities (aka BEMDECL ## Prerequisites -- [Node.js](https://nodejs.org/en/) 4.x+ +* [Node.js](https://nodejs.org/en/) 4.x+ ## Installation Run in your project directory: -```sh + +```bash npm install --save bem-decl ``` @@ -32,48 +33,57 @@ npm install --save bem-decl ```js const bemDecl = require('bem-decl'); -// Since we using sets stored in files we need to load them asyncronously +// Since we using sets stored in files we need to load them asynchronously async function() { - // Await loading of file and put it to `set1` variable - // NB: There are few formats of declaration files but bem-decl here to read them all + /* + Await loading of file and put it to `set1` variable + Note: There are few formats of declaration files but bem-decl here to read them all + */ const set1 = await bemDecl.load('set1.bemdecl.js'); - // File set1.bemdecl.js: - // exports.blocks = [ - // {name: 'button', elems: [{name: 'control'}, {name: 'icon'}]} - // ]; - - // `set1` is an array of BemCell objects, - // convert them to strings using `.map` and special `id` property: + /* + File set1.bemdecl.js: + exports.blocks = [ + {name: 'button', elems: [{name: 'control'}, {name: 'icon'}]} + ]; + */ + + /* + `set1` is an array of BemCell objects, + convert them to strings using `.map` and special `id` property: + */ set1.map(c => c.id); - // [ 'button', 'button__control', 'button__icon' ] + // ['button', 'button__control', 'button__icon'] // Let's load another set: const set2 = await bemDecl.load('set2.bemdecl.js'); - // File set2.bemdecl.js: - // exports.deps = [ - // {block: 'button', elem: 'icon'}, - // {block: 'link', mods: {theme: 'normal'}} - // ]; + /* File set2.bemdecl.js: + exports.deps = [ + {block: 'button', elem: 'icon'}, + {block: 'link', mods: {theme: 'normal'}} + ]; + */ set2.map(c => c.id); - // [ 'button__icon', 'link', 'link_theme', 'link_theme_normal' ] + // ['button__icon', 'link', 'link_theme', 'link_theme_normal'] // To subtract one set from another just use `.subtract` method: bemDecl.subtract(set1, set2).map(c => c.id); - // [ 'button', 'button__control' ] + // ['button', 'button__control'] // Result will be different if we swap arguments (as expected): bemDecl.subtract(set2, set1).map(c => c.id); - // [ 'link', 'link_theme', 'link_theme_normal' ] + // ['link', 'link_theme', 'link_theme_normal'] // To merge two sets use `.merge` method: bemDecl.merge(set1, set2).map(c => c.id); - // [ 'button', 'button__control', 'button__icon', - // 'link', 'link_theme', 'link_theme_normal' ] + /* + ['button', 'button__control', 'button__icon', + 'link', 'link_theme', 'link_theme_normal'] + */ // Also there is `.intersect` method to calculate intersection between them: bemDecl.intersect(set1, set2).map(c => c.id); - // [ 'button__icon' ] + // ['button__icon'] } ``` @@ -81,24 +91,41 @@ async function() { There are several formats and `bem-decl` is here to rule them all. -- 'v1' - the old [BEMDECL](https://en.bem.info/methodology/declarations/) format also known as `exports.blocks = ...`. -- 'v2' - format based on [`deps.js`](https://en.bem.info/platform/deps/)-files also known as `exports.deps = ...`. -- 'enb' - legacy format for widely used enb deps reader. +* 'v1' - the old [BEMDECL](https://en.bem.info/methodology/declarations/) format also known as `exports.blocks = ...`. +* 'v2' - format based on [`deps.js`](https://en.bem.info/platform/deps/)-files also known as `exports.deps = ...`. +* 'enb' - legacy format for widely used enb deps reader. ## API -* [`load(file: String, opts: *): Promise`](#loadfile-string-opts--promisebemcell) -* [`merge(BemCell[], BemCell[], ...): BemCell[]`](#mergebemcell-bemcell--bemcell) -* [`intersect(BemCell[], BemCell[], ...): BemCell[]`](#intersectbemcell-bemcell--bemcell) -* [`subtract(BemCell[], BemCell[]): BemCell[]`](#subtractbemcell-bemcell-bemcell) -* [`parse(bemdecl: String|Object): BemCell[]`](#parsebemdecl-stringobject-bemcell) -* [`stringify(BemCell[], {format: 'enb'}): String`](#stringifybemcell-format-enb-string) +* [load()](#load-method) +* [merge()](#merge-method) +* [intersect()](#intersect-method) +* [subtract()](#subtract-method) +* [parse()](#parse-method) +* [stringify()](#stringify-method) + +### load method + +Loads BEM entities from a file in any format. + +#### Syntax + +`load(filename[, options])` + +#### Input parameters -### `load(file: String, opts: *): Promise` +| Parameter | Type | Description | +|----------|-----|----------| +|**filename**|`string`|`bemdecl.js`-filename.| +|**options**|`*`|???| -Loads BEM entities from a file in any format +#### Output data + +A promise that represents `BemCell[]`. + +#### Example ```js bemDecl.load('set1.bemdecl.js') @@ -122,49 +149,87 @@ bemDecl.save('set1.bemdecl.js', decl, { format: 'enb' }); TODO: https://github.com/bem-sdk/bem-decl/issues/4 --> -### `merge(BemCell[], BemCell[], ...): BemCell[]` +### merge method + +Merges many sets of BEM entities into one. + +#### Syntax + +`merge(BemCell[], BemCell[], ...)` + +#### Output data -Merges many sets of BEM entities into one +`BemCell[]` + +#### Example ```js const decl1 = [ new BemCell({ entity: new BemEntityName({ block: 'button' }) }) ]; + const decl2 = [ new BemCell({ entity: new BemEntityName({ block: 'link' }) }) ]; + const decl3 = [ new BemCell({ entity: new BemEntityName({ block: 'button' }) }), new BemCell({ entity: new BemEntityName({ block: 'link' }) }) ]; + bemDecl.merge(decl1, decl2, decl3).map(c => c.id); -// [ 'button', 'link' ] + +// ['button', 'link'] ``` -### `intersect(BemCell[], BemCell[], ...): BemCell[]` +### intersect method + +Calculates the set of BEM entities that exists in each passed set. + +#### Syntax -Calculates the set of BEM entities that exists in each passed set +`intersect(BemCell[], BemCell[], ...)` + +#### Output data + +`BemCell[]` + +#### Example ```js const decl1 = [ new BemCell({ entity: new BemEntityName({ block: 'button' }) }), new BemCell({ entity: new BemEntityName({ block: 'select' }) }) ]; + const decl2 = [ new BemCell({ entity: new BemEntityName({ block: 'button' }) }), new BemCell({ entity: new BemEntityName({ block: 'link' }) }) ]; + const decl3 = [ new BemCell({ entity: new BemEntityName({ block: 'button' }) }), new BemCell({ entity: new BemEntityName({ block: 'attach' }) }) ]; + bemDecl.intersect(decl1, decl2, decl3).map(c => c.id); -// [ 'button' ] + +// ['button'] ``` -### `subtract(BemCell[], BemCell[]): BemCell[]` +### subtract method + +Calculates the set of BEM entities that occur only in the first passed set and does not exist in the rest. + +#### Syntax + +`subtract(BemCell[], BemCell[]): BemCell[]` -Calculates the set of BEM entities that occure only in the first passed set and does not exist in the rest +#### Output data + +`BemCell[]` + +#### Example ```js const decl1 = [ @@ -172,39 +237,72 @@ const decl1 = [ new BemCell({ entity: new BemEntityName({ block: 'select' }) }), new BemCell({ entity: new BemEntityName({ block: 'link' }) }) ]; + const decl2 = [ new BemCell({ entity: new BemEntityName({ block: 'link' }) }) ]; + const decl3 = [ new BemCell({ entity: new BemEntityName({ block: 'select' }) }) ]; + bemDecl.subtract(decl1, decl2, decl3).map(c => c.id); -// [ 'button' ] + +// ['button'] ``` -### `parse(bemdecl: String|Object): BemCell[]` +### parse method + +Parses raw string or evaluated JS object to a set of BEM entities. + +#### Syntax + +`parse(bemdecl)` -Parses raw string or evaluated JS object to a set of BEM entities +#### Input parameters + +| Parameter | Type | Description | +|----------|-----|----------| +|**bemdecl**|`string|Object`|???| + +#### Output data + +`BemCell[]` + +#### Example ```js bemDecl.parse('exports.deps = [{ block: "button" }]').map(c => c.id); -// [ 'button' ] + +// ['button'] ``` See also [Declarations in BEM](https://en.bem.info/methodology/declarations/) -### `stringify(BemCell[], {format: 'enb'}): String` +### stringify method Stringifies set of BEM entities to a specific format. -NB: Temporary there is just `enb` format. It will be fixed later. +**Note** Temporary there is just `enb` format. It will be fixed later. + +#### Syntax + +`stringify(BemCell[], {format: 'enb'})` + +#### Output data + +`String` + +#### Example ```js const decl = [ new BemCell({ entity: new BemEntityName({ block: 'button' }) }) ]; + bemDecl.stringify(decl, { format: 'enb' }); -// 'exports.deps = [\n {\n "block": "button"\n }\n];\n' + +/* 'exports.deps = [\n {\n "block": "button"\n }\n];\n' ``` ## Contributing From a2b54e4101f2c9eb25928e59b53e0874dc473c00 Mon Sep 17 00:00:00 2001 From: Sergei Bocharov Date: Sun, 29 Jan 2017 16:10:45 +0300 Subject: [PATCH 2/6] fix subtract method --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 76194e5..31ce6a2 100644 --- a/README.md +++ b/README.md @@ -223,7 +223,7 @@ Calculates the set of BEM entities that occur only in the first passed set and d #### Syntax -`subtract(BemCell[], BemCell[]): BemCell[]` +`subtract(BemCell[], BemCell[])` #### Output data @@ -302,7 +302,7 @@ const decl = [ bemDecl.stringify(decl, { format: 'enb' }); -/* 'exports.deps = [\n {\n "block": "button"\n }\n];\n' +// 'exports.deps = [\n {\n "block": "button"\n }\n];\n' ``` ## Contributing @@ -317,7 +317,7 @@ We use [SemVer](http://semver.org/) for versioning. For the versions available, * **Andrew Abramov** - *Initial work* - [blond](https://github.com/blond) -See also the full list of [contributors](https://github.com/bem-sdk/bem-decl/contributors) who participated in this project. +> See also the full list of [contributors](https://github.com/bem-sdk/bem-decl/contributors) who participated in this project. You may also get it with `git log --pretty=format:"%an <%ae>" | sort -u`. From 709e011809c5b57d234793fea088063f5b9abafb Mon Sep 17 00:00:00 2001 From: Sergei Bocharov Date: Sun, 29 Jan 2017 16:26:22 +0300 Subject: [PATCH 3/6] fix License --- README.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 31ce6a2..05a1fc5 100644 --- a/README.md +++ b/README.md @@ -16,9 +16,9 @@ Library with a couple of methods to work with sets of BEM entities (aka BEMDECL [david]: https://david-dm.org/bem-sdk/bem-decl [david-img]: https://img.shields.io/david/bem-sdk/bem-decl.svg -## Prerequisites +## Requirements -* [Node.js](https://nodejs.org/en/) 4.x+ +* [Node.js 4+](https://nodejs.org/en/) ## Installation @@ -323,8 +323,4 @@ You may also get it with `git log --pretty=format:"%an <%ae>" | sort -u`. ## License -Code and documentation are licensed under the Mozilla Public License 2.0 - see the [LICENSE.md](LICENSE.md) file for details. - - +Code and documentation copyright 2017 YANDEX LLC. Code released under the [Mozilla Public License 2.0](LICENSE.md). From 6f91f1829b9fe71cfb0fb81b899cf3b40780dd86 Mon Sep 17 00:00:00 2001 From: Sergei Bocharov Date: Sun, 29 Jan 2017 16:29:41 +0300 Subject: [PATCH 4/6] fix License --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 05a1fc5..4c2fc72 100644 --- a/README.md +++ b/README.md @@ -323,4 +323,4 @@ You may also get it with `git log --pretty=format:"%an <%ae>" | sort -u`. ## License -Code and documentation copyright 2017 YANDEX LLC. Code released under the [Mozilla Public License 2.0](LICENSE.md). +Code and documentation copyright © 2012 — 2017 YANDEX LLC. Code released under the [Mozilla Public License 2.0](LICENSE.md). From 9302b282f0f3f893338ea9b24e7da98ea53b08c0 Mon Sep 17 00:00:00 2001 From: Sergei Bocharov Date: Sun, 29 Jan 2017 16:40:10 +0300 Subject: [PATCH 5/6] fix BEMDECL formats --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 4c2fc72..c65c553 100644 --- a/README.md +++ b/README.md @@ -91,9 +91,9 @@ async function() { There are several formats and `bem-decl` is here to rule them all. -* 'v1' - the old [BEMDECL](https://en.bem.info/methodology/declarations/) format also known as `exports.blocks = ...`. -* 'v2' - format based on [`deps.js`](https://en.bem.info/platform/deps/)-files also known as `exports.deps = ...`. -* 'enb' - legacy format for widely used enb deps reader. +* **'v1'** — the old [BEMDECL](https://en.bem.info/methodology/declarations/) format, also known as `exports.blocks = [ /* ... */ ]`. +* **'v2'** — format based on [`deps.js`](https://en.bem.info/platform/deps/)-files, also known as `exports.deps = [ /* ... */ ]`. +* **'enb'** — legacy format for widely used enb deps reader. ## API From e391b144e0e336a768b6001de1a533e083f2f43e Mon Sep 17 00:00:00 2001 From: Sergei Bocharov Date: Sun, 29 Jan 2017 17:11:45 +0300 Subject: [PATCH 6/6] add example --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c65c553..4879d7a 100644 --- a/README.md +++ b/README.md @@ -118,7 +118,7 @@ Loads BEM entities from a file in any format. | Parameter | Type | Description | |----------|-----|----------| -|**filename**|`string`|`bemdecl.js`-filename.| +|**filename**|`string`|`bemdecl.js`-filename. Example: `example.bemdecl.js`| |**options**|`*`|???| #### Output data