Edit

Text.Ini

Ini files (short for initialization files) are simple text files used to store settings and configurations for applications. They are organized into sections, each containing key-value pairs known as properties. Ini files are a popular choice for storing settings because they are easy to read and modify by both humans and programs.

In this introduction, we will discuss the Ini file format in detail, covering its typical use cases, properties and sections, and how to use the module in BlitzMax to load, save, and edit Ini files. By the end of this guide, you will have the knowledge to create your own Ini files, either with a separate editor or using the text.ini module in BlitzMax.

Understanding the Ini File Format

An Ini file is composed of sections, where each section starts with a section name enclosed in square brackets (e.g., [SectionName]). Underneath each section are properties, which are key-value pairs separated by an equals sign (=). For example:

[Settings]
Volume=80
FullScreen=False
Resolution=1920x1080

[UserProfile]
Username=JohnDoe
Email=johndoe@example.com

In this example, there are two sections, "Settings" and "UserProfile". The "Settings" section contains three properties: Volume, FullScreen, and Resolution.

Using the module

The text.ini module provides a simple and efficient way to work with Ini files in BlitzMax. The following subsections will guide you through loading, saving, and editing Ini files using the module.

Loading an Ini File

To load an Ini file from disk, use the Load function, providing the file path:

Local iniFile:TIni = TIni.Load("config.ini")

Alternatively, to load an Ini file from a TStream, use the Load function with the stream as the argument:

Local stream:TStream = ReadFile("config.ini")
Local iniFile:TIni = TIni.Load(stream)

Saving an Ini File

To save an Ini file to disk, use the Save method and provide the file path:

iniFile.Save("config.ini")

To save an Ini file to a TStream, use the Save method with the stream as the argument:

Local stream:TStream = WriteFile("config.ini")
iniFile.Save(stream)

Working with Sections and Properties

To create a new section, use the AddSection method:

Local section:TIniSection = iniFile.AddSection("Settings")

To find a section by its name, use the FindSection method:

Local section:TIniSection = iniFile.FindSection("Settings")

To add a new property to a section, use the AddProperty method:

section.AddProperty("Volume", "80")

To find a property by its name, use the FindProperty method:

Local property:TIniProperty = section.FindProperty("Volume")

To get or set a property's value, use the GetValue and SetValue methods:

Local volume:Int = Int(property.GetValue())
property.SetValue("85")

Cleaning Up

When you are done working with an Ini file, call the Free method to release any resources used by the TIni instance:

iniFile.Free()

Here is a complete example that demonstrates how to create, edit, and save an Ini file using the text.ini module:

SuperStrict

Framework Text.Ini

' Create a new empty TIni instance
Local iniFile:TIni = New TIni

' Add sections and properties
Local settingsSection:TIniSection = iniFile.AddSection("Settings")
settingsSection.AddProperty("Volume", "80")
settingsSection.AddProperty("FullScreen", "False")
settingsSection.AddProperty("Resolution", "1920x1080")

Local userProfileSection:TIniSection = iniFile.AddSection("UserProfile")
userProfileSection.AddProperty("Username", "JohnDoe")
userProfileSection.AddProperty("Email", "johndoe@example.com")

' Save the Ini file to disk
iniFile.Save("config.ini")

' Load the Ini file from disk
Local loadedIniFile:TIni = TIni.Load("config.ini")

' Retrieve and modify a property
Local section:TIniSection = loadedIniFile.FindSection("Settings")
Local property:TIniProperty = section.FindProperty("Volume")
Local volume:Int = Int(property.GetValue())
property.SetValue(String(volume + 5))

' Save the modified Ini file to disk
loadedIniFile.Save("config_modified.ini")

' Clean up
iniFile.Free()
loadedIniFile.Free()

This example creates a new Ini file with two sections and several properties, saves it to disk, loads it back, modifies a property, and then saves the modified Ini file to a new file. The result is two Ini files: "config.ini" containing the original settings, and "config_modified.ini" containing the modified settings.

Types

Type	Description
TIni	Represents the contents of an ini file.
TIniSection	An ini section.
TIniProperty	An ini property, with a name and value.

Consts

Const INI_GLOBAL_SECTION:Int = 0

The index that indicates the global section.