Skip to content

Latest commit

 

History

History
126 lines (85 loc) · 3.59 KB

README.md

File metadata and controls

126 lines (85 loc) · 3.59 KB
Raw

Build Status

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.

forked from ini by Isaacs Z. Schlueter with added decoding filter support PR's welcome for more filters

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-extra')

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, [filters])

Decode the ini-style formatted inistring into a nested object. Optionally filters may be provided to manipulate the values, the caveat is that a filter will be applied to ALL values, so the onus is on the user to return an unaltered value if no modification should take place.

The filters object may contain the following:

  • function(key, value): value a single callback accepting a key and a value and returning the new value
  • [filters] an array of callbacks in the order in which they should be executed

Predefined Filters

zendBoolean: normalizes Zend Boolean values as true|false

ini.decode(inistring, ini.filters.decode.zendBoolean)

parse(inistring, [filters])

Alias for decode(inistring, [filters])

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:

  • section A string which will be the first section in the encoded ini data. Defaults to none.
  • 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.

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