Home Download Buy Blog Forum Support

New Unofficial Docs: Completions

New Unofficial Docs: Completions

Postby guillermooo on Sun Mar 06, 2011 3:24 pm

guillermooo
 
Posts: 729
Joined: Thu Jul 23, 2009 9:06 am

Re: New Unofficial Docs: Completions

Postby rchl on Sun Mar 06, 2011 6:10 pm

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.
rchl
 
Posts: 148
Joined: Fri Mar 04, 2011 11:02 pm

Re: New Unofficial Docs: Completions

Postby guillermooo on Sun Mar 06, 2011 6:26 pm

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.
guillermooo
 
Posts: 729
Joined: Thu Jul 23, 2009 9:06 am

Re: New Unofficial Docs: Completions

Postby rchl on Sun Mar 06, 2011 6:47 pm

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.
rchl
 
Posts: 148
Joined: Fri Mar 04, 2011 11:02 pm

Re: New Unofficial Docs: Completions

Postby guillermooo on Sun Mar 06, 2011 7:52 pm

rchl wrote: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.

rchl wrote: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
guillermooo
 
Posts: 729
Joined: Thu Jul 23, 2009 9:06 am

Re: New Unofficial Docs: Completions

Postby indiver on Tue Mar 08, 2011 9:43 am

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.
indiver
 
Posts: 30
Joined: Fri Mar 04, 2011 5:40 am
Location: Auckland, New Zealand

Re: New Unofficial Docs: Completions

Postby guillermooo on Tue Mar 08, 2011 10:03 am

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
guillermooo
 
Posts: 729
Joined: Thu Jul 23, 2009 9:06 am

Re: New Unofficial Docs: Completions

Postby jps on Tue Mar 08, 2011 11:17 am

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
jps
Site Admin
 
Posts: 3071
Joined: Wed Mar 19, 2008 12:33 pm

Re: New Unofficial Docs: Completions

Postby indiver on Tue Mar 08, 2011 5:41 pm

@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.
indiver
 
Posts: 30
Joined: Fri Mar 04, 2011 5:40 am
Location: Auckland, New Zealand

Re: New Unofficial Docs: Completions

Postby guillermooo on Tue Mar 08, 2011 7:04 pm

indiver wrote:@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.
guillermooo
 
Posts: 729
Joined: Thu Jul 23, 2009 9:06 am

Next

Return to General Discussion

Who is online

Users browsing this forum: Google [Bot] and 19 guests