# Basic ini string functions

Operate on variables instead of files. An easy to use ini parser.

#### License

© Copyright 2009, 2010 Tuncay

This program is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this program. If not, see http://www.gnu.org/licenses/.

See the file COPYING.txt and COPYING.LESSER.txt for license and copying conditions.

Summary

Basic ini string functions | Operate on variables instead of files.
Introduction | Ini files are used mostly as configuration files.
Examples |
Functions |
Parse |
About | Main functions for getting, setting and updating section or key.
Get | Functions for reading data.
ini_getValue | Read and return a value from a key
ini_getKey | Read and return a complete key with key name and content.
ini_getSection | Read and return a complete section with section name.
ini_getAllValues | Read and get a new line separated list of all values in one go.
ini_getAllKeyNames | Read and get a comma separated list of all key names in one go.
ini_getAllSectionNames | Read and get a comma separated list of all section names in one go.
Replace | Functions for replacing existing data.
ini_replaceValue | Updates the value of a key.
ini_replaceKey | Changes complete key with its name and value.
ini_replaceSection | Changes complete section with all its keys and contents.
Insert | Functions for adding new data.
ini_insertValue | Adds value to the end of existing value of specified key.
ini_insertKey | Adds a key pair with its name and value, if key does not already exists.
ini_insertSection | Adds a section and its keys, if section does not exist already.
Additional |
About | Other functions besides the core ones.
File | Related routines about file handling with some comfort.
ini_load | Reads an ini file into a variable and resolves any part of the path.
ini_save | Writes an ini file from variable to disk.
Edit | These manipulates the whole ini structure (or an extracted section only).
ini_repair | Repair and build an ini from scratch.
ini_mergeKeys | Merge two ini sources into first one.
Convert | Export and import functions to convert ini structure.
ini_exportToGlobals | Creates global variables from the ini structure.
Aliases |
About | Function wrappers to work with existing commands or functions via “Basic ini string functions”.
AutoHotkey | Built-in Commands of AutoHotkey.
Ini_Read | Reads a value.
Ini_Write | Writes a value.
Ini_Delete | Deletes a value or section.

### Introduction

Ini files are used mostly as configuration files. In general, they have the “.ini”-extension. It is a simple standardized organization of text data. Many other simple programs use them for storing text.

AutoHotkey provides three commands IniDelete, IniRead and IniWrite. These commands are stable, but they have some disadvantages. First disadvantage is, that they access the file directly. The file on the disk is opened, load into memory and then read or manipulated and then saved with every single command.

With the custom functions I wrote here, the user accessess on variables instead of files. This is super fast, in comparison to disk access. Ini files can be created by Ahk just like any other variable. But Ahk itself does not have any function to operate on ini strings (variables). If you read often from ini file, then this might for you.

No other framework or library is required, no special object files are created; just work on ordinary ini file contents or variables. The load and save functions are added for comfort reason and are not really needed.

- First do this:

>     FileRead, ini, config.ini

- or load default file with:

>     ini_load(ini)

- or create the content yourself:

>     ini =
>     (
>     [Tip]
>     TimeStamp = 20090716194758
>     [Recent File List]
>     File1=F:\testfile.ahk
>     File2=Z:\tempfile.tmp
>     )

In this example “Tip” and “Recent File List” are name of the sections. The file consist in this example of 2 sections. Every section contains variables, so called “keys”. Every key is a part of a section. In this example, the section “Tip” have one key “TimeStamp”. And every key has a content, called value. The “TimeStamp” key have the value “20090716194758”.

After that, you can access and modify the content of the ini variable with the following functions. But the modifications are only temporary and must me saved to disk. This should be done by overwriting the source (not appending).

Notes: A keys content (the value) goes until end of line. Any space surroounding the value is at default lost. For best compatibility, the names of section and key should consist of alpha (a-z), num (0-9) and the underscore only. In general, the names are case insensitiv.

#### Links

- Discussion: [http://www.autohotkey.com/forum/viewtopic.php?t=46226]
- License: [http://www.gnu.org/licenses/lgpl-3.0.html]

#### Date

2010-02-05

#### Revision

0.15.1

#### Status

Stable

#### Developers

- Tuncay, [tunc.nosp@m.ay.d@gmx.nosp@m..de] (Author)
- Mystiq (Tester and Co-Author of an important regex)
- Fry (Tester)

#### License

GNU Lesser General Public License 3.0 or higher [http://www.gnu.org/licenses/lgpl-3.0.html]

#### Category

String Manipulation

#### Type

Library

#### Tested AutoHotkey Version

1.0.48.05

#### Tested Platform

2000/XP

#### Standalone (such as no need for extern file or library)

Yes

#### StdLibConform (such as use of prefix and no globals use)

Yes

#### Related

Format Specifications (not strictly implemented)

- Wikipedia - INI file [http://en.wikipedia.org/wiki/INI_file]
- Cloanto Implementation of INI File Format [http://www.cloanto.com/specs/ini.html]

AutoHotkey Commands

- IniRead: [http://www.autohotkey.com/docs/commands/IniRead.htm]
- IniWrite: [http://www.autohotkey.com/docs/commands/IniWrite.htm]
- IniDelete: [http://www.autohotkey.com/docs/commands/IniDelete.htm]

Other Community Solutions

- INI Library by Titan: [http://www.autohotkey.com/forum/viewtopic.php?t=26141]
- [Class] IniFile by bmcclure: [http://www.autohotkey.com/forum/viewtopic.php?t=41506]
- [module] Ini by majkinetor: [http://www.autohotkey.com/forum/viewtopic.php?t=22495]
- Auto read,load and save by Superfraggle: [http://www.autohotkey.com/forum/viewtopic.php?t=21346]
- globalsFromIni by Tuncay: [http://www.autohotkey.com/forum/viewtopic.php?t=27928]
- Read .INI file in one go by Smurth: [http://www.autohotkey.com/forum/viewtopic.php?t=36601]

### Examples

#### Usage

>     value := ini_getValue(ini, "Section", "Key")                    ; <- Get value of a key.
>     value := ini_getValue(ini, "", "Key")                           ; <- Get value of first found key.
>     key := ini_getKey(ini, "Section", "Key")                        ; <- Get key/value pair.
>     section := ini_getSection(ini, "Section")                       ; <- Get full section with all keys.

>     ini_replaceValue(ini, "Section", "Key", A_Now)                  ; -> Update value of a key.
>     ini_replaceKey(ini, "Section", "Key")                           ; -> Delete a key.
>     ini_replaceSection(ini, "Section", "[Section1]Key1=0`nKey2=1")  ; -> Replace a section with all its keys.

>     ini_insertValue(ini, "Section", "Key" ",ListItem")              ; -> Add a value to existing value.
>     ini_insertKey(ini, "Section", "Key=" . A_Now)                   ; -> Add a key/value pair.
>     ini_insertSection(ini, "Section", "Key1=ini`nKey2=Tuncay")      ; -> Add a section.

>     keys := ini_getAllKeyNames(ini, "Section")                      ; <- Get a list of all key names.
>     sections := ini_getAllSectionNames(ini)                         ; <- Get a list of all section names.

#### Sample Script

Simple script for storing and showing how often it was executed.

>     #NoEnv
>     SendMode Input
>     SetWorkingDir %A_ScriptDir%

>     ; ----- User Configuration -----
>     #Include ini/ini.ahk
>     ConfigFilePath := "settings.ini"

>     ; ----- Main -----
>     IfNotExist, %ConfigFilePath%
>         createConfigFile(ConfigFilePath)

>     FileRead, ini, %ConfigFilePath%
>     value := ini_getValue(ini, "Config", "Started")
>     value++
>     ini_replaceValue(ini, "Config", "Started", value)
>     updateConfigFile(ConfigFilePath, ini)

>     FileRead, ini, %ConfigFilePath%
>     value := ini_getValue(ini, "Config", "Started")
>     MsgBox This script was started %value% time/s.

>     RETURN ; End of AutoExec-section

>     createConfigFile(Path)
>     {
>         Template =
>         (LTrim
>         [Config]
>         Started=0
>         )
>         FileAppend, %Template%, %Path%
>         Return
>     }

>     updateConfigFile(Path, ByRef Content)
>     {
>         FileDelete, %Path%
>         FileAppend, %Content%, %Path%
>         Return
>     }

### Functions

#### Parameters

Content | Content of an ini file (also this can be one section only).
Section | Unique name of the section. Some functions support the default empty string “”. This leads to look up at first found section.
Key | Name of the variable under the section.
Replacement | New content to use.
PreserveSpace | Should be set to 1 if spaces around the value of a key should be saved, otherwise they are lost. The surrounding single or double quotes are also lost.

The ‘get’ functions returns the desired contents without touching the variable.

The ‘replace’ and ‘insert’ functions changes the desired content directly and returns 1 for success and 0 otherwise.

There are some more type of functions and parameters. But these are not listed here.

#### Remarks

On success, ErrorLevel is set to ‘0’. Otherwise ErrorLevel is set to ‘1’ if key under desired section is not found.

The functions are not designed to be used in all situations. On rare conditions, the result could be corrupt or not usable. In example, there is no handling of commas inside the key or section names. Any “\E” would end the literal sequence and switch back to regex. The “\E” sequence is not escaped, because its very uncommon to use backslashes inside key and section names. To workaround this, replace at every key or section name the “\E” part with “\E\\E\Q”:

>     Name := "Folder\Edit\Test1"
>     IfInString, Name, \
>     {
>         StringReplace, Name, Name, \E, \E\\E\Q, All
>     }
>     MsgBox % ini_getValue(ini, "paths", Name)

This allows us to work with regex, but then at the end it should be closed with “\Q” again.

>     ; Used regex at keyname: "Time.*"
>     value := ini_getValue(ini, "Tip", "\ETime.*\Q")

## Parse

Summary

About | Main functions for getting, setting and updating section or key.
Get | Functions for reading data.
ini_getValue | Read and return a value from a key
ini_getKey | Read and return a complete key with key name and content.
ini_getSection | Read and return a complete section with section name.
ini_getAllValues | Read and get a new line separated list of all values in one go.
ini_getAllKeyNames | Read and get a comma separated list of all key names in one go.
ini_getAllSectionNames | Read and get a comma separated list of all section names in one go.
Replace | Functions for replacing existing data.
ini_replaceValue | Updates the value of a key.
ini_replaceKey | Changes complete key with its name and value.
ini_replaceSection | Changes complete section with all its keys and contents.
Insert | Functions for adding new data.
ini_insertValue | Adds value to the end of existing value of specified key.
ini_insertKey | Adds a key pair with its name and value, if key does not already exists.
ini_insertSection | Adds a section and its keys, if section does not exist already.

### About

#### Brief

Main functions for getting, setting and updating section or key.

### Get

Functions for reading data.

### ini_getValue

> ini_getValue( | ByRef | _Content, |  |
> |  | _Section, |  |
> |  | _Key, |  |
> |  | _PreserveSpace | = | False | )

Read and return a value from a key

#### Parameters

Content | Variable Content of an ini file (also this can be one section only).
Section | Unique name of the section. If it is specified to “”, then section is ignored and first found key is get.
Key | Name of the variable under the section.
PreserveSpace | Optional Should be set to 1 if spaces around the value of a key should be saved, otherwise they are lost. The surrounding single or double quotes are also lost. Default is deleting surrounding spaces and quotes.

#### Returns

On success the content of desired key is returned, otherwise an empty string.

#### Examples

>     value := ini_getValue(ini, "Tip", "TimeStamp")
>     MsgBox %value%

Output:

>     20090716194758

### ini_getKey

> ini_getKey( | ByRef | _Content,
> |  | _Section,
> |  | _Key | )

Read and return a complete key with key name and content.

#### Parameters

Content | Variable Content of an ini file (also this can be one section only).
Section | Unique name of the section. If it is specified to “”, then section is ignored and first found key is get.
Key | Name of the variable under the section.

#### Returns

On success the key and value pair in one string is returned, otherwise an empty string.

#### Examples

>     key := ini_getKey(ini, "Tip", "TimeStamp")
>     MsgBox %key%

Output:

>     TimeStamp = 20090716194758

### ini_getSection

> ini_getSection( | ByRef | _Content,
> |  | _Section | )

Read and return a complete section with section name.

#### Parameters

Content | Variable Content of an ini file (also this can be one section only).
Section | Unique name of the section. (An enmpty string “” is not working.)

#### Returns

On success the entire section in one string is returned, otherwise an empty string.

#### Examples

>     section := ini_getSection(ini, "Tip")
>     MsgBox %section%

Output:

>     [Tip]
>     TimeStamp = 20090716194758

### ini_getAllValues

> ini_getAllValues( | ByRef | _Content, |  |
> |  | _Section | = | "",
> | ByRef | _count | = | "" | )

Read and get a new line separated list of all values in one go.

#### Parameters

Content | Variable Content of an ini file (also this can be one section only).
Section | Optional Unique name of the section.
Count | Variable Optional The number of found values/keys.

#### Returns

On success a comma separated list with all name of keys is returned, otherwise an empty string. If section is specified, only those from that section is returned, otherwise from all sections.

#### Remarks

Other than the other getAll-functions list separator, this function uses the new line “`n” character instead the comma “,” for separating values. Also other than the other getValue functions, this does not provide any preserveSpaces option, as it allways preserves surrounding spaces and quotes.

#### Examples

>     values := ini_getAllValues(ini, "Recent File List")
>     MsgBox %values%

Output:

>     F:\testfile.ahk
>     Z:\tempfile.tmp

### ini_getAllKeyNames

> ini_getAllKeyNames( | ByRef | _Content, |  |
> |  | _Section | = | "",
> | ByRef | _count | = | "" | )

Read and get a comma separated list of all key names in one go.

#### Parameters

Content | Variable Content of an ini file (also this can be one section only).
Section | Optional Unique name of the section.
Count | Variable Optional The number of found keys.

#### Returns

On success a comma separated list with all name of keys is returned, otherwise an empty string. If section is specified, only those from that section is returned, otherwise from all sections.

#### Examples

>     keys := ini_getAllKeyNames(ini, "Recent File List")
>     MsgBox %keys%

Output:

>     File1,File2

### ini_getAllSectionNames

> ini_getAllSectionNames( | ByRef | _Content, |  |
> | ByRef | _count | = | "" | )

Read and get a comma separated list of all section names in one go.

#### Parameters

Content | Variable Content of an ini file (also this can be one section only).
Count | Variable Optional The number of found sections.

#### Returns

On success a comma separated list with all name of sections is returned, otherwise an empty string.

#### Examples

>     sections := ini_getAllSectionNames(ini)
>     MsgBox %sections%

Output:

>     Tip,Recent File List

### Replace

Functions for replacing existing data.

### ini_replaceValue

> ini_replaceValue( | ByRef | _Content, |  |
> |  | _Section, |  |
> |  | _Key, |  |
> |  | _Replacement | = | "",
> |  | _PreserveSpace | = | False | )

Updates the value of a key.

#### Parameters

Content | Variable Content of an ini file (also this can be one section only).
Section | Unique name of the section. If it is specified to “”, then section is ignored and first found key is get.
Key | Name of the variable under the section.
Replacement | Optional New content to use. If not specified, the content will be replaced with no content. That means it is deleted/set to empty string.
PreserveSpace | Optional Should be set to 1 if spaces around the value of a key should be saved, otherwise they are lost. The surrounding single or double quotes are also lost. Default is deleting surrounding spaces.

#### Returns

Returns 1 if key is updated to new value, and 0 otherwise (opposite of ErrorLevel).

#### Examples

>     ini_replaceValue(ini, "Tip", "TimeStamp", 2009)
>     value := ini_getValue(ini, "Tip", "TimeStamp")
>     MsgBox %value%

Output:

>     2009

### ini_replaceKey

> ini_replaceKey( | ByRef | _Content, |  |
> |  | _Section, |  |
> |  | _Key, |  |
> |  | _Replacement | = | "" | )

Changes complete key with its name and value.

#### Parameters

Content | Variable Content of an ini file (also this can be one section only).
Section | Unique name of the section. If it is specified to “”, then section is ignored and first found key is get.
Key | Name of the variable under the section.
Replacement | Optional New content to use. If not specified, the content will be replaced with no content. That means it is deleted/set to empty string. The replacement should contain an equality sign. (Expected form: “keyName=value”)

#### Returns

Returns 1 if key is updated to new value, and 0 otherwise (opposite of ErrorLevel).

#### Examples

>     ini_replaceKey(ini, "Tip", "TimeStamp", "TimeStamp=1980")
>     value := ini_getValue(ini, "Tip", "TimeStamp")
>     MsgBox %value%

Output:

>     1980

### ini_replaceSection

> ini_replaceSection( | ByRef | _Content, |  |
> |  | _Section, |  |
> |  | _Replacement | = | "" | )

Changes complete section with all its keys and contents.

#### Parameters

Content | Variable Content of an ini file (also this can be one section only).
Section | Unique name of the section. If it is specified to “”, then section is ignored and first found key is get.
Replacement | Optional New content to use. If not specified, the content will be replaced with no content. That means it is deleted/set to empty string. The replacement should contain everything what a section contains, like the “[“ and “]” before and after section name and all keys with its equality sign and value. (Expected form: “[sectionName]`nkeyName=value”)

#### Returns

Returns 1 if key is updated to new value, and 0 otherwise (opposite of ErrorLevel).

#### Examples

>     ini_replaceSection(ini, "Tip", "TimeStamp", "[Section1]`nKey1=Hello`nKey2=You!")
>     value := ini_getValue(ini, "Section1", "Key1")
>     MsgBox %value%

Output:

>     Hello

### Insert

Functions for adding new data.

### ini_insertValue

> ini_insertValue( | ByRef | _Content, |  |
> |  | _Section, |  |
> |  | _Key, |  |
> |  | _Value, |  |
> |  | _PreserveSpace | = | False | )

Adds value to the end of existing value of specified key.

#### Parameters

Content | Variable Content of an ini file (also this can be one section only).
Section | Unique name of the section. If it is specified to “”, then section is ignored and first found key is get.
Key | Name of the variable under the section.
Value | Value to be inserted at end of currently existing value.
PreserveSpace | Optional Should be set to 1 if spaces around the value of a key should be saved, otherwise they are lost. The surrounding single or double quotes are also lost. Default is deleting surrounding spaces.

#### Returns

Returns 1 if value is inserted, and 0 otherwise (opposite of ErrorLevel).

#### Examples

>     ini_insertValue(ini, "Recent File List", "File1", ", " . A_ScriptName)
>     value := ini_getValue(ini, "Recent File List", "File1")
>     MsgBox %value%

Output:

>     F:\testfile.ahk, ini.ahk

### ini_insertKey

> ini_insertKey( | ByRef | _Content,
> |  | _Section,
> |  | _Key | )

Adds a key pair with its name and value, if key does not already exists.

#### Parameters

Content | Variable Content of an ini file (also this can be one section only).
Section | Unique name of the section. (An enmpty string “” is not working.)
Key | Key and value pair splitted by an equality sign.

#### Returns

Returns 1 if key is inserted, and 0 otherwise (opposite of ErrorLevel).

#### Remarks

Currently, it works as a workaround with different function calls instead of one regex call. This makes it slower against the other functions.

#### Examples

>     ini_insertKey(ini, "Tip", "TimeNow=" . 20090925195317)
>     value := ini_getValue(ini, "Tip", "TimeNow")
>     MsgBox %value%

Output:

>     20090925195317

### ini_insertSection

> ini_insertSection( | ByRef | _Content, |  |
> |  | _Section, |  |
> |  | _Keys | = | "" | )

Adds a section and its keys, if section does not exist already.

#### Parameters

Content | Variable Content of an ini file (also this can be one section only).
Section | Unique name of the section to be added and checked if it is already existing.
Keys | Optional Set of key value pairs. Every key and value pair should be at its own line divided by a new line character.

#### Returns

Returns 1 if section and the keys are inserted, and 0 otherwise (opposite of ErrorLevel).

#### Examples

>     ini_insertSection(ini, "Tip", "Files", "Name1=Programs`nPath1=C:\Program Files")
>     value := ini_getValue(ini, "Files", "Name1")
>     MsgBox %value%

Output:

>     Programs

## Additional

Summary

About | Other functions besides the core ones.
File | Related routines about file handling with some comfort.
ini_load | Reads an ini file into a variable and resolves any part of the path.
ini_save | Writes an ini file from variable to disk.
Edit | These manipulates the whole ini structure (or an extracted section only).
ini_repair | Repair and build an ini from scratch.
ini_mergeKeys | Merge two ini sources into first one.
Convert | Export and import functions to convert ini structure.
ini_exportToGlobals | Creates global variables from the ini structure.

### About

#### Brief

Other functions besides the core ones.

### File

Related routines about file handling with some comfort.

### ini_load

> ini_load( | ByRef | _Content, |  |
> |  | _Path | = | "",
> |  | _convertNewLine | = | false | )

Reads an ini file into a variable and resolves any part of the path.

#### Parameters

Content | Variable On success, the file is loaded into this variable.
Path | Optional Source filename or -path to look for. It can contain wildcards. If this is an existing directory (or contains backslash at the end), then default filename is appended. Default filename is ScriptName with “.ini” extension (in example “script.ini”). Relative Pathes are solved to current WorkingDir. Every part of the path (like filename and -extension) are optional. Default extension is logically “.ini”. Binary files are not loaded. Empty string is resolved to “ScriptPathNoExt + .ini”.
convertNewLine | Optional If this is true, all “`r`n” (CRLF) new line sequence of files content will be replaced with “`n” (LF) only. Normally this is not necessary.

#### Returns

The resolved full path which was searched for. If file exists, the full path with correct case from the disk is get.

#### Remarks

This function is not necessary to work with the ini-library. In fact, in the heart, it does nothing else than FileRead. The filled variable is an ordinary string. You can work with custom functions other from this library on these variables, as if you would do allways.

If file is not found or content is binary, or at any other reason ErrorLevel is set to 1 and Content is set to “” (empty).

#### Examples

>     ; Load content of default file into variable "ini".
>     path := ini_load(ini)
>     MsgBox %path%

Output:

>     E:\Tuncay\AutoHotkey\scriptname.ini

### ini_save

> ini_save( | ByRef | _Content, |  |
> |  | _Path | = | "",
> |  | _convertNewLine | = | true,
> |  | _overwrite | = | true | )

Writes an ini file from variable to disk.

#### Parameters

Content | Variable Ini content to save at given path on disk.
Path | Optional Source filename or -path to look for. It can contain wildcards. If this is an existing directory (or contains backslash at the end), then default filename is appended. Default filename is ScriptName with “.ini” extension (in example “script.ini”). Relative Pathes are solved to current WorkingDir. Every part of the path (like filename and -extension) are optional. Default extension is logically “.ini”. Binary files are not loaded. Empty string is resolved to “ScriptPathNoExt + .ini”.
convertNewLine | Optional If this is true, all “`n” (LF) new line sequence of files content will be replaced with “`r`n” (CRLF). Normally, Windows default new line sequence is “`r`n”. (Source is not changed with this option.)
overwrite | Optional If this mode is enabled (true at default), the source file will be updated. Otherwise, the file is saved to disk only if source does not exist already.

#### Returns

The resolved full path which was searched for.

#### Remarks

If overwrite mode is enabled and file could not be deleted, then ErrorLevel is set to 1. Otherwise, if overwriting an existing file is not allowed (overwrite = false) and file is existing, then ErrorLevel will be set to 1 also.

#### Examples

>     ; Write and update content of ini variable to default file.
>     path := ini_save(ini)
>     MsgBox %path%

Output:

>     E:\Tuncay\AutoHotkey\scriptname.ini

### Edit

These manipulates the whole ini structure (or an extracted section only).

### ini_repair

> ini_repair( | _Content, |  |
> | _PreserveSpace | = | False,
> | _CommentSymbols | = | ";#",
> | _LineDelim | = | "`n" | )

Repair and build an ini from scratch. Leave out comments and trim unneeded whitespaces.

#### Parameters

Content | Content of an ini file (also this can be one section only).
PreserveSpace | Optional Should be set to 1 if spaces around the value of a key should be saved, otherwise they are lost. Default is deleting surrounding spaces.
CommentSymbols | Optional List of characters which are should be treated as comment symbols. Every single character in list is a symbol. Default are “;” and “#”, in example defined as “;#”.
LineDelim | Optional A sequence of characters which should be the delimiter as the line end symbol. Default is “`n”, a new line.

#### Returns

The new formatted ini string with trimmed whitespaces and without comments.

#### Remarks

Other than the most other functions here, the ini Content variable is not a byref and will not manipulated directly. The return value is the new ini. The LineDelim option can be leaved as is. Internally all commands of AutoHotkey like MsgBox or FileAppend are working correctly with this.

What it does is, building a new ini content string from an existing one. The reason to use this function is, if anyone have problems with the source ini because of whitespaces or comments and formatting. The new resulting ini is consistently reduced to standard ini format (at least, it should). Dublicate key entries in same section are merged into one key. The last instance overwrites just the one before.

#### Examples

>         ini =
>         (

>             [ malformed section  ]
>     city   =  Berlin'
>     whatever='this ; is nasty'

>          [bad]
>     cat    =     'miao'

>         )
>         ini := ini_repair(ini, true)
>         MsgBox %ini%

Output:

>     [malformed section]
>     city=  Berlin'
>     whatever='this
>     [bad]
>     cat=     'miao'

### ini_mergeKeys

> ini_mergeKeys( | ByRef | _Content, |  |
> | ByRef | _source, |  |
> |  | _updateMode | = | 1 | )

Merge two ini sources into first one. Adds new sections and keys and processess existing keys.

#### Parameters

Content | Variable Content of an ini file (also this can be one section only). This is the destination where new sections and keys are added into.
source | Variable This is also an ini content from which to retrieve the new data. These will be added into Content variable.
updateMode | Optional Defines how existing keys should be processed. Default is (‘1’) overwriting last instance with newest one.
updateMode: ‘1’ | (“Default”) Replace existng key with newest/last one from source.
updateMode: ‘2’ | Append everything to existing key in Content.
updateMode: ‘3’ | Replace only if source is higher than destination key in Content.
updateMode: ‘4’ | Exclude keys in Content, which exists in both sources.
updateMode: ‘0’ | (“Or any other value”) Does not manipulate existing keys in Content, leaving them in their orginal state. Just add new unknown keys to Content.

#### Returns

Returns the steps taken to manipulate the destination Content. Every added or manipulated key and section are rising by 1 the return value. 0 if nothing is changed.

#### Remarks

ErrorLevel is set to ‘1’ if something is changed in Content, ‘0’ otherwise.

The Content variable is updated with the content from source. This means, new sections and keys are added allways. In a conflict where same key was found in source again, in case it is existing in Content already, then the variable updateMode defines how they should be processed. Default is, to use last found key.

#### Examples

>     ini1=
>     (LTrim
>         [vasara]
>         tuni=1232
>         edg=94545
>         k=1
>     )
>     ini2=
>     (LTrim
>         [vasara]
>         tuni=9999
>         c=
>         edg=5
>         [taitos]
>         isa=17
>     )
>     ini_mergeKeys(ini1, ini2)
>     MsgBox %ini1%

Output:

>     [vasara]
>     tuni=9999
>     edg=5
>     k1
>     c=
>     [taitos]
>     isa=17

### Convert

Export and import functions to convert ini structure.

### ini_exportToGlobals

> ini_exportToGlobals( | ByRef | _Content, |  |
> |  | _CreateIndexVars | = | false,
> |  | _Prefix | = | "ini",
> |  | _Seperator | = | "_",
> |  | _SectionSpaces | = | "",
> |  | _PreserveSpace | = | False | )

Creates global variables from the ini structure.

#### Parameters

Content | Variable Content of an ini file (also this can be one section only).
CreateIndexVars | Optional If this is set to ‘true’, some additional variables are created. These are variables for indexed access of sections and keys. The scheme how the variables named are described below under Remarks.
Prefix | Optional This is the leading part of all created variable names. (Default: “ini”)
Seperator | Optional This is part of all created variable names. It is added between every section and key part and the leading part to separate them. (Default: “_”)
SectionSpaces | Optional Every space inside section name will be replaced by this character or string. This is needed for creating AutoHotkey variables, which cannot hold spaces at name. Default is to delete any space with empty value: “”.
PreserveSpace | Optional Should be set to 1 if spaces around the value of a key should be saved, otherwise they are lost. Surrounding quotes (“ or ‘) are also lost, if not set to 1. Default is deleting surrounding spaces and quotes.

#### Returns

Gets count of all created keys (attention, keys in sense of ini keys, not variables).

#### Remarks

Creates global variables from ini source. The scheme for building the variables is following:

>     Prefix  +  Seperator  +  SectionName  + Seperator  +  KeyName
>       ini   +      _      +      Tip      +     _      + TimeStamp
>     --------------------------------------------------------------
>     ini_Tip_TimeStamp := "20090716194758"

Standard prefix to every variable is “ini” and all parts are delimited by the separator “_”. The SectionSpaces parameter deletes at default every space from name of section, because spaces inside ahk variable names are not allowed.

#### CreateIndexVars

These variables are created additionally to the other variables, if option CreateIndexVars is set to true (or 1 or any other value evaluating to true).

Scheme for sections

>     Prefix  +  Seperator  +  Index
>       ini   +      _      +    1
>     ------------------------------
>     ini_1 := "Tip"

Scheme for keys

>     Prefix  +  Seperator  +  SectionName  + Index
>       ini   +      _      +      Tip      +   1
>     ---------------------------------------------
>     ini_Tip1 := "20090716194758"

The index “0” contains number of all elements.

#### Examples

>     ini_exportToGlobals(ini, 0)
>     ListVars
>     Msgbox % ini_RecentFileList_File2

Output:

>     Z:\tempfile.tmp

The example would create all these variables with following values:

>     ini_RecentFileList_File1 := "F:\testfile.ahk"
>     ini_RecentFileList_File2 := "Z:\tempfile.tmp"
>     ini_Tip_TimeStamp := "20090716194758"

These variables would be created in addition to the above ones, if CreateIndexVars option was set to true:

>     ini_0 := "2"
>     ini_1 := "Tip"
>     ini_2 := "RecentFileList"
>     ini_RecentFileList0 := "2"
>     ini_RecentFileList1 := "File1"
>     ini_RecentFileList2 := "File2"
>     ini_Tip0 := "1"
>     ini_Tip1 := "TimeStamp"

## Aliases

Summary

About | Function wrappers to work with existing commands or functions via “Basic ini string functions”.
AutoHotkey | Built-in Commands of AutoHotkey.
Ini_Read | Reads a value.
Ini_Write | Writes a value.
Ini_Delete | Deletes a value or section.

### About

#### Brief

Function wrappers to work with existing commands or functions via “Basic ini string functions”. They try to mimic the interface for look and feel of original. This can help to migrate others to this library with lesser possible work.

### AutoHotkey

Built-in Commands of AutoHotkey.

### Ini_Read

> Ini_Read( | ByRef | _OutputVar, |  |
> | ByRef | _Content, |  |
> |  | _Section, |  |
> |  | _Key, |  |
> |  | _Default | = | "ERROR" | )

Reads a value. Alias of IniRead.

#### Parameters

OutputVar | Variable The name of the variable in which to store the retrieved value. If the value cannot be retrieved, the variable is set to the value indicated by the Default parameter (described below).
Content | Variable Content of an ini file (also this can be one section only).
Section | Unique name of the section.
Key | Name of the variable under the section.
Default | Optional The value to store in OutputVar if the requested key is not found. If omitted, it defaults to the word ERROR.

#### Returns

Does not return anything.

#### Remarks

ErrorLevel is not set by this function (backed up and restored).

In Ahk you had to specify the filename of the ini file. Here you need to give the content, instead of. Compared to “Basic ini string functions” the parameter section is not allowed to be set to an empty string anymore.

#### Related

- IniRead: [http://www.autohotkey.com/docs/commands/IniRead.htm]

#### Examples

>     FileRead, ini, C:\Temp\myfile.ini
>     Ini_Read(OutputVar, ini, "section2", "key")
>     MsgBox %OutputVar%

### Ini_Write

> Ini_Write( |  | _Value,
> | ByRef | _Content,
> |  | _Section,
> |  | _Key | )

Writes a value. Alias of IniWrite.

#### Parameters

Value | The string or number that will be written to the right of Key’s equal sign (=).
Content | Variable Content of an ini file .
Section | Unique name of the section.
Key | Name of the variable under the section.

#### Returns

Does not return anything.

#### Remarks

ErrorLevel is set to 1 if there was a problem or 0 otherwise.

In Ahk you had to specify the filename of the ini file. Here you need to give the content, instead of. Compared to “Basic ini string functions” the parameter section is not allowed to be set to an empty string anymore.

#### Related

- IniWrite: [http://www.autohotkey.com/docs/commands/IniWrite.htm]

#### Examples

>     FileRead, ini, C:\Temp\myfile.ini
>     Ini_Write("this is a new value", ini, "section2", "key")
>     FileDelete, C:\Temp\myfile.ini
>     FileAppend, %ini%, C:\Temp\myfile.ini

### Ini_Delete

> Ini_Delete( | ByRef | _Content, |  |
> |  | _Section, |  |
> |  | _Key | = | "" | )

Deletes a value or section. Alias of IniDelete.

#### Parameters

Content | Variable Content of an ini file.
Section | Unique name of the section.
Key | Optional Name of the variable under the section.

#### Returns

Does not return anything.

#### Remarks

ErrorLevel is set to 1 if there was a problem or 0 otherwise.

In Ahk you had to specify the filename of the ini file. Here you need to give the content, instead of. Compared to “Basic ini string functions” the parameter section is not allowed to be set to an empty string anymore.

#### Related

- IniDelete: [http://www.autohotkey.com/docs/commands/IniDelete.htm]

#### Examples

>     FileRead, ini, C:\Temp\myfile.ini
>     Ini_Delete(ini, "section2", "key")
>     FileDelete, C:\Temp\myfile.ini
>     FileAppend, %ini%, C:\Temp\myfile.ini

> ini_getValue( | ByRef | _Content, |  |
> |  | _Section, |  |
> |  | _Key, |  |
> |  | _PreserveSpace | = | False | )

Read and return a value from a key

> ini_getKey( | ByRef | _Content,
> |  | _Section,
> |  | _Key | )

Read and return a complete key with key name and content.

> ini_getSection( | ByRef | _Content,
> |  | _Section | )

Read and return a complete section with section name.

> ini_getAllValues( | ByRef | _Content, |  |
> |  | _Section | = | "",
> | ByRef | _count | = | "" | )

Read and get a new line separated list of all values in one go.

> ini_getAllKeyNames( | ByRef | _Content, |  |
> |  | _Section | = | "",
> | ByRef | _count | = | "" | )

Read and get a comma separated list of all key names in one go.

> ini_getAllSectionNames( | ByRef | _Content, |  |
> | ByRef | _count | = | "" | )

Read and get a comma separated list of all section names in one go.

> ini_replaceValue( | ByRef | _Content, |  |
> |  | _Section, |  |
> |  | _Key, |  |
> |  | _Replacement | = | "",
> |  | _PreserveSpace | = | False | )

Updates the value of a key.

> ini_replaceKey( | ByRef | _Content, |  |
> |  | _Section, |  |
> |  | _Key, |  |
> |  | _Replacement | = | "" | )

Changes complete key with its name and value.

> ini_replaceSection( | ByRef | _Content, |  |
> |  | _Section, |  |
> |  | _Replacement | = | "" | )

Changes complete section with all its keys and contents.

> ini_insertValue( | ByRef | _Content, |  |
> |  | _Section, |  |
> |  | _Key, |  |
> |  | _Value, |  |
> |  | _PreserveSpace | = | False | )

Adds value to the end of existing value of specified key.

> ini_insertKey( | ByRef | _Content,
> |  | _Section,
> |  | _Key | )

Adds a key pair with its name and value, if key does not already exists.

> ini_insertSection( | ByRef | _Content, |  |
> |  | _Section, |  |
> |  | _Keys | = | "" | )

Adds a section and its keys, if section does not exist already.

> ini_load( | ByRef | _Content, |  |
> |  | _Path | = | "",
> |  | _convertNewLine | = | false | )

Reads an ini file into a variable and resolves any part of the path.

> ini_save( | ByRef | _Content, |  |
> |  | _Path | = | "",
> |  | _convertNewLine | = | true,
> |  | _overwrite | = | true | )

Writes an ini file from variable to disk.

> ini_repair( | _Content, |  |
> | _PreserveSpace | = | False,
> | _CommentSymbols | = | ";#",
> | _LineDelim | = | "`n" | )

Repair and build an ini from scratch.

> ini_mergeKeys( | ByRef | _Content, |  |
> | ByRef | _source, |  |
> |  | _updateMode | = | 1 | )

Merge two ini sources into first one.

> ini_exportToGlobals( | ByRef | _Content, |  |
> |  | _CreateIndexVars | = | false,
> |  | _Prefix | = | "ini",
> |  | _Seperator | = | "_",
> |  | _SectionSpaces | = | "",
> |  | _PreserveSpace | = | False | )

Creates global variables from the ini structure.

> Ini_Read( | ByRef | _OutputVar, |  |
> | ByRef | _Content, |  |
> |  | _Section, |  |
> |  | _Key, |  |
> |  | _Default | = | "ERROR" | )

Reads a value.

> Ini_Write( |  | _Value,
> | ByRef | _Content,
> |  | _Section,
> |  | _Key | )

Writes a value.

> Ini_Delete( | ByRef | _Content, |  |
> |  | _Section, |  |
> |  | _Key | = | "" | )

Deletes a value or section.
Close