csscomb-core

CSScomb Core

CSScomb Core is a framework for writing postprocessors.
It provides you with a nice set of features:

1. Parser with support of preprocessors
2. API to create and use options
3. API to process files and directories

Usage

var Comb = require('csscomb-core');
// Constructor accepts a list of options to use and list of acceptable syntaxes.
var comb = new Comb(options, 'css');

For a simple example of usage take a look at a template project.
Feel free to fork it and modify.

List of public methods

There are a number of methods that become available once you create an instance.

comb.use(option)

Use a plugin.

• Params: {Object} Option's plugin
• Return: {CombCore} Instance's object

comb.configure(config)

Load configuration from JSON.
Activate and configure needed options.

• Params: {Object} Config
• Return: {CombCore} Instance's object

comb.getOptionsOrder()

Get list of available options in exact order they will be processed.
Can be used for testing purpose.

• Return: {Array} List of options' names

comb.getValue(optionName)

Get option's value.
Can be used inside plugin's process method.

• Params: {String} Option's name
• Return: Value set by user for this option

comb.getSyntax()

Get name of syntax that is currently being used.
Can be used inside plugin's process method.

• Return: {String} Syntax name

comb.lintPath(path)

Lint a file or a directory.

• Params: {String} Path to file or directory
• Return: {Promise}

comb.lintDirectory(path)

Lint all files in a directory.

• Params: {String} Path to file or directory
• Return: {Promise}

comb.lintFile(path)

Lint a single file.

• Params: {String} Path to file
• Return: {Promise}

comb.lintString(string, options)

Lint a string.

• Params:
  {String} Code to process
  {{context: String, filename: String, syntax: String}} Options (optional) where context is Gonzales PE rule, filename is a file's name that is used to display errors and syntax is syntax name with css being a default value.
• Return: {Promise} Resolves with list of found errors.

comb.processPath(path)

Process a file or a directory.

• Params: {String} Path to file or directory
• Return: {Promise}

comb.processDirectory(path)

Process all files in a directory.

• Params: {String} Path to directory
• Return: {Promise}

comb.processFile(path)

Process a single file.

• Params: {String} Path to file
• Return: {Promise}

comb.processString(string, options)

Process a string.

• Params:
  {String} Code to process
  {{context: String, filename: String, syntax: String}} Options (optional) where context is Gonzales PE rule, filename is a file's name that is used to display errors and syntax is syntax name with css being a default value.
• Return: {Promise} Resolves with processed string.

Writing a plugin

A plugin is a JavaScript object that has methods to set value and process AST nodes.
Take a look at Flip Comb for an example.
There are some fields you should take care of.

name

Option's name as it should be used in config.

• Required: yes
• Acceptable value: {String}
• Example: "flip-comments"

syntax

List of syntaxes the option supports.
This depends on parser possibilities.
Currently the following work fine: css, less, sass and scss.

• Required: yes
• Acceptable value: {Array}
• Example: ['css']

accepts

In order to tell CSScomb Core which values are acceptable, plugin should have either accepts or setValue field.
accepts should be used to provide patterns, while setValue is good for modifying value before using it.

You can use one or several of the following:
– boolean: [true]
– boolean: [false]
– boolean: [true, false]
– string: /regexp/
– number: true

• Required: no, but if this field is missed, setValue must be set
• Acceptable value: {Object}
• Example: { boolean: [true] }

setValue

Function to modify option's value before using it.
This field overrides accepts field if it's set in the plugin too.

• Required: no, but if this field is missed, accepts must be set
• Acceptable value: {Function}
• Example: function(value) { return value * 4; }

runBefore

Run the plugin before another option.

• Required: no
• Acceptable value: {String} Another option's name
• Example: "block-indent"

process

Modify AST nodes.

• Required: yes
• Acceptable value: {Function}
• Example:

  function(nodeType, nodeContent) {
  if (nodeType === 'commentML') node[0] = ' (╯°□°）╯︵ ┻━┻ ';
  }