Class IniFile
VBScript Library: io\IniFile.vbs

Allows manipulation of .ini files both in-memory and to disk. This class works on the file in-memory and supports both section and key comments.

Important: There is no set standard for the format of .ini files. This class will not work with all .ini files. Read the file format section below to avoid headaches and potential data loss.

Reference

Method Detail

Return Type Method and Description
- addSection(byVal section)
Adds a new section to the file.

Parameters:

  • section (String): the name of the new section
- clear()
Clears the contents of the IniFile instance.

Calling this method restores this IniFile instance to it's initial state. The next call to saveFile() will use ASCII mode.

Bool getBooleanValue(byVal section, byVal key, byVal defaultValue)
Returns the value of a key as a boolean.

True is returned if the key has a (case insensitive) value of:

  • 1
  • on
  • t
  • true
  • y
  • yes

If the section or key does not exist the default value is returned.

Parameters:

  • section (String): the section they key is in
  • key (String): the key within the section to lookup
  • defaultValue (Bool): the default value to return if the section/key does not exist

Returns: the value for the key or the default value

Int getIntValue(byVal section, byVal key, byVal defaultValue)
Returns the value of a key as an integer.

If the section or key does not exist the default value is returned.

Parameters:

  • section (String): the section they key is in
  • key (String): the key within the section to lookup
  • defaultValue (Int): the default value to return if the section/key does not exist

Returns: the value for the key or the default value

Bool, String getKeyComment(byVal section, byVal key)
Returns a key comment or False if the key does not have a comment.

Parameters:

  • section (String): the section name the key belongs to
  • key (String): the key who's comment to return

Returns: the comment for the key or False

Int getKeyCount(byVal section)
Returns the number of keys in a section.

If the section does not exist, -1 is returned, > -1 if the section is empty or has keys.

Parameters:

  • section (String): the section to return the key count for

Returns: -1 if the section is empty or the number of keys in the section

Array(String), Bool getKeyNames(byVal section)
Returns a string array of all keys in a section.

If the section does not exist, False is returned otherwise a String array containing all key names is returned.

Parameters:

  • section (String): the section name who's keys to return

Returns: False or a String array of key names

Long getLongValue(byVal section, byVal key, byVal defaultValue)
Returns the value of a key as a Long

If the section or key does not exist the default value is returned.

Parameters:

  • section (String): the section they key is in
  • key (String): the key within the section to lookup
  • defaultValue (Long): the default value to return if the section/key does not exist

Returns: the value for the key or the default value

Bool, String getSectionComment(byVal section)
Returns a section comment or False if the section does not have a comment.

Parameters:

  • section (String): the section who's comment to return

Returns: the comment for the section or False

Int getSectionCount()
Returns the number of sections in this IniFile.

Returns: the number of sections in this IniFile

Array(String) getSectionNames()
Returns a string array of all sections in this IniFile.

Returns: a string array of all sections in this IniFile

String getStringValue(byVal section, byVal key, byVal defaultValue)
Returns the value of a key as a string.

If the section or key does not exist the default value is returned.

Parameters:

  • section (String): the section they key is in
  • key (String): the key within the section to lookup
  • defaultValue (String): the default value to return if the section/key does not exist

Returns: the value for the key or the default value

Bool hasBeenModified()
Returns true if this IniFile has been modified.

Returns: true if this IniFile has been modified since the last call to openFile(), saveFile() or clear()

Bool keyExists(byVal section, byVal key)
Checks whether a key exists within a section.

Parameters:

  • section (String): the section to look for the key in
  • key (String): the key to look for

Returns: True if the key exists, False if neither the key or section exist

Int openFile(byVal filePath)
Loads a .ini file from disk in ASCII mode (default).

If you need to open a Unicode file, use openFileUnicode() but read up on using Unicode with openTextFile().

Parameters:

  • filePath (String): the absolute or relative path to the file to open

Returns: 0 if the file was successfully loaded or an error code >0

Int openFileUnicode(byVal filePath)
Loads a .ini file from disk in Unicode mode.

When a file is opened in Unicode mode, any subsequent calls to saveFile() will write the file in Unicode mode until either clear() or openFile() are called.

Parameters:

  • filePath (String): the absolute or relative path to the file to open

Returns: 0 if the file was successfully loaded or an error code >0

Bool removeKey(byVal section, byVal key)
Removes a key from a section.

Any comments associated with this key will also be removed.

Parameters:

  • section (String): the section to remove the key from
  • key (String): the key to remove

Returns: True if the key was removed

Bool removeKeyComment(byVal section, byVal key)
Removes a comment from a key.

Parameters:

  • section (String): the section the key belongs to
  • key (String): the key to remove the comment from

Returns: True if the comment was removed

Bool removeSection(byVal section)
Removes an entire section including all keys and comments.

Parameters:

  • section (String): the section to remove

Returns: True if the section was removed

Bool removeSectionKeyComments(byVal section)
Removes comments from all keys within a section.

Parameters:

  • section (String): the section to remove key comments from

Returns: True if the section key comments were removed

Bool removeSectionComment(byVal section)
Removes a comment from a section.

Parameters:

  • section (String): the section to remove the comment from

Returns: True if the comment was removed

Int saveFile(byVal filePath)
Saves a .ini file to disk.

The file will be written in ASCII mode unless openFileUnicode() was used to open the file.

Parameters:

  • filePath (String): the absolute or relative path to the file to save this IniFile instance to

Returns: 0 if the file was successfully saved or an error code >0

Bool sectionExists(byVal section)
Checks whether a section exists within this IniFile instance.

Parameters:

  • section (String): the section name to lookup

Returns: True if the section exists

Bool, String setKeyComment(byVal section, byVal key, byVal comment)
Sets a comment for a key.

If the key already has a comment, it is overwritten and returned as the string value. True is returned if a new comment is created for the key. False if the section does not exist.

Parameters:

  • section (String): the section the key belongs to
  • key (String): the key to set the comment on
  • comment (String): the comment to set

Returns: the previous comment (String), True if a new comment or False if the section does not exist

Bool, String setSectionComment(byVal section, byVal comment)
Sets a comment for a section.

If the section already has a comment, it is overwritten and returned as the string value. True is returned if a new comment is created for the section. False if the section does not exist.

Parameters:

  • section (String): the section to set the comment on
  • comment (String): the comment to set

Returns: the previous comment (String), True if a new comment or False if the section does not exist

Bool setValue(byVal section, byVal key, byVal value)
Sets a key/value in a specified section.

If the section does not exist it is created. If the key already has a value, it is overwritten. Be sure not to pass objects, the value should be one of Bool, Double, Int, Long or String.

Parameters:

  • section (String): the section name
  • key (String): the key name
  • value (Bool,Double,Int,Long,String): the value

Returns: Boolean indicating if the key existed and was overwritten.

Supported File Format

The class considers the following to be a valid .ini file:

; Comments can start with a semi-colon
# or a hash symbol.
[section]
key=value

By default the class will open and save as ASCII text files, you can use Unicode with openFileUnicode() and saveFileUnicode(). In-line comments are not supported, see below.

Parsing

The file is parsed line by line. Blank lines are ignored. First the line is checked for a comment delimiter (; or #). If found, the line is cached and the next line read.

If the line is not a comment, the next check is for a section header. If found, the previously cached comment is attached to the section and the section name cached for subsequent keys.

Finally a check is made for a key/value pair. If found, any previously cached comment lines (between the section header and the key) are assigned to the key. The key becomes the left side of the = sign and the right the value. The value is right-trimmed to remove whitespace and line breaks.

Duplicate Values

The class does not support duplicate sections. Keys are unique to the section they are contained within. If duplicate sections are encountered they are effectively merged with any duplicate keys overwriting any previously read keys with the same name.

White-space

White-space is largely ignored: '[section]', '[ section]' and '[section ]' are separate sections. The same applies to key names. When checking for sections, white-space around the square brackets is removed.

Blank lines are ignored. When writing a file, a blank line is inserted at the end of every section.

Comments

The class supports only section and key comments. When reading the file comments are cached and assigned to the next section/key that is encountered.

Comment lines must start with either a semi-colon or hash (; or #). Comments can be multi-line, line breaks will be preserved when reading/writing files. Comments below the last key are not supported and will be lost when saving.

When writing files, comment lines will always use a semi-colon however hash is also supported when reading files.

In-line comments, like that found in many Linux configuration files are not supported. This was a design descision for data compatibility. You can always break down the value of a key yourself if you want to support in-line comments.

Sample Usage

The example code below will create a new INI file in MY_INI_FILE and populate it with a few sections, keys and comments. The file will then be re-opened and iterated through. The created INI file can be seen below the code sample.

Option Explicit

const MY_INI_FILE = "H:\temp\test.ini"

' Create a new file, add a key and comments and save the file as MY_INI_FILE '
Dim ini: Set ini = new IniFile
ini.setValue "Hello", "INI", "File"
ini.setKeyComment "Hello", "INI", "I'm a key comment."
ini.setSectionComment "Hello", "I'm a section comment, both key and section" & _
        VbCrLf & "comments can be multi-line."
ini.addSection "EmptySection"
ini.setValue "AnotherSection", "AnotherKey", "AnotherValue"
Dim saveResult: saveResult = ini.saveFile(MY_INI_FILE)

If saveResult = 0 Then
    WScript.Echo "Successfully saved new INI file as '" & MY_INI_FILE & "'."
Else
    WScript.Echo "Got error " & saveResult & " when saving file."
    WScript.Quit saveResult
End If
Set ini = Nothing

' Open the INI file and iterate through its contents '
Set ini = new IniFile
Dim openResult: openResult = ini.openFile(MY_INI_FILE)
If openResult = 0 Then
    WScript.Echo "'" & MY_INI_FILE & "' opened."
Else
    WScript.Echo "Got error " & openResult & " when opening file."
    WScript.Quit openResult
End If

Dim sectionCount: sectionCount = ini.getSectionCount()
Dim sectionNames: sectionNames = ini.getSectionNames()
Dim i, i2
For i = 0 To sectionCount - 1
    Dim sectionName: sectionName = sectionNames(i)
    WScript.Echo VbCrLf & "In section '" & sectionName & "'"
    Dim sectionComment: sectionComment = ini.getSectionComment(sectionName)
    If sectionComment <> False Then
        WScript.Echo "Section comment: " & sectionComment
    End If
    
    Dim keyCount: keyCount = ini.getKeyCount(sectionName)
    Dim keyNames: keyNames = ini.getKeyNames(sectionName)
    WScript.Echo "Section keys/comments:"
    For i2 = 0 To keyCount - 1
        Dim keyName: keyName = keyNames(i2)
        Dim keyComment: keyComment = ini.getKeyComment(sectionName, keyName)
        If keyComment <> False Then
            WScript.Echo "  " & sectionName & "." & keyName & ".comment='" _
                & keyComment & "'"
        End If
        WScript.Echo "  " & sectionName & "." & keyName & ".value='" _
                & ini.getStringValue(sectionName, keyName, "") & "'"
    Next
Next

The created INI file will contain:

; I'm a section comment, both key and section
; comments can be multi-line.
[Hello]
; I'm a key comment.
INI=File

[EmptySection]

[AnotherSection]
AnotherKey=AnotherValue