Writing Parsers
===============

Example Parser
--------------

        from . import ClassParserInterface, register_parser

        class SampleParser (ClassParserInterface):
            def parse(self, doc, location, model):
                uri = location and location.get_uri()
                start, end = doc.get_bounds()
                start_line = start.get_line() + 1
                end_line = end.get_line() + 1
                mid_line = (start_line + end_line) // 2
                it = model.append(parent_iter, 'Start', 'namespace', uri, start_line)
                model.append(it, 'Middle', None, uri, mid_line)
                model.append(parent_iter, 'End', None, uri, end_line, end.get_line_offset())
                
                
        register_parser(SampleParser.__name__, SampleParser, [], 'Sample Parser')


The parse method
----------------

Arguments:
 * doc: Gedit.Document, doc.get_text(start, end, True) is normally used for parsing
 * location: Gio.File, location.get_path() can be used for external programs like ctags
 * model: The parser result should passed to the append method of this object

The model interface
-------------------

The model object from the parse method has the following methods:
 * append(treeiter, name, typecode, uri, startline, startcol=0, endline=0, endcol=0)
    Appends a row to the Class Browser pane
    + treeiter: a Gtk.TreeIter or None
    + name: the text that will be shown
    + typecode: a string that determines the pixbuf and text color or None
    + uri: normally location.get_uri() is used
    + startline: the line where the found token starts, the first line in doc is 1
    + startcol: the column where the token starts if known, the first column is 0
    + endline: the line where the found token ends, 0 if unknown
    + endcol: the column after the token
    returns the Gtk.TreeIter of the created row
    
 * set_end(treeiter, line, col=0)
    Change end position of a previously created row
    + treeiter: a Gtk.TreeIter that was returned by a call of the append method
    + line: like endline of the append method
    + col: like endcol of the append method
    
 * get_startline(treeiter)
    returns startline from the row identified by treeiter
    
Restriction to position information
-----------------------------------

Tokens must be added in the order they are found in the source.
For nested tokens the children must in the range of the parent token.
If the endline of an token is unknown, it can be set to 0.
In that case it will be assumed the token ends where the next starts.

Typecodes
---------

The typecode is responsible for the icon and the text color for the row in the
classbrowser.
A row has an icon if the typecode has the same name as a file in the directory
`classbrowser3g/pixmaps` (without the extension).
A row has a text color if the typecode is in the colors dict of the Parser class.
Look at the implementation of `ClassParserInterface` in
`classbrowser3g/parsers/__init__.py`

