Usage of tha.tagfinder
======================

.. :doctest:

The goal of tha.tagfinder is to traverse though an svn structure and return
tags and trunks.

Three imports are needed:

    >>> from tha.tagfinder import extracter
    >>> from tha.tagfinder import finder
    >>> from tha.tagfinder import lister

You need a startpoint, which is either an svn url or a directory name.  Our
test fixture provides an svn repository:

    >>> repo_url
    'file://.../repo'

Give your startpoint to a lister, in this case an SvnLister, with an optional
list of directory names that should be ignored:

    >>> startpoint = lister.SvnLister(repo_url, ignore=['sandbox'])

Choose an extractor.  Normally the BaseExtracter, but you can subclass it:

    >>> info_extracter = extracter.BaseExtracter

Lastly, set up a finder with the startpoint and the extractor.  Optionally
pass in stop_indicators that, when found in a directory, will stop the finder
from recursing in that directory:

    >>> info = finder.Finder(startpoint, info_extracter,
    ...                      stop_indicators=[])

The main usage is to query this info object for the projects it has found:

    >>> print(info.projects)
    [<tha.tagfinder.extracter.BaseExtracter object at ...,
     <tha.tagfinder.extracter.BaseExtracter object at ...]

Every project object has attributes that are provided by the extracter.  So
subclass the extracter if you need extra attributes of your own:

    >>> project = info.projects[1]
    >>> project.name
    'project1'
    >>> project.location
    'file://.../repo/project1'
    >>> project.tags
    ['0.1', '0.2', '0.3-bugfix']
    >>> project.tag_location('0.2')
    'file://.../repo/project1/tags/0.2'
