The EXPAND_PATH function is used to expand a simple path-definition string into a full path listing. The returned path can be useful for setting the
| Note |
EXPAND_PATH accepts a single argument, a scalar string that contains a simple path-definition string. EXPAND_PATH expands the path-definition string into a list of directories that can be assigned to the
| Note |
IDL supports the following special notations within the path definition string:
.pro or .sav) if neither the DLM nor the HELP keywords to EXPAND_PATH are present, or in the IDL_PATH environment variable. .dlm) if the DLM keyword to EXPAND_PATH is present, or in the IDL_DLM_PATH environment variable..pdf) files, HTML format (.html or .htm) files, or have the file extension.help . On Windows systems, help files can be either HTML Help (.chm), WinHelp (.hlp), PDF (.pdf), or HTML (.html or .htm) files.Any directory containing one or more of the appropriate type of file is added to the path.
If the "+" is not present, the specified directory is added to the path regardless of its contents.
Order of Expanded Directories
When expanding a path segment starting with "+", IDL ensures that all directories containing the appropriate type files are placed in the path string. The order in which the directories in such an expanded path segment appear is completely unspecified, and does not necessarily correspond to any specific order (such as top-down alphabetized). This allows IDL to construct the path in the fastest possible way and speeds the process of loading paths from environment variables at startup. This is only a problem if two subdirectories in such a hierarchy contain a file with the same name.
If the order in which "+" expands directories is a problem for your application, you should add the directories to the path explicitly and not use "+". Only the order of the files within a given "+" entry are determined by IDL. It never reorders
<IDL_DEFAULT> in a path definition string with the default value IDL would have used if no environment variable or preference were set. The actual value of this placeholder depends on where IDL has been installed. Hence, to view IDL's default path:
PRINT, EXPAND_PATH('<IDL_DEFAULT>')
To append your own directory after IDL's default DLM path using the IDL_DLM_PATH environment variable (under UNIX):
% setenv IDL_DLM_PATH "<IDL_DEFAULT>:/your/path/here"
(Setting the Windows environment variable IDL_DLM_PATH to a similar string would produce the same result on a Windows system.) This substitution allows you to set up your paths without having to hard-code IDL's defaults into your startup scripts or environment variables.
Note that the actual path that the token <IDL_DEFAULT> expands to depends on the context in which it is used. The default path for .pro and .sav files is different from the default path for .dlm files or help files. To see this, enter the following statements into IDL:
PRINT, EXPAND_PATH('<IDL_DEFAULT>')
PRINT, EXPAND_PATH('<IDL_DEFAULT>', /DLM)
PRINT, EXPAND_PATH('<IDL_DEFAULT>', /HELP)
Three variations of the <IDL_DEFAULT> token eliminate this dependence on context:
<IDL_BIN_DIRNAME> in a path definition string with the name of the subdirectory within the installed IDL distribution where binaries for the current system are kept. This feature is useful for distributing packages of DLMs (Dynamically Loadable Modules) with support for multiple operating system and hardware combinations.<IDL_VERSION_DIRNAME> in a path definition string with a unique name for the IDL version that is currently running. This feature can be combined with <IDL_BIN_DIRNAME> to easily distribute packages of DLMs with support for multiple IDL versions, operating systems, and hardware platforms.
| Note |
<IDL_BIN_DIRNAME> and <IDL_VERSION_DIRNAME> tokens.
Result = EXPAND_PATH( String [, /ALL_DIRS] [, /ARRAY] [, COUNT=variable] [, /DLM] [, /HELP] )
Returns a list of directories that can be assigned to the
A scalar string containing the path-definition string to be expanded. See The Path Definition String for details.
Set this keyword to return all directories without concern for their contents, otherwise, EXPAND_PATH only returns those directories that contain .pro or .sav files.
Set this keyword to return the result as a string array with each element containing one path segment. In this case, there is no need for a separator character and none is supplied. Normally, the result is a string array with the path segments separated with the correct special delimiter character for the current operating system.
Set this keyword to a named variable which returns the number of path segments contained in the result.
Set this keyword to return those directories that contain IDL Dynamically Loadable Module (.dlm) description files.
Set this keyword to return directories that contain help files. On UNIX platforms, help files are in Adobe Portable Document Format (.pdf), HTML format (.html or .htm), or have the file extension .help . On Windows systems, help files can be either HTML Help (.chm), WinHelp (.hlp), PDF (.pdf), or HTML (.html or .htm) files.
Assume you have the following directory structure:
/home myfile.txt /programs /pro myfile.pro
Search the /home directory and all its subdirectories, and return the directories containing .pro and .sav files:
PRINT, EXPAND_PATH('+/home')
IDL prints:
/home/programs/pro
Search the same directory, but this time return all directories, not just those containing .pro and .sav files:
PRINT, EXPAND_PATH('+home', /ALL_DIRS)
IDL prints:
/home/programs/pro:/home/programs
Print the default value of the
PRINT, EXPAND_PATH('<IDL_DEFAULT>', /DLM)
Introduced: Pre 4.0
Modified to use the <IDL_*_PATH> syntax: 5.6
Running IDL Programs and IDL Environment System Variables