vscode-expand-abbreviation v0.5.8

Emmet abbreviation expander

Reference implementation of Emmet’s “Expand Abbreviation” action.

import { expand } from '@emmetio/expand-abbreviation';

console.log(expand('ul.nav>.nav-item{Item $}*2'));
// outputs:
// <ul class="nav">
//   <li class="nav-item">Item 1</li>
//   <li class="nav-item">Item 2</li>
// </ul>

// use XHTML-style output
console.log(expand('img[src=image.png]', {
    profile: {
        selfClosingStyle: 'xhtml'
    }
}));
// outputs: <img src="image.png" alt="" />

// Output in Slim syntax
console.log(expand('ul.nav>.nav-item{Item $}*2', {syntax: 'slim'}));
// outputs:
// ul.nav
//   li.nav-item Item 1
//   li.nav-item Item 2

API

This module exports two functions: parse(abbr, options) and expand(abbr, options).

The parse(abbr, options) function parses abbreviation into tree, applies various transformations required for proper output and returns parsed tree. The expand(abbr, options) does the same but returns formatted string. In most cases you should use expand(abbr, options) only but if you want to update parsed abbreviation somehow, you can parse() abbreviation first, update parsed tree and then expand() it:

import { parse, expand } from '@emmetio/expand-abbreviation';

// 1. Parse string abbreviation into tree
const tree = parse('ul>.item*3');

// 2. Walk on each tree node, update them somehow
tree.walk(node => { ... });

// 3. Output result
console.log(expand(tree));

Options

Both parse() and expand() methods accept the following options:

• syntax (string): abbreviation output syntax. Currently supported syntaxes are: html, slim, pug, haml.
• field(index, placeholder) (function): field/tabstop generator for host editor. Most editors support TextMate-style fields: ${0} or ${1:placeholder}. For TextMate-style fields this function will look like this:

const field = (index, placeholder) => `\${${index}${placeholder ? ':' + placeholder : ''}}`;

Emmet natively supports TextMate fields and provides module for parsing them.

• text (string or array of strings): insert given text string(s) into expanded abbreviation. If array of strings is given, the implicitly repeated element (e.g. li*) will be repeated by the amount of items in array.
• profile (object or Profile): either predefined output profile or options for output profile. Used for by markup formatters to shape-up final output.
• variables (object): custom variables for variable resolver.
• snippets (object, array of objects or SnippetsRegistry): custom predefined snippets for abbreviation. The expanded abbreviation will try to match given snippets that may contain custom elements, predefined attributes etc. May also contain array of items: either snippets (object) or references to default syntax snippets (string; the key in default snippets hash).
• addons (object): hash of additional transformations that should be applied to expanded abbreviation, like BEM or JSX. Since these transformations introduce side-effect, they are disabled by default and should be enabled by providing a transform name as key and transform options as value:

{
    bem: {element: '--'}, // enable transform & override options
    jsx: true // no options, just enable transform
}

• format (object): additional options for output formatter. Currently, HTML element commenting is the only supported format option.

See test folder for usage examples.

Design goals

This module is just an umbrella projects that combines various stand-alone submodules into a unified process for parsing and outputting Emmet abbreviations. Thus, you can create your own “Expand Abbreviation” implementation that can re-use these submodules with additional tweaks and transforms that matches your requirements.

The standard abbreviation expanding workflow:

1. Parse Emmet abbreviation into DOM-like tree.
2. Prepare parsed tree for markup output. This step includes implicit name resolving (.item → div.item), item numbering (.item$*2 → .item1+.item2) and so on.
3. Match tree nodes with predefined snippets. Snippets are basically another Emmet abbreviations that define element shape (name, attributes, self-closing etc.).
4. Resolve variables in parsed tree.
5. Convert parsed abbreviation to formatted string using markup formatters.

Build targets

@emmetio/expand-abbreviation NPM module is available in two flavors: CommonJS and ES6 modules. There’s also a complete, zero-dependency UMD module suitable for browsers (see dist/expand-full.js).