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

$3

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.

$3


#### 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.

Changelog

#### v1.1.2
- Bugfix: Adding new key would always be inserted into the first section, instead of the target section.

#### v1.1.1
- Update README.md

#### v1.1.0
- Rename method parseInitFromString to parseIniFromString
- Reorganize repository structure
- Move tests next to sources
- Build only with NodeNext flag
- Update documentation

#### v1.0.0
- Initial version