While trying to write my own snippets for Sublime Text 2, I ran into the following two problems:
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.
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>
View Current Scope of Cursor Position
- Place your cursor in the file where you wish to know the scope.
Use this keyboard-shortcut:
Windows: ctrl+shift+alt+p
Mac: ctrl+shift+p
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.
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.
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.
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.
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