--- layout: docs title: Config edit_url: "https://github.com/nylas/N1/blob/master/src/config.coffee" ---

Summary

Used to access all of Atom's configuration details.

An instance of this class is always available as the atom.config global.

Getting and setting config settings.

# Note that with no value set, ::get returns the setting's default value.
atom.config.get('my-package.myKey') # -> 'defaultValue'

atom.config.set('my-package.myKey', 'value')
atom.config.get('my-package.myKey') # -> 'value'

You may want to watch for changes. Use observe to catch changes to the setting.

atom.config.set('my-package.myKey', 'value')
atom.config.observe 'my-package.myKey', (newValue) ->
  # `observe` calls immediately and every time the value is changed
  console.log 'My configuration changed:', newValue

If you want a notification only when the value changes, use onDidChange.

atom.config.onDidChange 'my-package.myKey', ({newValue, oldValue}) ->
  console.log 'My configuration changed:', newValue, oldValue

Value Coercion

Config settings each have a type specified by way of a schema. For example we might an integer setting that only allows integers greater than 0:

# When no value has been set, `::get` returns the setting's default value
atom.config.get('my-package.anInt') # -> 12

# The string will be coerced to the integer 123
atom.config.set('my-package.anInt', '123')
atom.config.get('my-package.anInt') # -> 123

# The string will be coerced to an integer, but it must be greater than 0, so is set to 1
atom.config.set('my-package.anInt', '-20')
atom.config.get('my-package.anInt') # -> 1

Defining settings for your package

Define a schema under a config key in your package main.

module.exports =
  # Your config schema
  config:
    someInt:
      type: 'integer'
      default: 23
      minimum: 1

  activate: (state) -> # ...
  # ...

See Creating a Package for more info.

Config Schemas

We use json schema which allows you to define your value's default, the type it should be, etc. A simple example:

# We want to provide an `enableThing`, and a `thingVolume`
config:
  enableThing:
    type: 'boolean'
    default: false
  thingVolume:
    type: 'integer'
    default: 5
    minimum: 1
    maximum: 11

The type keyword allows for type coercion and validation. If a thingVolume is set to a string '10', it will be coerced into an integer.

atom.config.set('my-package.thingVolume', '10')
atom.config.get('my-package.thingVolume') # -> 10

# It respects the min / max
atom.config.set('my-package.thingVolume', '400')
atom.config.get('my-package.thingVolume') # -> 11

# If it cannot be coerced, the value will not be set
atom.config.set('my-package.thingVolume', 'cats')
atom.config.get('my-package.thingVolume') # -> 11

Supported Types

The type keyword can be a string with any one of the following. You can also chain them by specifying multiple in an an array. For example

config:
  someSetting:
    type: ['boolean', 'integer']
    default: 5

# Then
atom.config.set('my-package.someSetting', 'true')
atom.config.get('my-package.someSetting') # -> true

atom.config.set('my-package.someSetting', '12')
atom.config.get('my-package.someSetting') # -> 12

string

Values must be a string.

config:
  someSetting:
    type: 'string'
    default: 'hello'

integer

Values will be coerced into integer. Supports the (optional) minimum and maximum keys.

  config:
    someSetting:
      type: 'integer'
      default: 5
      minimum: 1
      maximum: 11

number

Values will be coerced into a number, including real numbers. Supports the (optional) minimum and maximum keys.

config:
  someSetting:
    type: 'number'
    default: 5.3
    minimum: 1.5
    maximum: 11.5

boolean

Values will be coerced into a Boolean. 'true' and 'false' will be coerced into a boolean. Numbers, arrays, objects, and anything else will not be coerced.

config:
  someSetting:
    type: 'boolean'
    default: false

array

Value must be an Array. The types of the values can be specified by a subschema in the items key.

config:
  someSetting:
    type: 'array'
    default: [1, 2, 3]
    items:
      type: 'integer'
      minimum: 1.5
      maximum: 11.5

object

Value must be an object. This allows you to nest config options. Sub options must be under a properties key

config:
  someSetting:
    type: 'object'
    properties:
      myChildIntOption:
        type: 'integer'
        minimum: 1.5
        maximum: 11.5

color

Values will be coerced into a Color with red, green, blue, and alpha properties that all have numeric values. red, green, blue will be in the range 0 to 255 and value will be in the range 0 to 1. Values can be any valid CSS color format such as #abc, #abcdef, white, rgb(50, 100, 150), and rgba(25, 75, 125, .75).

config:
  someSetting:
    type: 'color'
    default: 'white'

Other Supported Keys

enum

All types support an enum key. The enum key lets you specify all values that the config setting can possibly be. enum must be an array of values of your specified type. Schema:

config:
  someSetting:
    type: 'integer'
    default: 4
    enum: [2, 4, 6, 8]

Usage:

atom.config.set('my-package.someSetting', '2')
atom.config.get('my-package.someSetting') # -> 2

# will not set values outside of the enum values
atom.config.set('my-package.someSetting', '3')
atom.config.get('my-package.someSetting') # -> 2

# If it cannot be coerced, the value will not be set
atom.config.set('my-package.someSetting', '4')
atom.config.get('my-package.someSetting') # -> 4

title and description

The settings view will use the title and description keys to display your config setting in a readable way. By default the settings view humanizes your config key, so someSetting becomes Some Setting. In some cases, this is confusing for users, and a more descriptive title is useful.

Descriptions will be displayed below the title in the settings view.

config:
  someSetting:
    title: 'Setting Magnitude'
    description: 'This will affect the blah and the other blah'
    type: 'integer'
    default: 4

Note: You should strive to be so clear in your naming of the setting that you do not need to specify a title or description!

Best practices

Instance Methods

observe(keyPathoptionscallback)

Add a listener for changes to a given key path. This is different than onDidChange in that it will immediately call your callback with the current value of the config entry.

Examples

You might want to be notified when the themes change. We'll watch core.themes for changes

atom.config.observe 'core.themes', (value) ->
      # do stuff with value

Parameters
Argument Description
keyPath

String name of the key to observe
options

Object
callback

Function to call when the value of the key changes.
Returns
Return Values

Returns a {Disposable} with the following keys on which you can call .dispose() to unsubscribe.

onDidChange([keyPath][optional]callback)

Add a listener for changes to a given key path. If keyPath is not specified, your callback will be called on changes to any key.

Parameters
Argument Description
keyPath Optional

String name of the key to observe. Must be specified if scopeDescriptor is specified.
optional Optional

Object
callback

Function to call when the value of the key changes.
Returns
Return Values

Returns a {Disposable} with the following keys on which you can call .dispose() to unsubscribe.

get(keyPath[options])

Retrieves the setting for the given key.

Examples

You might want to know what themes are enabled, so check core.themes

atom.config.get('core.themes')

With scope descriptors you can get settings within a specific editor scope. For example, you might want to know editor.tabLength for ruby files.

atom.config.get('editor.tabLength', scope: ['source.ruby']) # => 2

This setting in ruby files might be different than the global tabLength setting

atom.config.get('editor.tabLength') # => 4
    atom.config.get('editor.tabLength', scope: ['source.ruby']) # => 2

You can get the language scope descriptor via TextEditor::getRootScopeDescriptor. This will get the setting specifically for the editor's language.

atom.config.get('editor.tabLength', scope: @editor.getRootScopeDescriptor()) # => 2

Additionally, you can get the setting at the specific cursor position.

scopeDescriptor = @editor.getLastCursor().getScopeDescriptor()
    atom.config.get('editor.tabLength', scope: scopeDescriptor) # => 2

Parameters
Argument Description
keyPath

The String name of the key to retrieve.
options Optional

Object
Returns
Return Values

Returns the value from Atom's default settings, the user's configuration file in the type specified by the configuration schema.

getAll(keyPath[options])

Get all of the values for the given key-path, along with their associated scope selector.

Parameters
Argument Description
keyPath

The String name of the key to retrieve
options Optional

Object see the options argument to get
Returns
Return Values

Returns an Array of Objects with the following keys:

  • scopeDescriptor The ScopeDescriptor with which the value is associated
  • value The value for the key-path

set(keyPathvalue[options])

Sets the value for a configuration setting.

This value is stored in Atom's internal configuration file.

Examples

You might want to change the themes programmatically:

atom.config.set('core.themes', ['ui-light', 'atom-light-syntax'])

You can also set scoped settings. For example, you might want change the editor.tabLength only for ruby files.

atom.config.get('editor.tabLength') # => 4
    atom.config.get('editor.tabLength', scope: ['source.ruby']) # => 4
    atom.config.get('editor.tabLength', scope: ['source.js']) # => 4

    # Set ruby to 2
    atom.config.set('editor.tabLength', 2, scopeSelector: 'source.ruby') # => true

    # Notice it's only set to 2 in the case of ruby
    atom.config.get('editor.tabLength') # => 4
    atom.config.get('editor.tabLength', scope: ['source.ruby']) # => 2
    atom.config.get('editor.tabLength', scope: ['source.js']) # => 4

Parameters
Argument Description
keyPath

The String name of the key.
value

The value of the setting. Passing undefined will revert the setting to the default value.
options Optional

Object
Returns
Return Values

Returns a Boolean

  • true if the value was set.
  • false if the value was not able to be coerced to the type specified in the setting's schema.

unset(keyPath[options])

Restore the setting at keyPath to its default value.

Parameters
Argument Description
keyPath

The String name of the key.
options Optional

Object

getSources()

Get an Array of all of the source Strings with which settings have been added via set.

getSchema(keyPath)

Retrieve the schema for a specific key path. The schema will tell you what type the keyPath expects, and other metadata about the config option.

Parameters
Argument Description
keyPath

The String name of the key.
Returns
Return Values

Returns an Object eg. {type: 'integer', default: 23, minimum: 1}.

Returns null when the keyPath has no schema specified.

getUserConfigPath()

Get the String path to the config file being used.

transact(callback)

Suppress calls to handler functions registered with onDidChange and observe for the duration of callback. After callback executes, handlers will be called once if the value for their key-path has changed.

Parameters
Argument Description
callback

Function to execute while suppressing calls to handlers.