Easy-INI - a simple way to manipulate INI files content

Table of Contents

• Getting Started
• API
• Good to know
• Use Cases
• Author
• License
• Acknowledgments

Getting Started

why should you use this package?

1. You don't want to manipulate an object and just use stright and forward methods (you can if you insist)
2. You care about preserving comments
3. You want easy formatting and cool logic like merge and replace

basic example

const INI = require('easy-ini')
const myINI = new INI('cool=awesome')
myINI.putStringInSection('; so important','[WOW]')
const giveItBack = myINI.createINIString()

Class Methods:

constructor(,{}) Create ini object

• str,
• optional: defSec = 'DEFAULT_SECTION!',
• optional: eol = require('os').EOL)
• optional: autoTrim = true

// You can start with an empty INI
const myINI = new INI('')

// By default the EOL is the taken from the OS, set it if needed
const myINI = new INI('',{eol: '\r\n'})

// DebSec is needed to represent the first lines that may not be under a section
// By default it's: [DEFAULT_SECTION!] , if for some reason you actually use this name for a section, provide another to avoid unwanted behavior
const myINI = new INI('',{defSec: 'NEXT_LEVEL_DEFAULT_SECTION'})

createINIString({}) Make an ini string from the object, every param is optional and do what it says

• shouldTrim = false,
• shouldFix = false,
• cleanHashComments = false,
• cleanBreakComment = false,
• cleanEmptyLines = false,
• noEmptySections = false,
• noSections = false

// To get true representation use without any parameter
const newINIString = myINI.createINIString()

createSimpleObject() Make an Object including only they types that are specified

• includeTypes = [4] supported types

// by passing [3,4] , will also create a level for sections
const newINIString = myINI.createSimpleObject()

getKeyIfExists() Get line object by referance {type, key, val}

• inputKey

// Changing the returned object will change the original
myINI.getKeyIfExists('cool').val = 'ouch'
// Returnes null if failed to find

findAndChangeKeyIfExists() finds a pair by key and replace value

• inputKey,
• inputValue = ''

// Same as using getKeyIfExists but without returning referance
myINI.findAndChangeKeyIfExists('cool','OUCH')
// Returnes true for success, otherwize false

findAndRemoveKeyIfExists() remove key value pair from object

• inputKey

// Remove a pair (key=value) by matching the key with input string
myINI.findAndRemoveKeyIfExists('cool')
// Returnes true for success, otherwize false

removeEverythingButSections() remove all other sections

• sections = []
• partialMatch = false

// wanting to remove everything else
myINI.removeEverythingButSections(['[GLOBALS]'])
// can also be ussed for partial mataches
myINI.removeEverythingButSections(['GLOB'], true)

findAndRemoveSectionIfExists() remove entire section from object

• sectionName
• partialMatch = false

// Remove an entire section
myINI.findAndRemoveSectionIfExists('[DO_NOT_REMOVE]')
// Returnes true for success, otherwize false

putStringInSection() adds a line to the end of a section

• string,
• sectionName = this.defSecName

// If section does not exist, will create it at the end
myINI.putStringInSection('#comment','[BLAHBLAH]')
// If the input is a key=value pair, and key exists in section , will change its value
// Also true when no section is provided (will use default one)

getLinesByMatch() find all lines containing a string

• token

// Will return an array with with all matches across all sections
myINI.getLinesByMatch('#INCLUDE=')

removeLineByMatch() matches keys, values or comments

• token,
• global = false,
• _done = false (internal use)

// Will return true if at least one line was removed, else false
myINI.removeLineByMatch(';DUAH', true)

findAndReplace() searches for the token and replaces with the value if found

• token,
• value = '',
• global = false,
• _done = false (internal use)

// if global is false will change only the first occurrence
myINI.findAndReplace('<<BASE_DOMAIN>>', 'mashu-mashu-mashu.com', true)
// Will return true if at least one line was removed, else false

solveDuplicates() fixes ini object so and removes duplicate keys leaving first or last occurence

• preferFirstOccurrence = false

// Will remove duplicate keys across the entire ini object
myINI.solveDuplicates()
// Returnes true when finished

solveSelfReferences() use values to replace matching content wrapped by a given prefix and suffix

• prefix
• suffix

/*  super_secret_config.ini:
        something=whatever
        say=ha
        dude=%say%%say%%say% %relax%
        relax=%something%               */

myINI.solveSelfReferences('%', '%')

/*  ==>
        something=whatever
        say=ha
        dude=hahaha whatever
        relax=whatever                  */

mergeWith() merges with another ini object

• anotherINIObject
• before = false

// If before is true will place new values at the beginning of each section
myINI.mergeWith(notMyINI)

Good To Know:

1. the INI class accepets a string input for the constructor ( not a path to an ini file )
2. the default section is a representation for the first lines that are not under any section (could be the whole file)
3. considers text only lines as garbage
4. You can edit myINI.iniData directly
5. line types:
   • 0: empty line
   • 1: hash comment
   • 2: break comment
   • 3: section
   • 4: pair
   • 5: garbage

Use Case Examples:

handling ini dependency

const fs = require('fs')
const INI = require('easy-ini')
const productConfig = new INI(fs.readFileSync('./amazing_app_info.ini',{encoding: 'utf8'}))

let includes
while (includes = productConfig.getLinesByMatch("#INCLUDE")){
    if (includes.length == 0) {break}
    productConfig.removeLineByMatch('#INCLUDE', true)
    for (const include of includes.reverse()) {
        const includePath = include.split('=')[1]
        const tempINI = new INI(fs.readFileSync(includePath, {encoding: 'utf8'}))
        productConfig.mergeWith(tempINI, true)
    }
}
productConfig.solveDuplicates()
const finalConfig = productConfig.createINIString()
fs.writeFileSync("./final.ini", finalConfig)

ini template proccessing

const fs = require('fs')
const INI = require('easy-ini')
const webCon = new INI(fs.readFileSync('./website_config.ini',{encoding: 'utf8'}))
// latest=GGEZ.v69.zip
// download-url=<<SubDomain>>.<<BaseDomain>>/download/%latest%
webCon.findAndReplace('<<BaseDomain>>', 'easy-ini.com', true)
webCon.findAndReplace('<<SubDomain>>', 'download', true)
webCon.findAndReplace('<<Author>>', 'Gal Angel', true)
webCon.solveSelfReferences('%', '%')
const upCon = webCon.createINIString()
fs.writeFileSync("./to_upload.ini", upCon)

Author

• Gal Angel

License

GNU General Public License v3.0

Acknowledgments

• stackOverflow
• coffee
• my cats