NAME
----

**tsearchpath** - Python Module For Path Searching

SYNOPSIS
--------

import tsearchpath

DESCRIPTION
-----------

``tsearchpath`` is a Python module for searching a list of paths for a
particular file system 'filename'.  This can be the name of a
directory, file, or any other entity in the file system.  This makes
it easy to add things like include- or configuration file paths to
your own programs.


API DOCUMENTATION
-----------------

::

   tsearchpath(filename,
                pathlist,
                PATHDELIM=DEFAULTDELIM
               )

    """
        Find all instances of a filename in a list of paths.

        Inputs:

              filename - The name of the filesystem entity (file,
                         directory, ...) to look for.

              pathlist - A list of paths to search separated by the
                         PATHDELIM character (Default: ":")

        Output:

              Returns a list of all instances of 'filename' found on
              the paths specified by 'pathlist'.  These appear in
              order of path appearance in 'pathlist' and are returned
              as fully qualified real path names.
              
        
        Options:

              PATHDELIM=char

                        Can be used to specify the separator character
                        used in 'pathlist'.  Provided primarily for
                        situations where you want to maintain
                        compatibility with Windows-style paths
                        that use ";" as a separator.

        Side Effects:

              Module does not check for duplicates in the the
              'pathlist'.  If multiple components there map to the
              same real path and 'filename' exists there, the returned
              list will have duplicate entries.

              There is no space stripping around PATHDELIM characters.
              Spaces are treated as part of the path component.  This
              is almost always a mistake:

                "path1 :path2 :path3"
       
    """
    

EXAMPLES
---------

Simple ``which`` type functionality::

  print tsearchpath("ls", os.getenv("PATH"))


Look for a particular file in many paths::

  print tsearchpath(".profile", "/:/etc:/usr/home/foo:/usr/home/bar")


Look for a particular subdirectory in many paths::

  print tsearchpath("etc", "/:/usr/local")

Look for a configuration file for your program::

  rcfile = tsearchpath(".myprogrc", "./:/usr/local/myprog:/etc/myprog")


TEST PROGRAM
------------

The ``tsearchpath`` distribution tarball contains a simple test
driver program to experiment with this module.  The syntax
for use is::

  testpath.py filename searchpath [Path Separator Character]
  

OTHER
-----

You must have a reasonably current version of Python installed.


BUGS AND MISFEATURES
--------------------

None known as of this release.

COPYRIGHT AND LICENSING
-----------------------

**tsearchpath** is Copyright (c) 2010 TundraWare Inc.

For terms of use, see the ``tsearchpath-license.txt`` file in the
program distribution.  If you install **tsearchpath** on a FreeBSD
system using the 'ports' mechanism, you will also find this file in
``/usr/local/share/doc/tsearchpath``.

AUTHOR
------

::

   Tim Daneliuk
   tsearchpath@tundraware.com


DOCUMENT REVISION INFORMATION
-----------------------------

::

  $Id: tsearchpath.rst,v 1.103 2010/06/25 16:31:32 tundra Exp $

You can find the latest version of this program at:

  http://www.tundraware.com/Software/tsearchpath