Merge pull request #160 from bem-sdk/yeti-or.presets

Change construct API to suit presets

CHANGELOG.md

@@ -148,6 +148,46 @@ stringify(entityName);
 [#152]: https://github.com/bem-sdk/bem-naming/issues/152
 [#95]: https://github.com/bem-sdk/bem-naming/issues/95
 
+#### The `bem-naming` constructor signature for custom-naming was changed ([#160]).
+
+`{ elem: '…', mod: '…' }` → `{ delims: { elem: '…', mod: '…' } }`
+
+**API v1.x.x**
+
+```js
+const bemNaming = require('bem-naming');
+
+const myNaming = bemNaming({
+    elem: '-',
+    mod: { name: '--', val: '_' }
+    wordPattern: '[a-zA-Z0-9]+'
+});
+
+myNaming.parse('block--mod_val'); // { block: 'block'
+                                  //   modName: 'mod',
+                                  //   modVal: 'val' }
+```
+
+**API v2.x.x**
+
+```js
+const bemNaming = require('@bem/naming');
+
+const myNaming = bemNaming({
+    delims: {
+        elem: '-',
+        mod: { name: '--', val: '_' }
+    },
+    wordPattern: '[a-zA-Z0-9]+'
+});
+
+myNaming.parse('block--mod_val'); // BemEntityName
+                                  // { block: 'block',
+                                  //   mod: { name: 'mod', val: 'val' } }
+```
+
+[#160]: https://github.com/bem-sdk/bem-naming/pull/160/files
+
 ### NPM
 
 Now BEM SDK modules are published in `@bem` scope, so the `bem-naming` module was renamed to [@bem/naming](https://www.npmjs.org/package/@bem/naming) (@blond [#158]).

README.md

@@ -140,41 +140,48 @@ Example:
 const bemNaming = require('@bem/naming');
 
 const myNaming = bemNaming({
-    elem: '-',
-    mod: { name: '--', val: '_' }
+    delims: {
+        elem: '-',
+        mod: { name: '--', val: '_' }
+    },
     wordPattern: '[a-zA-Z0-9]+'   // because element and modifier's separators include
 });                               // hyphen in it, we need to exclude it from block,
                                   // element and modifier's name
 
-myNaming.parse('block--mod_val'); // { block: 'block',
+myNaming.parse('block--mod_val'); // BemEntityName
+                                  // { block: 'block',
                                   //   mod: { name: 'mod', val: 'val' } }
 
-myNaming.stringify({              // 'blockName-elemName--simpleElemMod'
+const BemEntityName = require('@bem/entity-name');
+
+myNaming.stringify(new BemEntityName({
     block: 'blockName',
     elem: 'elemName',
     mod: 'simpleElemMod'
-});
+});                               // 'blockName-elemName--simpleElemMod'
+
 ```
 
 API
 ---
 
-* [bemNaming({ elem, mod, wordPattern })](#bemnaming-elem-mod-wordpattern-)
+* [bemNaming({ delims: {elem, mod}, wordPattern })](#bemnaming-elem-mod-wordpattern-)
 * [parse(str)](#parsestr)
 * [stringify(obj)](#stringifyobj)
 * [elemDelim](#elemdelim)
 * [modDelim](#moddelim)
 * [modValDelim](#modvaldelim)
 
-### bemNaming({ elem, mod, wordPattern })
+### bemNaming({ delims: {elem, mod}, wordPattern })
 
-Parameter     | Type     | Description                                                                       | Default
---------------|----------|-----------------------------------------------------------------------------------|----------------------------------------
-`elem`        | `string` | Separates element's name from block.                                              | `__`
-`mod`         | `string`, `{ name: string, val: string }` | Separates modifier from block or element.        | `_`
-`mod.name`    | `string` | Separates a modifier name from a block or an element.                             | `_`
-`mod.val`     | `string` | Separates the value of a modifier from the modifier name.                         | Default as the value of the `mod.name`.
-`wordPattern` | `string` | Defines which characters can be used in names of blocks, elements, and modifiers. | `[a-z0-9]+(?:-[a-z0-9]+)*`
+Parameter         | Type     | Description                                                                       | Default
+------------------|----------|-----------------------------------------------------------------------------------|----------------------------------------
+`delims`          | `object` | Defines delimeters for elem and/or mods                                           |
+`delims.elem`     | `string` | Separates element's name from block.                                              | `__`
+`delims.mod`      | `string`, `{ name: string, val: string }` | Separates modifier from block or element.        | `_`
+`delims.mod.name` | `string` | Separates a modifier name from a block or an element.                             | `_`
+`delims.mod.val`  | `string` | Separates the value of a modifier from the modifier name.                         | Default as the value of the `mod.name`.
+`wordPattern`     | `string` | Defines which characters can be used in names of blocks, elements, and modifiers. | `[a-z0-9]+(?:-[a-z0-9]+)*`
 
 ### parse(str)
 

index.js

@@ -9,15 +9,22 @@ const BemEntityName = require('@bem/entity-name');
  */
 const cache = {};
 
+/**
+ * Delims of bem entity, elem and/or mod.
+ *
+ * @typedef {Object} Delims
+ * @param {String} [elem='__']      Separates element's name from block.
+ * @param {String|Object} [mod='_'] Separates modifiers from blocks and elements.
+ * @param {String} [mod.name='_']   Separates name of modifier from blocks and elements.
+ * @param {String} [mod.val='_']    Separates value of modifier from name of modifier.
+ */
+
 /**
  * Creates namespace with methods which allows getting information about BEM entity using string as well
  * as forming string representation based on naming object.
  *
  * @param {Object} [options]              Options.
- * @param {String} [options.elem=__]      Separates element's name from block.
- * @param {String|Object} [options.mod=_] Separates modifiers from blocks and elements.
- * @param {String} [options.mod.name=_]   Separates name of modifier from blocks and elements.
- * @param {String} [options.mod.val=_]    Separates value of modifier from name of modifier.
+ * @param {Delims} [options.delims]       Defines delims for bem entity.
  * @param {String} [options.wordPattern]  Defines which symbols can be used for block, element and modifier's names.
  * @return {Object}
  */
@@ -123,7 +130,7 @@ function createNaming(options) {
  * Returns delims and wordPattern.
  *
  * @param {Object} options - user options
- * @returns {{delims: Object, wordPattern: String}}
+ * @returns {{delims: Delims, wordPattern: String}}
  */
 function init(options) {
     if (!options) {
@@ -143,11 +150,12 @@ function init(options) {
     const defaults = presets.origin;
     const defaultDelims = defaults.delims;
     const defaultModDelims = defaultDelims.mod;
-    const mod = options.mod || defaultDelims.mod;
+    const optionsDelims = options.delims || {};
+    const mod = optionsDelims.mod || defaultDelims.mod;
 
     return {
         delims: {
-            elem: options.elem || defaultDelims.elem,
+            elem: optionsDelims.elem || defaultDelims.elem,
             mod: typeof mod === 'string'
                 ? { name: mod, val: mod }
                 : {
@@ -162,7 +170,7 @@ function init(options) {
 /**
  * Builds regex for specified naming.
  *
- * @param {Object} delims      Separates block names, elements and modifiers.
+ * @param {Delims} delims      Separates block names, elements and modifiers.
  * @param {String} wordPattern Defines which symbols can be used for block, element and modifier's names.
  * @returns {RegExp}
  */

test/cache.test.js

@@ -12,14 +12,14 @@ test('should cache instance of original naming', t => {
 
 test('should consider `elem` option for cache', t => {
     const instance1 = naming();
-    const instance2 = naming({ elem: '==' });
+    const instance2 = naming({ delims: { elem: '==' } });
 
     t.not(instance1, instance2);
 });
 
 test('should consider `mod` option for cache', t => {
     const instance1 = naming();
-    const instance2 = naming({ mod: '=' });
+    const instance2 = naming({ delims: { mod: '=' } });
 
     t.not(instance1, instance2);
 });
@@ -32,16 +32,16 @@ test('should consider `wordPattern` option for cache', t => {
 });
 
 test('should cache instance of custom naming', t => {
-    const opts = { elem: '__', mod: '--' };
+    const opts = { delims: { elem: '__', mod: '--' } };
     const instance1 = naming(opts);
     const instance2 = naming(opts);
 
     t.is(instance1, instance2);
 });
 
 test('should cache instance of custom naming', t => {
-    const instance1 = naming({ elem: '__', mod: '_' });
-    const instance2 = naming({ elem: '__', mod: '--' });
+    const instance1 = naming({ delims: { elem: '__', mod: '_' } });
+    const instance2 = naming({ delims: { elem: '__', mod: '--' } });
 
     t.not(instance1, instance2);
 });

test/namespace.test.js

@@ -19,7 +19,7 @@ test('should be a original namespace', t => {
 });
 
 test('should be a custom namespace', t => {
-    const myNaming = bemNaming({ elem: '==' });
+    const myNaming = bemNaming({ delims: { elem: '==' } });
     const entities = ['block==elem'].map(myNaming.parse);
     const entity = entities[0];
 

test/options.test.js

@@ -13,27 +13,27 @@ test('should throw error if specified preset is unknow', t => {
 });
 
 test('should provide elem option', t => {
-    const myNaming = naming({ elem: '==' });
+    const myNaming = naming({ delims: { elem: '==' } });
 
     t.is(myNaming.elemDelim, '==');
 });
 
 test('should support mod option as string', t => {
-    const myNaming = naming({ mod: '--' });
+    const myNaming = naming({ delims: { mod: '--' } });
 
     t.is(myNaming.modDelim, '--');
     t.is(myNaming.modValDelim, '--');
 });
 
 test('should support mod option as object', t => {
-    const myNaming = naming({ mod: { name: '--', val: '_' } });
+    const myNaming = naming({ delims: { mod: { name: '--', val: '_' } } });
 
     t.is(myNaming.modDelim, '--');
     t.is(myNaming.modValDelim, '_');
 });
 
 test('should use modDelim if mod.val is not specified', t => {
-    const myNaming = naming({ mod: { name: '--' } });
+    const myNaming = naming({ delims: { mod: { name: '--' } } });
 
     t.is(myNaming.modDelim, '--');
     t.is(myNaming.modValDelim, '--');