#!/usr/bin/env python
# tsearchpath.py
# Copyright (c) 2010 TundraWare Inc.
# For Updates See:  http://www.tundraware.com/Software/tsearchpath

# Program Information

RCSID = "$Id: tsearchpath.py,v 1.104 2010/06/25 02:46:50 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'.

        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 stripping of spaces around PATHDELIM
              characters.  Spaces are treated as part of the path
              component.  This is almost always a mistake and will
              cause nothing to match:

                "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[-1] != PATHSEP:
            path += PATHSEP

        path += filename

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

    return retval

# End of 'tsearchpath()'