DotIniFile

Inherits: RefCounted < Object

INI configuration file handler with macros, type constraints, and serialization utilities.

Description

Provides an extended INI configuration system with support for sections, keys, macros, type constraints, and multiple serialization formats.

It can load and save configuration data from files, strings, buffers, and encrypted sources.

It also supports value interpolation, comments, automatic saving, and merging with other DotIniFile instances.

This class is designed as a more powerful alternative to ConfigFile, adding features such as macro expansion, typed values, and include handling.

Tutorials

• DotINI Module Test

Methods

void	add_macro(name: String, value: String)
void	add_type_constraint(section: String, key: String, type: Variant.Type)
void	append_value(section: String, key: String, value: Variant)
bool	check_for_updates()
void	clear()
void	clear_section(section: String)
DotIniFile	clone() const
Variant	ensure_value(section: String, key: String, default_value: Variant)
void	erase_section(section: String)
void	erase_section_key(section: String, key: String)
void	from_config_file(config: ConfigFile)
void	from_dictionary(dict: Dictionary)
DotIniFile	get_global_fallback() static
Array[DotIniFile]	get_included_files() const
String	get_key_comment(section: String, key: String) const
PackedStringArray	get_keys_matching(section: String, match_pattern: String) const
String	get_macro(name: String) const
Dictionary	get_section_as_dict(section: String) const
String	get_section_comment(section: String) const
PackedStringArray	get_section_keys(section: String) const
PackedStringArray	get_sections() const
Variant	get_value(section: String, key: String, default: Variant = null, interpolate: bool = true) const
Array	get_value_array(section: String, key: String, interpolate: bool = true) const
String	get_value_b64(section: String, key: String, default: String = "") const
bool	get_value_bool(section: String, key: String, default: bool = false, interpolate: bool = true) const
float	get_value_float(section: String, key: String, default: float = 0.0, interpolate: bool = true) const
int	get_value_int(section: String, key: String, default: int = 0, interpolate: bool = true) const
String	get_value_raw(section: String, key: String, default: String = "") const
String	get_value_string(section: String, key: String, default: String = "", interpolate: bool = true) const
bool	has_section(section: String) const
bool	has_section_key(section: String, key: String) const
bool	is_autosave_enabled() const
bool	is_read_only() const
Error	load(path: String, append: bool = false)
Error	load_encrypted(path: String, key: PackedByteArray, append: bool = false)
Error	load_encrypted_pass(path: String, pass: String, append: bool = false)
Error	load_from_base64(base64: String, append: bool = false)
Error	load_from_buffer(buffer: PackedByteArray, append: bool = false)
Error	load_from_string(string: String, append: bool = false)
void	merge_with(other: DotIniFile, overwrite: bool = true)
void	remove_type_constraint(section: String, key: String)
void	rename_key(section: String, old_key: String, new_key: String)
void	rename_section(old_section: String, new_section: String)
Error	save(path: String = "")
Error	save_all()
Error	save_encrypted(path: String, key: PackedByteArray)
Error	save_encrypted_pass(path: String, pass: String)
String	save_to_base64() const
PackedByteArray	save_to_buffer() const
String	save_to_string() const
void	set_autosave(enabled: bool)
void	set_default_padding(pre_key: String, post_key: String, pre_val: String, post_val: String)
void	set_global_fallback(fallback: DotIniFile) static
void	set_key_comment(section: String, key: String, comment: String)
void	set_read_only(read_only: bool)
void	set_section_comment(section: String, comment: String)
void	set_value(section: String, key: String, value: Variant)
void	set_value_b64(section: String, key: String, utf8_string: String)
void	sort_section_keys(section: String, ascending: bool = true)
ConfigFile	to_config_file() const
Dictionary	to_dictionary() const

---

Signals

file_reloaded() 🔗

Emitted when the file is reloaded after detecting external changes.

---

section_erased(section: String) 🔗

Emitted when a section is removed.

---

value_changed(section: String, key: String, new_value: Variant) 🔗

Emitted when a value is modified.

---

Method Descriptions

void add_macro(name: String, value: String) 🔗

Defines a macro with the given name and value.

---

void add_type_constraint(section: String, key: String, type: Variant.Type) 🔗

Adds a type constraint for the specified section and key.

---

void append_value(section: String, key: String, value: Variant) 🔗

Appends value to an existing key.

If the key does not store an array, it will be converted into one.

---

bool check_for_updates() 🔗

Checks whether the underlying file has changed on disk.

Returns true if it has been modified.

---

void clear() 🔗

Removes all sections, keys, macros, and constraints.

---

void clear_section(section: String) 🔗

Removes all keys from the specified section without deleting the section itself.

---

DotIniFile clone() const 🔗

Returns a deep copy of this DotIniFile instance.

---

Variant ensure_value(section: String, key: String, default_value: Variant) 🔗

Returns the value at section/key, creating it with default_value if it does not exist.

---

void erase_section(section: String) 🔗

Removes the entire section and all its keys.

---

void erase_section_key(section: String, key: String) 🔗

Removes a specific key from a section.

---

void from_config_file(config: ConfigFile) 🔗

Populates this instance using data from a ConfigFile.

---

void from_dictionary(dict: Dictionary) 🔗

Populates this instance from a nested dictionary structure.

---

DotIniFile get_global_fallback() static 🔗

Returns the global fallback DotIniFile used when a value is missing.

---

Array[DotIniFile] get_included_files() const 🔗

Returns a list of included DotIniFile instances.

---

String get_key_comment(section: String, key: String) const 🔗

Returns the comment associated with the specified key.

---

PackedStringArray get_keys_matching(section: String, match_pattern: String) const 🔗

Returns keys in a section matching the given pattern.

---

String get_macro(name: String) const 🔗

Returns the value of a defined macro.

---

Dictionary get_section_as_dict(section: String) const 🔗

Returns all key-value pairs in a section as a dictionary.

---

String get_section_comment(section: String) const 🔗

Returns the comment associated with a section.

---

PackedStringArray get_section_keys(section: String) const 🔗

Returns all keys within a section.

---

PackedStringArray get_sections() const 🔗

Returns all section names.

---

Variant get_value(section: String, key: String, default: Variant = null, interpolate: bool = true) const 🔗

Returns the value for a key, optionally performing macro interpolation.

Returns default if not found.

---

Array get_value_array(section: String, key: String, interpolate: bool = true) const 🔗

Returns the value as an Array.

If the stored value is not an array, it may be converted.

If interpolate is true, macro interpolation is applied.

---

String get_value_b64(section: String, key: String, default: String = "") const 🔗

Returns the value decoded from Base64.

If the key is not found, returns default.

---

bool get_value_bool(section: String, key: String, default: bool = false, interpolate: bool = true) const 🔗

Returns the value converted to a bool.

If the key is not found, returns default.

If interpolate is true, macro interpolation is applied.

---

float get_value_float(section: String, key: String, default: float = 0.0, interpolate: bool = true) const 🔗

Returns the value converted to a float.

If the key is not found, returns default.

If interpolate is true, macro interpolation is applied.

---

int get_value_int(section: String, key: String, default: int = 0, interpolate: bool = true) const 🔗

Returns the value converted to an int.

If the key is not found, returns default.

If interpolate is true, macro interpolation is applied.

---

String get_value_raw(section: String, key: String, default: String = "") const 🔗

Returns the raw string value without applying interpolation.

If the key is not found, returns default.

---

String get_value_string(section: String, key: String, default: String = "", interpolate: bool = true) const 🔗

Returns the value as a String.

If the key is not found, returns default.

If interpolate is true, macro interpolation is applied.

---

bool has_section(section: String) const 🔗

Returns true if the section exists.

---

bool has_section_key(section: String, key: String) const 🔗

Returns true if the specified key exists.

---

bool is_autosave_enabled() const 🔗

Returns true if autosave is enabled.

When enabled, changes to the configuration are automatically written to disk.

---

bool is_read_only() const 🔗

Returns true if the file is in read-only mode.

When read-only, modifications to values or structure are not allowed.

---

Error load(path: String, append: bool = false) 🔗

Loads configuration data from a file.

If append is true, merges with existing data.

---

Error load_encrypted(path: String, key: PackedByteArray, append: bool = false) 🔗

Loads configuration data from an encrypted file at path using the provided binary key.

If append is true, the loaded data is merged with existing data instead of replacing it.

Returns an Error code.

---

Error load_encrypted_pass(path: String, pass: String, append: bool = false) 🔗

Loads configuration data from an encrypted file at path using the provided password pass.

If append is true, the loaded data is merged with existing data instead of replacing it.

Returns an Error code.

---

Error load_from_base64(base64: String, append: bool = false) 🔗

Loads configuration data from a Base64-encoded string.

If append is true, the loaded data is merged with existing data instead of replacing it.

Returns an Error code.

---

Error load_from_buffer(buffer: PackedByteArray, append: bool = false) 🔗

Loads configuration data from a binary buffer.

If append is true, the loaded data is merged with existing data instead of replacing it.

Returns an Error code.

---

Error load_from_string(string: String, append: bool = false) 🔗

Loads configuration data from a plain text string in INI format.

If append is true, the loaded data is merged with existing data instead of replacing it.

Returns an Error code.

---

void merge_with(other: DotIniFile, overwrite: bool = true) 🔗

Merges another DotIniFile into this one.

If overwrite is true, existing values are replaced.

---

void remove_type_constraint(section: String, key: String) 🔗

Removes any type constraint associated with the specified section and key, allowing values of any type to be assigned.

---

void rename_key(section: String, old_key: String, new_key: String) 🔗

Renames a key from old_key to new_key within the given section, preserving its value and metadata.

---

void rename_section(old_section: String, new_section: String) 🔗

Renames a section from old_section to new_section, preserving all contained keys and metadata.

---

Error save(path: String = "") 🔗

Saves the configuration to disk.

If path is empty, uses the last loaded path.

---

Error save_all() 🔗

Saves this configuration and all included files to their respective paths.

Returns an Error code.

---

Error save_encrypted(path: String, key: PackedByteArray) 🔗

Saves the configuration to an encrypted file at path using the provided binary key.

Returns an Error code.

---

Error save_encrypted_pass(path: String, pass: String) 🔗

Saves the configuration to an encrypted file at path using the provided password pass.

Returns an Error code.

---

String save_to_base64() const 🔗

Serializes the configuration to a Base64-encoded string.

---

PackedByteArray save_to_buffer() const 🔗

Serializes the configuration to a binary buffer.

---

String save_to_string() const 🔗

Serializes the configuration to a plain text string in INI format.

---

void set_autosave(enabled: bool) 🔗

Enables or disables autosave.

When enabled, changes to the configuration are automatically written to disk.

---

void set_default_padding(pre_key: String, post_key: String, pre_val: String, post_val: String) 🔗

Sets the default formatting padding used when saving keys and values.

This controls spacing before and after keys and values.

---

void set_global_fallback(fallback: DotIniFile) static 🔗

Sets the global fallback DotIniFile used when a value is not found in the current instance.

---

void set_key_comment(section: String, key: String, comment: String) 🔗

Sets a comment for the specified key within a section.

---

void set_read_only(read_only: bool) 🔗

Enables or disables read-only mode.

When enabled, modifications to the configuration are not allowed.

---

void set_section_comment(section: String, comment: String) 🔗

Sets a comment for the specified section.

---

void set_value(section: String, key: String, value: Variant) 🔗

Sets the value for a given section and key.

---

void set_value_b64(section: String, key: String, utf8_string: String) 🔗

Encodes the given utf8_string as Base64 and stores it as the value for the specified section and key.

---

void sort_section_keys(section: String, ascending: bool = true) 🔗

Sorts the keys within the specified section alphabetically.

If ascending is false, keys are sorted in descending order.

---

ConfigFile to_config_file() const 🔗

Converts this DotIniFile into a ConfigFile instance containing the same sections and key-value pairs.

---

Dictionary to_dictionary() const 🔗

Exports the entire configuration as a dictionary.