#!/usr/bin/env python
# tsearchpath.py - Search Multiple Paths Looking For A Filename
# Copyright (c) 2010 TundraWare Inc.
# For Updates See:  http://www.tundraware.com/Software/tsearchpath

# Program Information

RCSID = "$Id: tsearchpath.py,v 1.108 2010/06/25 15:08:23 tundra Exp $"


#----------------------------------------------------------#
#                       Imports                            #
#----------------------------------------------------------#

import os


#----------------------------------------------------------#
#                Constants & Literals                      #
#----------------------------------------------------------#

DEFAULTDELIM = ":"
PATHSEP=os.path.sep



#####
# Search Path For Specific File
#####


def 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"
       
    """
    

    # What we'll return if we find nothing
    
    retval = []

    # Find all instances of filename in specified paths

    paths = pathlist.split(PATHDELIM)

    for path in paths:

        if path and path[-1] != PATHSEP:
            path += PATHSEP

        path += filename

        if os.path.exists(path):
            retval.append(os.path.realpath(path))

    return retval

# End of 'tsearchpath()'