CSS AST iterations

😄💚🌲 Provide a very simple API for complex iterations on the CSS abstract syntax tree (AST).

Table of contents

• How to install
• Basic Example
• CSS AST reference
• Methods list
  • Stylesheet Level - root
    • findAllRules
    • moonWalkAllRules
    • findAllRulesByType
    • findAllRulesBySelectors
    • addRule
    • removeRule
    • findAllSelectors
    • findAllImport
    • findAllDeclarations
    • findAllDeclarationsBySelectors
    • findAllDeclarationsByProperty
    • findAllDeclarationsByValue
  • Rule Level
    • findDeclarations
    • findDeclarationsBySelectors
    • findDeclarationsByProperty
    • findDeclarationsByValue
  • Declarations Level
    • addDeclaration
    • removeDeclaration
    • getParam
• Development
  • Code Style
  • Tests
• Versioning
• Contributing
• History
• License

---

How to install

$ npm install css --save
$ npm install css-ast-iterations --save

Basic Example

const css = require('css');
const addIterations = require('css-ast-iterations');

// Create the AST
const stylesheet = css.parse('.foo {color: #fff;} .bar { width: 50px;}');

// Add all methods for iterations
addIterations(stylesheet);

// Use a findRules method for find and iterates on all Rules
stylesheet.findRules((rule, ruleIndex) => {
  console.log(rule);
});

CSS AST reference

View the CSS AST Explorer.

Methods list

Stylesheet Level - root

Find and iterates on all Rules:

stylesheet.findAllRules((rule, ruleIndex) => {
  console.log(rule);
});

Find and iterates on all Rules (Backwards):

stylesheet.moonWalkAllRules((rule, ruleIndex) => {
  console.log(rule);
});

Find and iterates on all Rules (filter by rule rules):

stylesheet.findAllRulesByType('rule', (rule, ruleIndex) => {
  console.log(rule);
});

Find and iterates on all Rules (filter by import rules):

stylesheet.findAllRulesByType('import', (rule, ruleIndex) => {
  console.log(rule);
});

Find and iterates on all Rules (filter by comment rules):

stylesheet.findAllRulesByType('comment', (rule, ruleIndex) => {
  console.log(rule);
});

Find and iterates on all Rules (filter by selectors):

stylesheet.findAllRulesBySelectors('.foo', (rule, ruleIndex) => {
  console.log(rule);
});

Add a single rule:

stylesheet.addRule(newRule, 0); //Rule position

Remove a single rule:

stylesheet.removeRule(0); //Rule position

Find and iterates on all Selectors:

stylesheet.findAllSelectors((selectors, selectorIndex) => {
  console.log(selectors);
});

Find and iterates on all imports:

stylesheet.findAllImport((url) => {
  console.log(url);
});

Find and iterates on all Declarations:

stylesheet.findAllDeclarations((declaration) => {
    console.log(declaration.property);
    console.log(declaration.value);
});

Find and iterates on all Declarations (filter by selectors):

stylesheet.findAllDeclarationsBySelectors('.foo', (declaration) => {
    console.log(declaration.property);
    console.log(declaration.value);
});

Find and iterates on all Declarations (filter by property):

stylesheet.findAllDeclarationsByProperty('max-width', (declaration) => {
    console.log(declaration.property);
    console.log(declaration.value);
});

Find and iterates on all Declarations (filter by value):

stylesheet.findAllDeclarationsByValue('500px', (declaration) => {
    console.log(declaration.property);
    console.log(declaration.value);
});

Rule Level

Find and iterates on Declarations:

// Stylesheet Level (root)
stylesheet.findAllRulesByType('rule', (rule, ruleIndex) => {

  // Rule Level
  rule.findDeclarations((declaration, declarationIndex) => {
    console.log(declaration);
  });

});

Find and iterates on Declarations (filter by selectors):

// Stylesheet Level (root)
stylesheet.findAllRulesByType('rule', (rule, ruleIndex) => {

  // Rule Level
  rule.findDeclarationsBySelectors('.foo', (declaration, declarationIndex) => {
    console.log(declaration);
  });

});

Find and iterates on Declarations (filter by property):

// Stylesheet Level (root)
stylesheet.findAllRulesByType('rule', (rule, ruleIndex) => {

  // Rule Level
  rule.findDeclarationsByProperty('max-width', (declaration, declarationIndex) => {
    console.log(declaration);
  });

});

Find and iterates on Declarations (filter by value):

// Stylesheet Level (root)
stylesheet.findAllRulesByType('rule', (rule, ruleIndex) => {

  // Rule Level
  rule.findDeclarationsByValue('500px', (declaration, declarationIndex) => {
    console.log(declaration);
  });

});

Declarations Level

Add a new declaration:

// Stylesheet Level (root)
stylesheet.findAllRulesByType('rule', (rule, ruleIndex) => {

  // Rule Level
  rule.findDeclarationsByProperty('max-width', (declaration, declarationIndex) => {

    // Declarations Level
    rule.addDeclaration('width', '50px', declarationIndex);

  });

});

Remove a declaration:

// Stylesheet Level (root)
stylesheet.findAllRulesByType('rule', (rule, ruleIndex) => {

  // Rule Level
  rule.findDeclarationsByProperty('max-width', (declaration, declarationIndex) => {

    // Declarations Level
    rule.removeDeclaration(declarationIndex);

  });

});

Get a specific param from a value:

// Stylesheet Level (root)
stylesheet.findAllRulesByType('rule', (rule, ruleIndex) => {

  // Rule Level
  rule.findDeclarationsByProperty('max-width', (declaration, declarationIndex) => {

    // Declarations Level
    declaration.getParam(0); // position of param

  });

});

---

Development

Code Style

Follow the NodeJS code style guide.

Validate the code style with ESLint:

$ npm run eslint

Tests

Run the unit tests with mocha:

$ npm test

Calculate the coverage with Istanbul:

$ npm run cover

---

Versioning

To keep better organization of releases we follow the Semantic Versioning 2.0.0 guidelines.

Contributing

Find on our issues the next steps of the project ;)
Want to contribute? Follow these recommendations.

History

See Releases for detailed changelog.

License

MIT License © Afonso Pacifer