|
|
IDL Reference Guide: Procedures and Functions |
|
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 !PATH, and !HELP_PATH system variables, for example.
| Note The mechanism used by EXPAND_PATH to expand the path-definition string is the same as that is used to expand the contents of the IDL_PATH, IDL_DLM_PATH, and IDL_HELP_PATH preferences at startup. See The Path Definition String below for more information. |
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 !PATH, !DLM_PATH, or !HELP_PATH system variables.
| Note The syntax of the path definition string describe here can also be used when setting the IDL_PATH, IDL_DLM_PATH, and IDL_HELP_PATH preferences. When IDL starts, it will treat the value of the preference in the same way EXPAND_PATH treats the path definition string. |
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.
.dlm) if the DLM keyword to EXPAND_PATH is present.
.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 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 !PATH (or !DLM_PATH or !HELP_PATH) in any other way. You can therefore obtain any search order you desire by writing the path explicitly.
<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 See !DLM_PATH for examples using the <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 !PATH, !DLM_PATH, or !HELP_PATH system variables given a string path to be expanded.
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 !DLM_PATH system variable:
PRINT, EXPAND_PATH('<IDL_DEFAULT>', /DLM)
IDL Environment System Variables.
IDL Online Help (March 06, 2007)