kaelzhang / rc-parser

Find and parse rc, rc.js, rc.yaml or etc if any one of them exists

rc-parser

Find and parse rc, rc.js, rc.yaml or etc if any one of them exists. rc-parser searches the giving path(s), and parses out that if the runtime configuration file with the certain extension listed in options.extensions exists. If found, it parses and returns the config object.

rc-parser featured in:

• Supports to define custom parser for a certain file type.
• Better error messages and syntax hint.
• Fully customizable.

Install

$ npm i rc-parser

Usage

const parse = require('rc-parser')
const sync = require('rc-parser/sync')  // The synchronous version

const options = {
  path: __dirname,  // current directory
  name: '.travis'
}

const rc = await parse(options)

console.log(rc.extension)         // 'yml'
console.log(rc.value.language)    // 'node_js'

console.log(sync(options))  // the same as rc

Define your own parsers to support more file types

const ini = require('ini')

parse({
  path: '/path/to',
  name: 'somerc',
  extensions: ['ini', 'js'],
  parsers: {
    ini (content) {
      return ini.parse(content)
    }
  }
})
.then(({extension, value}) => {
  console.log(extension)   // 'ini'
  console.log(value)       // the parsed object from ini
})

APIs

parse(options): Promise<RCResult>

• options
  • path string | Array<string> the search path(s) for the rc file.
  • name string the prefix name of the rc file to search.
  • extensions Extensions | undefined
  • parsers Object{[Extension]: ParserFunction}
  • not_found_error NotFoundErrorFunction will be executed if no rc files are found.
  • code_frame CodeFrameFunction | false

Returns Promise<RCResult>

type Extension = string | parse.NO_EXT
type Extensions = Array<Extension>

options.extensions specifies the extension priority for searching rc files. Defaults to ['yaml', 'yml', 'js', parse.NO_EXT]

parse.NO_EXT is a special extension which indicates there is no extension after name

# Suppose: options.name === '.eslintrc'
#             filepath      |  extension
# ------------------------- | -----------------
/path/to/project
          |-- .eslintrc        # rc-parser.NO_EXT
          |-- .eslintrc.js     # 'js'
          |-- .eslintrc.yaml   # 'yaml'

If options.extensions as ['yaml', 'js', NO_EXT], then we will get .eslintrc.yaml.

Similarly, ['js', 'yaml', NO_EXT] => .eslintrc.js

interface RCResult {
  extension: string;
  abspath: string;
  value: object;
}

• extension the extension string of the found rc file, excluding .
• value the parsed value
• abspath the absolute path of the rc file.

function ParserFunction (object: {
  content: string,
  filepath: string,
  abspath: string,
  extension: string
}): object throws ParserError

• content the content of the rc file
• filepath the filepath relative to the current search path

Parses the content of rc files, returns the parsed object, or throws error if there is a parse error.

interface ParserError extends Error {
  line?: number;
  column?: number;
}

If the error (ParserError) thrown by ParserFunction contains both the line property and the column property, the error.message will be argumented by CodeFrameFunction

interface Location {
  line: number;
  column: number;
}

function CodeFrameFunction (
  rawLines: string,
  loc: Location
): string

function NotFoundErrorFunction (
  paths: Array<string>,
  extensions: Extensions
): Error

sync(options): RCResult

• options the same as options of parse(options)

Built-in parsers

parse.PARSERS.<type>

yaml, yml

Based on js-yaml

json

Based on json5

License

MIT

rc-parser's Issues

readrc name collision

Hi Kael,

I noticed you claimed my npm repo readrc. Is there any chance you'd please consider renaming your project or going with a different npm name?

Although I hadn't published a new version to npm, readrc is an in-progress project with a website https://readrc.club and a conference talk (see Seth Thompson). You can read more about my ambitions for the project here.

Happy to chat more over any medium (Twitter, email, here, etc.).

Thanks for your understanding,
Seth