[WIP] Docs on scopes

[MaximSokolov]

Just scopes with examples. No description yet. Based on the Textmate docs

Refs atom/atom#8430

New scopes

• constant
  • character
    • escape
      • :question: unicode
        • 16-bit-hex (\u0394|...)
        • 32-bit-hex (\U00000394|...)
  • language
    • :question: boolean
      • (false|true)
    • :question: nothing (e.g. None in Python or null, nil etc. Should it be one standart scope?)
  • other
    • :question: rgb-value (#cfcddd, ...)
• keyword
  • control
    • :question: exception (try|catch|finally|throw|...)
    • :question: statement (break|continue|pass|return|yield|...)
  • operator
    • :question: comparison ( = | == | < | > | != | ... )
    • :question: arithmetic (+, -, /, *, ...)
    • :question: assignment ( = | := | ... )
      • ~~augmented~~ compound ( += | -= | *= | %= | ... )
    • :question: logical ( ! | && | and | not | or |...)
    • :question: reference (& in &x)
    • :question: dereference (* in int *pointer)
    • :question: bitwise (<<, >>, |, &, ...)
    • :question: ~~increment-decrement~~ (e.g. in Java and PHP)
    • :question: increment (++ in ++x and x++)
    • :question: decrement (-- in --x and x--)
• storage
  • type
    • :question: primitive
• markup
  • :question: changed
  • :question: inserted
  • :question: deleted
  • :question: strike
  • raw
    • :question: inline
    • :question: block
• meta
  • :question: function (function test(param1, param2) in function test(param1, param2){})
    • :question: inline
  • :question: function-call (functionCall(arg1, arg2))
    • :question: without-arguments
  • :question: method-call (methodCall(arg1, arg2) in obj.methodCall(arg1, arg2))
    • :question: without-arguments
  • :question: parameters ((param1, param2) in function test(param1, param2){})
  • :question: arguments ((arg1, arg2) in functionCall(arg1, arg2) , obj.methodCall(arg1, arg2))
• string
  • :question: heredoc
• :new: punctuation
  • definition
    • (string|parameters|arguments|comment)
  • separator
    • (key-value|parameters|arguments|...)
      • (period|comma|...)
  • :question: delimiter
    • (object|method|...)
      • (period|comma|...)
  • :question: statement
    • (terminator|...)
• variable
  • other
    • :question: argument
    • :question: assignment (x in x = 10)
    • :question: interpolation (x in "#{x}")
    • :question: readwrite (not a constant I guess. See @variable in Coffeescript)

[simurai]

:+1: Having an official grammar naming convention would be great. Then there is at least a place to refer to. And the convention could be refined over time.

How much does this version differ from the TextMate convention? I think until an Atom 2.0, it would need to stay somewhat close. Just because there are already lots of themes out there that are mostly based on TextMate's convention. Smaller changes are fine, just not big ones.

[MaximSokolov]

How much does this version differ from the TextMate convention?

The main difference is the punctuation scope. Most of suggested scopes already is used.

[MaximSokolov]

I think these scopes are redundant:

comment

• line
  • double-slash
  • double-dash
  • number-sign
  • percentage
  • character

string

• quoted
  • single
  • double
  • triple
  • other
• unquoted

These scopes don't append any information about language symbol. I doubt someone would use different color for 'string' and "string"

[mnquintana]

I doubt someone would use different color for 'string' and "string"

That may be true, but scopes are used for far more than just syntax highlighting - since they're what give raw text semantic structure in Atom, they're also used for things like autocomplete and static analysis. So while the distinction between single- and double-quoted strings might not really matter for syntax highlighting, it could make all the difference in other contexts.

[MaximSokolov]

Agree. However we can get punctuation via string -> punctuation.definition

[chbk]

Where would brackets, braces and parentheses go? How about a "section" category in "punctuation", I like the way language-ruby handles those characters.

[MaximSokolov]

Where would brackets, braces and parentheses go? How about a "section" category in "punctuation", I like the way language-ruby handles those characters.

IMO punctuation.definition scope is better for this purpose:

// `punctuation.definition.parameters` for `(`, `)`
test(param, param) {
  // `punctuation.definition.function[.brace.curly]` for `{`, `}`
  ...
}

punctuation.definition.array for [, ] punctuation.definition.parameters punctuation.definition.arguments etc. Even punctuation.definition.section

[lee-dohm]

Is this up-to-date with all the changes that the @atom/languages team have been doing?

[alexchandel]

@MaximSokolov In addition to documenting these scopes, could you document how these scopes can be debugged for a particular grammar (e.g. when looking at a file highlighted with that grammar, when trying to find out why a particular scope was applied to a string of text, etc...)? The Hacking Atom: Debugging has laughably little to say on this.

[infininight]

@MaximSokolov Didn't see this until now, we never added the punctuation scope to the documentation but we do have a spec I've posted here for reference. This is what we go by for the TextMate grammars.

This isn't the most complete list but there is also completion for scopes when editing grammars in TextMate, the list of scopes completed is in this command.

- Michael Sheets, TextMate Bundle Maintainer

[ghost]

I noticed that this does not reference the entity scope in the textmate doc, is this intentional? for python this would be useful for "import somepackage" where "somepackage" would be entity.name.package

[tabathap]

👌