core.settings module

Configuration and raw manipulation for Dwarf Fortress.

class core.settings.DFConfiguration(base_dir, df_info)

Bases: object

Reads and modifies Dwarf Fortress configuration textfiles.

create_file(filename, fields)

Create a new file containing the specified fields.

Parameters:

• filename – name of the file to write.

• fields – list of all field names to write.

create_option(name, field_name, default, values, files, cond=True, validate=None)

Register an option to write back for changes. If the field_name has been registered before, no changes are made. Fields that do not exist in the current DF version are simply registered with a field name mapping, but they will not be expected in the init files.

Parameters:

• name – The name you want to use to refer to this field (becomes available as an attribute on this class).

• field_name – The field name used in the file. If this is different from the name argument, this will also become available as an attribute.

• default – The value to initialize this setting to.

• values –

  An iterable of valid values for this field. Used in cycle_list. Special values defined in this file:

  None:

  Unspecified value; cycling has no effect.

  _disabled:

  Boolean option toggled by replacing the [] around the field name with !!.

  force_bool:

  Values other than “YES” and “NO” are interpreted as “YES”.

• files – A tuple of files this value is read from. Used for e.g. aquifer toggling, which requires editing multiple files.

• cond (bool) – If True, the field will be treated as valid. If False, this will merely register the field name mapping. Defaults to True.

• validate – An optional function(x) which may be used to validate a value for this field. Will be sent the value as parameter, must return a tuple (ok, errormsg).

cycle_item(name)

Cycle the setting <name>.

Parameters:

name – name of the setting to cycle.

static cycle_list(current, items)

Cycles setting between a list of items.

Parameters:

• current – current value.

• items – list of possible values (optionally a special value).

Returns:

If no list of values is given, returns current. If the current value is the last value in the list, or the value does not exist in the list, returns the first value in the list. Otherwise, returns the value from items immediately following the current value.

static has_field(filename, field, num_params=-1, min_params=-1, max_params=-1)

Returns True if <field> exists in <filename> and has the specified number of parameters.

Parameters:

• filename – the file to check.

• field – the field to look for.

• num_params – the exact number of parameters for the field. -1 for no limit.

• min_params – the minimum number of parameters for the field. -1 for no limit.

• max_params – the maximum number of parameters for the field. -1 for no limit.

read_file(filename, fields, auto_add, auto_add_key=None)

Reads DF settings from the file <filename>.

Parameters:

• filename – the file to read from.

• fields – an iterable containing the field names to read.

• auto_add – whether to automatically register all unknown fields for changes.

• auto_add_key – key to register the fields under (if auto_add is True).

read_settings()

Read settings from known filesets. If fileset only contains one file ending with “init.txt”, all options will be registered automatically.

set_value(name, value)

Sets the setting <name> to <value>.

Parameters:

• name – name of the setting to alter.

• value – new value for the setting.

update_file(filename, fields)

Write settings to a specific file.

Parameters:

• filename – name of the file to write.

• fields – list of all field names to change.

validate_config()

Checks if all settings are set to valid values. Returns a list of strings with error messages.

validate_truetype(value)

Validates the Truetype setting.

version_has_option(option_name)

Returns True if <option_name> exists in the current DF version.

write_settings()

Write all settings to their respective files.