idlastro / Miscellaneous (Non-Astronomy) Procedures: FIND_ALL_DIR

[Source code]

NAME
FIND_ALL_DIR()
PURPOSE
Finds all directories under a specified directory.
EXPLANATION
This routine finds all the directories in a directory tree when the
root of the tree is specified.  This provides the same functionality as
having a directory with a plus in front of it in the environment
variable IDL_PATH.
CALLING SEQUENCE
Result = FIND_ALL_DIR( PATH )
        PATHS = FIND_ALL_DIR('+mypath', /PATH_FORMAT)
        PATHS = FIND_ALL_DIR('+mypath1:+mypath2')
INPUTS
PATH    = The path specification for the top directory in the tree.
        Optionally this may begin with the '+' character but the action
        is the same unless the PLUS_REQUIRED keyword is set.
        One can also path a series of directories separated
        by the correct character (";" for Windows ":" for Unix)
OUTPUTS
The result of the function is a list of directories starting from the
top directory passed and working downward from there.   Normally, this
will be a string array with one directory per array element, but if
the PATH_FORMAT keyword is set, then a single string will be returned,
in the correct format to be incorporated into !PATH.
OPTIONAL INPUT KEYWORDS
PATH_FORMAT     = If set, then a single string is returned, in
                          the format of !PATH.
PLUS_REQUIRED   = If set, then a leading plus sign is required
                in order to expand out a directory tree.
                This is especially useful if the input is a
                series of directories, where some components
                should be expanded, but others shouldn't.
RESET   = Often FIND_ALL_DIR is used with logical names.  It
        can be rather slow to search through these subdirectories.
        The /RESET keyword can be used to redefine an environment
        variable so that subsequent calls don't need to look for the
        subdirectories.
        To use /RESET, the PATH parameter must contain the name of a
        *single* environment variable.  For example
                        setenv,'FITS_DATA=+/datadisk/fits'
                        dir = find_all_dir('FITS_DATA',/reset,/plus)
        The /RESET keyword is usually combined with /PLUS_REQUIRED.
PROCEDURE CALLS
DEF_DIRLIST, FIND_WITH_DEF(), BREAK_PATH()
RESTRICTIONS
PATH must point to a directory that actually exists.
REVISION HISTORY
Version 11, Zarro (SM&A/GSFC), 23-March-00
        Removed all calls to IS_DIR
Version 12, William Thompson, GSFC, 02-Feb-2001
        In Windows, use built-in expand_path if able.
Version 13, William Thompson, GSFC, 23-Apr-2002
        Follow logical links in Unix
        (Suggested by Pascal Saint-Hilaire)
Version 14, Zarro (EER/GSFC), 26-Oct-2002
        Saved/restored current directory to protect against
        often mysterious directory changes caused by 
        spawning FIND in Unix
Version 15, William Thompson, GSFC, 9-Feb-2004
        Resolve environment variables in Windows.
Version Version 16 W. Landsman GSFC Sep 2006
Remove VMS support