Settings

Settings is a utility class to retrieve config information from YAML files. A settings object can be created using the static method Settings.load(String) where the parameter is a path to a YAML file.

All config files are found in the settings folder. Most modules share settings.yml, considered to be the main config file. However, modules with more complex configuration needs (e.g. FAQListener, IPListener, Permissions) often use their own config files.

Methods: general management

load(String)

This is a static method to load any YAML file as a Settings object. This object is considered the "root" object, and is responsible for saving any changes made and for updating all of its children when reloaded from file.

get(String)

Finds an existing child Settings object by this name, or creates a new one, and returns it. Each module has a Settings object obtained by this.settings = Settings.settings.get(this.name);, where Settings.settings is a static field obtained by Settings.load("settings/settings.yml"). All child objects are doubly linked to their parents and singly linked to the root object they came from, which means its contents can be reloaded and its changes saved to file by any of its relatives.

reload()

Reloads this Settings object and all of its relatives. This is always handled by the root object, and any children objects are updated recursively.

save()

Saves any changes made to this Settings object or any of its relatives. This is always handled by the root object. Any changes made are not applied until save() is called.

sort()

Sorts key-value mapping of this Settings object alphabetically. This makes the assumption that all keys are comparable (e.g. all Strings or all Integers). An exception may be thrown otherwise.

Methods: getting values by key

For the following methods, the first parameter is the key, and the second parameter (if available) is the default value to use if the entry does not exist or the value is of the wrong type.

getString(Object, String)

Expects a non-null object, returns a string representation if the value is not a string. Defaults to using the second parameter if entry does not exist or the value is null.

getInt(Object, int)

Expects a 32-bit integer. Defaults to using the second parameter if entry does not exist or value is not an integer.

getBool(Object, boolean)

Expects either true or false. Defaults to using the second parameter if entry does not exist or value is not a boolean.

getDuration(Object, String)

Expects a String representing a duration expression (e.g. "1h"). Defaults to evaluating the second parameter if entry does not exist or value is not a duration expression. If the second parameter is not a valid duration expression, an exception may be thrown.

getTime(Object, String)

Expects a String that can be parsed as a LocalTime (i.e. either hh:mm or hh:mm:ss). Defaults to evaluating the second parameter if entry does not exist or value cannot be parsed as a LocalTime. If the second parameter cannot be parsed as a LocalTime, an exception may be thrown.

getPercentage(Object, double)

Expects a double or a String that can be parsed as a double with an optional percentage sign (e.g. "100.0%"). Defaults to using the second parameter if entry does not exist or value cannot be parsed as a double.

getStrings(Object, String...)

Expects a list, returns an ArrayList of Strings. Any non-null, non-string elements are converted to a string representation. Defaults to a list of all secondary parameters if entry does not exist or value is not a list.

getStringSet(Object, String...)

Expects a list, returns a HashSet of Strings. Any non-null, non-string elements are converted to a string representation. Defaults to a set of all secondary parameters if entry does not exist or value is not a list.

getMap(Object)

Expects a sequence of key:value pairs, returns a Map of Object keys and Object values. Defaults to an empty Map.