"""
.. :doctest:

Finding trunk and tag directories in svn
========================================

A finder uses a lister (SvnLister or DirLister) to traverse a dir/svn
structure.  It looks for a trunk/tags structure and returns that information.


Setup
-----

For testing, we use the fixture_dir:

    >>> fixture_dir
    '...tha/tagfinder/tests/fixture'

Set up a dirlister.  Ignore the fixture_dir's ``.svn`` directories:

    >>> from tha.tagfinder import lister
    >>> startpoint = lister.DirLister(fixture_dir, ignore=['.svn'])

And we need an info extracter:

    >>> from tha.tagfinder import extracter
    >>> info_extracter = extracter.BaseExtracter


Finding trunk/tags
------------------

Set up a Finder with above DirLister and BaseExtracter:

    >>> from tha.tagfinder import finder
    >>> info = finder.Finder(startpoint, info_extracter)

``projects`` is a list of found projects, which provide information as
extracted from the found (svn) directory by the extracter.  The BaseExtracter
provides, amongst others, the location:

    >>> from pprint import pprint
    >>> pprint([project.location for project in info.projects])
    ['...tests/fixture/customer/site',
     '...tests/fixture/project1',
     '...tests/fixture/sandbox/reinout/reinout_project']


Omitting parts of the tree
==========================

We're not interested in everything.  Omit certain parts of the directory
structure by omitting it through the lister.  Omit the sandbox dir (and thus
all its contents) and reinout_project doesn't show up anymore:

    >>> startpoint = lister.DirLister(fixture_dir,
    ...                               ignore=['.svn', 'sandbox'])
    >>> info = finder.Finder(startpoint, info_extracter)
    >>> pprint([project.location for project in info.projects])
    ['...tests/fixture/customer/site',
     '...tests/fixture/project1']

Sometimes a project does not have a trunk/tags structure, so it won't
immediately be recognized as a project.  There are often other indicators
(like a ``buildout.cfg`` file).  We'll remove ``sandbox`` from the ignore list
(as used above) so that reinout_project shows up again:

    >>> startpoint = lister.DirLister(fixture_dir, ignore=['.svn'])
    >>> info = finder.Finder(startpoint, info_extracter)
    >>> pprint([project.location for project in info.projects])
    ['...tests/fixture/customer/site',
     '...tests/fixture/project1',
     '...tests/fixture/sandbox/reinout/reinout_project']

There's an ``omit_test.txt`` inside sandbox/reinout:

    >>> pprint(startpoint.traverse('sandbox').traverse('reinout').contents)
    ['omit_test.txt', 'reinout_project']

If we set that as a flag to stop traversing, the reinout_project inside
sandbox/reinout will be missing again:

    >>> info = finder.Finder(startpoint, info_extracter,
    ...                      stop_indicators=['omit_test.txt'])
    >>> pprint([project.location for project in info.projects])
    ['...tests/fixture/customer/site',
     '...tests/fixture/project1']




"""