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 functionatily:

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

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.102 2010/06/25 16:23:19 tundra Exp $

You can find the latest version of this program at:

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