Kévin Tessier 04fab6ba46 install gulp 6 years ago
..
lib 04fab6ba46 install gulp 6 years ago
node_modules 04fab6ba46 install gulp 6 years ago
test 04fab6ba46 install gulp 6 years ago
.npmignore 04fab6ba46 install gulp 6 years ago
README.md 04fab6ba46 install gulp 6 years ago
TODO.nani 04fab6ba46 install gulp 6 years ago
coverage.html 04fab6ba46 install gulp 6 years ago
package.json 04fab6ba46 install gulp 6 years ago

README.md

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.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: {String} 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] = ' (╯°□°)╯︵ ┻━┻ ';
      }