Section contents
cfile.oxh
Parse can also be used to select components from different file and path specifications. The ParseSet function takes three arguments. They are each parsed into four components:
ParseSet arguments | Drive | Path | Filename | Extension |
---|---|---|---|---|
*.obj |
.obj |
|||
hello.cpp |
hello |
.cpp |
||
c:\projects\hello\ |
c: |
\projects\hello\ |
The result of ParseFullName is obtained by taking the
first component that is defined from each column in this table,
thus c:\projects\hello\hello.obj
. The other getter
functions return corresponding components of this full name. Note
the trailing backslash after each directory name: without this,
the example would not work correctly.
Thus, Parse can be used to combine a directory with a filename, or even to combine a directory with a filename and change the extension.
The matching can use wildcards *
(asterisk) meaning any sequence of characters within any part of
a component, and ?
(question mark) meaning any
single character. If wildcard matching is not desired, ParseSetNoWild
should be used instead of ParseSet. The wildcard
characters are fixed.
Parse operations occur without reference to the file server. The FsParse function perform a ParseSet using the session path as the default$ argumentt. Use these FsParse function to parse filenames with reference to the session path.
The following restrictions apply to path components. If any are violated, Parse will return K32ErrBadName:
DIR\
is neither a directory nor a file. err%=ParseSet%(this&,"DIR\\","","")
err%=ParseSet%(this&,"C: \\DIR\\","","")
this& = NewParse&:
Creates a file parse object and returns a handle which allows the object to be manipulated.
this& |
An value which represents the created file parse object |
If the object could not be created then an error is generated
which should be trapped by an ONERR
handler.
LOCAL this& this& = NewParse&: DeleteParse:(this&)
DeleteParse:(BYREF this&)
Destroys the file parse object.
BYREF this& |
A handle to a file parse object |
LOCAL this& this& = NewParse&:() DeleteParse:(this&)
err% = ParseAddDir%:(this&,name$)
Use this function to add a single directory onto the end of the path in the fully parsed specification. The directory is inserted between the final directory and the filename, if there is one.
this& |
A handle to a file parse object |
name$ |
The directory to add. It must not start with a \\ otherwise the function does not recognize it as a valid directory name and an error is returned. The directory name must not end with a \\ since the function adds this automatically. Must not exceed the maximum filename length (KMaxFileName&) or an error is returned. |
err% |
An error code |
drive$ = ParseDrive$:(this&)
Use this function to get the drive letter, in the form:
drive-letter:
this& |
A handle to a file parse object |
drive$ |
The drive letter and colon |
If the drive$
string cannot be created then an
error is generated which should be trapped by an ONERR
handler.
drive$ = ParseDriveAndPath$:(this&)
Use this function to get the drive letter and path in the form
drive-letter:\path\
this& |
A handle to a file parse object |
drive$ |
The drive and path |
If the drive$
string cannot be created then an
error is generated which should be trapped by an ONERR
handler.
bool% = ParseDrivePresent%:(this&)
Use this function to get whether a drive is present.
this& |
A handle to a file parse object |
bool% |
True if drive present, false if not. |
ext$ = ParseExt$:(this&)
Use this function to get the extension, in the form
.extension
this& |
A handle to a file parse object |
ext$ |
The extension and preceding dot. |
bool% = ParseExtPresent%:(this&)
Use this function to get whether an extension is present. This function returns true even if the extension contains only wildcards. It only returns false if nothing is specified.
this& |
A handle to a file parse object |
bool% |
True if extension present, false if not. |
name$ = ParseFullName$:(this&)
Use this function to get the complete file specification, in the form:
drive-letter:\path\filename.extension
this& |
A handle to a file parse object |
name$ |
The fully parsed file specification. |
If the name$
string cannot be created then an
error is generated which should be trapped by an ONERR
handler.
bool% = ParseIsExtWild%:(this&)
Use this function to get whether the extension in the fully parsed specification contains one or more wildcard characters.
this& |
A handle to a file parse object |
bool% |
True if extension contains wildcards, false if not. |
bool% = ParseIsNameWild%:(this&)
Use this function to get whether the filename in the fully parsed specification contains one or more wildcard characters.
this& |
A handle to a file parse object |
bool% |
True if filename contains wildcards, false if not. |
bool% = ParseIsRoot%:(this&)
Use this function to get whether the path in the fully parsed specification indicates the root directory.
this& |
A handle to a file parse object |
bool% |
True if path is root, false if not. |
bool% = ParseIsWild%:(this&)
Use this function to get whether either the filename or extension in the fully parsed specification contains one or more wildcard characters.
this& |
A handle to a file parse object |
bool% |
True if wildcards present, false if not. |
name$ = ParseName$:(this&)
Use this function to get the filename, in the form
filename
this& |
A handle to a file parse object |
name$ |
The filename |
If the name$
string cannot be created then an
error is generated which should be trapped by an ONERR
handler.
name$ = ParseNameAndExt$:(this&)
Use this function to get the filename and extension, in the form
filename.ext
this& |
A handle to a file parse object |
name$ |
The filename and extension |
If the name$
string cannot be created then an
error is generated which should be trapped by an ONERR
handler.
bool% = ParseNamePresent%:(this&)
Use this function to get whether a file name is present. This function will return TRUE even if the filename specified contains only wildcards. It only returns FALSE if nothing is specified.
this& |
A handle to a file parse object |
bool% |
True if name present, false if not. |
bool% = ParseNameOrExtPresent%:(this&)
Use this function to get whether a filename or an extension are present. This function returns true even if the filename or extension specified contain only wildcards. It only returns false if nothing is specified.
this& |
A handle to a file parse object |
bool% |
True if either name or extension or both are present, otherwise false. |
name$ = ParsePath$:(this&)
Use this function to get the path, in the form:
\path\
this& |
A handle to a file parse object |
name$ |
The path. Always begins and ends in a backslash. |
If the name$
string cannot be created then an
error is generated which should be trapped by an ONERR
handler.
bool% = ParsePathPresent%:(this&)
Use this function to get whether a path is present.
this& |
A handle to a file parse object |
bool% |
True if path present, false if not. |
err% = ParsePopDir%:(this&)
Use this function to remove the last directory from the path in the fully parsed specification. This function may be used to navigate up one level in a directory hierarchy. An error is returned if the specified directory is the root.
this& |
A handle to a file parse object |
err% |
An error code |
err% = ParseSet%:(this&,name$,related$,default$)
Use this function to parse a file specification. Wildcards are allowed in the filename and extension. This function sets up the Parse object so that it can be used to yield useful information.
this& |
A handle to a file parse object |
name$ |
The file specification to be parsed |
related$ |
The related file specification optional: specify "" to omit |
default$ |
The default file specification optional: specify "" to omit |
err% |
An error code |
err% =
ParseSetNoWild%:(this&,name$,related$,default$)
Use this function to parse a file specification. Wildcards are not allowed in any part of the filename or extension. If you need to specify wildcards use ParseSet. Otherwise, this function operates in the same way as ParseSet.
this& |
A handle to a file parse object |
name$ |
The file specification to be parsed |
related$ |
The related file specification optional: specify "" to omit |
default$ |
The default file specification optional: specify "" to omit |
err% |
An error code |