#!/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.103 2010/06/24 20:28:30 tundra Exp $"


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

import os


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

DEFAULTDELIM = ":"



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


def tsearchpath(filename,
                pathlist,
                PATHDELIM=DEFAULTDELIM,
                PATHSEP=os.path.sep
               ):

    """ Search 'pathlist' looking for 'filename' returning on first
        (leftmost in 'pathlist') match.  The function is insensitive
        to whether 'filename' is actually a file.  It merely looks for
        some filesystem entity having the given name.

        If found, return the fully qualified filename.
        If not found, return None.

        'pathlist' is a list of paths to search separated by
        PATHDELIM characters.

        If the 'filename' passed contains 'PATHSEP' characters,
        presume it to be a relative/absolute path specified by the
        caller.  In this case, ignore 'pathlist' and just return the
        fully qualified filename.

        Caller can override the delimiter used to separate path
        entries and the path separator character by passing explicit
        instances of PATHDELIM= and PATHSEP= respectively.
    """
    

    # What we'll return if we find nothing
    
    retval = None

    # Handle explicit/relative filename path specifications
    
    if filename.find(PATHSEP) > -1:
        retval = filename


    # Find first matching filename on specified path

    else:
        
        paths = pathlist.split(PATHDELIM)

        for path in paths:

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

            path += filename

            if os.path.exists(path):
                retval = path
                break
    if retval:
        retval = os.path.abspath(retval)

    return retval

# End of 'tsearchpath()'