Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jednano/ini-parser
A highly forgiving and configurable INI parser for the informal INI file format.
https://github.com/jednano/ini-parser
browser configurable format ini parse parser read write
Last synced: 4 months ago
JSON representation
A highly forgiving and configurable INI parser for the informal INI file format.
- Host: GitHub
- URL: https://github.com/jednano/ini-parser
- Owner: jednano
- License: mit
- Created: 2017-10-23T18:17:55.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2023-01-04T21:58:20.000Z (about 2 years ago)
- Last Synced: 2024-10-18T04:14:11.078Z (4 months ago)
- Topics: browser, configurable, format, ini, parse, parser, read, write
- Language: TypeScript
- Homepage:
- Size: 527 KB
- Stars: 7
- Watchers: 2
- Forks: 3
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# @jedmao/ini-parser
[](https://www.npmjs.com/package/@jedmao/ini-parser)
[](https://www.npmjs.com/package/@jedmao/ini-parser)
[](https://travis-ci.org/jedmao/ini-parser)
[](https://codecov.io/gh/jedmao/ini-parser)
[](https://gemnasium.com/github.com/jedmao/ini-parser)
[](https://nodei.co/npm/@jedmao/ini-parser/)
A highly forgiving and configurable INI parser for the [informal INI file format](https://en.wikipedia.org/wiki/INI_file).
## Introduction
The INI file format is informal. Different parsers behave differently, in that they support different features. This parser aims to be a bit more flexible and [configurable](#options) to suite your needs, whatever they may be. Also, it assumes INI files out there in the wild could have some pretty crazy things in them. This parser does its best to understand whatever crazy you throw at it.
No dependencies on Node.js here, so you should be able to use it in the browser.
## Usage
```ini
; example.ini
a=b
[c]
d:e
[c]
f=g
```
```ts
import { readFileSync } from "fs";
import Parser from "@jedmao/ini-parser";
const { configure, parse } = new Parser(/* config */);
parse(fs.readFileSync("./example.ini"));
```
See [`Parser#parse`](#parserparse-contents-string-) API.
### Result
```json
[
{
"a": "b"
},
[
[
"c",
{
"d": "e"
}
],
[
"c",
{
"f": "g"
}
]
]
]
```
## API
```ts
import Parser from "@jedmao/ini-parser";
```
### `new Parser( options?: ParseOptions )`
Class constructor. Accepts [`ParseOptions`](#interface-parseoptions) for initial configuration.
### `Parser#configure( options?: ParseOptions )`
Sets configuration options, preserving existing configuration and overriding only the new keys you provide.
### `Parser#resetConfiguration()`
Resets configuration to default settings as if you created a `new Parser()`.
### `Parser#parse( contents?: string )`
Parses INI file contents as a string. The result will be an array:
- Index `0` will have any/all root properties.
- Index `1` will have an array of any/all sections that follow.
_Note: repeated sections will also be repeated in the array._
See [`Usage`](#usage) for an example.
### `interface ParseOptions`
```ts
interface ParseOptions {
/**
* Indicates accepted comment chars. Only works if you specify single-char
* comment values in RegExp form. A setting of `false` turns off comments
* completely, treating comment chars as normal string values.
* @default {RegExp} /[#;]/
*/
comment?: RegExp | false;
/**
* Accepts comment chars in a property key or value. If a space
* follows the comment char, it is considered an actual comment.
* Example: "#k;=#v; #z" -> { "#k;": "#v;" }
* @default {false} false
*/
isCommentCharInProp?: boolean;
/**
* Indicates accepted delimiter chars. Only works if you specify
* single-char delimiter values in RegExp form.
* @default {RegExp} /[=:]/
*/
delimiter?: RegExp;
/**
* Indicates accepted newline sequences in the form of a RegExp.
* @default {RegExp} /\r?\n/
*/
newline?: RegExp;
/**
* By default, attempts to parse property values with `JSON.parse`.
* If unsuccessful, returns property value as a string. You may also
* provide your own resolve function here for custom property value
* resolution.
* @default {true} true
*/
resolve?: boolean | ResolveCallback;
}
```
### `interface ResolveCallback`
```ts
interface ResolveCallback {
(value: string, key?: string, fallback?: typeof parseValue): any;
}
```
### `parseValue( value: string )`
Attempts to parse a string value with `JSON.parse`. If unsuccessful, returns input string untouched.
## Testing
Run the following command:
```
$ npm test
```
This will build scripts, run tests and generate a code coverage report. Anything less than 100% coverage will throw an error.
### Watching
For much faster development cycles, run the following commands in 2 separate processes:
```
npm run build:watch
```
Compiles TypeScript source into the `./dist` folder and watches for changes.
```
$ npm run watch
```
Runs the tests in the `./dist` folder and watches for changes.