Sublime Forum

New Unofficial Docs: Completions

#1

sublimetext.info/docs/extensibil … tions.html

0 Likes

#2

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.

0 Likes

#3

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.

0 Likes

#4

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.

0 Likes

#5

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.

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

Cheers,
Guillermo

0 Likes

#6

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.

0 Likes

#7

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:

sublimetext.info/docs/extensibil … tml#scopes

0 Likes

#8

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

0 Likes

#9

@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.

0 Likes

#10

[quote=“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).[/quote]

.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.

0 Likes

#11

What is the best way to modify or remove default snippets or completions?

Adding the canvas element to HTML can be done easily by adding it to Packages\User\HTML\HTML.sublime-completions.

However, what if I want to get rid of the frameset element defined in Packages\HTML\HTML.sublime-completions? Or if I want to change the html snippet defined in Packages\HTML\html.sublime-snippet to include a ?

If I copy html.sublime-snippet over to Packages\User\HTML and edit it there, both will exist, instead of the one in Packages\HTML being overridden. And HTML.sublime-completions from both Packages\HTML and Packages\User\HTML are in use, so even if frameset isn’t defined in Packages\HTML\HTML.sublime-completions it still exists.

Should I just edit the files directly in Packages\HTML? That doesn’t seem very clean, and won’t they get recreated on upgrade?

0 Likes

#12

If you reach a point where you need to make substantial changes to a shipped package, there aren’t many options left short of maintaining your own version.

What you could do in this case, though, is split the default HTML.sublime-completions in two files, say HTML (Main).sublime-completions and HTML (Additional).sublime-completions, and ask for them to be included in the default installation. That way you could rename one of them to deactivate the completions in it, even between upgrades.

There’s a public repo on google code for Sublime Packages. I don’t know whether it’s in sync with the packages shipped with Sublime, but it’s a starting point.

0 Likes

#13

Hm, I might have to maintain my own version, then. Many of the changes I’m interested in doing would not be of interest to anyone else.

I’ll see about contributing to the public repo. Canvas and other HTML5 elements should at least be included by default.

0 Likes