Loading

Which constructor to use is a question about your program, not the API: Loading answers it. Every constructor that reads files can also fail with the parse errors listed under reading.

from_env#

Finds the root config the way OpenMW does at startup and loads its chain: OPENMW_CONFIG, then OPENMW_CONFIG_DIR, then an openmw.cfg beside the running executable, then the global config where the platform has one. Never falls back to the user’s config by itself.

from_env_or_user_config#

from_env(), and when that fails with CannotFindRootConfig, the user’s openmw.cfg (?userconfig?/openmw.cfg) instead. Fails with CannotFindAnyConfig when that does not exist either. Every other error from from_env() is returned unchanged.

This is the constructor for tools that run outside OpenMW’s directory.

new#

Loads the chain starting at path, which is an openmw.cfg file or a directory containing one. None starts at the user’s config, ?userconfig?/openmw.cfg, which skips OpenMW’s root config: see why that matters.

A relative path is made absolute from the current directory. Symlinks are followed but not resolved: the configuration keeps the path you gave.

new_empty#

A configuration with no settings, rooted at user_config_dir/openmw.cfg. Reads nothing and needs nothing to exist. New entries are attributed to that file, and save_user() creates the directory and writes it. A relative directory is made absolute from the current directory.

Fails with NotFileOrDirectory when user_config_dir is empty or ends in openmw.cfg: it takes a directory, the place a whole family of config files would live.

load_optional#

new(Some(path)) when there is a config at path, otherwise new_empty() in the same place:

• a directory without an openmw.cfg: empty, rooted in that directory;
• a missing file named openmw.cfg: empty, rooted in its parent;
• any other missing path: empty, treating it as a directory.

Fails with NotFileOrDirectory when path is empty, and with any error new() returns when there is a config to load.

root_config_file#

The openmw.cfg the chain started at. For from_env() that is OpenMW’s root config, usually not the user’s.

root_config_dir#

The directory of root_config_file(). Panics if the root config path has no parent, which no constructor produces.

user_config_path#

The directory of the user’s config: the last config= directory in effect, whether or not it holds an openmw.cfg yet, or root_config_dir() when nothing chained. save_user() writes openmw.cfg here, and every entry the editing methods add is attributed to it. Loading creates the directory when it is missing, as OpenMW’s engine does, but writes no openmw.cfg in it.

is_user_config#

Whether the root config is the user’s config: true when nothing chained further. Paths that resolve to the same file count as equal.

user_config#

A configuration loaded from user_config_path() as load_optional() loads it, replacing this one: empty and rooted there when its openmw.cfg does not exist yet. When this configuration already starts there, it is returned unchanged. Errors are those of load_optional().

user_config_ref#

user_config() without consuming self: a new configuration loaded from the user’s config, empty when it does not exist yet, or a clone of this one when it already starts there.

Errors while reading#

Every constructor that reads files stops at the first problem, with the file and, where there is one, the line:

ConfigError lists every variant’s fields and messages.