Scope Definition

One of the main concerns when creating a LiClipse language file is determining how to partition the source code for a language. Based on this information, LiClipse may handle each of these scopes differently for highlighting, navigation, outline, etc.

The main definition for that is the scope_definition_rules element, which should be a top-level element in the YAML file. This section defines the top-level scopes for a file.

Afterwards, another top-level entry named scope is used to provide the actual colors for the contents of a previously matched partition.

The default colors for each partition are given by yet another entry called scope_to_color_name. The names of the colors which are available can be seen at: ColorThemeKeys.java. The actual colors assigned to each of those will depend on the theme selected. See: Change Color Theme for details.

Below is a commented example which shows how this works in a simple structure.

Example:

	       
# For this example we have a language which has multi-line comments where we start and end with "###".
# Also, it has a class definition as: class ClassName, and the indentation is used to define new scopes.

scope_to_color_name: {
 multiLineComment: string, # For this example, our multiLineComment will use the string color defined in general > appearance > color theme
 default: foreground, # In the default scope, we'll use the foreground color
 # Anything else uses a color with the same name as the scope (i.e.: class, keyword)
}

scope_definition_rules:
  # Define that our comment is anything between ###....###
  # Note that any text that does not match any of these rules is considered to be in the default scope.
  - {type: MultiLineRule, scope: multiLineComment, start: "###", end: "###", escapeCharacter: \}


scope: # Here we'll specify sub-partition for top-level scopes

  default: # We're defining things internal to the default scope (in this example we could also define things in the multiLineComment scope).

    #keyword must be a color at this point already (not a scope)
    keyword: [class, pass] # Define that we want to consider 'class' and 'pass' as a keyword, colored with the 'keyword' color.

    sub_rules: [
      # There are things which may need more work to match in a scope, so, for this case we can
      # use sub_rules.
      {type: CompositeRule, sub_rules: [ # A composite rule will only be matched if all containing rules also match.
        { type: SequenceRule, scope: keyword, sequence: 'class'}, # Define that 'class' is a keyword
        { type: OneOrMoreSpacesRule, scope: default}, # After class we need at least a space
        { type: AnyWordRule, scope: class }] # And any name after that is the class we matched
      },
    ]

file_extensions: [liclipse_example] # The extensions matched by this language
filename: []
name: LiClipse Example # Name of the language

outline: # Note that we just specify 'flat' items here, the indent is later used to specify that an item creates a new scope.
  - {type: Scope, scope: [default, class], define: class} # Wherever we have a class inside the default scope we'll show a class icon in the outline.

indent: {
  type: spaces, # Our example language uses spaces for indenting
  outline_scopes: [class], # We have to say which outline entries actually create a new scope (so, indent and outline work toghether to specify the tree).
}

# Specify that the default comment action (Ctrl+/) creates a multiLineComment and that it should wrap it with '###'.
comment: {type: multiLine, start: '###', end: '###', scope: multiLineComment}

The rules available are:

CompositeRule:

sub_rules

Example:

	       
  #In this example, if we have a word and a colon afterwards, the word will use the class color and the sequence the operator color.
  default:
    sub_rules: [
      {type: CompositeRule, sub_rules: [
        { type: AnyWordRule, scope: class},
        { type: SequenceRule, scope: operator, sequence: ':'}]
      },
    ]}

MultiLineRule:

start

end

scope

escapeCharacter

Example:

	       
scope_definition_rules:
  # Matching a multi line comment for HTML
  - {type: MultiLineRule, scope: multiLineComment, start: '<!--', end: '-->', escapeCharacter: '\0'}
  # Matching a multi line string in Python
  - {type: MultiLineRule, scope: singleQuotedMultiLineString, start: "'''", end: "'''", escapeCharacter: \}

OptionalMultiLineRule:

Same thing as a MultiLineRule, usually used in a CompositeRule to specify that some multi line pattern may be optionally matched.
MultiLineRuleWithSkip:

start

end

scope

escapeCharacter

skip_rules

Example:

	       
	#Matching '<' all the way through '>' and skipping strings which may have < or > inside it.
	{type: MultiLineRuleWithSkip, scope: tag, start: '<', end: '>', escapeCharacter: '\0',
      skip_rules:[
        #Needed because if we find the end sequence within a string, we want to skip it.
        {type: MultiLineRule, scope: unused0, start: '"', end: '"', escapeCharacter: '\0'},
        {type: MultiLineRule, scope: unused1, start: "'", end: "'",  escapeCharacter: '\0'},
      ]
    }

MultiLineRuleRecursive:

Example:

	       
	#Matching '<' all the way through '>' and skipping strings which may have < or > inside it.
	{type: MultiLineRuleRecursive, scope: tag, start: '<', end: '>', escapeCharacter: '\0',
      skip_rules:[
        #Needed because if we find the end sequence within a string, we want to skip it.
        {type: MultiLineRule, scope: unused0, start: '"', end: '"', escapeCharacter: '\0'},
        {type: MultiLineRule, scope: unused1, start: "'", end: "'",  escapeCharacter: '\0'},
      ]
    }

RegexpRule:

Example:

	       
# Matches a regular expression
{ type: RegexpRule, regexp: 'aabb', scope: decorator }

AnyWordRule:

mustStartUppercase

except

additionalChars

Example:

	       
# Matching any word after detecting we're in a decorator context in Python.
{ type: AnyWordRule, scope: decorator, mustStartUppercase: False }

PatternRule:

startSequence

endSequence

scope

escapeCharacter

breaksOnEOL

breaksOnEOF

escapeContinuesLine

Example:

	       
scope_definition_rules:
  # Matching [xxxx]_ only in the current line
  - {type: PatternRule, scope: javadocLink, startSequence: '[',
     endSequence: ']_', escapeCharacter: '\0', breaksOnEOL: true,
     breaksOnEOF: false, escapeContinuesLine: false}

SingleLineRule:

sequence

scope

escapeCharacter

escapeContinuesLine

Example:

	       
scope_definition_rules:
  # Matching a double quoted string in Python
  - {type: SingleLineRule, scope: doubleQuotedString, sequence: '"', escapeCharacter: \, escapeContinuesLine: true}

SequenceRule:

sequence

scope

Example:

	       
#Matching the word 'function'
{ type: SequenceRule, scope: keyword, sequence: 'function'}

SequencesRule:

sequences

scope

Example:

	       
#Matching the word 'function' or 'def'
{ type: SequenceRule, scope: keyword, sequences: ['function', 'def']}

OptionalSequenceRule:

Same thing as the SequenceRule to be used in a CompositeRule to optionally match some sequence.

EndOfLineRule:

start

scope

Example:

	       
scope_definition_rules:
  # Matching a comment in Python
  - {type: EndOfLineRule, scope: singleLineComment, start: '#'}

OneOrMoreSpacesRule:

scope

ZeroOrMoreSpacesRule:

scope

NumberRule:

scope

SwitchLanguageHtmlRule:

Example:

	       
scope_definition_rules:
  #The SwitchLanguageHtmlRule is a special hand-made rule to match the html script tag.
  #If there are other 'language' switching cases, this may need to be more flexible.
  #It create sub-tokens for the tag as the rules here (open_tag, close_tag, class, etc, so, if this
  #changes, the rule may need to be changed too).
  - {type: SwitchLanguageHtmlRule, #custom rule matching for: '<script type="???", language="???">', end: '</script>'
     scope: this, #On a switch, the scope must alway be 'this'
     tag: 'script',
     type_attr: {
        'application/javascript': javascript, 'application/ecmascript': javascript, 'application/x-javascript': javascript,
        'application/x-ecmascript': javascript, 'text/javascript': javascript, 'text/ecmascript': javascript, 'text/jscript':javascript
     },
     language_attr: {JavaScript: javascript} #the expected language attr to switch to the target language (used with startswith() and case-independent)
    }

SwitchLanguageRule:

scope

start

end

language

Example:

	       
{type: SwitchLanguageRule, scope: python_block, start: '<%', end: '%>', language: python}

IndentedBlockRule:

start

scope

column

additional_start

Example:

	       
scope_definition_rules:
  #Literal Block (column -1 means it can start anywhere)
  # literal block::
  #    xxx xxx xxx
  #    xxx xxx xxx
  - {type: IndentedBlockRule, scope: literalBlock, start: '::', column: -1}

MatchLineStartRule:

scope

Example:

	       
scope_definition_rules:
  # Matching an rst title:
  # xxxxx
  # ------
  - {type: CompositeRule, sub_rules:[ #Note: when a composite rule is defined here,
                                      # all the scopes in the inner parts must have the same type.
    { type: MatchLineStartRule, scope: title},
    { type: SkipLineRule, scope: title},
    { type: RepeatCharToEolRule, scope: title, chars: ['-', '=', '_', '~', '`']},
  ]}

SkipLineRule:

scope

Example:

	       
scope_definition_rules:
  # Matching an rst title:
  # xxxxx
  # ------
  - {type: CompositeRule, sub_rules:[ #Note: when a composite rule is defined here,
                                      # all the scopes in the inner parts must have the same type.
    { type: MatchLineStartRule, scope: title},
    { type: SkipLineRule, scope: title},
    { type: RepeatCharToEolRule, scope: title, chars: ['-', '=', '_', '~', '`']},
  ]}

RepeatCharToEolRule:

scope

chars

Example:

	       
scope_definition_rules:
  # Matching an rst title:
  # xxxxx
  # ------
  - {type: CompositeRule, sub_rules:[ #Note: when a composite rule is defined here,
                                      # all the scopes in the inner parts must have the same type.
    { type: MatchLineStartRule, scope: title},
    { type: SkipLineRule, scope: title},
    { type: RepeatCharToEolRule, scope: title, chars: ['-', '=', '_', '~', '`']},
  ]}

PrevCharNotIn:

scope

chars

Example:

	       
  # Single Line Strings start only if not right after a number.
  - {type: CompositeRule, sub_rules: [
    {type: PrevCharNotIn, scope: singleQuotedString, chars: '0123456789'}, # I.e.: we can't be inside a number
    {type: SingleLineRule, scope: singleQuotedString, sequence: "'", escapeCharacter: \, escapeContinuesLine: true},
  ]}

SingleLineRuleWithSkip:

scope

start

escapeCharacter

escapeContinuesLine

skipRules

Example:

	       
  {type: SingleLineRuleWithSkip, scope: line_statement, start: '#', escapeCharacter: '\0', escapeContinuesLine: false, skipRules:[
    {type: MultiLineRule, scope: keyword, start: '(', end: ')', escapeCharacter: '\0'},
    {type: MultiLineRule, scope: keyword, start: '[', end: ']', escapeCharacter: '\0'},
    {type: MultiLineRule, scope: keyword, start: '{', end: '}', escapeCharacter: '\0'},
  ]}