Defining scope for custom Sublime Text 2 snippets

Question

While trying to write my own snippets for Sublime Text 2, I ran into the following two problems:

1. Finding scope keys. I figured out that I can look through my packages one by one and find references to a declared "scope" property. For example in ~/Library/Application Support/Sublime Text 2/Packages/JavaScript/Comments.tmPreferences (a file in my HTML package) there's these two lines:

   <key>scope</key>
   <string>source.js</string>
   

   So if I want my current snippet to work on javascript files, I define my scope like:

   <scope>source.js</scope>
   

   I'm assuming all these scope keys are defined on-the-fly based on what Packages I have installed. Does Sublime Text build a list anywhere that I can more easily reference? Perusing through a bunch of package files seems overly tedious.

2. Defining multiple scope properties. This I've figured out, and the following line allows my snippet to work in both HTML and JavaScript files.

   <scope>text.html, source.js</scope>
   

Answer 1

To answer, #1, look in the syntax's .tmLanguage file, look for the key: scopeName. This is what the syntax uses for the snippet's scope value.

For example, an excerpt from nathos / sass-textmate-bundle

<key>scopeName</key>
<string>source.sass</string>

So you would use source.sass in your snippet.

Here is more info on defining a syntax

Answer 2

Here is a list of scopes to use in Sublime Text 2 snippets -

ActionScript: source.actionscript.2
AppleScript: source.applescript
ASP: source.asp
Batch FIle: source.dosbatch
C#: source.cs
C++: source.c++
Clojure: source.clojure
CoffeeScript: source.coffee
CSS: source.css
D: source.d
Diff: source.diff
Erlang: source.erlang
Go: source.go
GraphViz: source.dot
Groovy: source.groovy
Haskell: source.haskell
HTML: text.html(.basic)
JSP: text.html.jsp
Java: source.java
Java Properties: source.java-props
Java Doc: text.html.javadoc
JSON: source.json
Javascript: source.js
BibTex: source.bibtex
Latex Log: text.log.latex
Latex Memoir: text.tex.latex.memoir
Latex: text.tex.latex
LESS: source.css.less
TeX: text.tex
Lisp: source.lisp
Lua: source.lua
MakeFile: source.makefile
Markdown: text.html.markdown
Multi Markdown: text.html.markdown.multimarkdown
Matlab: source.matlab
Objective-C: source.objc
Objective-C++: source.objc++
OCaml campl4: source.camlp4.ocaml
OCaml: source.ocaml
OCamllex: source.ocamllex
Perl: source.perl
PHP: source.php
Regular Expression(python): source.regexp.python
Python: source.python
R Console: source.r-console
R: source.r
Ruby on Rails: source.ruby.rails
Ruby HAML: text.haml
SQL(Ruby): source.sql.ruby
Regular Expression: source.regexp
RestructuredText: text.restructuredtext
Ruby: source.ruby
SASS: source.sass
Scala: source.scala
Shell Script: source.shell
SQL: source.sql
Stylus: source.stylus
TCL: source.tcl
HTML(TCL): text.html.tcl
Plain text: text.plain
Textile: text.html.textile
XML: text.xml
XSL: text.xml.xsl
YAML: source.yaml

If anything is missing, add it in this gist https://gist.github.com/4705378.

Answer 3

Actually, you can use the Ctrl+Alt+Shift+P (without using Scope Hunter) and it will show you the scope on the bottom bar on the left side right after the Col/Line information. It's pretty small print but it's there.

Answer 4

View Current Scope of Cursor Position

1. Place your cursor in the file where you wish to know the scope.

2. Use this keyboard-shortcut:

   Windows: ctrl+shift+alt+p
   Mac: ctrl+shift+p

3. The current scope will be displayed in the left side of the status bar on Windows, or in a popup window on Mac.

Use these as the <scope> key in your foo.sublime-snippet file.

The returned scopes are listed generic to specific. Choose the scope(s) which best "scoped" the snippet to where it should be available to tab trigger.

Answer 5

There's a package called Scope Hunter, by Isaac Muse, which is really helpful for this.

It can show you the scope under any cursor in a document, which I've found really helpful when debugging my own snippets. Sometimes it's very detailed; a sample scope from my frontmost document:

Scope: text.tex.latex
       meta.function.environment.list.latex
       meta.function.environment.general.latex
       meta.function.environment.math.latex
       string.other.math.block.environment.latex
       meta.group.braces.tex
       meta.space-after-command.latex

(Wrapped for ease of reading)

I wouldn't have been able to find that if I spent a week picking SL2 apart, but this package gets it in seconds. Highly recommended.

This level of detail also means that you can define snippets in a very granular way, if you want. For example, the meta.function.environment.list.latex corresponds broadly to lists in LaTeX, so I have a snippet that inserts a new \item when I press super+enter in a list environment, but nobody else. I can target snippets much more effectively than with blind guesswork.

The source code is in Github, or you can install it through Package Control.