+
+ Config
+Summary
+Used to access all of N1's configuration details.
+An instance of this class is always available as the NylasEnv.config global.
+Getting and setting config settings.
+
+NylasEnv.config.get('my-package.myKey')
+
+NylasEnv.config.set('my-package.myKey', 'value')
+NylasEnv.config.get('my-package.myKey')
+
+You may want to watch for changes. Use observe to catch changes to the setting.
+NylasEnv.config.set('my-package.myKey', 'value')
+NylasEnv.config.observe 'my-package.myKey', (newValue) ->
+
+ console.log 'My configuration changed:', newValue
+
+If you want a notification only when the value changes, use onDidChange.
+NylasEnv.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:
+
+NylasEnv.config.get('my-package.anInt')
+
+
+NylasEnv.config.set('my-package.anInt', '123')
+NylasEnv.config.get('my-package.anInt')
+
+
+NylasEnv.config.set('my-package.anInt', '-20')
+NylasEnv.config.get('my-package.anInt')
+
+Defining settings for your package
+Define a schema under a config key in your package main.
+module.exports =
+
+ config:
+ someInt:
+ type: 'integer'
+ default: 23
+ minimum: 1
+
+ activate: (state) ->
+
+
+Config Schemas
+We use json schema which allows you to define your value's
+default, the type it should be, etc. A simple example:
+
+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.
+NylasEnv.config.set('my-package.thingVolume', '10')
+NylasEnv.config.get('my-package.thingVolume')
+
+
+NylasEnv.config.set('my-package.thingVolume', '400')
+NylasEnv.config.get('my-package.thingVolume')
+
+
+NylasEnv.config.set('my-package.thingVolume', 'cats')
+NylasEnv.config.get('my-package.thingVolume')
+
+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
+
+
+NylasEnv.config.set('my-package.someSetting', 'true')
+NylasEnv.config.get('my-package.someSetting')
+
+NylasEnv.config.set('my-package.someSetting', '12')
+NylasEnv.config.get('my-package.someSetting')
+
+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:
+NylasEnv.config.set('my-package.someSetting', '2')
+NylasEnv.config.get('my-package.someSetting')
+
+
+NylasEnv.config.set('my-package.someSetting', '3')
+NylasEnv.config.get('my-package.someSetting')
+
+
+NylasEnv.config.set('my-package.someSetting', '4')
+NylasEnv.config.get('my-package.someSetting')
+
+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.
+
+
+
+
+
+
+
+
+
+Instance Methods
+
+ observe(keyPathcallback)
+
+
+
+
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
+
+```coffee
+NylasEnv.config.observe 'core.themes', (value) ->
+ # do stuff with value
+```
+
Parameters
+
+
+ | Argument |
+ Description |
+
+
+ |
+ keyPath
+ |
+
+
+ {String} name of the key to observe
+ |
+
+
+ |
+ 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]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.
+ |
+
+
+ |
+ 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)
+
+
+
+
Retrieves the setting for the given key.
+
+### Examples
+
+You might want to know what themes are enabled, so check `core.themes`
+
+```coffee
+NylasEnv.config.get('core.themes')
+```
+
+
+ | Argument |
+ Description |
+
+
+ |
+ keyPath
+ |
+
+
+ The {String} name of the key to retrieve.
+ |
+
+
+
+Returns
+
+
+ | Return Values |
+
+ | Returns the value from N1's default settings, the user's configuration
+file in the type specified by the configuration schema. |
+
+
+ set(keyPathvalue)
+
+
+
+
Sets the value for a configuration setting.
+
+This value is stored in N1's internal configuration file.
+
+### Examples
+
+You might want to change the themes programmatically:
+
+```coffee
+NylasEnv.config.set('core.themes', ['ui-light', 'my-custom-theme'])
+```
+
+
+ | 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.
+ |
+
+
+
+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.
+
+
+ | Argument |
+ Description |
+
+
+ |
+ keyPath
+ |
+
+
+ The {String} name of the key.
+ |
+
+
+ |
+ options
+ |
+
+ Optional
+ {Object}
+ |
+
+
+
+
+ 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. |
+
+
+ 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.
+ |
+
+
+
+
+
+
+