Sublime Forum

**leo2020** · November 11, 2020, 5:41pm

Hi, I’m curious about the meaning of multiple scope values in syntax definition files.

Firstly, consider this:

sublimehq/Packages/blob/master/Python/Python.sublime-syntax#L176




imports-from-import-body:
  - meta_scope: meta.statement.import.python
  - include: line-continuation-or-pop
  - match: (?=\()
    set:
      - meta_include_prototype: false
      - match: \(
        scope: punctuation.section.import-list.begin.python
        set:
          - meta_scope: meta.statement.import.python meta.import-list.python
          - match: \)
            scope: punctuation.section.import-list.end.python
            pop: true
          - include: comments
          - include: import-name-list
  - match: (?=\S)
    set: import-alias-list


import-alias-list:
  - meta_content_scope: meta.statement.import.python

There are two meta scopes. Are they both just pushed onto the stack?

The second interesting place is here:

github.com

sublimehq/Packages/blob/master/C++/C++.sublime-syntax#L1989


    set: preprocessor-if-branch-statements
  - match: ^\s*(#\s*endif)\b
    captures:
      1: meta.preprocessor.c++ keyword.control.import.c++
    set: preprocessor-if-branch-function-call-arguments-finish
  - include: expressions


preprocessor-if-branch-function-call-arguments-finish:
  - meta_content_scope: meta.function-call.c++ meta.group.c++
  - match: \)
    scope: meta.function-call.c++ meta.group.c++ punctuation.section.group.end.c++
    pop: true
  - include: expressions


preprocessor-block-if-branch-statements:
  - meta_scope: meta.block.c++
  - match: ^\s*(#\s*endif)\b
    captures:
      1: meta.preprocessor.c++ keyword.control.import.c++
    set: preprocessor-block-finish-statements
  - match: (?=^\s*#\s*(elif|else)\b)

In this case the meta scopes apply exactly to the pattern. In the same fashion as ordinary scopes do. Am I right?

And the final example:

github.com

sublimehq/Packages/blob/master/Python/Python.sublime-syntax#L900


          - include: illegal-assignment-expression
          - match: (?=[,):])
            pop: true
          - include: expression-in-a-group
      - include: illegal-names
      - match: '{{identifier}}'
        scope: variable.parameter.python


lambda:
  - match: \b(lambda)(?=\s|:|$)
    scope: 
      meta.function.inline.python
      storage.type.function.inline.python
      keyword.declaration.function.inline.python
    push: [lambda-parameters, allow-unpack-operators]


lambda-parameters:
  - meta_content_scope: meta.function.inline.parameters.python
  - include: line-continuation-or-pop
  - match: '\:'
    scope: punctuation.section.function.begin.python

Here we see two ordinary scopes applied to the same pattern. What does it mean? Which one of them will define the style?

Thanks!

**deathaxe** · November 11, 2020, 7:46pm

Basically we distinguish two kinds of scopes.

The meta. scopes are used to create logical units which provide semantical context for completions or plugins.
storage, keyword, variable,punctuation … scopes which primarily target syntax highlighting.

About snippet 1 (Python)

The whole import statement is scoped meta.statement.import.python.

import package

from .foo import bar

from .foo import (bar as baz)
...

The second scope meta.import-list is used to scope only (bar as baz).

Stacking meta scopes like that is one way to create multiple layers of logical units. This is useful especially if such scopes like meta.import-lists are used in different contexts.

If only the import list is of interest a selector may look like meta.import-list, which targets all those regions no matter whether they belong to meta.statement.import or any other one.

If only certain regions are needed a selector can easily combine those by (meta.statement.import | meta.statement.whatever) & meta.import-list.

An alternative was to put everything into one scope name, which would then look like meta.statement.import.import-list. A real life example is meta.function-call.[identifier|arguments].

This solution makes general purpose selectors to match all import lists hard. You always need to address meta.statment.import.import-list, meta.statement.whatever.import-list, ...

Hence it should be used with care and only if the statements structure is very clear.

About snippet 2 (C++)

That’s an older versions of function calls. The meta.group is a very general scope used to denote all kinds of parenthesed code sections. A selector targeting meta.function-call meta.group - meta.function-call meta.block could be used to match function call arguments.

More recent syntaxes use meta.function-call.arguments only or in conjunction with meta.group.
This makes selectors a bit more straight forward: meta.function-call.arguments is enough to target function call arguments, while meta.group if present could be used for general purpose functions if someone wants to match all kinds of parenthesed sections no matter if they are function arguments, or expression groups.

The punctuation is the highlighting part, which may be addressed by color schemes to give the parentheses their color. It is part of the scope naming guidelines that the related meta scope of a section should span the opening and closing punctuation. Hence those are stacked.

About snippet 3 Pthon lambda

Here two highlighting scopes storage.type and keyword.declaration are stacked because of some kind of backward compatibility considerations with older color schemes.

While the return value of a function in C/C++ like int or char may clearly be scoped storage.type situation is more confuse in dynamically typed syntaxes like python, which just use general keywords like def to denote function definitions. Those keywords were scoped storage.type.function in the past.

Same applies to class keyword. But … in a statement like class ClassName, what is the type? Is it class or ClassName? We came up with class to be a keyword.declaration which declares a data type. Same applies to python functions/lambdas. Those keywords are more like declaration keywords than data types. Hence those were changed.

It turned out stacking those is not as backward compatible as desired. The internal ST4 beta comes with a core feature to maintain backward compatibility with older color schemes even if we remove the legacy storage.type in such constructs. One thing still on the TODO.

Hope, that helps a bit.

**leo2020** · November 12, 2020, 8:34am

Great, it makes it clear. The only thing left is that in the first example the meta.statement.import.python scope is already pushed onto the stack in line 168. What is the reason for repeating it in line 176?

**deathaxe** · November 17, 2020, 7:01pm

The reason are the set statements, which replace the context of line 168 by the one around 176 at the current stack slot/level. Hence any information including meta scopes is no longer available.

set is used here in order to make pop: true in line 179 pop off the whole imports-from-import-body off stack and continue with whatever top-level context comes next.

Meaning of multiple scopes in syntax definitions