Expands a file name to a full pathname and then returns the full pathname or one of its fields (directory, name, or extension).
The format for the $ZPARSE function is:
$ZPARSE(expr1[,expr2[,expr3[,expr4[,expr5]]]])
The first expression specifies the file name; if the file name is not valid, $ZPARSE() returns a null string; if the file name contains a wildcard (* and/or ?), $ZPARSE() returns a file name containing the wildcard(s).
The optional second expression specifies the field of the pathname that $ZPARSE() returns; if this argument is missing or null, $ZPARSE() returns a full pathname constructed using default values in place of any fields missing for directory, file and extension.
The optional third and fourth expressions specify default values to use during file name expansion for missing fields (directory, name, or extension), if any, in the original file name. For any field missing in the original file name specified in expr1, $ZPARSE() will attempt to substitute the corresponding field from expr3; if that field is not present in expr3, $ZPARSE() will attempt to use the corresponding field from expr4.
If the file extension is missing from all three of expr1, expr3, and expr4, $ZPARSE() will return a null string for the corresponding field. If the file or directory is missing from all three of expr1, expr3, and expr4, $ZPARSE() will substitute the information from your current working directory.
The optional fifth expression specifies the mode or type of parse that $ZPARSE() performs.
$ZPARSE() provides a tool for verifying that a file name is syntactically correct, for examining specific fields of a file name, and for filling in missing pieces in a partial specification based on a hierarchy of defaults. For information about determining whether a file exists, see “$ZSEARCH()”.
$ZPARSE() arguments, after the first, are optional. If you use no other arguments, a single argument is sufficient. However, if you use selected arguments $ZPARSE() requires that null strings ("") be filled in for the unspecified arguments.
The acceptable keywords for the second argument are:
"DIRECTORY": Directory name
"NAME": File name (excluding file extension)
"TYPE": File type extension
The keywords may be entered in either upper or lower case. Variables that evaluate to these strings and indirection are acceptable for argument two. When the keywords themselves appear as string literals, they must be enclosed in quotation marks (" ").
The following guidelines must be followed in constructing arguments one, three and four:
Directory specifications must end in a slash; anything after the final slash in the directory specification is assumed to be part of the name specification.
A file name with an extension must include at least one character to the left of the period (.). Thus, "/user/.login" refers to the file named ".login", while "/usr/taxes.c" refers to a file named "taxes" with the extension "c". If a file name includes more than one period, the extension includes all letters to the right of the rightmost period.
The keywords for the fifth argument $ZPARSE() are:
NULL (""): Returns a full file-specification or device
"SYNTAX_ONLY": Disables checking for the existence of the directory or device.
Example:
GTM>write $zparse("test","","/usr/work/","dust.lis")
/usr/work/test.lis
GTM>
This uses $ZPARSE() to demonstrate defaulting using the third and fourth arguments. The result gets the directory field from the third expression, the name from the first expression, and the type from the fourth expression.
Example:
GTM>r!,"file :",f w ?20,$zparse(f,"directory") file: test.list /usr/work/ GTM>
This uses $ZPARSE() to display the directory for the file name entered as input at the prompt file: , in this case, the current working directory.
Example:
$ cd /usr/work/me
$ $gtm
GTM>write $zparse("test","","x.list","y.c")/usr/work/me/test.lis
GTM>write $zparse("test","","/usr/work/","/dev/y.c")/usr/work/test.c
GTM>write $zparse("test","","/usr/work","/dev/y.c")/usr/test.c
GTM>
This example illustratest the use of the third and fourth arguments to $ZPARSE(). In the first statement, the first argument has no directory or extension field, so $ZPARSE() substitutes the extension field from the third argument. Since neither the third nor fourth argument specifies a directory, and because the fourth argument does not contain any fields that are not present in the third argument, the fourth argument is not used.
In the second statement, the first argument to $ZPARSE() is again missing both the directory and extension. In this instance, $ZPARSE() uses the directory specified in the third argument and, becuase neither the first nor third argument specifies a file extension, $ZPARSE() uses the file extension from the fourth argument.
In the third statement, because "/usr/work" does not end with a backward slash (/), $ZPARSE() interprets the substring "work" as a file name. Then, $ZPARSE() substitutes "/usr/" for the directory missing in the first argument and substitutes ".c" from the fourth argument for the extension missing from both the first and third arguments.
Example:
$ cd /usr/work/me
$ /usr/lib/fis-gtm/V5.4-002B_x86/gtm
GTM>For i="DIRECTORY","NAME","TYPE","" Write $ZPARSE("test.m",i),!
/usr/work/me/
test
.m
/usr/work/me/test.m
GTM>
This example illustrates the output produced for each of the possible values for the second argument.