EditorConfig JavaScript Core

The EditorConfig JavaScript core will provide the same functionality as the EditorConfig C Core and EditorConfig Python Core.

Installation

You need node to use this package.

To install the package locally:

$ npm install editorconfig

To install the package system-wide:

$ npm install -g editorconfig

Usage

Options

Most of the API takes an options object, which has the following defaults:

{
  config: '.editorconfig',
  version: pkg.version,
  root: '/',
  files: undefined,
  cache: undefined,
  unset: false,
};

in Node.js:

parse(filePath[, options])

Search for .editorconfig files starting from the current directory to the root directory. Combine all of the sections whose section names match filePath into a single object.

Example:

const editorconfig = require('editorconfig');
const path = require('path');

const filePath = path.join(__dirname, 'sample.js');

(async () => {
  console.log(await editorconfig.parse(filePath, {files: []}));
})();
/*
  {
    indent_style: 'space',
    indent_size: 2,
    end_of_line: 'lf',
    charset: 'utf-8',
    trim_trailing_whitespace: true,
    insert_final_newline: true,
    tab_width: 2
  };
  assert.deepEqual(files, [
    { fileName: '[DIRECTORY]/.editorconfig', glob: '*' },
    { fileName: '[DIRECTORY]/.editorconfig', glob: '*.js' }
  ])
*/

parseSync(filePath[, options])

Synchronous version of editorconfig.parse().

parseBuffer(fileContent)

The parse() function above uses parseBuffer() under the hood. If you have the contents of a config file, and want to see what is being processed for just that file rather than the full directory hierarchy, this might be useful.

parseString(fileContent)

This is a thin wrapper around parseBuffer() for backward-compatibility. Prefer parseBuffer() to avoid an unnecessary UTF8-to-UTF16-to-UTF8 conversion. Deprecated.

parseFromFiles(filePath, configs[, options])

Low-level interface, which exists only for backward-compatibility. Deprecated.

Example:

const editorconfig = require('editorconfig');
const fs = require('fs');
const path = require('path');

const configPath = path.join(__dirname, '.editorconfig');
const configs = [
  {
    name: configPath,
    contents: fs.readFileSync(configPath, 'utf8')
  }
];

const filePath = path.join(__dirname, '/sample.js');

(async () => {
  console.log(await editorconfig.parseFromFiles(filePath, Promise.resolve(configs)))
})();
/*
  {
    indent_style: 'space',
    indent_size: 2,
    end_of_line: 'lf',
    charset: 'utf-8',
    trim_trailing_whitespace: true,
    insert_final_newline: true,
    tab_width: 2
  };
*/

parseFromFilesSync(filePath, configs[, options])

Synchronous version of editorconfig.parseFromFiles(). Deprecated.

in Command Line

$ ./bin/editorconfig

Usage: editorconfig [options] <FILEPATH...>

Arguments:
  FILEPATH       Files to find configuration for.  Can be a hyphen (-) if you
                 want path(s) to be read from stdin.

Options:
  -v, --version  Display version information from the package
  -f <path>      Specify conf filename other than '.editorconfig'
  -b <version>   Specify version (used by devs to test compatibility)
  --files        Output file names that contributed to the configuration,
                 rather than the configuation itself
  -h, --help     display help for command

Example:

$ ./bin/editorconfig /home/zoidberg/humans/anatomy.md
charset=utf-8
insert_final_newline=true
end_of_line=lf
tab_width=8
trim_trailing_whitespace=sometimes

$ ./bin/editorconfig --files /home/zoidberg/humans/anatomy.md
/home/zoidberg/.editorconfig [*]
/home/zoidberg/.editorconfig [*.md]
/home/zoidberg/humans/.editorconfig [*]

Development

To install dependencies for this package run this in the package directory:

$ npm install

Next, run the following commands:

$ npm run build
$ npm link

The global editorconfig will now point to the files in your development repository instead of a globally-installed version from npm. You can now use editorconfig directly to test your changes.

If you ever update from the central repository and there are errors, it might be because you are missing some dependencies. If that happens, just run npm link again to get the latest dependencies.

To test the command line interface:

$ editorconfig <filepath>

Testing

CMake must be installed to run the tests.

To run the tests:

$ npm test

To run the tests with increased verbosity (for debugging test failures):

$ npm run ci