EXPAND_PATH

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.

!PATH is a list of locations where IDL searches for currently undefined procedures and functions.

!HELP_PATH is a list of locations where IDL searches for online help files when the online help facility is used.

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.

The Path Definition String

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:

Using "+" — When IDL encounters a "+" in front of a directory name, it searches the directory and all of its subdirectories for files of the appropriate type for the given path:

IDL program files (.pro or .sav) if neither the DLM nor the HELP keywords to EXPAND_PATH are present.

Dynamically Loadable Module files (.dlm) if the DLM keyword to EXPAND_PATH is present.

Files that can be used by IDL's online help system, if the HELP keyword to EXPAND_PATH is present. On UNIX platforms, help files are Adobe Portable Document Format (.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.

Using "<IDL_DEFAULT>" — IDL replaces any occurrence of the token <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_DEFAULT_PATH> defines the default path to .pro and .sav files.

<IDL_DEFAULT_DLM> defines the default path to .dlm files.

<IDL_DEFAULT_HELP> defines the default path to help (.pdf, .html, and .chm) files.

Using "<IDL_BIN_DIRNAME>" — IDL replaces any occurrence of the token <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.

Using "<IDL_VERSION_DIRNAME>" — IDL replaces any occurrence of the token <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.

Syntax

Result = EXPAND_PATH( String [, /ALL_DIRS] [, /ARRAY] [, COUNT=variable] [, /DLM] [, /HELP] )

Return Value

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.

Arguments

String

A scalar string containing the path-definition string to be expanded. See The Path Definition String for details.

Keywords

ALL_DIRS

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.

ARRAY

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.

COUNT

Set this keyword to a named variable which returns the number of path segments contained in the result.

DLM

Set this keyword to return those directories that contain IDL Dynamically Loadable Module (.dlm) description files (that is, directories specified by the !DLM_PATH system variable).

HELP

Set this keyword to return directories that contain help files (that is, directories specified by the !HELP_PATH system variable). 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.

Note
In IDL 7.0, the files that comprise IDL's online help system are not included in the !HELP_PATH, and are thus not found by this keyword.

Examples

Example 1

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

Example 2

Search the same directory, but this time return all directories, not just those containing .pro and .sav files:

PRINT, EXPAND_PATH('+home', /ALL_DIRS)