diff --git a/tsearchpath.rst b/tsearchpath.rst index 3aa636d..42915ea 100644 --- a/tsearchpath.rst +++ b/tsearchpath.rst @@ -1,29 +1,114 @@ NAME ---- -**test** - Short Description +**tsearchpath** - Python Module For Path Searching SYNOPSIS -------- -test.py [-hv] +import tsearchpath DESCRIPTION ----------- -Long 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. -OPTIONS -------- - -h Print help information. - -v Print detailed program version information and exit. +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 -------------------- @@ -32,12 +117,12 @@ COPYRIGHT AND LICENSING ----------------------- -**test** is Copyright (c) 2010 TundraWare Inc. +**tsearchpath** is Copyright (c) 2010 TundraWare Inc. -For terms of use, see the ``test-license.txt`` file in the -program distribution. If you install **test** on a FreeBSD +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/test``. +``/usr/local/share/doc/tsearchpath``. AUTHOR ------ @@ -45,7 +130,7 @@ :: Tim Daneliuk - test@tundraware.com + tsearchpath@tundraware.com DOCUMENT REVISION INFORMATION @@ -53,11 +138,11 @@ :: - $Id: tsearchpath.rst,v 1.100 2010/06/25 16:13:10 tundra Exp $ + $Id: tsearchpath.rst,v 1.101 2010/06/25 16:19:33 tundra Exp $ You can find the latest version of this program at: - http://www.tundraware.com/Software/test + http://www.tundraware.com/Software/tsearchpath