rc-parser
Version:
Find and parse rc, rc.js, rc.yaml or etc if any one of them exists
184 lines (138 loc) • 4.73 kB
Markdown
[](https://travis-ci.org/kaelzhang/rc-parser)
[](https://codecov.io/gh/kaelzhang/rc-parser)
<!-- optional appveyor tst
[](https://ci.appveyor.com/project/kaelzhang/rc-parser)
-->
<!-- optional npm version
[](http://badge.fury.io/js/rc-parser)
-->
<!-- optional npm downloads
[](https://www.npmjs.org/package/rc-parser)
-->
<!-- optional dependency status
[](https://david-dm.org/kaelzhang/rc-parser)
-->
# 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
```sh
$ npm i rc-parser
```
## Usage
```js
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
```js
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>`
```ts
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`
```sh
# 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`
```ts
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.
```ts
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.
```ts
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`
```ts
interface Location {
line: number;
column: number;
}
function CodeFrameFunction (
rawLines: string,
loc: Location
): string
```
```ts
function NotFoundErrorFunction (
paths: Array<string>,
extensions: Extensions
): Error
```
### sync(options): RCResult
- **options** the same as `options` of `parse(options)`
## Built-in parsers
```js
parse.PARSERS.<type>
```
### yaml, yml
Based on [`js-yaml`](https://npmjs.org/package/js-yaml)
### json
Based on [`json5`](https://npmjs.org/package/json5)
## License
MIT