Cool-ini-parser NPM

TypeScript parser for *.ini files

Yet another parser for INI files. This parser supports multiline values without escaping the new line symbol. Sections and key/values can be indented. Comes with API for content modifications. Currently the following modifications are supported:

Adding keys with/without values
Removing keys
Changing the value of a key

Each modification generates a string which holds the new configuration. Modifications respect the original content's formatting and comments.

Installation

To Install run:

npm install cool-ini-parser

API

Parse API

Parse the configuration.ini file using the function parseIniFromString(...). It will return a Configuration object.

import { parseIniFromString } from 'cool-ini-parser'
import { Configuration } from "cool-ini-parser/dist/types";

const content = "..."; // The ini file content
const config: Configuration = parseIniFromString(content);

Configuration

indentSymbol: string - The last key's indentation symbol (' ' or '\t'). This symbol will be used when new key/values are added and they need to be indented.
content: string - The string content of the configuration.
sections: Section[] - Array of parsed sections

Section

startOffset: number - Index in the Configuration.content string where this section starts. Used internally for modifications.
endOffset: number - Index in the Configuration.content string where this section ends. Used internally for modifications.
name: string - The name of the section
entries: SectionEntry[] - Array of parsed key/values

SectionEntry

key - The name of the key
value - The parsed value, trimmed of whitespaces. Multiline values will be separated by '\n'. Keys without a value will return empty string.
rawValue - The value with all whitespaces and indentations.
keyStartOffset - The start index of the key
valueStartOffset - The start index of the value. If no value is pressent, the index will be -1.
rawValueEndOffset - The index of the last symbol in the rawValue. Usually this will be a new line or the EOF. If no value is pressent, the index will be -1.
delimiterOffset - The index of the key/value delimiter. If no delimiter is pressent, the index will be -1.

Modification API

Adding a key with value

import { parseIniFromString, addConfigurationSectionKey } from 'cool-ini-parser';
import { Configuration } from "cool-ini-parser/dist/types";

const content: string = '...';
const config: Configuration = parseIniFromString(content);

const newContent: string = addConfigurationSectionKey(config, "section", "newKey", "newValue");

addConfigurationSectionKey(config: Configuration, section: string, key: string, value: string): string | undefined - adds a key with value at the end of the section to the configuration. If there are multiple sections with the same name, the key will be added to the first section.
input parameters:
config - The configuration object to modify
section - The name of the section to which the key should be added.
key - The name of the new key
value - The value string. If a multilined value needs to be added, you can concatenate it with just new lines ('\n'). The API will format and indent it as necessary. If you want to add just a key without a value, pass an empty string for value. A key without a delimiter will be added.
return value - A string with the modified content. The original content's comment and indentation is preserved. Returns undefined if any error is detected, like invalid section name.
addConfigurationSectionKeyByIndex(config: Configuration, sectionIdx: number, key: string, value: string): string | undefined - If the configuration file has multiple sections with the same name, this method will let you specify the section's index for better control of where to add the new key.

Removing a key

import { parseIniFromString, removeConfigurationSectionKey } from 'cool-ini-parser'
import { Configuration } from "cool-ini-parser/dist/types";

const content: string = '...';
const config: Configuration = parseIniFromString(content);

const newContent: string = removeConfigurationSectionKey(config, "section", "key");

removeConfigurationSectionKey(config: Configuration, section: string, key: string): string | undefined - removes a key from the section. If there are multiple sections with the same name, the first found section will be selected. Same goes for the key.
input parameters:
config - The configuration object to modify
section - The name of the section from which the key should be removed.
key - The name of the key to remove
return value - A string with the modified content. The original content's comment and indentation is preserved. Returns undefined if any error is detected, like invalid section name.
removeConfigurationSectionKeyByIndex(config: Configuration, sectionIdx: number, keyIdx: number): string | undefined - If the configuration file has multiple sections with the same name and keys this method will let you specify the section and key indexes for better control of where to remove the key.

Modifing the value of a key

import { parseIniFromString, modifyConfigurationSectionKey } from 'cool-ini-parser'
import { Configuration } from "cool-ini-parser/dist/types";

const content: string = '...';
const config: Configuration = parseIniFromString(content);

const newContent: string = modifyConfigurationSectionKey(config, "section", "newKey", "newValue");

modifyConfigurationSectionKey(config: Configuration, section: string, key: string, newValue: string): string | undefined - modifies the value of a key. If there are multiple sections with the same name, the first found section will be selected. Same goes for the key.
input parameters:
config - The configuration object to modify
section - The name of the section in which the key should be modified.
key - The name of the key to modify
value - The new value to set
return value - A string with the modified content. The original content's comment and indentation is preserved. Returns undefined if any error is detected, like invalid section name.
modifyConfigurationSectionKeyByIndex(config: Configuration, sectionIdx: number, keyIdx: number, newValue: string): string | undefined - If the configuration file has multiple sections with the same name and keys this method will let you specify the section and key indexes for better control of where to modify the key.

Basic rules

This parser follows the native Python 3 configparser rules (https://docs.python.org/3/library/configparser.html) which in turn follows the Microsoft Windows INI files structure.

Sections

Section headers are mandatory. If a key is declared before a section, the parser will throw an exception.
Sections must always be on a single line
No non-whitespace charecters are allowed on the same line outside the section's perimeter ('' and ''). Comments are allowed.
✅ section name
✅ section name ; Comment
❌ section name
❌ section name ; Comment
Sections can be indented
✅ |section name
✅ | section name

Keys and Values

A key/value pair is delimited by the symbols ':' and '='
✅ key : value
✅ key = value
Keys can have empty values:
✅ key
✅ key =
A value can spawn multiple lines. For a new line to be considered as a value line, it needs to be more indented than the key it belongs to.

key = value
 value

This will give us a single key key with value value\nvalue

key = value
value

This will give us two keys: key with value value and value with empty value

Key's indentationis not linked to the section's indentation. The following are all valid cases:

[section]
    key = value

    [section]
key = value

The keys in the same section are restricted to the same indentation. Multiple keys in the same section can have different indentation, but only in a decreasing amount.

[section]
        key1 = value1
    key2 = value2
key3 = value3

This example will give us 3 keys with their respective values.

[section]
    key1 = value1
        key2 = value2
key3 = value3

This example however will give us 2 keys:
key1 with value: value1\nkey2 = value2
key3 with value: value3

The key's value can have multiple blank lines. The indentation restriction of the value still applies

key =


    value

This will produce a key with value value

The key's delimiter MUST BE on the same line as the key's definition. The following are invalid examples

❌ Invalid example

    key
        = value

❌ Invalid example

    key
        =
        value

❌ Invalid example

    key
    =
     value

Comments

Comments start with the symbols ';' and/or '#' and end at the end of the line.
Once a comment is started, it always ends at the end of the line.
Comments are single line only. There is't a comment block symbol.

    ; Comment line 1
    ; Comment line 2
    # Comment line 3
    [section] ; Comment line 4
    key = value # Comment line 5
    # Comment ; line 6
    key2 = value
    ; Comment # line 7
    key3 = value

Every symbol after the comment symbol is ignored by the parser.
The TypeScript objects DO NOT hold any comments.
Comments are "invisible" to the parser and can not be retrieved.
The modification API will preserve any comments that are not intertwine in a value. This means that any comment that is on the same line as a value, which is going to change, will be lost. Values that spawn multiple lines and have comments inbetween their lines will also lose their comments.