mensch

What is mensch?

The mensch npm package is a CSS parser and stringifier. It allows you to parse CSS into an abstract syntax tree (AST) and then stringify it back into CSS. This can be useful for manipulating CSS programmatically.

What are mensch's main functionalities?

Parsing CSS

This feature allows you to parse a CSS string into an abstract syntax tree (AST). The AST can then be manipulated programmatically.

const mensch = require('mensch');
const css = 'body { color: red; }';
const ast = mensch.parse(css);
console.log(ast);

Stringifying CSS

This feature allows you to convert an abstract syntax tree (AST) back into a CSS string. This is useful after you have made programmatic changes to the AST.

const mensch = require('mensch');
const ast = {
  type: 'stylesheet',
  stylesheet: {
    rules: [
      {
        type: 'rule',
        selectors: ['body'],
        declarations: [
          {
            type: 'declaration',
            property: 'color',
            value: 'red'
          }
        ]
      }
    ]
  }
};
const css = mensch.stringify(ast);
console.log(css);

Other packages similar to mensch

postcss

PostCSS is a tool for transforming CSS with JavaScript plugins. It provides a more extensive ecosystem and is more powerful than mensch, allowing for a wide range of CSS manipulations and optimizations.

css

The css package is another CSS parser/stringifier. It provides similar functionality to mensch but with a different API. It is also widely used and well-documented.

csstree

CSSTree is a toolset for CSS including a fast detailed parser, walker, generator, lexer, and validator. It offers more detailed parsing and validation capabilities compared to mensch.

README

mensch

A decent CSS parser.

usage

npm install mensch

var mensch = require('mensch');

var ast = mensch.parse('p { color: black; }');
var css = mensch.stringify(ast);

console.log(css);
// => p { color: black; }

api

parse(css, [options={}])

Convert a CSS string or an array of lexical tokens into a stringify-able AST.

• css {String|Array} CSS string or array of lexical tokens
• [options] {Object}
• [options.comments=false] {Boolean} Allow comment nodes in the AST.
• [options.position=false] {Boolean} Allow line/column position in the AST.

When {position: true}, AST node will have a position property:

{
  type: 'comment',
  text: ' Hello World! ',
  position: {
    start: { line: 1, col: 1 },
    end: { line 1, col: 18 }
  }
}

stringify(ast, [options={}])

Convert a stringify-able AST into a CSS string.

• ast {Object} A stringify-able AST
• [options] {Object}
• [options.comments=false] {Boolean} Allow comments in the stringified CSS.
• [options.indentation=''] {String} E.g., indentation: ' ' will indent by two spaces.

lex(css)

Convert a CSS string to an array of lexical tokens for use with .parse().

• css {String} CSS

non-validating

Mensch is a non-validating CSS parser. While it can handle the major language constructs just fine, and it can recover from gaffes like mis-matched braces and missing or extraneous semi-colons, mensch can't tell you when it finds invalid CSS like a misspelled property name or a misplaced @import.

comments

Unlike most CSS parsers, mensch allows comments to be represented in the AST and subsequently stringified with the {comments: true} option.

var options = { comments: true };

var ast = mensch.parse('.red { color: red; /* Natch. */ }', options);
var css = mensch.stringify(ast, options);

console.log(css);
//=> .red { color: red; /* Natch. */ }

However, comments within the context of a selector, property, etc., will be ignored. These comments are difficult to represent in the AST.

var ast = mench.parse('.red /*1*/ { color /*2*/: /*3*/ red /*4*/; }', options);
var css = mesch.stringify(ast, options);

console.log(css);
//=> .red { color: red; }

ast

The structure of mensch's AST riffs on several existing CSS parsers, but it might not be 100% compatible with other CSS parsers. Here it is in a nutshell:

{
  type: 'stylesheet'
  stylesheet: {
    rules: [{
      type: 'rule',
      selectors: ['.foo'],
      declarations: [{
        type: 'property',
        name: 'color',
        value: 'black'
      }]
    }]
  }
}

credits

Mensch is based on several existing CSS parsers, but nzakas/parser-lib and visionmedia/css are notable influences.

known users

voidlabs/mosaico uses Mensch parser to parse custom-flavored CSS rules in email templates and make the template editable: positions, comment parsing, multiple declarations for the same property have been keys to the choice of Mensch!

Automattic/juice moved to Mensch CSS parser since 3.0 release in order to fix dozen of issues with the previous parser, expecially with support for "multiple properties declarations" in the same ruleset and with invalid values.

Please let us know if you use Mensch in your library!