• Packages
  • Themes
  • Documentation
  • Blog
  • Discuss
Sign in
Whoops, there was an error
v1.26.1
v1.26.0
v1.25.1
v1.25.0
v1.24.1
v1.24.0
v1.23.3
v1.23.2
v1.23.1
v1.23.0
v1.22.1
v1.22.0
v1.21.2
v1.21.1
v1.21.0
v1.20.1
v1.20.0
v1.19.7
v1.19.6
v1.19.5
v1.19.4
v1.19.3
v1.19.2
v1.19.1
v1.19.0
v1.18.0
v1.17.2
v1.17.1
v1.17.0
v1.16.0
v1.15.0
v1.14.4
v1.14.3
v1.14.2
v1.14.1
v1.14.0
v1.13.1
v1.13.0
v1.12.9
v1.12.8
v1.12.7
v1.12.6
v1.12.5
v1.12.4
v1.12.3
v1.12.2
v1.12.1
v1.12.0
v1.11.2
v1.11.1
v1.11.0
v1.10.2
v1.10.1
v1.10.0
v1.9.9
v1.9.8
v1.9.7
v1.9.6
v1.9.5
v1.9.4
v1.9.3
v1.9.2
v1.9.1
v1.9.0
v1.8.0
v1.7.4
v1.7.3
v1.7.2
v1.7.1
v1.7.0
v1.6.2
v1.6.1
v1.6.0
v1.5.4
v1.5.3
v1.5.2
v1.5.1
v1.5.0
v1.4.3
v1.4.2
v1.4.1
v1.4.0
v1.3.3
v1.3.2
v1.3.1
v1.3.0
v1.2.4
v1.2.3
v1.2.2
v1.2.1
v1.2.0
v1.1.0
v1.0.19
v1.0.18
v1.0.17
v1.0.16
v1.0.15
v1.0.14
v1.0.13
v1.0.12
v1.0.11
v1.0.10
v1.0.9
v1.0.8
v1.0.7
v1.0.6
v1.0.5
v1.0.4
v1.0.3
v1.0.2
v1.0.1
v1.0.0
v0.211.0
v0.210.0
v0.209.0
v0.208.0
v0.207.0
v0.206.0
v0.205.0
v0.204.0
v0.203.0
v0.202.0
v0.201.0
v0.200.0
v0.199.0
v0.198.0
v0.197.0
v0.196.0
v0.195.0
v0.194.0
v0.193.0
v0.192.0
v0.191.0
v0.190.0
v0.189.0
v0.188.0
v0.187.0
Loading…

Essential Classes

  • Atom
  • Color
  • CommandRegistry
  • CompositeDisposable
  • Config
  • Decoration
  • Disposable
  • Emitter
  • Marker
  • Point
  • Range
  • TextEditor
  • TooltipManager
  • ViewRegistry
  • Workspace

Extended Classes

  • BufferedNodeProcess
  • BufferedProcess
  • Clipboard
  • ContextMenuManager
  • Cursor
  • DeserializerManager
  • Directory
  • File
  • GitRepository
  • Grammar
  • GrammarRegistry
  • KeymapManager
  • MenuManager
  • PackageManager
  • Pane
  • Panel
  • Project
  • ScopeDescriptor
  • Selection
  • StyleManager
  • Task
  • TextBuffer
  • ThemeManager

Config essential

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

  • Don't depend on (or write to) configuration keys outside of your keypath.

Config Subscription

::observe(keyPath, options, callback)

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 
Argument Description
keyPath

String name of the key to observe

options

Object

.scopeDescriptor optional

ScopeDescriptor describing a path from the root of the syntax tree to a token. Get one by calling {editor.getLastCursor().getScopeDescriptor()}. See ::get for examples. See the scopes docs for more information.

callback(value)

Function to call when the value of the key changes.

value

the new value of the key

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.

Argument Description
keyPath optional

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

optional optional

Object

.scopeDescriptor optional

ScopeDescriptor describing a path from the root of the syntax tree to a token. Get one by calling {editor.getLastCursor().getScopeDescriptor()}. See ::get for examples. See the scopes docs for more information.

callback(event)

Function to call when the value of the key changes.

event

Object

.newValue

the new value of the key

.oldValue

the prior value of the key.

.keyPath

the keyPath of the changed key

Return values

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

Managing Settings

::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 
Argument Description
keyPath

The String name of the key to retrieve.

options optional

Object

.sources optional

Array of String source names. If provided, only values that were associated with these sources during ::set will be used.

.excludeSources optional

Array of String source names. If provided, values that were associated with these sources during ::set will not be used.

.scope optional

ScopeDescriptor describing a path from the root of the syntax tree to a token. Get one by calling {editor.getLastCursor().getScopeDescriptor()} See the scopes docs for more information.

Return values

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

::set(keyPath, value, [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', ['atom-light-ui', '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 
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

.scopeSelector optional

String. eg. '.source.ruby' See the scopes docs for more information.

.source optional

String The name of a file with which the setting is associated. Defaults to the user's config file.

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.

Argument Description
keyPath

The String name of the key.

options optional

Object

.scopeSelector optional

String. See ::set

.source optional

String. See ::set

Extended Methods

::getAll(keyPath, [options])

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

Argument Description
keyPath

The String name of the key to retrieve

options optional

Object see the options argument to ::get

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

::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.

Argument Description
keyPath

The String name of the key.

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.

Argument Description
callback()

Function to execute while suppressing calls to handlers.

  • Terms of Use
  • Privacy
  • Code of Conduct
  • Releases
  • FAQ
  • Contact
with by