A clean class-based API for parsing, editing, and creating INI files.
npm install ini-api
npm i ini-api
`
Note: As of v2.0.1, this library ships with both ESM and CommonJS builds. Use whichever import style matches your project.
$3
`js
import { Ini, IniSection, IniLine, lineTypes } from 'ini-api';
const myIni = new Ini('; ini text here');
`
$3
`javascript
let { Ini, IniSection, IniLine, lineTypes } = require('ini-api');
let myIni = new Ini('; ini text here');
`
API
Ini
Class for interfacing with Ini files. Contains an array of IniSections in the sections property and a single globals section in the globals property.
$3
Creates a new instance of the Ini class, parsing the text passed.
arguments:
text (optional) the text to parse
returns:
The new Ini.
examples:
`javascript
import { Ini } from 'ini-api';
import fs from 'fs';
import path from 'path';
// creates an empty Ini file
const emptyIni = new Ini();
// creates an ini file with a section named "section"
const newIni = new Ini('[section]\r\na=b\r\n; comment');
// loading an ini file from disk
const text = fs.readFileSync('config.ini');
const configIni = new Ini(text);
`
$3
Gets the first section matching name if present.
arguments:
name the name of the section to get.
returns:
The matching IniSection if present. Returns undefined if a matching section wasn't found.
examples:
`javascript
ini.getSection('section');
`
$3
Adds a new section to the Ini.
arguments:
text the name of the section to add.
returns:
The new IniSection.
examples:
`javascript
ini.addSection('section');
`
$3
Deletes the first section matching name if present.
arguments:
name the name of the section to delete.
returns:
Nothing.
examples:
`javascript
ini.deleteSection('section');
`
$3
Removes all of the Ini's sections and clears the globals section.
returns:
Nothing.
examples:
`javascript
ini.clear();
`
$3
Converts the Ini to a string.
arguments
options (optional) additional options for customization. Object with supported fields:
* blankLineBeforeSection (default: false) Ensures there is a blank line before
* removeBlankLines (default: false) Removes all blank lines (except blank lines added through the blankLineBeforeSection option)
* removeCommentLines (default: false) Removes all comment lines. Comments after key-value pairs/headers are preserved.
$3
Combines two or more Inis into a new Ini. Blank lines are stripped, but comments are preserved. Merges key-value pairs, including arrays (the last version of the array is used).
arguments:
...inis the inis to merge.
returns:
The new merged Ini.
examples:
`javascript
const ini1 = new Ini('[section]\r\na=b\r\n\r\n; comment');
const ini2 = new Ini('[section]\r\n\r\na=c\r\n');
const ini3 = new Ini('; global comment\r\n\r\n[section 2]\r\nhello=world');
const mergedIni = Ini.merge(ini1, ini2, ini3);
console.log(mergedIni.stringify());
/*
; global comment
[section]
a=c
; comment
[section 2]
hello=world
*/
`
IniSection
Class for interfacing with Ini sections. Contains an array of IniLines in the lines property and a name property. Note: the name property will be undefined if the section does not have a valid section header.
$3
Creates a new instance of the IniSection class, treating the text passed as the first line.
arguments:
text (optional) the first line of the IniSection
returns:
The new IniSection.
examples:
`javascript
// creates an empty IniSection with no name or lines
const emptySection = new IniSection('');
// creates a section named "section"
const section = new IniSection('[section]');
`
$3
Adds a new line to the section.
arguments:
text the text of the line to add.
returns:
The new IniLine.
examples:
`javascript
section.addLine('a=b');
`
$3
Adds multiple lines to the section.
arguments:
lines array of strings to add as new lines.
returns:
Array of new IniLines.
examples:
`javascript
section.addLines(['a=b', 'hello=world', 'key=value ; comment', ' ']);
`
$3
Gets the first key-value pair line matching key if present.
arguments:
key the key of the key-value pair line to get.
returns:
The matching IniLine if present. Returns undefined if a matching line wasn't found.
examples:
`javascript
section.getLine('key');
`
$3
Deletes the first key-value pair line matching key if present.
arguments:
key the key of the key-value pair line to delete.
returns:
Nothing.
examples:
`javascript
section.deleteLine('key');
`
$3
Removes all lines from the section except the header line if present.
returns:
Nothing.
examples:
`javascript
section.clear();
`
$3
Gets the value of the first key-value pair line matching key if present.
arguments:
key the key of the key-value pair line to get the value of.
returns:
The value of the IniLine if present. Returns undefined if a matching line wasn't found.
examples:
`javascript
const section = new IniSection('[section]');
section.addLine('a=b');
section.getValue('a'); // returns b
`
$3
Sets the value of the first key-value pair line matching key if present.
arguments:
key the key of the key-value pair line to get the value of.
value the value to set.
returns:
The matching IniLine if present. Returns undefined if a matching line wasn't found.
examples:
`javascript
const section = new IniSection('[section]');
section.addLine('a=b');
section.getValue('a'); // returns b
`
$3
Gets the value of the key-value array corresponding to key if present.
arguments:
key the key of the array to get the value of, excluding the [].
returns:
An array of the values found. Returns an empty array if no matching lines were found.
examples:
`javascript
const section = new IniSection('[section]');
section.addLines(['a[]=1', 'a[]=2', 'a[]=3']);
section.getArray('a'); // returns [1, 2, 3]
`
$3
Clears any existing array at key and creates a new array with values corresponding to the values in array;
arguments:
key the key of the array to set the value of, excluding the [].
array the array of values to apply.
returns:
An array of the created IniLines.
examples:
`javascript
const section = new IniSection('[section]');
section.addLines(['a[]=1', 'a[]=2', 'a[]=3']);
section.setArray('a', [9, 8, 7]);
section.getArray('a'); // returns [9, 8, 7]
`
IniLine
Class for interfacing with Ini lines. Stores the line's type in the lineType property.
$3
Creates a new instance of the IniLine class, treating the text as the line's text.
arguments:
text the line's text
returns:
The new IniLine.
examples:
`javascript
const blankLine = new IniLine('');
const commentLine = new IniLine('; comment');
const headerLine = new IniLine('[header]');
const pairLine = new IniLine('key = value ; comment');
`
$3
Getter/setter for line key. Note: attempting to set the key of a line that does not have a key-value pair will raise an exception.
examples:
`javascript
const line = new IniLine('a=b ; comment')
console.log(line.key); // output: 'a'
line.key = 'new key';
console.log(line.text); // output: new key=b ; comment
`
$3
Getter/setter for line value. Note: attempting to set the value of a line that does not have a key-value pair will raise an exception.
examples:
`javascript
const line = new IniLine('a=b ; comment')
console.log(line.value); // output: 'b'
line.value = 'new value';
console.log(line.text); // output: a=new value ; comment
`
$3
Getter/setter for line comment. Set to an empty string to remove a comment from a line.
examples:
`javascript
const line = new IniLine('a=b ; comment')
console.log(line.comment); // output: 'comment'
line.comment = 'new comment';
console.log(line.text); // output: a=b ; new comment
`
$3
Getter/setter for line text.
examples:
`javascript
const line = new IniLine('a=b ; comment')
console.log(line.text); // output: 'a=b ; comment'
line.text = 'new=text ; here';
``