EMaskError is a EConvertError descendant representing the exception raised when an invalid character is found in a mask expression, or when an invalid value is assigned to properties in a mask class instances. EMaskError is the exception type raised in TMaskBase methods like:

• Exception_InvalidCharMask
• Exception_MissingCloseChar
• Exception_IncompleteMask
• Exception_InvalidEscapeChar
• Exception_InternalError

Calls the CreateFmt constructor using the values in msg and aCode as arguments.

CreateFmt is an overridden constructor used to create an exception instance with the values specified in the msg and aCode arguments. It stores the value in ACode to the cCode member, and calls the inherited method.

msg is a String which contains a formatting specification using the notation allowed for the RTL Format routine. Values from the args parameter are substituted for the placeholders found in the msg argument.

Code is a read-only TMaskExceptionCode property with the code for a mask exception class instance. The value in Code is passed as argument to the Create or CreateFmt constructors.

TMaskOpcodes is the type passed as argument to the constructor for TMaskBase and TWindowsMaskUTF8 classes, and used to implement their MaskOpCodes property.

Omits the op code identifiers mocAnyCharOrNone, mocRange, and mocSet.

Interprets '[?]' as a literal question mark instead of 0..1 character wildcard. Disables escape characters like '\?'. Omits the op code values mocAnyCharOrNone and mocEscapeChar.

DefaultMaskOpCodes includes the TMaskOpCode values found in AllMaskOpCodes with the exception of mocEscapeChar. This disables use of the escape character ('\' is the default) in a mask expression. DefaultMaskOpCodes is used as the default value for an argument passed to the TMaskBase.Create and TMaskList.Create methods.

TWindowsQuirk is an enumerated type used to represent ways in which a Windows/DOS mask works differently than a regular mask. Windows/DOS masks have many quirks and corner cases inherited from CP/M, then adapted to DOS (8.3) file names, and adapted again for long file names.

A TWindowsQuirks type is passed as an argument to the Create method in TWindowsMaskUTF8, and is the type used for its Quirks property.

AllWindowsQuirks can be passed an argument to the constructor in TWindowsMaskUTF8, or assigned directly to the Quirks property in the mask class instance.

DefaultWindowsQuirks can be passed an argument to the constructor in TWindowsMaskUTF8, or assigned directly to the Quirks property in the mask class instance. Omits the values wqExtension3More and wqAllByExtension.

TMaskOption is an enumerated type with values for options that can be enabled in TMask class instances. Values from the enumeration are stored in the TMaskOptions set type, and passed as an argument to an alternate constructor in TMaskBase and descendent classes. Values in the set also control the values assigned to the CaseSensitive and MaskOpCodes properties in the mask class instance.

TMaskOption and TMaskOptions are provided for backward compatibility with previous versions of LazUtils.

TMaskBase provides the framework or API used to examine and handle a mask expression. It provides member fields used to store the compiled op codes for the mask expression as well other state information. Methods are provides to raise exceptions for specific mask error conditions. Properties are also implemented to represent the case sensitivity, escape character, range handling, and op codes enabled for a mask expression.

Please note that TMaskBase does not capture, compile or store the mask expression. Those actions are performed in a descendent class.

Used in the Add and IncrementLastCounterBy methods.

TMaskFailCause is the type returned from the IntfMatches method in TMaskUTF8 and descendent classes.

Add is an overloaded method used to add one or more op codes for compiled mask expression. The overloaded variants allow the op code to be specified as a TMaskParsedCode enumeration value, as a pointer to byte values for the parsed op code(s), or as an Integer.

Add is called is from the Compile method (in descendent classes) when UTF-8 codepoints in the mask expression are translated into their corresponding op codes.

Calls Exception_InternalError when the op code at the current position does not match the value in AOpCode. IncrementLastCounterBy is called from the private CompileRange method.

Used to implement the Compile method in descendent classes.

Exception_InvalidCharMask is a class procedure used to raise an exception when a character in the mask expression is invalid. Exception_InvalidCharMask is one of the methods called during execution of the Compile method (in descendent classes) when an invalid Mask expression is detected for the class instance.

In TMaskBase, an EMaskError exception is always raised. The base class does not implement the required mask expression, nor does it provide a complete implementation of the Compile method.

Exception_MissingCloseChar is a class procedure used to raise an EMaskError exception when the closing ']' character is omitted from a set or range expression. The exception message is determined by the value in the aOffset argument. When aOffset is a positive value (or zero), the value in rsMissingCloseCharMaskAt is used as the exception message. Otherwise, the value in rsMissingCloseCharMask is used.

Exception_MissingCloseChar is called from the private CompileRange method in TMaskUTF8 when the range or set expression is not closed.

The exception is raised with the message in the rsIncompleteMask resource string.

Exception_InvalidEscapeChar is a class procedure used to raise an EMaskError exception when an invalid value is assigned to the EscapeChar property. This occurs when the new property value is not in the range #0..#127. The exception is raised with the message in the rsInvalidEscapeChar resource string.

The method is called from the IncrementLastCounterBy method when a range expression is handled in Compile.

Create is the overloaded constructor for the class instance. One variant allows case sensitivity for mask expressions and the allowed op codes to be specified as arguments. The other variant accepts an argument with the set of mask options for the class instance.

Create the sets the initial values for the CaseSensitive, AutoReverseRange, and EscapeChar properties.

CaseSensitive is a Boolean property which indicates if character in a mask expression are handle with case sensitivity. Its value is determined by an explicit argument passed to the Create method, or the presence of moCaseSensitive in the TMaskOptions passed to the constructor.

Changing the value for the property causes Compile to be called when the Matches method in descendent classes is executed. When set to False, both the mask expression and the compared values are converted to lowercase for the comparison performed in Matches.

Setting AutoReverseRange to True would cause a range expression like '[e-a]' to be treated as if it were specified as '[a-e]'. The default value for the property is True, as assigned in the Create constructor.

Changing the value for the property causes Compile to be called during execution of the Matches method. The property value is used in the implementation of the private CompileRange method in descendent classes.

EscapeChar causes the character that immediately follows the value to be treated as a literal character instead of a wildcard. It is used to allow wildcard characters (like '?' or '*') or set / range characters (like '[', '-', or ']') to be used as literals in the Mask expression. The default value for the property is '\' (Backslash) as assigned in the Create constructor.

EscapeChar must be one of the 7-bit ASCII characters in the range #0..#127. Setting the property to a value larger than #127 (ASCII Delete) causes an EMaskError exception to be raised with the message in the rsInvalidEscapeChar resource string.

Changing the value for the property causes Compile to be called during execution of the Matches method.

Descendent classes (which include the Mask expression) use the value in their Compile and CompileRange methods. Make sure the class instance has the value mocRange in the MaskOpCodes property to enable range notation in the Mask expression.

MaskOpCodes is a TMaskOpCodes property with the set of op codes enabled for the Mask expression in the class instance. MaskOpCodes is populated with enumeration values from TMaskOpCode when characters in the mask expression are examined in the Compile method. The allowed values in the set can be specified as an argument to the Create constructor.

Values in MaskOpCodes are used when the Matches method is called to compare a string value to the Mask expression.

Setting a new value for the property causes Compile to be called during execution of the Matches method in descendent classes.

TMaskUTF8 is a TMaskBase descendant which implements a class used for mask expressions using UNIX file system conventions. It extends the ancestor class with support for a UTF-8-encoded Mask expression. The mask expression uses wildcards and other notation specific to UNIX-like file systems, including:

'?'

Represents any single required character in a file or directory name. For instance, 'c?t' matches 'cat' and 'cut', but not 'coat' or 'cult'. An expression like 'cl??' would matches values like 'clap' and 'clot', but not 'clean' or 'clt'.

'*'

Matches all entries in a directory. This includes entries with or without a file extension, and does not differentiate between files and directories. This is commonly referred to as the "all files" mask.

'*.*'

Matches all entries which have any given file extension. The file extension is required though. Please note that this notation is different than the one implemented for the Windows file system.

'*.ext'

Matches all entries which have a '.ext' file extension.

'file*

Matches all entries that start with 'file' and may contain any number of additional optional characters or a file extension. Matches 'file', 'filename' and 'filename.ext'.

'[]' (square brackets)

Represents a choice of characters that may represent a match on the file system. They are used in both set and range expressions. A set is expressed using notation like 'c[au]t'. This would match entries like 'cat' or 'cut', but not 'cot'. A range uses notation like 'g[a-f]z'. This would match values like 'gaz', 'gbz', and 'gcz'. It would not match 'ggz', 'gxz', or 'gz'.

'[!]'

Used to negate a set or range expression. It matches any character value which is NOT in the set or range.

'\' (Backslash)

The default escape character which forces the following character to be interpreted as a literal and not a wildcard. The escape character is configurable in the class instance using the EscapeChar property.

TMaskUTF8 provides an overridden Compile method which examines and converts the Mask expression into a list of op codes needed in Matches and MatchesWindowsMask.

CompareUTF8Sequences is an Integer class function used to compare the UTF-8 codepoints in the values specified by P1 and P2. The return value is the numeric difference between the byte values in the differing UTF-8 codepoints. The return value is 0 (zero) when P1 and P2 have the same UTF-8-encoded content.

CompareUTF8Sequences is used in the implementation of the CompileRange and IntfMatches methods.

IntfMatches is a TMaskFailCause function which implements the Matches method in the class instance.

IntfMatches uses the compiled op codes for the Mask expression to determine whether a value in the compared string are suitable for op codes. The return value indicates the success or reason for failure in the method.

IntfMatches is called from the Matches method.

Create is the overloaded constructor for the class instance. It includes an AMask argument which contains the expression stored in the Mask property. Variants of the method also allow the value in CaseSensitive to be set. Set arguments can be provided which contain the TMaskOpCode values or the TMaskOption values used in the class instance.

Compile is a virtual method used to examine and convert values from the Mask property into TMaskParsedCode values for the positions in the mask expression.

CaseSensitive indicates if case is significant for the value in Mask. Mask is converted to lowercase prior to processing in the method when CaseSensitive is set to False.

Compile examines each of the UTF-8 codepoints in Mask, and adds values to an internal list representing the character ranges, literal values, or other TMaskParsedCode values needed to evaluate the Mask expression. Compile may raise an exception when an invalid or incomplete mask is encountered. If the Compile method is called again using the same value in Mask, it simply returns False rather than re-raise the exception.

Compile is called from the Matches method when the Mask expression has not already been compiled.

Matches calls Compile if the MaskOpCodes have not been compiled for the Mask expression, or when one the configuration parameters has been changed for the class instance. When CaseSensitive is set to False, the value in aStringToMatch is converted to a lowercase UTF-8 codepoint for the comparison.

Matches calls the IntfMatches method to implement the comparison between the specified value using the MaskOpCodes for the class instance. The return value is True if the call to IntfMatches is successful. It is False if either the Mask expression or the compared value is too long or too short.

Mask is a String property which contains the mask expression used to compare / evaluate a value in the Matches method. The property value is initially set using the arguments passed to the Create constructor. Values in Mask use the UNIX file system conventions for wildcards and related notations.

Character values in Mask are translated into op codes in the Compile method. These op codes are used in the Matches method to evaluate and compare a given value to the compiled mask expression.

Changing the value for the property causes Compile to be called when the Matches method is executed.

TMask is an alias for the TMaskUTF8 class. Provided for compatibility with previous LazUtils versions.

Use TWindowsMaskUTF8 or TWindowsMask for mask expressions using DOS/Windows-specific notation and file system conventions.

TWindowsMaskUTF8 is a TMask descendant which implements a class used for mask expressions using Windows file system conventions. It extends the ancestor class with support for a UTF-8-encoded Mask expression. The mask expression uses wildcards and other notation specific to Windows/DOS file systems, including:

'?'

Represents any single required character in a file or directory name. For instance, 'c?t' matches 'cat' and 'cut', but not 'coat' or 'cult'. An expression like 'cl??' would matches values like 'clap' and 'clot', but not 'clean' or 'clt'.

'*'

Matches any entries found in a directory. This includes files that have a file extension. Behaves the same as '*.*'.

'*.*'

Matches all entries in a directory. The file extension is optional. Please note that this notation is different than the behavior in TMaskUTF8 / TMask.

'*.ext'

Matches all entries which have a '.ext' file extension.

'file*

Matches all entries that start with 'file' and may contain any number of additional optional characters or an optional file extension. Matches 'file', 'filename' and 'filename.ext'.

'[]' (square brackets)

Represents a choice of characters that may represent a match on the file system. They are used in both set and range expressions. A set is expressed using notation like 'c[au]t'. This would match entries like 'cat' or 'cut', but not 'cot'. A range uses notation like 'g[a-f]z'. This would match values like 'gaz', 'gbz', and 'gcz'. It would not match 'ggz', 'gxz', or 'gz'.

'[!]'

Used to negate a set or range expression. It matches any character value which is NOT in the set or range.

'\' (Backslash)

The default escape character which forces the following character to be interpreted as a literal and not a wildcard. The escape character is configurable in the class instance using the EscapeChar property.

TWindowsMaskUTF8 provides an overridden Compile method which examines and converts the Mask expression into a list of op codes needed in Matches and MatchesWindowsMask. TWindowsMaskUTF8 re-implements the read and write access specifiers for the Mask property to use the FWindowsMask member for the property value.

SplitFileNameExtension is a method used to separate the value in ASourceFileName into file name and file extension values.

The values are returned in the AFileName and AExtension arguments. AExtension can contain an empty string ('') if a file extension is not found in ASourceFileName.

AIsMask indicates whether the value in ASourceFileName is treated as a mask specification instead of a file name. When set to True, a value like '.foo' is treated as a mask where the file name is '.foo' instead of a file extension, like a hidden file name on UNIX-like file systems.

Create is the overloaded, overridden constructor for the class instance. Create ensures that argument values are stored in the Mask, CaseSensitive, MaskOpCodes and Quirks properties. The inherited Create method is called prior to exit.

Compile is an overridden method used to examine and convert values from the Mask property into TMaskParsedCode values for the positions in the mask expression. It provides support for Windows-specific quirks that enabled in the class instance using the Quirks property.

CaseSensitive indicates if case is significant for the value in Mask. Mask is converted to lowercase prior to processing in the method when CaseSensitive is set to False.

Compile examines each of the UTF-8 codepoints in Mask, and adds TMaskParsedCode values when the specific mask op codes are included in the MaskOpCodes property. The value in Mask is decomposed into file name and extension component values that are used in the method. These temporary values may be altered when particular quirks are enabled and encountered in the Mask expression. The modified values are applied to the Mask property prior to calling the inherited Compile method.

Compile may raise an exception when an invalid or incomplete mask is encountered. The the Compile method is called again with the same value in Mask, is simply returns False rather than re-raise the exception.

Compile is called from the Matches method when it has not already been compiled.

Matches calls Compile if the MaskOpCodes have not been compiled for the Mask expression, or when one the configuration parameters has been changed for the class instance.

Matches provides support for values in the Quirks property such as wqNoExtension. When specified and found in the mask expression, SplitFileNameExtension is called to get the file name and extension components for the value in AFileName.

Matches calls the inherited method to compare the specified values using the MaskOpCodes for the class instance. The return value is True if the file name argument matches the Mask expression. It is False if either the Mask expression or the compared value is too long or too short.

Quirks is a TWindowsQuirks property with the set of Windows-specific "quirks" allowed when comparing a value to the Mask expression. It contains values from the TWindowsQuirk enumeration which are enabled for the class instance.

The default value for Quirks is assigned using an argument passed to the Create constructor. If the value is omitted, values in the DefaultWindowsQuirks constant are assigned to the property.

Values in Quirks are used when the Compile method generates the MaskOpCodes for the Mask expression. Changing the property value causes the Compile method to be called during the next execution of the Matches method.

TWindowsMask is a TWindowsMaskUTF8 descendant, and introduces no new properties, methods, or events. It is essentially an alias for the TWindowsMaskUTF8 type.

TMaskClass is the type returned from the GetMaskClass method in TMaskList.

TParseStringList is a TStringList descendant used to parse text which uses the specified line separators. An alternate constructor is introduced with parameters for the lines of text and the separators used in the class instance.

TParseStringList is used to get a list of file masks from a string value in the TMaskList.Create method.

Create is constructor for the class instance. Values in the AText and ASeparator arguments determine the content stored as lines of text in the instance. AText contains one or more file mask expressions separated by one of the delimiters characters n ASeparators.

Each line in the string list represents a single mask value from AText.

TMaskList is a class used to maintain a list with TMaskUtf8 instances for mask expressions. Parameter values passed to the constructor are used when mask instances are created and stored in the list.

TMaskList is used in the implementation of the MatchesMaskList function.