Language Support

On LiClipse, it's possible to add support for new languages by editing LiClipse language files.

Language files may be found at plugins/org.brainwy.liclipsetext.editor/languages (any file which ends with a .liclipse in that folder is considered a LiClipse language file).

You can open one of those files inside LiClipse to get proper highlighting and validation for the file.

Each LiClipse file is a valid YAML file but with a custom expected structure.

Usually, the first thing to work on in a language defining some basic data, such as its name (which must be unique among the available languages), the file-extensions and filenames which are usually used with the given language as well as a pattern to match the language shebang (if available).

Afterwards, the second thing is defining its basic partitioning, which in practice means defining rules which will create scopes for each part of the document being edited (which will enable us to provide syntax-highlighting to the language). Note that everything that doesn't match a partition is considered to be in the 'default' scope.

Some examples:

In Python, we create separate partitions for comments single line strings and multi-line strings (note that each rule must create a separete scope: things may work improperly if the same scope is used in 2 different rules).

In XML we create partitions to separate comments, CDATA partitions and tags.

In Javascript we create partitions to separate comments, multi-line comments and strings.

That partitioning is defined in the scope_definition_rules top-level entry, which specifies a list where each entry defines a rule. See: Scope Definition for more details on defining these rules.

After defining the basic scopes, which should've enabled proper syntax highlighting for a language, it can be later extended to offer outline, better indenting, code-completion, etc. Below is a reference on the available structures to configure the language.

Reference on the main top-level elements of the language definition:

• file_extensions: List with the file-extensions that should be opened with this language.
• filename: List of filenames which should be opened with this language.
• name: The name of this language.
• shebang: A String or Array of Strings with the patterns to match the first line of the document to consider it of the given language.
• scope_definition_rules: List where each entry is a Dictionary defining the rules which define the top-level scopes of the document.
• scope_to_color_name: Dictionary which maps a scope to the name of the color in the theme to be used for that scope.
  Theme colors available are:
  • foreground
  • background
  • selectionForeground
  • selectionBackground
  • currentLine
  • lineNumber
  • searchResultIndication
  • filteredSearchResultIndication
  • occurrenceIndication
  • writeOccurrenceIndication
  • deletionIndication
  • findScope
  • singleLineComment
  • multiLineComment
  • commentTaskTag
  • sourceHoverBackground
  • number
  • string
  • bracket
  • operator
  • keyword
  • class
  • interface
  • enum
  • method
  • methodDeclaration
  • annotation
  • localVariable
  • localVariableDeclaration
  • inheritedMethod
  • abstractMethod
  • staticMethod
  • javadoc
  • javadocTag
  • javadocKeyword
  • javadocLink
  • field
  • staticField
  • staticFinalField
  • parameterVariable
  • typeArgument
  • typeParameter
  • deprecatedMember
  • debugCurrentInstructionPointer
  • debugSecondaryInstructionPointer
  • constant
  • stderr
  • stdin
  • stdout
  • hyperlink
  • activeHyperlink
  • matchingBracket
  • searchViewMatchHighlight
  • compareOutgoing
  • compareIncoming
  • compareConflicting
  • compareResolved
  • selectedTabInitialBackground
  • selectedTabActiveInitialBackground
• scope: Dictionary where each key should be the name of the scope being customized. The values are the name of a color mapping to a list with the names that should be colored with that color or there can be a special entry named sub_rules to create sub-partitions which should be colored differently within that partition (and may be used for other things such as specifying the entries for the outline).
• outline: List of Dictionaries which define how the outline is computed for this language.
  Example showing how to add a sub-partition 'method' in the scope 'default' appear in the outline:
  - {type: Scope, scope: [default, method], define: method}
  Example showing how to match a regex in a partition to show in the outline:
  - {type: Regexp, scope: [singleLineComment], regexp: '#---.*', define: comment, group: 0}
  If using CTags, it's possible to make all the entries from ctags appear in the outline with:
  - {type: Ctags}
• indent: Defines how indent-scopes are created (spaces, braces or defined scopes), if we should change spaces for tabs in the language and the tab width. Also helps in specifying leveling for the outline (the outline will define the entries, but the indent will define if it defines a new nesting scope). See: Indent for more details.
• comment: Defines how comments are created/removed in the language (Ctrl+/).
  Example specifying single-line comments:
  comment: {type: singleLine, sequence: '//'}
  Example showing how to deal with multi-line comments:
  comment: {type: multiLine, start: '/*', end: '*/', scope: multiLineComment}
• separators: Defines which characters should be considered a separator in the language. Default: ./\\()\"'-:,.;<>~!@#$%^&*|+=[]{}`~?
• code_completion: Dictionary which currently only supports one setting: use_only_templates as true or false (default is false, which also shows completions based on keywords used in syntax highlighting).
• auto_edit: Defines actions which are taken when the user enters some text.
  Example:
  

  auto_edit:
    # In a new line, indent after ':'
    - {after: ':', trigger: '\n', action: indent, scope: default}
  
    # Skip ':' if already there
    - {before: ':', trigger: ':', action: skip, scope: default}
  
    # To work, the scopes must be: SingleLineRule(sequence used for start/end) or MultiLineRule.
    - {auto_close_scopes: [doubleQuotedString, singleQuotedString], scope: default}
  
    # Will close the parens if it's not properly balanced
    - {auto_close_parens: ['(', '[', '{'], scope: default}
  
    # Will skip the close parens if it's properly balanced
    - {auto_skip_parens: [')', ']', '}'], scope: default}
  

• rule_aliases: May be used to create rules which may be later referenced only by the name.
  Example:
  

  rule_aliases: {
    'HashCommentRule': {type: EndOfLineRule, scope: singleLineComment, start: '#'},
    'PythonCommentRule': 'HashCommentRule',
  }
  
  scope_definition_rules:
    # Use a rule alias
    - 'PythonCommentRule'
  
    # Declare a regular rule
    - { type: NumberRule, scope: number}
  

• templates: Defines code-completion entries based on templates. See Templates for more details
• template_variables: It's possible to create variables which present a list of choices for the user as a variable in the template. See Templates for more details
• inherit: Signal that the language definition should start from the contents of another language. New top-level contents will override the values from the specified entries.
• patch: Only available when inherit is defined. Instead of totally overriding entries, entries specified will be appended to the entries from the inherited language.
• case: sensitive|insensitive (specifies if the language is case-insensitive or not).
• spell_check: Enables how spell-checking should work. See: Spell Checking for more details.