Comparing version 4.1.1 to 4.1.2
@@ -228,3 +228,3 @@ const { hasOwnProperty } = Object.prototype | ||
const unsafe = (val, doUnesc) => { | ||
const unsafe = val => { | ||
val = (val || '').trim() | ||
@@ -231,0 +231,0 @@ if (isQuoted(val)) { |
@@ -5,3 +5,3 @@ { | ||
"description": "An ini encoder/decoder for node", | ||
"version": "4.1.1", | ||
"version": "4.1.2", | ||
"repository": { | ||
@@ -14,3 +14,3 @@ "type": "git", | ||
"eslint": "eslint", | ||
"lint": "eslint \"**/*.js\"", | ||
"lint": "eslint \"**/*.{js,cjs,ts,mjs,jsx,tsx}\"", | ||
"lintfix": "npm run lint -- --fix", | ||
@@ -25,3 +25,3 @@ "test": "tap", | ||
"@npmcli/eslint-config": "^4.0.0", | ||
"@npmcli/template-oss": "4.15.1", | ||
"@npmcli/template-oss": "4.21.3", | ||
"tap": "^16.0.1" | ||
@@ -39,3 +39,3 @@ }, | ||
"//@npmcli/template-oss": "This file is partially managed by @npmcli/template-oss. Edits may be overwritten.", | ||
"version": "4.15.1", | ||
"version": "4.21.3", | ||
"publish": "true" | ||
@@ -42,0 +42,0 @@ }, |
223
README.md
@@ -1,58 +0,80 @@ | ||
An ini format parser and serializer for node. | ||
Sections are treated as nested objects. Items before the first | ||
heading are saved on the object directly. | ||
An INI format parser & serializer. | ||
## Note | ||
- Sections are treated as nested objects. | ||
- Section-less items are treated as globals. | ||
## Usage | ||
Consider an ini-file `config.ini` that looks like this: | ||
Consider an INI file such as the following: | ||
```ini | ||
; this comment is being ignored | ||
scope = global | ||
; This comment is being ignored | ||
scope = global | ||
[database] | ||
user = dbuser | ||
password = dbpassword | ||
database = use_this_database | ||
[database] | ||
user = dbuser | ||
password = dbpassword | ||
database = use_this_database | ||
[paths.default] | ||
datadir = /var/lib/data | ||
array[] = first value | ||
array[] = second value | ||
array[] = third value | ||
[paths.default] | ||
datadir = /var/lib/data | ||
array[] = first value | ||
array[] = second value | ||
array[] = third value | ||
``` | ||
You can read, manipulate and write the ini-file like so: | ||
You can **read**, **modify** and **write** it like so: | ||
```js | ||
var fs = require('fs') | ||
, ini = require('ini') | ||
import { writeFile , readFile } from 'node:fs/promises' | ||
import { stringify , parse } from 'ini' | ||
var config = ini.parse(fs.readFileSync('./config.ini', 'utf-8')) | ||
// Read INI file as text | ||
config.scope = 'local' | ||
config.database.database = 'use_another_database' | ||
config.paths.default.tmpdir = '/tmp' | ||
delete config.paths.default.datadir | ||
config.paths.default.array.push('fourth value') | ||
let text = await readFile(`./Original.ini`,{ | ||
encoding : 'utf-8' | ||
}) | ||
fs.writeFileSync('./config_modified.ini', ini.stringify(config, { section: 'section' })) | ||
// Parse text data to object | ||
const config = parse(text) | ||
// Modify data object | ||
config.scope = 'local' | ||
config.database.database = 'use_another_database' | ||
config.paths.default.tmpdir = '/tmp' | ||
delete config.paths.default.datadir | ||
config.paths.default.array.push('fourth value') | ||
// Stringify data object | ||
text = stringify(config,{ | ||
section : 'section' | ||
}) | ||
// Write INI file as text | ||
await writeFile(`./Modified.ini`,text) | ||
``` | ||
This will result in a file called `config_modified.ini` being written | ||
to the filesystem with the following content: | ||
The written file will contain the following: | ||
```ini | ||
[section] | ||
scope=local | ||
[section.database] | ||
user=dbuser | ||
password=dbpassword | ||
database=use_another_database | ||
[section.paths.default] | ||
tmpdir=/tmp | ||
array[]=first value | ||
array[]=second value | ||
array[]=third value | ||
array[]=fourth value | ||
[section] | ||
scope=local | ||
[section.database] | ||
user=dbuser | ||
password=dbpassword | ||
database=use_another_database | ||
[section.paths.default] | ||
tmpdir=/tmp | ||
array[]=first value | ||
array[]=second value | ||
array[]=third value | ||
array[]=fourth value | ||
``` | ||
@@ -62,65 +84,98 @@ | ||
### decode(inistring) | ||
### Parse | ||
Decode the ini-style formatted `inistring` into a nested object. | ||
Attempts to turn the given INI string into a nested data object. | ||
### parse(inistring) | ||
```js | ||
// You can also use `decode` | ||
const object = parse(`<INI Text>`) | ||
``` | ||
Alias for `decode(inistring)` | ||
### Stringify | ||
### encode(object, [options]) | ||
Encodes the given data object as an INI formatted string. | ||
Encode the object `object` into an ini-style formatted string. If the | ||
optional parameter `section` is given, then all top-level properties | ||
of the object are put into this section and the `section`-string is | ||
prepended to all sub-sections, see the usage example above. | ||
```js | ||
// You can also use `encode` | ||
stringify(object,{ | ||
The `options` object may contain the following: | ||
/** | ||
* Whether to insert spaces before & after `=` | ||
* | ||
* Disabled by default to have better | ||
* compatibility with old picky parsers. | ||
*/ | ||
* `align` Boolean to specify whether to align the `=` characters for | ||
each section. This option will automatically enable `whitespace`. | ||
Defaults to `false`. | ||
* `section` String which will be the first `section` in the encoded | ||
ini data. Defaults to none. | ||
* `sort` Boolean to specify if all keys in each section, as well as | ||
all sections, will be alphabetically sorted. Defaults to `false`. | ||
* `whitespace` Boolean to specify whether to put whitespace around the | ||
`=` character. By default, whitespace is omitted, to be friendly to | ||
some persnickety old parsers that don't tolerate it well. But some | ||
find that it's more human-readable and pretty with the whitespace. | ||
Defaults to `false`. | ||
* `newline` Boolean to specify whether to put an additional newline | ||
after a section header. Some INI file parsers (for example the TOSHIBA | ||
FlashAir one) need this to parse the file successfully. By default, | ||
the additional newline is omitted. | ||
* `platform` String to define which platform this INI file is expected | ||
to be used with: when `platform` is `win32`, line terminations are | ||
CR+LF, for other platforms line termination is LF. By default, the | ||
current platform name is used. | ||
* `bracketedArrays` Boolean to specify whether array values are appended | ||
with `[]`. By default this is true but there are some ini parsers | ||
that instead treat duplicate names as arrays. | ||
whitespace : false , | ||
For backwards compatibility reasons, if a `string` options is passed | ||
in, then it is assumed to be the `section` value. | ||
/** | ||
* Whether to align the `=` character for each section. | ||
* -> Also enables the `whitespace` option | ||
*/ | ||
### stringify(object, [options]) | ||
align : false , | ||
Alias for `encode(object, [options])` | ||
/** | ||
* Identifier to use for global items | ||
* and to prepend to all other sections. | ||
*/ | ||
### safe(val) | ||
section , | ||
Escapes the string `val` such that it is safe to be used as a key or | ||
value in an ini-file. Basically escapes quotes. For example | ||
/** | ||
* Whether to sort all sections & their keys alphabetically. | ||
*/ | ||
sort : false , | ||
/** | ||
* Whether to insert a newline after each section header. | ||
* | ||
* The TOSHIBA & FlashAir parser require this format. | ||
*/ | ||
newline : false , | ||
/** | ||
* Which platforms line-endings should be used. | ||
* | ||
* win32 -> CR+LF | ||
* other -> LF | ||
* | ||
* Default is the current platform | ||
*/ | ||
platform , | ||
/** | ||
* Whether to append `[]` to array keys. | ||
* | ||
* Some parsers treat duplicate names by themselves as arrays | ||
*/ | ||
bracketedArray : true | ||
}) | ||
``` | ||
*For backwards compatibility any string passed as the* | ||
*options parameter is treated as the `section` option.* | ||
```js | ||
ini.safe('"unsafe string"') | ||
stringify(object,'section') | ||
``` | ||
would result in | ||
### Un / Escape | ||
"\"unsafe string\"" | ||
Turn the given string into a safe to | ||
use key or value in your INI file. | ||
### unsafe(val) | ||
```js | ||
safe(`"unsafe string"`) // -> \"unsafe string\" | ||
``` | ||
Unescapes the string `val` | ||
Or reverse the process with: | ||
```js | ||
unsafe(`\\"safe string\\"`) // -> "safe string" | ||
``` |
181
12096