@dream/ini

local ini = require("@dream/ini")

A frozen table: version and five functions over plain tables. Names are camelCase throughout, and so are option fields, result fields and kind values.

local result = ini.importPaths({
    ini = "Morrowind/Morrowind.ini",
    cfg = "openmw/openmw.cfg",
    gameFiles = true,
})

for _, file in result.cfg.content do
    print(file)
end
for _, warning in result.warnings do
    print(warning.message)
end

Multimaps#

A cfg, or a parsed INI, is a table from each key to an array of its values, in order. Keys that repeat, such as content or data, keep every value:

local cfg = {
    encoding = { "win1252" },
    content = { "Morrowind.esm", "Tribunal.esm" },
}

An INI’s keys are Section:Key, such as General:Disable Audio. Every value must be a string: a number, even one that looks like a setting, is an error naming the key.

version#

The dream-ini version, such as "0.4.0".

parseIni#

Parses a Morrowind.ini from its raw bytes, as read from disk. encoding decodes them: "win1250", "win1251" or "win1252", the default. The rules are the importer’s own, in How the INI is read.

local parsed = ini.parseIni("[General]\r\nDisable Audio=1\r\nWerewolf FOV=\r\n")
assert(parsed.entries["General:Disable Audio"][1] == "1")
assert(parsed.warnings[1].kind == "ignoredEmptyValue")
assert(parsed.warnings[1].key == "General:Werewolf FOV")

parseCfg#

Parses openmw.cfg text. Lines whose first character that is not a space is # are comments. Key and value are trimmed of spaces; a line with no =, or nothing before it, is skipped. Nothing is resolved: config= lines, tokens and relative paths stay as written.

serializeCfg#

key=value lines, one per value, keys in byte order and values in their order, each ending in a newline. No comments, and no formatting of the cfg it came from.

assert(ini.serializeCfg({ content = { "A.esm", "B.esp" }, encoding = { "win1252" } })
    == "content=A.esm\ncontent=B.esp\nencoding=win1252\n")

importMaps#

Imports a parsed INI into a copy of cfg; the table passed in is not changed. It still searches the disk for content and archives. Two options of its own:

So importMaps on parseCfg(cfgText) and parseIni(iniBytes).entries imports what importPaths would from the same files, given the same encoding and a cfgDir naming the cfg’s folder, except that cfgText is taken as written: its config= lines are not followed, and its paths keep their spelling in the result.

importPaths#

Reads ini, and cfg if given, and imports. A cfg that does not exist starts empty. The cfg is read as OpenMW would: its config= chain followed and its paths resolved. Relative dataDirs are relative to the cfg’s folder, or to cfgDir without a cfg, or to the current folder. It writes nothing; what to do with the result is the script’s business.

ImportOptions#

Both import functions take these, all optional:

What an import does explains each.

ImportResult#

Warnings, each with a message in the command line’s words:

Events:

Errors#

A failed call raises an error; nothing is returned.

A missing INI in importPaths is a failed import, in the system’s words: dream.ini: Morrowind.ini: No such file or directory (os error 2).

Type definitions#

What plan.type_definitions() generates for the module, for an editor’s language server:

-- module @dream/ini (provided by dream.ini)
-- Morrowind.ini import into OpenMW cfg data, on multimap tables.
export type Module__dream_ini = {
    -- The dream-ini crate version.
    version: string,
    -- Parses a Morrowind.ini's raw bytes, decoded with `encoding` (default win1252).
    parseIni: (text: string | buffer, options: { encoding: string? }?) -> { entries: { [string]: { string } }, warnings: { { kind: string, message: string, key: string?, line: string?, file: string? } } },
    -- Parses openmw.cfg text into a multimap.
    parseCfg: (text: string) -> { [string]: { string } },
    -- Serializes a multimap as normalized cfg text.
    serializeCfg: (cfg: { [string]: { string } }) -> string,
    -- Imports a parsed INI into a copy of `cfg`; `iniPath` (default "Morrowind.ini") locates the fallback `Data Files` folder.
    importMaps: (cfg: { [string]: { string } }, ini: { [string]: { string } }, options: { game: string?, gameFiles: boolean?, fonts: boolean?, archives: boolean?, verbose: boolean?, encoding: string?, dataDirs: { string }?, dataLocal: string?, resources: string?, userData: string?, cfgDir: string?, iniPath: string? }?) -> { cfg: { [string]: { string } }, text: string, warnings: { { kind: string, message: string, key: string?, line: string?, file: string? } }, events: { { kind: string, path: string, modified: number? } } },
    -- Reads `ini` and the optional `cfg` from disk and imports; it writes nothing.
    importPaths: (options: { ini: string, cfg: string?, game: string?, gameFiles: boolean?, fonts: boolean?, archives: boolean?, verbose: boolean?, encoding: string?, dataDirs: { string }?, dataLocal: string?, resources: string?, userData: string?, cfgDir: string? }) -> { cfg: { [string]: { string } }, text: string, warnings: { { kind: string, message: string, key: string?, line: string?, file: string? } }, events: { { kind: string, path: string, modified: number? } } },
}
declare dreamIni: Module__dream_ini

The last line appears when the host exposes the dreamIni global.