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.
Usage
Consider an ini-file config.ini
that looks like this:
; this comment is being ignored
scope = global
[database]
user = dbuser
password = dbpassword
database = use_this_database
[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:
var fs = require('fs')
, ini = require('ini')
var config = ini.parse(fs.readFileSync('./config.ini', 'utf-8'))
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')
fs.writeFileSync('./config_modified.ini', ini.stringify(config, { section: 'section' }))
This will result in a file called config_modified.ini
being written
to the filesystem with the following content:
[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
API
decode(inistring)
Decode the ini-style formatted inistring
into a nested object.
parse(inistring)
Alias for decode(inistring)
encode(object, [options])
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.
The options
object may contain the following:
align
Boolean to specify whether to align the=
characters for each section. This option will automatically enablewhitespace
. Defaults tofalse
.section
String which will be the firstsection
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 tofalse
.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 tofalse
.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: whenplatform
iswin32
, 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.
For backwards compatibility reasons, if a string
options is passed
in, then it is assumed to be the section
value.
stringify(object, [options])
Alias for encode(object, [options])
safe(val)
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
ini.safe('"unsafe string"')
would result in
"\"unsafe string\""
unsafe(val)
Unescapes the string val