Parse


Section contents


Overview

Defined in

cfile.oxh

Description
Component masking

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.

Parsing with reference to the session default directory

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.

Illegal paths

The following restrictions apply to path components. If any are violated, Parse will return K32ErrBadName: —

    err%=ParseSet%(this&,"DIR\\","","")
    err%=ParseSet%(this&,"C: \\DIR\\","","")

Construction / destruction


NewParse - Constructor

Usage

this& = NewParse&:

Description

Creates a file parse object and returns a handle which allows the object to be manipulated.

Return Value
this& An value which represents the created file parse object
Error Handling

If the object could not be created then an error is generated which should be trapped by an ONERR handler.

Example
  LOCAL this&

  this& = NewParse&:
  DeleteParse:(this&) 

DeleteParse - Destructor

Usage

DeleteParse:(BYREF this&)

Description

Destroys the file parse object.

Arguments
BYREF this& A handle to a file parse object
Example
  LOCAL this&

  this& = NewParse&:()
  DeleteParse:(this&) 

Methods provided


ParseAddDir - add a directory

Usage

err% = ParseAddDir%:(this&,name$)

Description

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.

Arguments
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.
Return value
err% An error code

ParseDrive - get drive letter

Usage

drive$ = ParseDrive$:(this&)

Description

Use this function to get the drive letter, in the form:

      drive-letter:

Arguments
this& A handle to a file parse object
Return value
drive$ The drive letter and colon
Error Handling

If the drive$ string cannot be created then an error is generated which should be trapped by an ONERR handler.


ParseDriveAndPath - get drive and path

Usage

drive$ = ParseDriveAndPath$:(this&)

Description

Use this function to get the drive letter and path in the form

      drive-letter:\path\

Arguments
this& A handle to a file parse object
Return value
drive$ The drive and path
Error Handling

If the drive$ string cannot be created then an error is generated which should be trapped by an ONERR handler.


ParseDrivePresent - get whether drive present

Usage

bool% = ParseDrivePresent%:(this&)

Description

Use this function to get whether a drive is present.

Arguments
this& A handle to a file parse object
Return value
bool% True if drive present, false if not.

ParseExt - get extension

Usage

ext$ = ParseExt$:(this&)

Description

Use this function to get the extension, in the form

      .extension

Arguments
this& A handle to a file parse object
Return value
ext$ The extension and preceding dot.

ParseExtPresent - get whether extension present

Usage

bool% = ParseExtPresent%:(this&)

Description

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.

Arguments
this& A handle to a file parse object
Return value
bool% True if extension present, false if not.

ParseFullName - get complete file specification

Usage

name$ = ParseFullName$:(this&)

Description

Use this function to get the complete file specification, in the form:

      drive-letter:\path\filename.extension

Arguments
this& A handle to a file parse object
Return value
name$ The fully parsed file specification.
Error Handling

If the name$ string cannot be created then an error is generated which should be trapped by an ONERR handler.


ParseIsExtWild - get whether extension contains wildcards

Usage

bool% = ParseIsExtWild%:(this&)

Description

Use this function to get whether the extension in the fully parsed specification contains one or more wildcard characters.

Arguments
this& A handle to a file parse object
Return value
bool% True if extension contains wildcards, false if not.

ParseIsNameWild - get whether file contains wildcards

Usage

bool% = ParseIsNameWild%:(this&)

Description

Use this function to get whether the filename in the fully parsed specification contains one or more wildcard characters.

Arguments
this& A handle to a file parse object
Return value
bool% True if filename contains wildcards, false if not.

ParseIsRoot - get whether path is root

Usage

bool% = ParseIsRoot%:(this&)

Description

Use this function to get whether the path in the fully parsed specification indicates the root directory.

Arguments
this& A handle to a file parse object
Return value
bool% True if path is root, false if not.

ParseIsWild - get whether wildcards present

Usage

bool% = ParseIsWild%:(this&)

Description

Use this function to get whether either the filename or extension in the fully parsed specification contains one or more wildcard characters.

Arguments
this& A handle to a file parse object
Return value
bool% True if wildcards present, false if not.

ParseName - get filename

Usage

name$ = ParseName$:(this&)

Description

Use this function to get the filename, in the form

      filename

Arguments
this& A handle to a file parse object
Return value
name$ The filename
Error Handling

If the name$ string cannot be created then an error is generated which should be trapped by an ONERR handler.


ParseNameAndExt - get filename and extension

Usage

name$ = ParseNameAndExt$:(this&)

Description

Use this function to get the filename and extension, in the form

      filename.ext

Arguments
this& A handle to a file parse object
Return value
name$ The filename and extension
Error Handling

If the name$ string cannot be created then an error is generated which should be trapped by an ONERR handler.


ParseNamePresent - get whether name present

Usage

bool% = ParseNamePresent%:(this&)

Description

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.

Arguments
this& A handle to a file parse object
Return value
bool% True if name present, false if not.

ParseNameOrExtPresent - get whether name or extension present

Usage

bool% = ParseNameOrExtPresent%:(this&)

Description

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.

Arguments
this& A handle to a file parse object
Return value
bool% True if either name or extension or both are present, otherwise false.

ParsePath - get path

Usage

name$ = ParsePath$:(this&)

Description

Use this function to get the path, in the form:

      \path\

Arguments
this& A handle to a file parse object
Return value
name$ The path. Always begins and ends in a backslash.
Error Handling

If the name$ string cannot be created then an error is generated which should be trapped by an ONERR handler.


ParsePathPresent - get whether path present

Usage

bool% = ParsePathPresent%:(this&)

Description

Use this function to get whether a path is present.

Arguments
this& A handle to a file parse object
Return value
bool% True if path present, false if not.

ParsePopDir - pop last directory

Usage

err% = ParsePopDir%:(this&)

Description

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.

Arguments
this& A handle to a file parse object
Return value
err% An error code

ParseSet - parse a file specification

Usage

err% = ParseSet%:(this&,name$,related$,default$)

Description

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.

Arguments
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
Return value
err% An error code

ParseSetNoWild - parse a file specification, no wildcards

Usage

err% = ParseSetNoWild%:(this&,name$,related$,default$)

Description

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.

Arguments
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
Return value
err% An error code