Questions about the "scope stack" and related APIs

[ngppgn]

Before anything, sorry if these questions is noobish, but I tried searching the docs and the info on this, maybe because it’s assumed to be common knowledge, has eluded me.

1 In completion (and other type of) files, yoy can specify scope selectors to restrict aplicability of some functionality. And example from the unofficial docs on completions:
"scope": "text.html - source - meta.tag, punctuation.definition.tag.begin"

Now, what does this mean exactly? I assume the , is an OR operator, but how do I understand each of the operands? For example, the section after the comma could mean one of these four things, in pseudo code:
a) scope_stack == [‘punctuation.definition.tag.begin’]
b) scope_stack == […, ‘punctuation.definition.tag.begin’,…]
c) scope_stack == […,‘punctuation.definition.tag.begin’]
d) scope_stack == [‘punctuation.definition.tag.begin,…’]

where ‘…’ means "some, possibly 0, arbitrary elements of the stack.

Which one is the correct interpretation?
And then, how should I read the hyphen-separated list of scopes before the comma?

A related question. In aplugin, say I have a point, and I want to get the full stack of scopes applied to that point. What’s the preferred way to do that?

[Remi]

The usage of scope selectors is not well documented. There are some articles on Stack Overflow where folks have answered and documented some of it, but it’s not gotten into the official or unofficial documents in detail.

In general though it ought to work like you think it does. Scopes are dot separated tokens from generic to most specific, always ending in the language used. So one of the most basic scopes would be source.cpp as an example. A very long and specified scope might be meta.group.codeblock.braces.begin.cpp (by the way I made that up – I don’t know that’s an actual scope).

So if you are trying to write a scope selector, it performs checks against the scopes. The operators are more like set notation. You don’t have to fully specify a particular scope. If you wanted a selector to only work on source, you could just put source and it would work on source.cpp, source.python, source.vhdl etc. So a subtraction would be to remove a certain set of scopes. So maybe I want to color just the top of a VHDL process declaration My scope selector might be source.vhdl (meta.block.process - meta.block.process.body) This would, for VHDL source only, score the portions of a process without the body.

That just really hits the surface. Like I said, there’s a couple of SO explanations that might show up on Google searches too. Hope it gets you pointed in the right direction.

[OdatNurd]

The scope system is taken from TextMate, so looking up how it works there may also provide some insight. Additionally you might find this post helpful:

Preventing unwanted auto-completion in comments

In short, no it does not; order is important to a large degree. Sublime Text borrows a system called scopes (sometimes referred to as scope selectors or just selectors) from TextMate. Scopes are applied to a file based on the currently assigned syntax definition (such as Plain Text or TypeScript), so every character in a file is assigned one or more scopes that define what it is. The best way to get a handle on what's going on with scopes is to move the cursor to various locations in a fi…

[ngppgn]

Thank you. It is a bit confusing that the underlying architecture is a list/stack but the operation uses set notation. Will heed you and @OdatNurd and look up the TextMate docs and see if I find something in stackOverflow then.

Meanwhile, if anyone has intel as to the other part of the OP (how to retrieve the scope stack at a given point in a sublime view through the API), I’d be most grateful for that too.

[OdatNurd]

Oh sorry, I missed that in your original question, view.scope_name() is what you want for that; see the file Default/show_scope_name.py for an example of how to use it; that file defines the command that shows you the scope name popup in response to the Tools > Developer > Show Scope Name menu item,

[ngppgn]

Thank yoy very much!