Punctuation Scopes.markdown

Punctuation Scopes

Note: For the punctuation that are used in pairs there is an optional .begin & .end that can be tacked on right before the language name at the end. They are not required to be used but should be standardized where found useful.

The third level of the following scopes is open to new scopes as you see fit, however try to keep then as generic as possible to keep the total number down. Try to reuse a scope if possible before creating anew.

• punctuation.definition

  Punctuation that is intended to delimit the bounds of a single item, generally something that will become a real singular object in compiled/interpreted code. Can also be used in markup languages for delimiters that define small conceptual units (headers, list items, etc).

  Examples: string, array, token, header, list, symbol, table

  Notes: table refers to the characters that surround tables in a text markup language.

• punctuation.section

  The start/end of a structured section of some sort (comment, paragraph, opening and closing braces in code, etc). Any potentially large (multi-lined?) section that can be described as serving a single function.

  Examples: comment, function, scope, quote, paragraph

  Notes: quote and paragraph refer to the blocks in textual markup languages when there is a visual delimiter.

• punctuation.separator

  Any punctuation intended to separate two internal parts of a logical whole.

  Examples: key-value, list, arguments

  Notes: key-value refers to the delimiter between a key/value relationship in languages like HTML/XML/YAML, should not be used for true assignments.

• punctuation.terminator

  Punctuation that terminates a statement, rule, etc. (the ; in print "foo";)

  Examples: statement, rule, line

• punctuation.whitespace

  The whitespace that precedes or trails a context, this should be used sparingly as it makes sense for matching multiple items or for highlighting purposes. The forth item should be leading or trailing depending.

  Examples:

  The whitespace preceding a line comment only when there is nothing between it and the start of the line, this allows matching successive line comments as a block via scope.

  The whitespace both leading and trailing a embedded block when nothing is between it and the start/end of the line, this allows coloring the background of the embedded scope in a cleaner manner.

I'd also add this:

punctuation.delimiter

Any punctuation used to separate a list of elements whose order or omission would not affect the source's context or interpretation. It should not be used for punctuation that describe a relationship between two adjoining tokens (such as the colon between a key/value pair). For this, the punctuation.separator scope should be used.

Examples:

• Commas between array values or arguments of a function-call: foo , bar , baz ,
• Dots between property names in a JavaScript accessor chain: document . body . firstElementChild
• Pipes between alternations in a RegExp capturing group: foo | bar | baz