30.15. $applySearchPath

The PROCEDUREs $applySearchPath and $getSearchPath are used together to examine a file searchpath from a program. File searchpaths may be set with the PROCEDURE $setSearchPath or with the MAINEX subcommand SETSEARCHPATH.

The algorithm for figuring out how the searchpath mechanism maps a given file name to the file names open actually tries is:

• Repeatedly call $getSearchPath to get information on the searchpath for each pattern that the initial file name matches.

• After each call to $getSearchPath, repeatedly call $applySearchPath to return each of the actual file names specified by the path for the current pattern and the initial file name.

The PROCEDURE $getSearchPath returns information about a searchpath whose pattern matches fileName. There may be more than one such searchpath; e.g., the file name /dir/myfile.xyz matches both of the following searchpaths:

SEARCHPATH /dir/* /otherNode/otherDir/*
SEARCHPATH *.xyz *.xyz /xyzDir/*.xyz

To handle this case, it is possible to call $getSearchPath repeatedly, as described below; each call to $getSearchPath returns information about one of the searchpaths.

wildCardParts contains the parts of fileName that matched the wild cards in the searchpath's pattern. path is the searchpath's path. The exact format of these two STRINGs is not specified; they are intended for use by $applySearchPath and not for examination directly by the user or application program. p is a POINTER to a record that allows $getSearchPath to keep track of which searchpath it last returned; p should be NULLPOINTER on the first call to $getSearchPath for a particular fileName (the fields of the CLASS $searchPath are not documented).

For example, assuming the two searchpaths above (and assuming that the searchpath for /dir/* was entered second, since the most recently searchpaths are tried first), the code:

p := NULLPOINTER;
bo := $getSearchPath("/dir/myfile.xyz",wildCardParts,path,p);

would set bo to TRUE, wildCardParts to the part of /dir/myfile.xyz that matched /dir/*, path to the path /otherNode/otherDir/*, and p to a value that indicated the searchpath for the pattern /dir/*. The values of wildCardParts and path could then be passed to $applySearchPath, as described below, to see what file names the searchpath actually expanded to.

The next call to $getSearchPath:

$getSearchPath("/dir/myfile.xyz",wildCardParts,path,p);

would also return TRUE, but set wildCardParts, path, and p to information describing the searchpath for the pattern *.xyz. Assuming that there are no further searchpaths that match the initial file name /dir/myfile.xyz, the next call to $getSearchPath:

$getSearchPath("/dir/myfile.xyz",wildCardParts,path,p);

would return FALSE, meaning that no more searchpaths match the given file name.

$applySearchPath takes wildCardParts and path STRINGs as produced by $getSearchPath and applies the next element in the path to the wild card parts. The result is a final file name, such as would be used by open after it applied searchpaths; this is the value returned by $applySearchPath. $applySearchPath returns the empty STRING when there are no more elements in the path STRING.

The following short program that sets and then examines a searchpath:

BEGIN "tsp"

INITIAL PROCEDURE;
BEGIN
STRING s,wildCardParts,path;
POINTER($searchPath) p;
$setSearchPath("*.xyz","*.xyz /xyzDir/*.xyz");
$setSearchPath("/dir/*","/otherNode/otherDir/*");
p := NULLPOINTER;
WHILE $getSearchPath
        ("/dir/myfile.xyz",wildCardParts,path,p) DO
    WHILE s := $applySearchPath(wildCardParts,path) DO
        write(logFile,s,eol);
END;

END "tsp"

An execution of this program looks like:

*tsp<eol>
/otherNode/otherDir/myfile.xyz
/dir/myfile.xyz
/xyzDir//dir/myfile.xyz

The searchpath pattern and path syntax may change in future releases.