Language Specific Configuration Settings
October 31, 2014 benogle
Update: The
scoped-properties
directory in language packages is now namedsettings
. See themaster
branch of the language-gfm and language-python packages for the latest examples.
Previously Atom had no way to set language-specific configuration settings without a package. Language-specific settings are now built in . For example, you may want Atom to soft wrap markdown files, have two-space tabs for ruby files, and four-space tabs for python files.
There are several settings now scoped to an editor’s language. Here is the list so far:
editor.tabLength
editor.softWrap
editor.softWrapAtPreferredLineLength
editor.preferredLineLength
editor.scrollPastEnd
editor.showInvisibles
editor.showIndentGuide
editor.nonWordCharacters
editor.invisibles
editor.autoIndent
editor.normalizeIndentOnPaste
Language-specific Settings in the Settings View
Now you can edit these config settings in the settings view on a per-language basis. Just search for the language of your choice in the left panel, select it, and edit away!
Language-specific Settings in your Config File
Open your config file via the command palette (cmd-shift-p
or ctrl-shift-p
for windows / linux), type open config
, and hit enter.
Global settings are now under a global
key, and each language can have its own top-level key. This key is the language’s scope. Language-specific settings override anything set in the global
section.
'global': # all languages unless overridden
'editor':
'softWrap': false
'tabLength': 8
'.source.gfm': # markdown overrides
'editor':
'softWrap': true
'.source.ruby': # ruby overrides
'editor':
'tabLength': 2
'.source.python': # python overrides
'editor':
'tabLength': 4
Finding a language’s scope name
The scope name is shown in the settings view for each language. Search for the language of your choice in the left panel, select it, and you should see the scope name under the language name heading:
Using in your own packages
You can use scoped settings in your own packages. Config::get now accepts a scopeDescriptor
and Config::set accepts a scopeSelector
. See the the scopes docs to learn more about scopes.
The simplest way to implement language specific settings is to get
your setting with the language scope descriptor — the editor’s root scope descriptor.
# Falls back to a global value if no language specific value is defined.
atom.config.get(editor.getRootScopeDescriptor(), 'my-package.my-setting')
You can watch for changes on a given keyPath for a scope with Config::observe.
atom.config.observe editor.getRootScopeDescriptor(), 'my-package.my-setting', (value) ->
# do stuff
When watching for changes to a config setting for a given scope, you should take grammar changes into account.
editor = atom.workspace.getActiveTextEditor()
subscription = null
editor.observeGrammar (grammar) ->
subscription?.dispose()
# re-observe the setting when the grammar is changed.
subscription = atom.config.observe editor.getRootScopeDescriptor(), 'my-package.my-setting', (value) ->
# do stuff
Language defaults
A language grammar can provide language-specific defaults. For example, the Markdown grammar now defaults editor.softWrap
to true
in its scoped-properties file, and Python now has a default tab length of 4.
Conclusion
We hope this improves the editing experience to all of you who regularly use a variety of languages!