@bem/sdk.naming.entity.parse

parse

Parser for a BEM entity string representation.

• Introduction
• Try parse
• Quick start
• API reference
• Parameter tuning
  • Using Two Dashes style
  • Using React style
  • Using a custom naming convention
• Usage examples
  • Parsing filenames

Introduction

The tool parses a BEM entity string representation and creates an object representation from it.

You can choose which naming convention to use for creating a parse() function.

Note. If you don't have any BEM projects available to try out the @bem/sdk.naming.entity.parse package, the quickest way to create one is to use bem-express.

Try parse

An example is available in the RunKit editor.

Quick start

Attention. To use @bem/sdk.naming.entity.parse, you must install Node.js 8.0+.

To run the @bem/sdk.naming.entity.parse package:

• Install required packages.
• Create a parse() function.
• Parse a string.

Installing required packages

Install the following packages:

• @bem/sdk.naming.entity.parse, which contains the parse() function.
• @bem/sdk.naming.presets, which contains presets with well-known naming conventions.

To install the packages, run the following command:

$ npm install --save @bem/sdk.naming.entity.parse @bem/sdk.naming.presets

Creating a parse() function

Create a JavaScript file with any name (for example, app.js) and do the following:

• Choose the naming convention and import the preset with this convention (for example, origin naming convention).

  For examples with other naming conventions, see the Parameter tuning section.

• Import the @bem/sdk.naming.entity.parse package and create the parse() function using the imported preset:

const originNaming = require('@bem/sdk.naming.presets/origin');
const parse = require('@bem/sdk.naming.entity.parse')(originNaming);

Parsing a string

Parse a string representation of a BEM entity:

parse('button__run');

This function will return the BemEnityName object with the block name button and the element name run.

Example:

const originNaming = require('@bem/sdk.naming.presets/origin');
const parse = require('@bem/sdk.naming.entity.parse')(originNaming);

// Parse a block name.
parse('my-block');

// Parse an element name.
parse('my-block__my-element');

// Parse a block modifier name.
parse('my-block_my-modifier');

// Parse a block modifier name with a value.
parse('my-block_my-modifier_some-value');

// Parse an element modifier name.
parse('my-block__my-element_my-modifier');

// Parse an element modifier name with a value.
parse('my-block__my-element_my-modifier_some-value');

Also you can normalize a returned BemEnityName object with the valueOf() function:

parse('my-block__my-element_my-modifier_some-value').valueOf();
// => Object { block: "my-block",
//             elem: "my-element",
//             mod: Object {name: "my-modifier", val: "some-value"}}

RunKit live example

API reference

parse()

Parses string into object representation.

/**
 * @typedef BemEntityName
 * @property {string} block — Block name.
 * @property {string} [elem] — Element name.
 * @property {Object} [mod] — Modifier name or object with name and value.
 * @property {string} mod.name — Modifier name.
 * @property {string} [mod.val=true] — modifier value.
 */

/**
 * @param {string} str — String representation of a BEM entity.
 * @returns {(BemEntityName|undefined)}
 */
parse(str);

Parameter tuning

Using Two Dashes style

Parse a string using the Two Dashes style naming convention.

Example:

const twoDashesNaming = require('@bem/sdk.naming.presets/two-dashes');
const parse = require('@bem/sdk.naming.entity.parse')(twoDashesNaming);

// Parse a block name.
parse('my-block');

// Parse an element name.
parse('my-block__my-element');

// Parse a block modifier name.
parse('my-block--my-modifier');

// Parse a block modifier name with a value.
parse('my-block--my-modifier_some-value');

// Parse an element modifier name.
parse('my-block__my-element--my-modifier');

// Parse an element modifier name with a value.
parse('my-block__my-element--my-modifier_some-value');

RunKit live example

Using React style

Parse a string using the React style naming convention.

For creating a parse function there is no difference between the react and origin-react presets. You can use either of them.

Example:

const reactNaming = require('@bem/sdk.naming.presets/react');
const parse = require('@bem/sdk.naming.entity.parse')(reactNaming);

// Parse a block name.
parse('myBlock');

// Parse an element name.
parse('myBlock-myElement');

// Parse a block modifier name.
parse('myBlock_myModifier');

// Parse a block modifier name with a value.
parse('myBlock_myModifier_value');

// Parse an element modifier name.
parse('myBlock-myElement_myModifier');

// Parse an element modifier name with a value.
parse('myBlock-myElement_myModifier_value');

RunKit live example

Using a custom naming convention

Specify an INamingConvention object with the following fields:

• delims — the delimiters that are used to separate names in the naming convention.
• wordPattern — a regular expression that will be used to match an entity name.

Use this object to make your parse() function.

Example:

const convention = {
    wordPattern: '\\w+?',
    delims: {
        elem: '_EL-',
        mod: {
            name: '_MOD-',
            val: '-'
    }}};
const parse = require('@bem/sdk.naming.entity.parse')(convention);

// Parse an element modifier name.
console.log(parse('myBlock_EL-myElement_MOD-myModifier'));
/**
 * => BemEntityName {
 * block: 'myBlock',
 * elem: 'myElement',
 * mod: { name: 'myModifier', val: true } }
 */

RunKit live example

Usage examples

Parsing filenames

If you have the input_type_search.css file, you can parse the filename and get the BemEnityName object that represents this file. You can parse all files in your project this way.

The parse() function uses in the walk package to parse filenames in the BEM project. You can find more examples in the walkers' code for following the file structure organization: Flat and Nested.