Difference between revisions of "Gkini"
Ravenwolf397 (Talk | contribs) (Correct WriteString() length limit) |
Ravenwolf397 (Talk | contribs) m (→ReadString2: Add another linebreak) |
||
| (7 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
| − | These are functions to manipulate the | + | These are functions to manipulate the game's config file config.ini, located at "INSTALL_DIR/config.ini". |
The format of the file looks like this: | The format of the file looks like this: | ||
| − | [section] | + | <source lang="ini"> |
| − | key=value | + | [section] |
| − | + | key=value | |
| − | . | + | key2=value2 |
| + | key3=value3 | ||
| + | ... | ||
| − | + | [section2] | |
| + | key4=value4 | ||
| + | key5=value5 | ||
| + | key6=value6 | ||
| + | ... | ||
| + | </source> | ||
| + | For example, here is an excerpt from one config.ini: | ||
| + | <source lang="ini"> | ||
| + | [Vendetta] | ||
| + | version=4 | ||
| + | skin=skins/platinum/ | ||
| + | maxframerate=120 | ||
| + | </source> | ||
| + | |||
| + | Values are usually strings or integers. All identifiers (sections and keys) are case-sensitive. | ||
| + | |||
| + | Each entry is exactly one line; this means they cannot contain newline characters ("\n"). The key and value are separated by the ''first'' equal sign in the line; for example, "key==value" is interpreted as a key "key" and value "=value". All entries are limited to 767 characters (including key, equal sign, and value). Entries larger than this might be truncated, split, or ignored. If any of your strings have a null character ("\0") in them, then they will be treated as if they ended there. So for these functions, a string like "foo\0bar" will be treated like it was just "foo". Empty ("") section names will work correctly, empty keys will not. | ||
| Line 27: | Line 45: | ||
'''default''' value to return if key not found | '''default''' value to return if key not found | ||
<br><br> | <br><br> | ||
| − | '''Returns:''' | + | '''Returns:''' configured value, or default if not present/empty |
<br><br> | <br><br> | ||
'''Example:'''<br> | '''Example:'''<br> | ||
| − | <source lang="lua">gkini.ReadInt("Vendetta", "showhelpstring", 1) -> 0 -- showhelpstring is | + | <source lang="lua">gkini.ReadInt("Vendetta", "showhelpstring", 1) -> 0 -- showhelpstring is currently set to 0</source> |
<br><br> | <br><br> | ||
| + | |||
| + | |||
| + | === ReadInt2 === | ||
| + | Unknown<br><br> | ||
| Line 44: | Line 66: | ||
'''section''' a section of the config file<br> | '''section''' a section of the config file<br> | ||
'''key''' key within a section<br> | '''key''' key within a section<br> | ||
| − | '''default''' value to return if key not found | + | '''default''' value to return if key not found or value is empty (eg. "foo=") |
<br><br> | <br><br> | ||
| − | '''Returns:''' | + | '''Returns:''' configured value, or default if not present/empty |
<br><br> | <br><br> | ||
'''Example:'''<br> | '''Example:'''<br> | ||
<source lang="lua">gkini.ReadString("Vendetta", "Username", "dude") -> "hans" -- get the default username from the config file</source> | <source lang="lua">gkini.ReadString("Vendetta", "Username", "dude") -> "hans" -- get the default username from the config file</source> | ||
| + | '''Notes:'''<br> | ||
| + | - Leading/trailing spaces are stripped from the return value. For example, if your file reads "key= value ", then ReadString(section, "key", "") will return "value", not " value ". This appears to apply only to space characters, and does not include tabs ("\t").<br> | ||
| + | - If the entry is longer than 767 characters (including key, equal sign, and value), then further characters will be ignored. | ||
<br><br> | <br><br> | ||
| + | === ReadString2 === | ||
| + | '''Definition:'''<br> | ||
| + | ReadString2(string section, string key, string default, string file) -> string value | ||
| + | <br><br> | ||
| + | '''Description:'''<br> | ||
| + | Read a string from the given section and key, from any .ini file. | ||
| + | <br><br> | ||
| + | '''Arguments:'''<br> | ||
| + | '''section''' a section of the config file<br> | ||
| + | '''key''' a key of the config file<br> | ||
| + | '''default''' value to return if entry is not present<br> | ||
| + | '''file''' path to the config file to read from (relative to VO install directory) | ||
| + | <br><br> | ||
| + | '''Returns:''' Configured value, or default if not present/empty | ||
| + | <br><br> | ||
| + | '''Example:'''<br> | ||
| + | <source lang="lua">gkini.ReadString2("foo", "bar", "", "plugins/myplugin/settings.ini") -> "baz" -- read the foo/bar entry from plugins/myplugin/settings.ini</source> | ||
| + | '''Notes:'''<br> | ||
| + | - Essentially identical to ReadString, except for the fourth argument allowing you to specify the file from which to read.<br> | ||
| + | - There is no paired "WriteString2" function; you can only write configuration to the game's config.ini file, nowhere else. | ||
| + | <br><br> | ||
=== WriteInt === | === WriteInt === | ||
| Line 66: | Line 112: | ||
'''value''' value of a key as an integer | '''value''' value of a key as an integer | ||
<br><br> | <br><br> | ||
| − | '''Returns:''' | + | '''Returns:''' nil |
<br><br> | <br><br> | ||
'''Example:'''<br> | '''Example:'''<br> | ||
| Line 86: | Line 132: | ||
'''value''' value of a key as a string | '''value''' value of a key as a string | ||
<br><br> | <br><br> | ||
| − | '''Returns:''' | + | '''Returns:''' nil |
<br><br> | <br><br> | ||
'''Example:'''<br> | '''Example:'''<br> | ||
<source lang="lua">gkini.WriteString("Vendetta", "Username", "dude") -- change the Username option to dude</source> | <source lang="lua">gkini.WriteString("Vendetta", "Username", "dude") -- change the Username option to dude</source> | ||
| + | '''Notes:'''<br> | ||
| + | - ''value''=nil is accepted without error, but appears to do nothing.<br> | ||
| + | - Unlike ReadString, leading and trailing spaces are ''not'' trimmed from values.<br> | ||
| + | - Newline and equal sign characters are accepted without escaping or translation. This means you can do, for example, WriteString(section, "foo", "bar\n\n[baz]x=13") and get | ||
| + | <source lang="ini"> | ||
| + | foo=bar | ||
| + | |||
| + | [baz] | ||
| + | x=13 | ||
| + | </source> | ||
| + | Note that this also moves the keys after "foo" to the "bar" section. For this reason, it is generally wise to avoid providing newlines or equal signs to WriteString. (This includes ''key''; WriteString(section, "key=", "value") will create a line "key==value", which will be interpreted by ReadString as "key" and "=value", not "key=" and "value".) | ||
<br><br> | <br><br> | ||
[[Category:Tables]] | [[Category:Tables]] | ||
Latest revision as of 18:30, 27 May 2023
These are functions to manipulate the game's config file config.ini, located at "INSTALL_DIR/config.ini".
The format of the file looks like this:
[section] key=value key2=value2 key3=value3 ... [section2] key4=value4 key5=value5 key6=value6 ...
For example, here is an excerpt from one config.ini:
[Vendetta] version=4 skin=skins/platinum/ maxframerate=120
Values are usually strings or integers. All identifiers (sections and keys) are case-sensitive.
Each entry is exactly one line; this means they cannot contain newline characters ("\n"). The key and value are separated by the first equal sign in the line; for example, "key==value" is interpreted as a key "key" and value "=value". All entries are limited to 767 characters (including key, equal sign, and value). Entries larger than this might be truncated, split, or ignored. If any of your strings have a null character ("\0") in them, then they will be treated as if they ended there. So for these functions, a string like "foo\0bar" will be treated like it was just "foo". Empty ("") section names will work correctly, empty keys will not.
Contents
Functions
ReadInt
Definition:
ReadInt(string section, string key, int default) -> int value
Description:
Read an integer from the given section and key
Arguments:
section a section of the config file
key key within a section
default value to return if key not found
Returns: configured value, or default if not present/empty
Example:
gkini.ReadInt("Vendetta", "showhelpstring", 1) -> 0 -- showhelpstring is currently set to 0
ReadInt2
Unknown
ReadString
Definition:
ReadString(string section, string key, string default) -> string value
Description:
Read a string from the given section and key
Arguments:
section a section of the config file
key key within a section
default value to return if key not found or value is empty (eg. "foo=")
Returns: configured value, or default if not present/empty
Example:
gkini.ReadString("Vendetta", "Username", "dude") -> "hans" -- get the default username from the config file
Notes:
- Leading/trailing spaces are stripped from the return value. For example, if your file reads "key= value ", then ReadString(section, "key", "") will return "value", not " value ". This appears to apply only to space characters, and does not include tabs ("\t").
- If the entry is longer than 767 characters (including key, equal sign, and value), then further characters will be ignored.
ReadString2
Definition:
ReadString2(string section, string key, string default, string file) -> string value
Description:
Read a string from the given section and key, from any .ini file.
Arguments:
section a section of the config file
key a key of the config file
default value to return if entry is not present
file path to the config file to read from (relative to VO install directory)
Returns: Configured value, or default if not present/empty
Example:
gkini.ReadString2("foo", "bar", "", "plugins/myplugin/settings.ini") -> "baz" -- read the foo/bar entry from plugins/myplugin/settings.ini
Notes:
- Essentially identical to ReadString, except for the fourth argument allowing you to specify the file from which to read.
- There is no paired "WriteString2" function; you can only write configuration to the game's config.ini file, nowhere else.
WriteInt
Definition:
WriteInt(string section, string key, int value) -> nil
Description:
Write an integer to the given section and key
Arguments:
section a section of the config file
key key within a section
value value of a key as an integer
Returns: nil
Example:
gkini.WriteInt("Vendetta", "showhelpstring", 1) -- change the showhelpstring option to 1
WriteString
Definition:
WriteString(string section, string key, string value) -> nil
Description:
Write a string to the given section and key. The entire entry must be <= 767 characters in total, including the key, equals sign, and value. If the entry is longer than this, then it will be truncated to 767 characters.
Arguments:
section a section of the config file
key key within a section
value value of a key as a string
Returns: nil
Example:
gkini.WriteString("Vendetta", "Username", "dude") -- change the Username option to dude
Notes:
- value=nil is accepted without error, but appears to do nothing.
- Unlike ReadString, leading and trailing spaces are not trimmed from values.
- Newline and equal sign characters are accepted without escaping or translation. This means you can do, for example, WriteString(section, "foo", "bar\n\n[baz]x=13") and get
foo=bar [baz] x=13
Note that this also moves the keys after "foo" to the "bar" section. For this reason, it is generally wise to avoid providing newlines or equal signs to WriteString. (This includes key; WriteString(section, "key=", "value") will create a line "key==value", which will be interpreted by ReadString as "key" and "=value", not "key=" and "value".)
