Atom data-grammar syntax for keybindings

Question

Can someone give a full explanation of the syntax for Atom's data-grammar attribute (used in keybinding selectors)?

For instance, what is the difference between

[data-grammar='source example']

and

[data-grammar~='source example']

?

Also, how do you specify multiple grammars? For instance, how would you specify that a key binding should be limited to html or xml formats?

If there already exists documentation on this somewhere, I have not yet found it, but would appreciate being pointed to it.

Answer 1

Quick Example:

keymap.cson:

"atom-text-editor[data-grammar='text tex latex']":
  'f5':'latex:build'

Grammar Information & Documentation

I began by looking at the file-types package. source and text categorize languages - source deals with development languages, while text deals with documentation/logs formats. You can add and customize language recognition by reading the flight manual. I've linked some specific sections below that are helpful for that.

Flight Manual | Basic Customization:

Language Recognition

Language Specific Settings

Working with [data-grammar]:

The little doocumentation given is listed under the Keymaps in Depth section.

Flight Manual | Keymaps in Depth

Selectors and Custom Packages.

This also describes the not([...]) functionality used below and how to manipulate various rules.

Although in the above, grammars are listed in a dot format, ie source.c, to use them in the [data-grammar='<name>'] format spaces are instead required.

An example of how I might use the data grammar option in my keymap.cson config is as such (here I'm using the latex package):

"atom-text-editor[data-grammar='text tex latex']":
  'f5':'latex:build'

The ~ is not the correct syntax for desired functionality with data-grammar. Instead, use something like "atom-text-editor:not([data-grammar='<name>'])":

Note that you wouldn't use data-grammar in something like config.cson. The syntax for language specifics looks something like this instead:

# **config.cson**
".latex.tex.text":
  editor:
    softWrap: true

Extra useful information - List of registered Grammars

A dump of the output of Object.keys(atom.grammars.grammarsByScopeName).sort().join('\n') through the Dev Console (View > Developer > Toggle Developer Options > Console)

source.c
source.cake
source.clojure
source.coffee
source.cpp
source.cs
source.css
source.css.less
source.css.scss
source.csx
source.diff
source.gfm
source.git-config
source.go
source.gotemplate
source.java
source.java-properties
source.js
source.js.rails source.js.jquery
source.js.regexp
source.js.regexp.replacement
source.json
source.litcoffee
source.makefile
source.nant-build
source.objc
source.objcpp
source.perl
source.perl6
source.plist
source.python
source.python.django
source.regexp.python
source.ruby
source.ruby.gemfile
source.ruby.rails
source.ruby.rails.rjs
source.sass
source.shell
source.sql
source.sql.mustache
source.sql.ruby
source.strings
source.toml
source.verilog
source.yaml
text.bibtex
text.git-commit
text.git-rebase
text.html.basic
text.html.erb
text.html.gohtml
text.html.jsp
text.html.mustache
text.html.php
text.html.ruby
text.hyperlink
text.junit-test-report
text.log.latex
text.plain
text.plain.null-grammar
text.python.console
text.python.traceback
text.shell-session
text.tex
text.tex.latex
text.tex.latex.beamer
text.tex.latex.memoir
text.todo
text.xml
text.xml.plist
text.xml.xsl

Answer 2

To complement Mr G's answer, atom-text-editor[data-grammar~='html'] with the ~= means match an <atom-text-editor> HTML element with a data-grammar attribute that contains "html" amongst any other possible whitespace separated words.

For example, if the current language of the file is PHP, then the text-editor HTML element will look something like this:

<atom-text-editor data-grammar="text html php">

And atom-text-editor[data-grammar~='html'] will match this.

More info on attribute selectors: https://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors

As for trying to select multiple grammars, I don't think it's possible unless they share a common word in the data-grammar attribute, e.g., both HTML and PHP share "html", or both C and JavaScript share "source" (but in this case many other grammars share "source"). The only other way is to specify a keymap for each grammar individually even if it's the same key combination.