bx-ini: INI File Handling

BoxLang is the AI-native software productivity platform for building, modernizing and running applications, with developers and AI agents working together.

Installation

install-bx-module bx-ini
# CommandBox
box install bx-ini

BIFs

BIF	Description
getIniFile( file )	Open (or create) an INI file, returns an IniFile object
getProfileString( iniFile, section, entry )	Get a single entry value
setProfileString( iniFile, section, entry, value )	Set a single entry value
getProfileSection( iniFile, section )	Get an entire section as a struct
getProfileSections( iniFile )	Get all sections as a struct of structs
removeProfileSection( iniFile, section )	Remove an entire section
removeProfileString( iniFile, section, entry )	Remove a single entry

Reading an INI File

# /app/config/app.ini
[General]
appName=MyApplication
version=1.2.3
debug=false

[Database]
host=localhost
port=5432
dbname=myapp

[Logging]
logLevel=DEBUG
logFile=/var/log/myapp.log

// Read individual values
appName = getProfileString( "/app/config/app.ini", "General", "appName" )
host    = getProfileString( "/app/config/app.ini", "Database", "host" )
port    = getProfileString( "/app/config/app.ini", "Database", "port" )

// If entry doesn't exist, returns empty string
missingValue = getProfileString( "/app/config/app.ini", "General", "nonExistent" )
// Returns ""

// Read entire section as a struct
dbConfig = getProfileSection( "/app/config/app.ini", "Database" )
// { host: "localhost", port: "5432", dbname: "myapp" }

// Read all sections
allConfig = getProfileSections( "/app/config/app.ini" )
// { General: {...}, Database: {...}, Logging: {...} }

Writing an INI File

// Write a single value (creates section + key if not present)
setProfileString( "/app/config/app.ini", "General", "debug", "true" )

// Create a new section and populate it
setProfileString( "/app/config/app.ini", "Cache", "enabled", "true" )
setProfileString( "/app/config/app.ini", "Cache", "ttl", "300" )
setProfileString( "/app/config/app.ini", "Cache", "provider", "redis" )

Fluent IniFile Object API

// Get the IniFile object for fluent chaining
var ini = getIniFile( "/app/config/settings.ini" )

// Create a section
ini.createSection( "MySettings" )

// Set entries
ini.setEntry( "MySettings", "timeout", "30" )
ini.setEntry( "MySettings", "retries", "3" )
ini.setEntry( "MySettings", "endpoint", "https://api.example.com" )

// Read entries
timeout = ini.getEntry( "MySettings", "timeout" )

// Remove a single entry
ini.removeEntry( "MySettings", "retries" )

// Remove an entire section
ini.removeSection( "OldSettings" )

Config File Pattern

// Load per-environment config
env    = server.system.environment.APP_ENV ?: "development"
config = getProfileSections( "/app/config/#env#.ini" )

// Access config
println( config.Database.host )
println( config.General.appName )

Common Pitfalls

• ✅ All values returned from INI files are strings — convert to numeric/boolean as needed: val( port )
• ❌ INI files do not support nested sections — use YAML (bx-yaml) for hierarchical config
• ✅ getIniFile() creates the file if it doesn't exist — safe for first-time setup
• ✅ getProfileString() returns an empty string for missing entries — always check if empty when the value is required