cIniFile


Index:
Articles
Classes
Hooks

Quick navigation:
BannerPattern
BossBarColor
BossBarDivisionType
cArrowEntity
cBeaconEntity
cBedEntity
cBlockArea
cBlockEntity
cBlockEntityWithItems
cBlockInfo
cBoat
cBoundingBox
cBrewingstandEntity
cChatColor
cChestEntity
cChunkDesc
cClientHandle
cColor
cCommandBlockEntity
cCompositeChat
cCraftingGrid
cCraftingRecipe
cCryptoHash
cCuboid
cDispenserEntity
cDropperEntity
cDropSpenserEntity
cEnchantments
cEnderCrystal
cEntity
cEntityEffect
cExpBottleEntity
cExpOrb
cFallingBlock
cFile
cFireChargeEntity
cFireworkEntity
cFloater
cFlowerPotEntity
cFurnaceEntity
cGhastFireballEntity
cHangingEntity
cHopperEntity
cIniFile
cInventory
cItem
cItemFrame
cItemGrid
cItems
cJson
cJukeboxEntity
cLeashKnot
cLineBlockTracer
cLuaWindow
cMap
cMapManager
cMobHeadEntity
cMobSpawnerEntity
cMojangAPI
cMonster
cNetwork
cNoteEntity
cObjective
cPainting
cPawn
cPickup
cPlayer
cPlugin
cPluginLua
cPluginManager
cProjectileEntity
cRankManager
cRoot
cScoreboard
cServer
cServerHandle
cSignEntity
cSplashPotionEntity
cStringCompression
cTCPLink
cTeam
cThrownEggEntity
cThrownEnderPearlEntity
cThrownSnowballEntity
cTNTEntity
cUDPEndpoint
cUrlClient
cUrlParser
CustomStatistic
cUUID
cWebAdmin
cWindow
cWitherSkullEntity
cWorld
EffectID
HTTPFormData
HTTPRequest
HTTPTemplateRequest
ItemCategory
lxp
SmokeDirection
sqlite3
StatisticsManager
TakeDamageInfo
tolua
Vector3d
Vector3f
Vector3i
Globals

Contents


cIniFile class

This class implements a simple name-value storage represented on disk by an INI file. These files are suitable for low-volume high-latency human-readable information storage, such as for configuration. Cuberite itself uses INI files for settings and options.

The INI files follow this basic structure:

; Header comment line
[KeyName0]
; Key comment line 0
ValueName0=Value0
ValueName1=Value1

[KeyName1]
; Key comment line 0
; Key comment line 1
ValueName0=SomeOtherValue
The cIniFile object stores all the objects in numbered arrays and provides access to the information either based on names (KeyName, ValueName) or zero-based indices.

The objects of this class are created empty. You need to either load a file using ReadFile(), or insert values by hand. Then you can store the object's contents to a disk file using WriteFile(), or just forget everything by destroying the object. Note that the file operations are quite slow.

Cuberite will write the characters '\n' in place of line breaks in the values of the cIniFile when it is being stored into a file. It will also replace '\n' with line breaks when it reads an INI file.

For storing high-volume low-latency data, use the sqlite3 class. For storing hierarchically-structured data, use the XML format, using the LuaExpat parser in the lxp class.


Constants

NameValueNotes
noID -1

Functions

NameParametersReturn valueNotes
() (constructor)
cIniFile
Creates a new empty cIniFile object.
AddHeaderComment
Commentstring
Adds a comment to be stored in the file header.
AddKeyComment
KeyNamestring
Commentstring
Adds a comment to be stored in the file under the specified key
AddKeyComment
KeyIDnumber
Commentstring
Adds a comment to be stored in the file under the specified key
AddKeyName
KeyNamestring
number
Adds a new key of the specified name. Returns the KeyID of the new key.
AddValue
KeyNamestring
ValueNamestring
Valuestring
Adds a new value of the specified name to the specified key. If another value of the same name exists in the key, both are kept (nonstandard INI file)
AddValueB
KeyNamestring
ValueNamestring
Valueboolean
Adds a new bool value of the specified name to the specified key. If another value of the same name exists in the key, both are kept (nonstandard INI file)
AddValueF
KeyNamestring
ValueNamestring
Valuenumber
Adds a new float value of the specified name to the specified key. If another value of the same name exists in the key, both are kept (nonstandard INI file)
AddValueI
KeyNamestring
ValueNamestring
Valuenumber
Adds a new integer value of the specified name to the specified key. If another value of the same name exists in the key, both are kept (nonstandard INI file)
CaseInsensitive Sets key names' and value names' comparisons to case insensitive (default).
CaseSensitive Sets key names and value names comparisons to case sensitive.
Clear Removes all the in-memory data. Note that , like all the other operations, this doesn't affect any file data.
DeleteHeaderComment
CommentIDnumber
IsSuccessboolean
Deletes the specified header comment. Returns true if successful.
DeleteHeaderComments Deletes all headers comments.
DeleteKey
KeyNamestring
IsSuccessboolean
Deletes the specified key, and all values in that key. Returns true if successful.
DeleteKeyComment
KeyNamestring
CommentIDnumber
IsSuccessboolean
Deletes the specified key comment. Returns true if successful.
DeleteKeyComment
KeyIDnumber
CommentIDnumber
IsSuccessboolean
Deletes the specified key comment. Returns true if successful.
DeleteKeyComments
KeyIDnumber
IsSuccessboolean
Deletes all comments for the specified key. Returns true if successful.
DeleteKeyComments
KeyNamestring
IsSuccessboolean
Deletes all comments for the specified key. Returns true if successful.
DeleteValue
KeyNamestring
ValueNamestring
IsSuccessboolean
Deletes the specified value. Returns true if successful.
DeleteValueByID
KeyIDnumber
ValueIDnumber
IsSuccessboolean
Deletes the specified value. Returns true if successful.
FindKey
KeyNamestring
number
Returns the KeyID for the specified key name, or the noID constant if the key doesn't exist.
FindValue
KeyIDnumber
ValueNamestring
ValueIDnumber
Returns the ValueID for the specified value name, or the noID constant if the specified key doesn't contain a value of that name.
Flush
boolean
Writes the data stored in the object to the file that was last associated with the object (ReadFile() or WriteFile()). Returns true on success, false on failure.
GetHeaderComment
CommentIDnumber
string
Returns the specified header comment, or an empty string if such comment doesn't exist
GetKeyComment
KeyIDnumber
CommentIDnumber
string
Returns the specified key comment, or an empty string if such a comment doesn't exist
GetKeyComment
KeyNamestring
CommentIDnumber
string
Returns the specified key comment, or an empty string if such a comment doesn't exist
GetKeyName
KeyIDnumber
string
Returns the key name for the specified key ID. Inverse for FindKey().
GetNumHeaderComments
number
Retuns the number of header comments.
GetNumKeyComments
KeyIDnumber
number
Returns the number of comments under the specified key
GetNumKeyComments
KeyNamestring
number
Returns the number of comments under the specified key
GetNumKeys
number
Returns the total number of keys. This is the range for the KeyID (0 .. GetNumKeys() - 1)
GetNumValues
KeyNamestring
number
Returns the number of values stored under the specified key.
GetNumValues
KeyIDnumber
number
Returns the number of values stored under the specified key.
GetValue
KeyIDnumber
ValueIDnumber
DefaultValuestring
string
Returns the value of the specified name under the specified key. Returns DefaultValue (empty string if not given) if the value doesn't exist.
GetValue
KeyNamestring
ValueNamestring
DefaultValuestring
string
Returns the value of the specified name under the specified key. Returns DefaultValue (empty string if not given) if the value doesn't exist.
GetValueB
KeyNamestring
ValueNamestring
DefaultValueboolean
boolean
Returns the value of the specified name under the specified key, as a bool. Returns DefaultValue (false if not given) if the value doesn't exist.
GetValueF
KeyNamestring
ValueNamestring
DefaultValuenumber
number
Returns the value of the specified name under the specified key, as a floating-point number. Returns DefaultValue (zero if not given) if the value doesn't exist.
GetValueI
KeyNamestring
ValueNamestring
DefaultValuenumber
number
Returns the value of the specified name under the specified key, as an integer. Returns DefaultValue (zero if not given) if the value doesn't exist.
GetValueName
KeyIDnumber
ValueIDnumber
string
Returns the name of the value specified by its ID. Inverse for FindValue().
GetValueName
KeyNamestring
ValueIDnumber
string
Returns the name of the value specified by its ID. Inverse for FindValue().
GetValueSet
KeyNamestring
ValueNamestring
DefaultValuestring
string
Returns the value of the specified name under the specified key. If the value doesn't exist, creates it with the specified default (empty string if not given).
GetValueSetB
KeyNamestring
ValueNamestring
DefaultValueboolean
boolean
Returns the value of the specified name under the specified key, as a bool. If the value doesn't exist, creates it with the specified default (false if not given).
GetValueSetF
KeyNamestring
ValueNamestring
DefaultValuenumber
number
Returns the value of the specified name under the specified key, as a floating-point number. If the value doesn't exist, creates it with the specified default (zero if not given).
GetValueSetI
KeyNamestring
ValueNamestring
DefaultValuenumber
number
Returns the value of the specified name under the specified key, as an integer. If the value doesn't exist, creates it with the specified default (zero if not given).
HasValue
KeyNamestring
ValueNamestring
boolean
Returns true if the specified value is present.
ReadFile
FileNamestring
AllowExampleFallbackboolean
IsSuccessboolean
Reads the values from the specified file. Previous in-memory contents are lost. If the file cannot be opened, and AllowExample is true, another file, "filename.example.ini", is loaded and then saved as "filename.ini". Returns true if successful, false if not.
SetValue
KeyNamestring
ValueNamestring
NewValuestring
CreateIfNotExistsboolean
IsSuccessboolean
Overwrites the specified value with a new value. If CreateIfNotExists is true (default) and the value doesn't exist, it is first created. Returns true if the value was successfully set, false if not (didn't exists, CreateIfNotExists false).
SetValue
KeyIDnumber
ValueIDnumber
NewValuestring
IsSuccessboolean
Overwrites the specified value with a new value. If the specified value doesn't exist, returns false (doesn't add).
SetValueB
KeyNamestring
ValueNamestring
NewValueboolean
CreateIfNotExistsboolean
IsSuccessboolean
Overwrites the specified value with a new bool value. If CreateIfNotExists is true (default) and the value doesn't exist, it is first created. Returns true if the value was successfully set, false if not (didn't exists, CreateIfNotExists false).
SetValueF
KeyNamestring
ValueNamestring
NewValuenumber
CreateIfNotExistsboolean
IsSuccessboolean
Overwrites the specified value with a new floating-point number value. If CreateIfNotExists is true (default) and the value doesn't exist, it is first created. Returns true if the value was successfully set, false if not (didn't exists, CreateIfNotExists false).
SetValueI
KeyNamestring
ValueNamestring
NewValuenumber
CreateIfNotExistsboolean
IsSuccessboolean
Overwrites the specified value with a new integer value. If CreateIfNotExists is true (default) and the value doesn't exist, it is first created. Returns true if the value was successfully set, false if not (didn't exists, CreateIfNotExists false).
WriteFile
FileNamestring
IsSuccessboolean
Writes the current in-memory data into the specified file. Returns true if successful, false if not.

Code example: Reading a simple value

cIniFile is very easy to use. For example, you can find out what port the server is supposed to use according to settings.ini by using this little snippet:
local IniFile = cIniFile();
if (IniFile:ReadFile("settings.ini")) then
	ServerPort = IniFile:GetValueI("Server", "Port");
end

Code example: Enumerating all objects in a file

To enumerate all keys in a file, you need to query the total number of keys, using GetNumKeys(), and then query each key's name using GetKeyName(). Similarly, to enumerate all values under a key, you need to query the total number of values using GetNumValues() and then query each value's name using GetValueName().

The following code logs all keynames and their valuenames into the server log:

local IniFile = cIniFile();
IniFile:ReadFile("somefile.ini")
local NumKeys = IniFile:GetNumKeys();
for k = 0, (NumKeys - 1) do
	local NumValues = IniFile:GetNumValues(k);
	LOG("key \"" .. IniFile:GetKeyName(k) .. "\" has " .. NumValues .. " values:");
	for v = 0, (NumValues - 1) do
		LOG("  value \"" .. IniFile:GetValueName(k, v) .. "\".");
	end
end
Generated by APIDump on 2024-07-12 00:49:19, Build ID 63, Commit 5f4d2f004bc41bc44d0df7376e48cbb5567db1be