Syntax Plugin Specifications

Included in this document are the specifications of what is needed to write a 
plugin to extend the syntax highlighting functionality of the editor. TO add a
new syntax file grab the syntax_mod template from the templates directory and fill
it out to match the specs of the language you want to provide highlighting for.

0: Before you begin
    - Editra uses Scintilla for its text control. Since documentation is not
      readily available, I suggest you grab the Scintilla sources and see what
      settings are available for each language.

1: File Specifications
    - The plugin file is a python module that provides the editor with the 
      information that it needs to properly setup the lexer.

2: What the plugin needs to provide

    METHODS:
      - FUNCTION: Keywords(lang_id=0)
        DESC: Provides a set of language keywords and their level to set in
              the editor.
        PARAM: integer "lang_id" is an optional parameter for requesting a
               particular subset of keywords or for specifying a certain dialect
               of a language. This allows for modules to handle multiple related
               but different syntax sets. The passed values are the ones defined
               in synglob.py.
        RETURN: An ordered/unorder list of tuples.
        SPECIFICATIONS:
            The tuples in the list each contain two items.
                -The first item is an integer value specifying the Scintilla
                 keyword type to set for the Lexer.
                -The second is a string of space separated keywords.
        EXAMPLE RETURN: [(0, "spam ni"), (1, "monty python")]

      - FUNCTION: SyntaxSpec(lang_id=0)
        DESC: This function is called to get the mapping of the stc style attributes
              to the Editra Style Sheet tags.
        PARAM: lang_id, just as in Keywords
        RETURN: List of tuple string pairs, that pair the STC value to the wanted
                style tag.
        SPECIFICATIONS:
            The values in tuples of the return list must be ordered as follows
                - (STC_* value, Editra Style Tag)
        EXAMPLE RETURN: [('STC_C_DEFAULT', 'default_style'), 
                         (STC_C_COMMENT, 'comment_style')] 

      - FUNCTION: Properties(lang_id=0)
        DESC: This function is called to get any extra lexer properties that the
              editor should set for the given language.
        PARAM: lang_id, just as in Keywords
        RETURN: List of tuples
        SPECIFICATIONS:
            The values in the tuples of the return list must be as follows
                - ("property", "value")
            If there are no needed  properties to set the function should
            return an empty list.
        EXAMPLE RETURN: [("fold", "1"), ("fold.comment", "1")]

    - FUNCTION: CommentPattern(lang_id=0)
        DESC: Get the patern of comment meta characters to use for commenting
              out code in the given language.
        PARAM: integer "lang_id", used for same purpose as in Keywords()
        RETURN: Ordered List of strings
        SPECIFICATIONS:
            The returned list of strings must be in the order that the characters
            are to be added to the document. This only applies to languages that
            have multi character sequences required for comments.
        EXAMPLE RETURN:
            - Bash: [ "#" ]
            - C:    ["/*", "*/]

    - FUNCTION: KeywordString(option=0)
        DESC: Provided primarly for other syntax modules that may wish to request
              resources from this module.
        PARAM: integer "option", is an optional argument for requesting a subset
               or particular keyword string.
        RETURN: A string of keywords
        SPECIFICATIONS:
        EXAMPLE RETURN: "int double short"

    - FUNCTION: StyleText(stc, start, end)
        DESC: Used for styling the text in a buffer that is using a container
              lexer.
        PARAM: stc The EditraStyledText control instance to do the styling in
        PARAM: start The start position of the styling
        PARAM: end The end position to style to
        SPECIFICATIONS:
        EXAMPLE:

    - FUNCTION: AutoIndenter(stc, current_pos, indent_char)
        DESC: Provide context sensitive auto indentation support
        PARAM: stc The buffer to do the indentation in
        PARAM: current_pos The current position of the caret in the buffer
        PARAM: indent_char Prefered character to use for indentation 
               ("\t" or " " * tabwidth)
        RETURN: Text to insert at current_pos
        SPECIFICATIONS: Called when the Return key is hit. Note that the new
                        line character is not sent to the buffer so it needs
                        to be handled by this method. For any new line lines
                        that need to be inserted use a '\n' character. The
                        buffer will handle any necessary conversions on
                        platforms that use other characters or for preferences
                        set at the user level.
