Elektra  0.8.26
Plugin: ini

This plugin allows Elektra's users to read and write INI files. INI files consist of simple key value pairs of the form key = value. Additionally keys can be categorized into different sections. Sections must be enclosed in "[]", for example "[section]". Each section is converted into a directory key (without value) and keys below the section are located below the section key. If the same section appears multiple times, the keys of all sections with the same name are merged together under the section key.

The plugin is feature rich and customizable (+1000 in status)

Usage

If you want to add an ini file to the global key database, simply use mount:

1 sudo kdb mount file.ini user/tests/ini ini

Then you can modify the contents of the ini file using set:

1 kdb set user/tests/ini/key value
2 #> Create a new key user/tests/ini/key with string "value"
3 kdb set user/tests/ini/section
4 #> Create a new key user/tests/ini/section with null value
5 kdb set user/tests/ini/section/key value
6 #> Create a new key user/tests/ini/section/key with string "value"

Find out which file you modified:

1 kdb file user/tests/ini
2 # STDOUT-REGEX: .+/file.ini
3 
4 # Undo modifications
5 kdb rm -r user/tests/ini
6 sudo kdb umount user/tests/ini

Comments

The ini plugin supports the use of comments. Comment lines start with a ';' or a '#'. Comments are put into the comment metadata of the key following the comment. This can be either a section key or a normal key. When creating new comments (e.g. via kdb setmeta) you can prefix your comment with the comment indicator of your choice (';' or '#') which will be used when writing the comment to the file. If the comment is not prefixed with a comment indicator, the ini plugin will use the character defined by the comment option, or default to '#'.

Multi-Line Support

The ini plugin supports multiline ini values. Continuations of previous values have to start with whitespace characters.

For example consider the following ini file:

1 key1 = value1
2 key2 = value2
3  with continuation
4  lines

This would result in a KeySet containing two keys. One key named key1 with the value value1 and another key named key2 with the value value2\nwith continuation\nlines.

By default this feature is enabled. The default continuation character is tab (\t). If you want to use another character, then please specify the configuration option linecont.

Arrays

The ini plugin handles repeating keys by turning them into an elektra array when the array config is set.

For example a ini file looking like:

1 [sec]
2 a = 1
3 a = 2
4 a = 3
5 a = 4

will be interpreted as

1 /sec
2 /sec/a
3 /sec/a/#0
4 /sec/a/#1
5 /sec/a/#2
6 /sec/a/#3

The following example shows how you can store and retrieve array values using the ini plugin.

1 # Mount the INI plugin with array support
2 sudo kdb mount config.ini user/tests/ini ini array=true
3 
4 # Add an array storing song titles
5 kdb set user/tests/ini/songs/#0 "Non-Zero Possibility"
6 kdb set user/tests/ini/songs/#1 "Black Art Number One"
7 kdb set user/tests/ini/songs/#2 "A Story Of Two Convicts"
8 
9 # Check if INI saved all array entries
10 kdb ls user/tests/ini/songs
11 #> user/tests/ini/songs
12 #> user/tests/ini/songs/#0
13 #> user/tests/ini/songs/#1
14 #> user/tests/ini/songs/#2
15 
16 # Retrieve an array item
17 kdb get user/tests/ini/songs/#2
18 #> A Story Of Two Convicts
19 
20 # Check the file written by the INI plugin
21 kdb file user/tests/ini | xargs cat
22 #> songs = Non-Zero Possibility
23 #> songs = Black Art Number One
24 #> songs = A Story Of Two Convicts
25 
26 # Undo modifications
27 kdb rm -r user/tests/ini
28 sudo kdb umount user/tests/ini

Binary Data

By default the INI plugin does not support binary data. You can use the Base64 plugin to remove this limitation.

```

Mount INI and recommended plugin Base64

We add the required plugin base64 (which provides binary) at the end too,

since otherwise this command leaks memory.

sudo kdb mount –with-recommends config.ini user/tests/ini ini base64

Add empty binary value

printf 'nothing = "@BASE64"
' > kdb file user/tests/ini

Copy binary data

kdb cp system/elektra/modules/ini/exports/get user/tests/ini/binary

Add textual data

kdb set user/tests/ini/text 'Na na na na na na na na na na na na na na na na Batman!'

Print empty binary value

kdb get user/tests/ini/nothing #>

Print binary data

kdb get user/tests/ini/binary

STDOUT-REGEX: ^(\x[0-9a-f]{1,2})+$

Print textual data

kdb get user/tests/ini/text #> Na na na na na na na na na na na na na na na na Batman!

kdb rm -r user/tests/ini sudo kdb umount user/tests/ini

1 ## Metadata
2 
3 The INI plugin also supports to store arbitrary metadata in comments after the `@META` declarative.

sudo kdb mount config.ini user/tests/ini ini

Add a new key and some metadata

kdb set user/tests/ini/brand new kdb setmeta user/tests/ini/brand description "The Devil And God Are Raging Inside Me" kdb setmeta user/tests/ini/brand rationale "Because I Love It"

The plugin stores metadata as comments inside the INI file

kdb file user/tests/ini | xargs cat #> # description = The Devil And God Are Raging Inside Me #> # rationale = Because I Love It #> brand = new

Retrieve metadata

kdb lsmeta user/tests/ini/brand | grep -v 'internal'

rationale

description

kdb getmeta user/tests/ini/brand description #> The Devil And God Are Raging Inside Me kdb getmeta user/tests/ini/brand rationale #> Because I Love It

The plugin ignores some metadata such as comment!

kdb setmeta user/tests/ini/brand comment "Where Art Thou?" kdb getmeta user/tests/ini/brand comment

STDERR: Metakey not found

RET: 2

kdb rm -r user/tests/ini sudo kdb umount user/tests/ini ```

Sections

The ini plugin supports 3 different sectioning modes (via section=):

1 sudo kdb mount /empty.ini dir/tests ini
2 kdb set dir/tests/a/b ab
3 kdb get dir/tests/a # <-- key is suddenly here
4 cat empty.ini
5 #> [a]
6 #> b = ab
7 
8 # Undo modifications
9 kdb rm -r dir/tests
10 sudo kdb umount dir/tests

By changing the option section you can suppress the automatic creation of keys. E.g., if you use NULL instead you only get a section if you explicitly create it:

1 sudo kdb mount /empty.ini dir/tests ini section=NULL
2 kdb set dir/tests/a/b ab
3 kdb get dir/tests/a # no key here
4 # RET: 11
5 cat empty.ini
6 #> a/b = ab
7 kdb rm dir/tests/a/b
8 kdb set dir/tests/a # create section first
9 kdb set dir/tests/a/b ab
10 cat empty.ini
11 #> [a]
12 #> b = ab
13 
14 # Undo modifications
15 kdb rm -r dir/tests
16 sudo kdb umount dir/tests

Merge Sections

The ini plugin supports merging duplicated section entries when the mergesections config is set. The keys will be appended to the first occurrence of the section key.

Ordering

The ini plugin preserves the order. Inserted subsections get appended to the corresponding parent section and new sections by name.

Example:

1 sudo kdb mount test.ini /tests/ini ini
2 
3 cat > `kdb file /tests/ini` <<EOF \
4 [Section1]\
5 key1 = val1\
6 [Section3]\
7 key3 = val3\
8 EOF
9 
10 kdb file /tests/ini | xargs cat
11 #> [Section1]
12 #> key1 = val1
13 #> [Section3]
14 #> key3 = val3
15 
16 kdb set /tests/ini/Section1/Subsection1/subkey1 subval1
17 kdb set /tests/ini/Section2/key2 val2
18 kdb file /tests/ini | xargs cat
19 #> [Section1]
20 #> key1 = val1
21 #> [Section1/Subsection1]
22 #> subkey1 = subval1
23 #> [Section2]
24 #> key2 = val2
25 #> [Section3]
26 #> key3 = val3
27 
28 # Undo modifications
29 kdb rm -r /tests/ini
30 sudo kdb umount /tests/ini

Special Characters

The INI plugin also supports values and keys containing delimiter characters (=) properly.

``` sudo kdb mount test.ini user/tests/ini ini

printf '[section1]
' > kdb file user/tests/ini printf 'hello = world
' >> kdb file user/tests/ini

kdb get user/tests/ini/section1/hello #> world

kdb set user/tests/ini/section1/x=x 'a + b = b + a' kdb get user/tests/ini/section1/x=x #> a + b = b + a

Undo modifications

kdb rm -r user/tests/ini sudo kdb umount user/tests/ini ```