New Unofficial Docs: Completions

[guillermooo]

http://sublimetext.info/docs/extensibil ... tions.html

[rchl]

Completions are stored in Data\Packages\HTML\HTML.sublime-completions, for example.

What's the best way to extend these that will cause minimal problems when upgrading?

For example, what will happen when I modify this file and then sublime ships with updated package for HTML? Will my file be overwritten or will won't be touched but new changes won't be picked?

Using sublime 2.

[guillermooo]

I believe only Packages/User is guaranteed to be kept untouched after upgrades. Either maintain a copy of the HTML package under version control, put your completions under Packages/User, or improve the HTML package and ask Jon to update the master.

[rchl]

Ah, just putting my custom completions in user directory works fine. I thought that I've tried this before but must have done something wrong.

Question regarding initial post. What's really the difference between snippets/completions? Linked doc just briefly mentions "They can be thought of as a more flexible way to insert snippets.".

Are completions just snippets that can be defined in more compact way? Are they more limited than snippets or they provide same functionality?

I see that some snippets use {${0:$TM_SELECTED_TEXT}} variable for example. Is it possible to use them in completions? I think this does not really work right now in sublime2 so can't even test.

[guillermooo]

Question regarding initial post. What's really the difference between snippets/completions? Linked doc just briefly mentions "They can be thought of as a more flexible way to insert snippets." Are completions just snippets that can be defined in more compact way? Are they more limited than snippets or they provide same functionality?

Don't think the current wording conveys the idea very well, but I was referring more or less to what you say. There's still a few bits and pieces I need to clarify. I will update the information when I do. Snippets and completions seem to overlap in funcionality.

I see that some snippets use {${0:$TM_SELECTED_TEXT}} variable for example. Is it possible to use them in completions? I think this does not really work right now in sublime2 so can't even test.

Haven't tried myself yet, but I'll investigate and update the docs accordingly.

Cheers,
Guillermo

[indiver]

Hi

I have a question about the first line of the sublime-completions file.

"scope": "text.html - source - meta.tag, punctuation.definition.tag.begin",

I can understand that it refers to text.html scope. But what is the " - source - meta.tag, punctuation.definition.tag.begin" ?

I'm trying to make a sublime-completion file for ColdFusion, and trying to add a couple of snippets to test, and I'm not sure what goes in the first line?

Should it be:

"scope": "text.html.cfm - source - meta.tag, punctuation.definition.tag.begin",

Or something else.

Thanks.

[guillermooo]

Scopes are a contextual hint for Sublime. You can roughly see scopes as CSS selectors. Actually, what you're seeing in the completions file is a "scope selector".

Scopes work together with syntax definitions to chop text up into named regions. Thus, Sublime can know whether the caret's in a "string.quoted.double", for example. Furthermore, it can know too that you're in a "source.python" file. So the actual scope would be "string.quoted.double source.python".

Additionally, some top language scopes like "source.javascript" might be nested within another source language or markup language ("text.html"). If you wanted to target "text.html", but not when you're within a script tag (which would add "source.js" to the scope hierarchy), you want to exclude them. The "text.html - source" selector does that: it targets everything where "text.html" matches except where "source" matches too.

Commas in scope selectors add "or" conditions: match "text.html - source" or "punctuation.definition.tag.begin".

I might have got something wrong here, but that's the gist of it: you're refining what regions to target.

More:

http://sublimetext.info/docs/extensibil ... tml#scopes

[jps]

Also handy is the show_scope_name command (Ctrl+Alt+P on Windows and Linux, Command+Option+P on OSX) will show the current scope in the status bar

[indiver]

@guillermooo

Thanks that is a good explanation. I think I understand. However, can I put in a request for some more examples on the completions page. It would make it easier to follow. Also, if there is an example showing a completion based on a TextMate snippets. Will make it easier for people to understand what is going (esp. people like me who are coming from TextMate and want to do more in Sublime).

The link explaining source and source selectors is great.

@jps

That is a great shortcut. Thanks.

[guillermooo]

@guillermooo

Thanks that is a good explanation. I think I understand. However, can I put in a request for some more examples on the completions page. It would make it easier to follow. Also, if there is an example showing a completion based on a TextMate snippets. Will make it easier for people to understand what is going (esp. people like me who are coming from TextMate and want to do more in Sublime).

.sublime-completions files are a brand new feature of Sublime, and I'm struggling myself to make them fit among snippets, key bindings, etc., but I'll see what I can do! Thanks for your feedback.