This README is also available in Russian.
About
This tool allows getting information about BEM-entity using string as well as forming string representation based on BEM-naming.
String representation
To define BEM-entities we often use a special string format that allows us 100% define what entity exactly is represented.
Originally this string will look like the following:
'block[_blockModName[_blockModVal]][__elemName[_elemModName[_elemModVal]]]'
(In square brackets we have parameters that are optional)
- BLock —
block-name
. - Block's modifier in key-value format —
block-name_mod-name_mod-val
. - Block's boolean modifier —
block-name_mod
. - Block's element —
block-name__elem-name
. - Element's modifier in key-value format —
block-name__elem-name_mod-name_mod-val
. - Element's boolean modifier —
block-name__elem_mod
.
BEM-naming
BEM-entities can be defined with a help of js-object with the following fields:
block
— block's name. The field is required because it is impossible for any BEM-entity to exist.elem
— element's name.modName
— modifier's name.modVal
— modifier's value.
API
parse(str)
- String
str
— a string that defines BEM-entity.
It parses string str
into BEM-naming.
Example:
var naming = require('bem-naming');
naming.parse('block__elem_mod_val'); // { block: 'block', elem: 'elem',
// modName: 'mod', modVal: 'val' }
stringify(obj)
- String
obj
— hash-object (BEM-naming) that defines BEM-entity.
It forms a string according to BEM-naming obj
.
Example:
var naming = require('bem-naming');
naming.stringify({
block: 'block', elem: 'elem',
modName: 'mod', modVal: 'val'
}); // 'block__elem_mod_val'
Own style
To use your own style to define strings that represent BEM-entities we need to create instance of BEMNaming-class.
Constructor BEMNaming
gets the object from the following options:
- String
modSeparator
— sepatates names and values of modifiers from blocks and elements. Default as_
. - String
elemSeparator
— separates element's name from block. Default as__
. - String
literal
— defines which symbols can be used as block, element and modifier's names. Default as[a-zA-Z0-9-]
.
Example:
var BEMNaming = require('bem-naming').BEMNaming;
var naming = new BEMNaming({
elemSeparator: '-',
modSeparator: '--',
literal: '[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
naming.parse('block--mod'); // { block: 'blockName',
// modName: 'boolMod', modVal: true }
naming.stringify({ // 'blockName-elem--boolElemMod'
block: 'blockName',
elem: 'elemName',
modName: 'boolElemMod'
});