diff options
Diffstat (limited to 'doc/api/libinifile/index.txt')
| -rw-r--r-- | doc/api/libinifile/index.txt | 135 |
1 files changed, 0 insertions, 135 deletions
diff --git a/doc/api/libinifile/index.txt b/doc/api/libinifile/index.txt deleted file mode 100644 index 3952796..0000000 --- a/doc/api/libinifile/index.txt +++ /dev/null @@ -1,135 +0,0 @@ -{ - title: libinifile - description: Libinifile API documentation. -} - -Summary -------- - - pkg inifile = - type error = union - `Fileerr - `Parseerr int - `Dupkey int - ;; - - type inifile = - ;; - - /* reading */ - const load : (path : byte[:] -> std.result(inifile#, error)) - const loadf : (file : std.fd -> std.result(inifile#, error)) - const free : (ini : inifile# -> void) - - /* writing */ - const write : (ini : inifile#, path : byte[:] -> bool) - - /* key getting/setting */ - const get : (ini : inifile#, sect : byte[:], key : byte[:] -> std.option(byte[:])) - const getv : (ini : inifile#, sect : byte[:], key : byte[:], val : byte[:] -> byte[:]) - const has : (ini : inifile#, sect : byte[:], key : byte[:] -> bool) - const put : (ini : inifile#, sect : byte[:], key : byte[:], val : byte[:] -> void) - ;; - - -Overview --------- - -Libinifile is a simple ini file parser. It does little interpretation of the -data, and provides little in the way of convenience features. Loading will -read the file into memory, and will not reflect changes of the on-disk data. - -Functions ---------- - - const load : (path : byte[:] -> std.result(inifile#, error)) - -Load will read a file from disk, parsing it, and returning either a pointer to -an `inifile` data structure, or an error reporting the problem parsing it, and -if applicable, the line that the error occurred on. - -This data structure must be freed with `inifile.free()`. - - const loadf : (file : std.fd -> std.result(inifile#, error)) - -This is identical to `inifile.load`, only it reads from a `std.fd` that has -already been opened in read mode, instead of a path. - - const free : (ini : inifile# -> void) - -Releases all storage associated with an inifile data structure. - - const write : (ini : inifile#, path : byte[:] -> bool) - -Write will take the content of an infile, and serialize it to disk. Comments -from the original ini file are not currently preserved. - - const get : (ini : inifile#, sect : byte[:], key : byte[:] -> std.option(byte[:])) - const getv : (ini : inifile#, sect : byte[:], key : byte[:], val : byte[:] -> byte[:]) - -Get and getv act like `std.hget` and `std.htgetv`. They will retrieve an entry -from the ini file. - -Htget will return `\`std.Some val` if the key is present in the given section, -or `\`std.None` if there is no value present in the ini file. Htgetv will -return the default value `val` passed to it if the key is not found. - -For a key that is outside of a section, the empty string (`""`) should be -passed for the section name. - - const has : (ini : inifile#, sect : byte[:], key : byte[:] -> bool) - -Queries whether a key is present in the ini file. Returns true if the key is -present, or false if it is not. - - const put : (ini : inifile#, sect : byte[:], key : byte[:], val : byte[:] -> void) - -Places a key value pair into the in-memory representation of the .ini file. -This key value pair added if it is not present, and replaced if it is. The key -and value are both copied, and ownership is not taken. The responsibility for -freeing the previous value lies with the ini file implementation. - -Supported Syntax --------------- - -The dialect that it supports allows for a list of zero or more key-value pairs -before any sections are declared, followed by a list of sections containing -more key value pairs. - -Keys are any sequence of characters, excluding an '=' sign. Values are any -sequence of characters. For both of these, both leading and trailing white -space is ignored. - -Sections are lists of characters started by `[` and end by `]`. The only -character disallowed within a section name is `]`. Leading and trailing -whitespace is stripped from a section. - -Keys within a file must be unique, otherwise this is an error. - -Section declarations may repeat throughout the file, but this will merely -switch back into the old section. - -Example ------- - -Assuming that an file named `demo.ini` exists, and contains the following -text: - - toplev = hey, there's a value! - [section] - key = wait, there's another - -Then the following program will read it and show the values of the keys: - - use std - use inifile - - const main = { - var ini - - ini = std.try(inifile.load("demo.ini")) - std.put("{}\n", inifile.getv(ini, "", "toplev", "not present") - std.put("{}\n", inifile.getv(ini, "section", "key", "not present") - inifile.free(ini) - } - |