BPM Library: INI

Read an INI file into memory. Additional functions allow you to get the list of sections and keys, or get individual values.

Installation

Add to you bpm.ini file the following dependency.

[dependencies]
ini=*

Run bpm install to add the library. Finally, use it in your scripts.

#!/usr/bin/env bash
. bpm
bpm::include ini

Quick Example

Assume we have the following INI file, example/test.ini.

[section name]
key1=value1

[Section Name]
key 2 = value 2A

Here is the bulk of a script that would read the file and display information. It's also in the repository as example/test-script.

. bpm
bpm::include ini

# Get a unique prefix for loading the file
ini::prefix prefix

# Get the list of section names.
ini::get sectionNames "$prefix"
set | grep ^sectionNames=
# sectionNames=([0]="" [1]="SECTION NAME")

# Get the keys, note that the section is not case sensitive.
ini::get keys "$prefix" "section name"
set | grep ^keys=
# keys=([0]="KEY1" [1]="KEY 2")

# Get the values and note that keys are not case sensitive.
ini::get key1 "$prefix" "section name" KEY1
set | grep ^key1=
# key1=value1
ini::get key2 "$prefix" "section name" "Key 2"
set | grep ^key2=
# key2='value 2'

You will notice that the keys and sections are dealt in a case-insensitive way.

API

ini::get()

Retrieves a list of sections, list of keys, or a key's value.

• $1 - Target variable.
• $2 - Prefix, required.
• $3 - Section, optional. Required if you want to access a key.
• $4 - Key name, optional

Examples

# Assume the following INI file:
#
# [sectionName]
# keyName = theValue

ini::parse INI "$iniFileContents"
ini::get target INI
set | grep ^target=
# target=([0]="" [1]="sectionName")

ini::get target INI sectionName
set | grep ^target=
# target=([0]="keyName")

ini::get target INI sectionName keyName
# target="theValue"

Returns nothing

ini::keyName()

Encode a prefix, section and key in order to generate a safe variable name for Bash. All section names and key names are case insensitive.

• $1 - Prefix for environment variables, required.
• $2 - Section, optional. Required if you want to access a key.
• $3 - Key name, optional.

ini::parse()

Parses an INI file into the environment.

• $1 - Prefix for environment variables that will be assigned.
• $2 - INI file contents

Variables are stored in memory, encoded in hex to ensure the variable names are valid variables.

PREFIX=(array of unencoded section names)
PREFIX_SECTIONENCODED=(array of unencoded key names)
PREFIX_SECTIONENCODED_KEYENCODED=value

Duplicated section names are merged together. Duplicated keys will have their values changed into an array so all of the values will be captured. For example, the INI on the left will be parsed into variables similar to the right side. Keep in mind that section names and keys are case insensitive.

[Section1] PREFIX=(SECTION1 SECTION2 Key=value kEy=value2 PREFIX_SECTION1=(KEY)

[Section2] PREFIX_SECTION2=(ANOTHER) another=value PREFIX_SECTION1_KEY=(value value2 value3) [SECTION1] KEY=value3 PREFIX_SECTION2_ANOTHER=value

You should not use the generated environment variables directly. Instead, use the other utility functions (eg. ini::get) to access the values.

  $1: Prefix for variables.
  $2: INI file contents

ini::prefix()

Generates a unique INI file prefix that has not yet been used.

• $1 - Destination variable name for the INI prefix.

Returns nothing.

ini::remove()

Removes a key from a section or a section from a loaded INI. Frees up memory by unsetting environment variables. If no section is specified, removes all of the INI from memory.

• $1 - Prefix for environment variables, required.
• $2 - Section name, optional.
• $3 - Key name, optional.

Returns nothing.

ini::set()

Assigns a value to a property

This will set the value if it isn't already assigned. If it is assigned, it will add the value to the array in memory.

• $1 - Prefix for environment variables, required.
• $2 - Section name, required.
• $3 - Key, required.
• $4 - Value, required.

Returns nothing.

ini::toString()

Transfers the in-memory contents of the INI file back into a string.

You will lose all of your comments that were in the INI file. The order of the sections may not be preserved. The order of the keys may not be preserved. Any values that were overwritten in the original INI file shall be eliminated.

Think of it as a cleansing to see what's really parsed instead of losing data.

• $1 - Destination variable name for the string.
• $2 - INI prefix

Returns nothing.