Nautilus: Pelagic Mollusc

    @bem/sdk.naming.cell.match

    0.1.3 • Public • Published

    naming.cell.match

    Parser for the file path of a BEM cell object.

    NPM Status

    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.match package, 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:

    1. Install required packages.
    2. Create a match() function.
    3. Create a BEM cell object.
    4. Get a file path.

    Installing required packages

    Install the following packages:

    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:

    1. 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.presets package documentation.
    2. Import the @bem/sdk.naming.cell.match package and create the match() 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;
    // => true

    This 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}

    RunKit live example.

    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.
    • isMatchtrue if the path matches a BEM cell and false if not.
    • rest — some additional text at the end of the path. If the value is not null then the isMatch value will be false.
    /**
     * @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}

    RunKit live example.

    See more examples of creating presets in the @bem/sdk.naming.presets package documentation.

    Install

    npm i @bem/sdk.naming.cell.match

    DownloadsWeekly Downloads

    21

    Version

    0.1.3

    License

    MPL-2.0

    Unpacked Size

    15.5 kB

    Total Files

    4

    Last publish

    Collaborators

    • blond
    • qfox
    • tadatuta
    • veged
    • vithar
    • yeti-or