# Luakit Documentation / Modules / settings

# Module `settings`

Centralized settings system

The `settings` module provides a central place to access and modify settings for all of luakit's modules.

## Functions

### settings.register_settings (settings)

Register a table of settings. Entries in the table of settings to register should be keyed by the setting path string.

#### Parameters

- settings
  Type: {[string]=table}
  The table of settings to register.

  ##### Parameter table format

  Each value elements of the `settings` argument is in the following format:

      { type, default }

  - `type`: string, the type of the setting value. When a container, use `conatiner_name:inner_type` (the colon is the important part). Example for an array of strings: `"array:string"`
  - `default`: `type`, the default setting value when it isn't set manually

### settings.get_setting_for_view (view, key)

Retrieve the value of a setting for a webview.

This function considers, in order:

1. any view-specific overrides
2. the setting's domain-specific values
3. the setting's non-domain-specific value
4. the setting's default value

The settings key must be a valid settings key.

#### Parameters

- view
  Type: widget
  The webview.
- key
  Type: string
  The key of the setting to retrieve.

#### Return Values

- any type
  The value of the setting.

### settings.override_setting_for_view (view, key)

Add or remove a view-specific override for a setting. Passing `nil` as the `value` will clear any override.

The settings key must be a valid settings key.

#### Parameters

- view
  Type: widget
  The webview.
- key
  Type: string
  The key of the setting to override.

#### Return Values

- any type
  The new value of the setting override.

### settings.override_setting (key, The)

Add an override for a setting.

The settings key must be a valid settings key.

#### Parameters

- key
  Type: string
  The key of the setting to override.
- The
  Type: any type
  value of the setting override.

### settings.get_setting (key)

Retrieve the value of a setting, whether it's explicitly set or the default.

This does not take into account any domain-specific values.

The settings key must be a valid settings key.

#### Parameters

- key
  Type: string
  The key of the setting to retrieve.

#### Return Values

- any type
  The value of the setting.

### settings.set_setting (key, value, opts)

Assign a value to a setting. Values assigned in this way are persisted to disk, and automatically set when luakit starts.

The settings key must be a valid settings key.

#### Parameters

- key
  Type: string
  The key of the setting to retrieve.
- value
  Type: any type
  The new value of the setting.
- opts
  Type: table
  Table of options. Currently the only valid field is `domain`, which allows setting a domain-specific setting value.

### settings.get_settings ()

Retrieve information about all registered settings and their values.

#### Return Values

- table
  A table of records, one for each setting.

### settings.add_migration_warning ()

Deprecated: should be used only for existing code

Migration helper function.

### settings.migrate_global ()

Deprecated: should be used only for existing code

Migration helper function.

## Attribution

#### Copyright

- 2017 Aidan Holm