Are there any more resources for creating code completion files for Sublime Text 4?

[JokerNZ]

I am a casual user of Sublime Text 3 and now 4. I now have reasons to explore being able to extend code syntaxes, and code completions and so on.

The official and community documentation for code completions is sparse at best.

I can understand superficially how variables and fields are supposed to work. I think. But there are MANY ambiguities in the documentation. And reading the code samples is difficult, without a background in what seems to me to be quite esoteric coding.

Before I start asking really newbie questions, are there any other resources that break things down a lot better? The docs usually only give a code example, with no actual examples of the results you should be getting out.

• The scope of the completion file is ambiguous. At least, at my current understanding. I am pretty new to scopes, but I’ve encountered them when extending a syntax file. I need the scope of this to apply to a new syntax file I created. But that is an extension of YAML. And I haven’t found if I can create (or am creating) a new scope when creating that extended syntax file.

• There’s no mention of where the settings go on this page:
  https://www.sublimetext.com/docs/completions.html#settings
  I did a search for some of the names in the ST preferences file. And couldn’t find any of them.

• The docs are so sparse in this area, that I can only assume there is an underlying code base that I’m unaware of. Without any indication of that code base or information we would be wise to explore.

I don’t mind looking further afield for helpful information. And I don’t expect documentation to actively contain every possible code explanation. But if background information would be helpful, then a link to it is great.

Thanks

[bschaaf]

• The scope of the completion file is ambiguous. At least, at my current understanding. I am pretty new to scopes, but I’ve encountered them when extending a syntax file. I need the scope of this to apply to a new syntax file I created. But that is an extension of YAML. And I haven’t found if I can create (or am creating) a new scope when creating that extended syntax file.

Scopes are “created” by syntax definitions. The scope selector in completions files selects for the scopes from syntax definitions. The Python.sublime-syntax sets the scope of all python code to source.python and the completions file example in the documentation selects that using source.python.

There’s no mention of where the settings go on this page:
https://www.sublimetext.com/docs/completions.html#settings
I did a search for some of the names in the ST preferences file. And couldn’t find any of them.

Those are all settings that apply to open files; they’re all under Preferences > Settings. You can read more about settings here: https://www.sublimetext.com/docs/settings.html

A good place to look for examples is the Default packages: https://github.com/sublimehq/Packages. They contain plenty of completions.

[JokerNZ]

A good place to look for examples is the Default packages: https://github.com/sublimehq/Packages. They contain plenty of completions.

Thanks for the reply.

Yes, you’re right there are lots of completions there. But its all just the code. I have been looking at completion files. But (quite reasonably for code) there are no explanations of the expected behaviour.

So the completion files are as opaque as the docs.

I clearly have a gap in knowledge, but I have no real idea of what to look for.

I’ve been trying to get completions to work and its inconsistent at best.

I am trying to create completions for a syntax extended from YAML.

When I view the scope of the cursor in the Sublime Text file, it does say the scope is: source.yaml

For instance, I have tried this code in a sublime-completions file:

{
	"scope": "source.yaml",

	"completions": [
		"Rule","View","Views","Look","BuiltinTransform"
		
	]
}

When I type

!<

I get a autocompletion popup that contains words that have been created by Sublime. And it acknowledges the two completion words in the completion file.

But none of the others are there in the list.

In my explorations through the docs, Goggle and these forums, there seems to be indications that the pop-up list of autocompletions, and completions are not precisely the same things.

In my mind, if I’ve set a completions file for a scope, then all the completion options should appear in that drop down. And there should be an option for prioritising completions we have specified at the top of the list, and auto generated completions at the bottom.

As far as I can see, none of the available completion settings make this work as I would hope.

My expectations may be wrong, but the descriptions in the docs of what we SHOULD expect from completions is very vague.

[bschaaf]

But none of the others are there in the list.

Are you sure they’re not just further down? If you start typing Builtin does BuiltinTransform show up?

[JokerNZ]

Hmmm, yes you’re right. That then does pop up. I can’t scroll down the list at all.

I was expecting the full list I supplied to be there, and scrollable.

I’d like this to be a prompt list of the specific available keywords.

That was what I was expecting. Which may be an incorrect expectations…

[JokerNZ]

I have also tried this format:

{
	"scope": "source.yaml",

	"completions": [
		"View","Views","Look","BuiltinTransform",
		{ 
		"trigger": "!<", 
		"contents": "Rule> $0",
		"kind": "type",
		"annotation": "OCIO Rule"
	}
		
	]
}

When I save this file, and type !< I get a similar popup.

The bottom item is the trigger condition referenced in the above sublime-completions file.

My understanding from the docs is that “annotation” text should appear in the bottom item. To enable a small explanation. Since it appears its not making any attempt to put in the “contents” or the result in the line. But that seems wrong as well.

Note that I cannot scroll through the popup.

[deathaxe]

I was expecting the full list I supplied to be there, and scrollable.

ST only provides a limited list of nearest matching words according to internal heuristics. It should update the list as you type. Alternatively hit ctrl+space.

[deathaxe]

static completion files don’t work well for tokens which do not look like normal words. ! and < are word separator chars, which causes !< not to be recognized as proper word / trigger. You could try to escape them, but AFAIK the only way to get such completions is via plugins, currently.

[JokerNZ]

OK. Fair enough.

Thanks

[JokerNZ]

When you say “nearest matching words” does that mean nearest matching from the list of completions in the completions file plus the auto generated list? I assume so, otherwise the completions files are pointless.

As for ctrl+space… Why is that any different from the automatic list?

This is all incredibly confusing, and totally unexplained in the docs. The docs can also explain limitations in software. That’s a good service to users too.

[JokerNZ]

Then how do completion files for HTML work? They are using <> etc all the time.

[JokerNZ]

Also ctrl+space gives worse results in the list than the automatic popup. Presumably because it hasn’t been activated by the trigger.

[JokerNZ]

My understanding from the docs is that “annotation” text should appear in the bottom item. To enable a small explanation. Since it appears its not making any attempt to put in the “contents” or the result in the line. But that seems wrong as well.

Is there any reason that the annotations aren’t working? Or the name of the replacement text isn’t appearing in the completion from the completion list?

I’d like to just get the parts workjing that are promised in the docs. ie actually seeing the contents in the pop up. Along with annotations.

[OdatNurd]

With a sublime-completions file like:

{
    "scope": "source.yaml",

    "completions": [
        {
            "trigger": "rule",
            "contents": "Rule> $0",
            "kind": "type",
            "annotation": "OCIO Rule",
            "details": "Insert an OCIO Rule"
        }
    ]
}

The trigger is the text that will be matched and replaced with the completion contents, so long as the word to the left of all of the active cursors in the file is a prefix substring of the trigger (so r, ru, rul and rule would work, but rub would not). This also takes fuzzy filtering into account as well, so re works because the filter has an r and an e in it, in that order.

The contents is the text that gets replaced. That’s not generally placed into the popup panel because it’s arbitrarily big.

The kind is used to provide a colorized icon/text to the left of the completion in the menu, to provide some additional hints as to what it is.

The annotation is a piece of text that gets displayed to the right of the completion (aligned on the right edge of the popup), which gives you context hints as to what the completion is or will insert (i.e. this is here because it’s more controlled than just dumping the entire contents out).

details provide an extra piece of text along the bottom of the panel, to provide more detailed context, since normally you want the annotation to be a shorter piece of text or the AC panel would get to wide.

So with the above, in a YAML file typing just r (as the shortest possible prefix substring of the completion), you see:

The prefix matching wants to match the word to the left of the cursor to an autocomplete and show you all of the possible matching completions, so:

• Summoning the AC panel manually will show you all possible completions that match the current situation, which may be more than you expect
• The completions may be displayed in an order that seems random, based on their source, heuristics, or to the settings you have applied, like auto_complete_use_history and auto_complete_preserve_order for example
• As you type the trigger, or part of the trigger, the list filters; so a completion with a trigger of long_rule_here could be filtered down to via lr or lrh
• The completion system wants to replace the trigger word with the replacement text; characters like !< are not considered words and so would not be considered to be part of the trigger text.

If the up and down arrows don’t scroll through the AC panel, you might want to double check if any bindings are blocking it; perhaps a package has overridden a key binding in a way that’s stopping it from working.

[JokerNZ]

Thank you for the extensive reply.

Given the difficulty with using !< as a trigger, perhaps there’s away of using scopes to limit where particular completions appear.

I notice that as I type “!<” it gets highlit with red, indicating a scope of:

invalid.illegal.tag-handle.yaml

So I thought I could use that scope as a way of indicating where my completions file should be used.

However, when I examine the scope at the cursor position immediately after “!<” it shows the root scope of:

source.yaml

If I move the cursor between the “!<” then it shows the expected scope.

source.yaml meta.property.yaml invalid.illegal.tag-handle.yaml

The docs say that Ctrl+Alt+Shift+P gets the scope under the cursor. Which I guess in this case means that the cursor is outside the scope.

Is there any way of capturing the scope immediately to the left of the cursor? Or perhaps the scope that’s just been created?

[JokerNZ]

If the up and down arrows don’t scroll through the AC panel, you might want to double check if any bindings are blocking it; perhaps a package has overridden a key binding in a way that’s stopping it from working.

Sorry, what I meant was that the arrow keys scroll up and down the list, but they don’t scroll to any more completions that don’t show already.

My understanding from context and a comment from someone else, was that we could scroll to more completions that are off the bottom of the pop up list.

When I use Ctrl+Space to invoke the completion popup, it also doesn’t let me scroll to any more completions that might be off the bottom of the list.

I only have Package Manager, and PackageDev installed.

[JokerNZ]

The autocompletion popup shows a bunch of keywords associated with a YAML tag rule. Fair rnough.

However, when I add my own completion rule, the auto created rule/s remain. This is at best incredibly confusing.

You can see in the above popup the Rule at the top of the list has been auto generated.

And immediately below it, is my completion rule.

I would have hoped that rules from completion files replace auto generated rules.

I’m unsure if there are any settings that may help this.

[deathaxe]

ST limits the number of completions it provides. It is likely desired ones are therefore missing, because internal ST heuristics judged them not relevant enough. That’s why my suggestion to re-trigger via ctrl+space. Depending on already typed trigger it may or may not improve the presented items. If no trigger has been typed - st has no info about what you might want and thus the list might be a bit of not useful.

[deathaxe]

Then how do completion files for HTML work? They are using <> etc all the time.

HTML ships plugin-based completions. That’s way more flexible as trigger can be analyzed by python code to make decisions of what items to return. The entry point is https://github.com/sublimehq/Packages/blob/b451c77f8c7303d44ce0a09288d6ff25958a2425/HTML/html_completions.py#L457

[deathaxe]

When you say “nearest matching words” does that mean nearest matching from…

ST uses various internal heuristics based on already existing content, typed trigger, etc. to decide, which completion items may be most relevant. I don’t know the exact algorithm though, but I know it sometimes feels like magic - as if ST already knows what you want - and sometimes it epically fails. Quality of syntax defintions and symbol definitions are quite important to get good results.