Editra Syntax Xml

SPECIFICATION: Editra Syntax XML
REVISION: 1.0

PURPOSE:

This document will describe and define the XML used by Editra to allow for user defined file type extensions and for overriding builtin file type modes with user defined behavior.


VERSION INFO:

Version 1 of this xml specification will only support the use of builtin scintilla lexers that are available in the wxPython StyledTextCtrl. (see STC Quick Reference)


FILE EXTENSION:

edxml

SYNTAX:

Editra Syntax XML uses standard XML syntax


DOCUMENT STRUCTURE:

<editra version="1">
   <syntax language="LanguageName" lexer="STC_LEX_FOO" id="ID_LANG_LANGNAME">
      <associations value="foo"/>
 
      <keywordlist>
         <keywords value="0">
           char data
         </keywords>
      </keywordlist>
 
      <syntaxspeclist>
         <syntaxspec value="STC_LEXER_STYLE_VALUE" tag="EDITRA_STYLE_TAG"/>
      </syntaxspeclist>
 
      <propertylist>
         <property value="fold" enable="1"/>
      </propertylist>
 
      <commentpattern value="//"/>
 
   </syntax>
 
   <syntax ...>
   ...
   </syntax>
 
</editra>


TAGS:

This section will describe the supported XML elements and their roles in defining the file type support.

Editra Tag:

This is the main outer tag of the document. There should only be one of these tags in the whole file and it should be formatted as follows.

<editra version="1"></editra>

The tag has one attribute version which takes an integer value specifing the XML version that is in use. Currently only version 1 is supported. This tag can contain multiple syntax groups within it.

Syntax Tag:

This tag defines the outer grouping for a file type mode and is formated as follows:

<syntax language="" lexer="" id=""></syntax>

The syntax tag require three attributes to be defined as follows.

  • language: This will be the display name for the file type.
  • lexer: This must be one of the STC_LEX_* constants from the wx.stc module (ref)
  • id: This will be used internally by Editra as the language identifier. It must be a unique string prefixed with ID_LANG_.

The syntax tag is a child of the editra tag.

Associations Tag:

The associations tag is used to specify what file extensions to associate the file type with. The tag is formated as follows:

<associations value=""/>

This tag has one attribute value which takes a space separated list of file extensions to associate with the syntax mode being defined.

The associations tag is a child element of the the syntax tag.

KeywordList Tag:

The keywordlist tag is a container element for keyword items.

<keywordlist></keywordlist>

The keywordlist tag is a child of the syntax tag.

Keyword Tag:

The keyword tag is a container for keyword char data and is formated as follows:

<keyword value="">word1 word2</keyword>

This tag has one attribute value which takes an integer value that is an index into the given lexers keyword list. Documentation is limited on what keyword indexes are available for what lexers. For further information it is suggested to refer to an existing syntax mode module in Editra's source code.

The keyword tag is a child of the keywordlist tag.

SyntaxSpecList Tag:

The syntaxspeclist tag is a container for syntaxspec items.

<syntaxspeclist></syntaxspeclist>

This tag is just an outer grouping for syntaxspec elements.

The syntaxspeclist tag is a child of the syntax tag.

SyntaxSpec Tag:

The syntaxspec tag is used to associate a lexer's style ID with an Editra styling tag.

<syntaxspec value="" tag=""/>

This tag has two attributes:

  • value: Must specify a builtin styling ID for the lexer specified in the syntax tag's lexer attribute. (ref)
  • tag: Must specify a valid Editra Style Tag. (ref)

The syntaxspec tag is a child of the syntaxspeclist tag.

PropertyList Tag:

The propertylist tag is a container for property items.

<propertylist></propertylist>

The propertylist tag is a child of the syntax tag.

Property Tag:

The property tag is used to specify and enable optional Scintilla features such as folding.

<property value="" enable=""/>

This tag has two attributes:

  • value: Specifies the Scintilla property to enable. What properties are available is completely lexer specific. This is most often used to control folding (i.e "fold")
  • enable: This attribute can take one of two values 1 (enable), 0 (disable)

This tag is a child of the propertylist tag.

CommentPattern Tag:

The commentpattern tag specifies the comment pattern to be used by the Toggle Comment feature in Editra.

<commentpattern value=""/>

This tag has one attribute value which accepts an arbitrary string that defines how to comment out a line of code for the file type defined by the enclosing syntax group. If there is a space in the string it will be broken into tokens where the first token will be inserted at the beginning of the selected lines and the second token will be inserted at the end to create a block comment.

This tag is a child of the syntax tag.


EXAMPLES:

see: Python highlighting customization example