naming.cell.match
Parser for the file path of a BEM cell object.
Introduction
The tool checks if the specified file path can be a path of a BEM cell. This tool can also be used to parse the file path and create a BEM cell object from it.
You can choose a preset with a naming convention for creating a match() function. See the full list of supported presets in the @bem/sdk.naming.presets package documentation.
All provided presets use the nested file structure. To use the flat structure that is better for small projects, see Using a custom naming convention.
Note. If you don't have any BEM projects available to try out the
@bem/sdk.naming.cell.matchpackage, the quickest way to create one is to use bem-express.
Try match
An example is available in the RunKit editor.
Quick start
Attention. To use
@bem/sdk.naming.cell.match, you must install Node.js 8.0+.
To run the @bem/sdk.naming.cell.match package:
Installing required packages
Install the following packages:
-
@bem/sdk.naming.cell.match, which makes the
match()function. - @bem/sdk.naming.presets, which contains presets with well-known naming conventions.
To install these packages, run the following command:
$ npm install --save @bem/sdk.naming.cell.match @bem/sdk.naming.presets
Creating a match() 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).
See the full list of supported presets in the
@bem/sdk.naming.presetspackage documentation. - Import the
@bem/sdk.naming.cell.matchpackage and create thematch()function using the imported preset:
const originNaming = require('@bem/sdk.naming.presets/origin');
const match = require('@bem/sdk.naming.cell.match')(originNaming);Check a correct file path
Check a file path:
match('my-layer.blocks/my-block/my-block.js').isMatch;
// => trueThis function also converts the path to a BemCell object and returns it.
match('my-layer.blocks/my-block/my-block.js').cell.valueOf();
// => {entity: {block: "my-block"}, tech: "js", layer: "my-layer"}Check an incorrect file path
If the file path is incorrect, the isMatch value will be false but the BemCell object can still be created. This will happen if the file path has some additional text at the end. The extra text will be written in the rest value.
let incorrectPath = 'my-layer.blocks/my-block/my-block.js_some-text';
match(incorrectPath);
// => {cell: BemCell, isMatch: false, rest: "_something"}
match(incorrectPath).cell.valueOf();
// => {entity: {block: "my-block"}, tech: "js", layer: "my-layer"}If the file path hasn't been parsed, the cell and rest values will be null.
incorrectPath = 'some incorrect string';
match(incorrectPath);
// => {cell: null, isMatch: false, rest: null}The file path may look correct, but it does not match the file structure pattern from the used preset:
incorrectPath = 'my-block/my-block.js';
match(incorrectPath);
// => {cell: null, isMatch: false, rest: null}Example:
const originNaming = require('@bem/sdk.naming.presets/origin');
const match = require('@bem/sdk.naming.cell.match')(originNaming);
// Examples with correct paths.
let correctPath = 'my-layer.blocks/my-block/my-block.js';
match(correctPath).isMatch;
// => true
match(correctPath).cell.valueOf();
// => {entity: {block: "my-block"}, tech: "js", layer: "my-layer"}
correctPath = 'common.blocks/my-block/_my-modifier/my-block_my-modifier.css';
match(correctPath).isMatch;
// => true
match(correctPath).cell.valueOf();
// => {entity: { block: "my-block", mod: {name: "my-modifier", val: true}}, tech: "js", layer: "my-layer"}
// Examples with incorrect paths.
let incorrectPath = 'my-layer.blocks/my-block/my-block.js_some-text';
match(incorrectPath);
// => {cell: BemCell, isMatch: false, rest: "_something"}
match(incorrectPath).cell.valueOf();
// => {entity: {block: "my-block"}, tech: "js", layer: "my-layer"}
incorrectPath = 'some incorrect string';
match(incorrectPath);
// => {cell: null, isMatch: false, rest: null}
incorrectPath = 'my-block/my-block.js';
match(incorrectPath);
// => {cell: null, isMatch: false, rest: null}API reference
match()
Tries to convert the specified path to a BEM cell object and return an object that contains the result.
The returned object has the follow properties:
-
cell— converted BEM cell. -
isMatch—trueif the path matches a BEM cell andfalseif not. -
rest— some additional text at the end of the path. If the value is notnullthen theisMatchvalue will befalse.
/**
* @typedef BemCell — Representation of cell.
* @property {BemEntityName} entity — Representation of entity name.
* @property {string} tech — Tech of cell.
* @property {string} [obj.layer] — Layer of cell.
*/
/**
* @param {string} path — Object representation of the BEM cell.
* @returns {cell: ?BemCell, isMatch: boolean, rest: ?string}
*/
match(path);Parameter tuning
Using a custom naming convention
To create a preset with a custom naming convention, use the create() function from the @bem/sdk.naming.presets package.
For example, create a preset that uses the flat scheme to describe the file structure organization.
Use the created preset to make your match() function.
Example:
const options = {
fs: { scheme: 'flat' }
};
const originFlatNaming = require('@bem/sdk.naming.presets/create')(options);
const match = require('@bem/sdk.naming.cell.match')(originFlatNaming);
// Examples with correct paths.
let correctPath = 'my-layer.blocks/my-block.js';
match(correctPath).isMatch;
// => true
match(correctPath).cell.valueOf();
// => {entity: {block: "my-block"}, tech: "js", layer: "my-layer"}
correctPath = 'common.blocks/my-block_my-modifier.css';
match(correctPath).isMatch;
// => true
match(correctPath).cell.valueOf();
// => {entity: { block: "my-block", mod: {name: "my-modifier", val: true}}, tech: "js", layer: "my-layer"}
// Examples with incorrect paths.
let incorrectPath = 'my-layer.blocks/my-block.js_some-text';
match(incorrectPath);
// => {cell: BemCell, isMatch: false, rest: "_something"}
match(incorrectPath).cell.valueOf();
// => {entity: {block: "my-block"}, tech: "js", layer: "my-layer"}
incorrectPath = 'some incorrect string';
match(incorrectPath);
// => {cell: null, isMatch: false, rest: null}
incorrectPath = 'my-block/my-block.js';
match(incorrectPath);
// => {cell: null, isMatch: false, rest: null}See more examples of creating presets in the @bem/sdk.naming.presets package documentation.