Contains classes for matching file names to file masks.

masks.pas contains classes, types, and routines used implement file masks. File masks are patterns used to match file names found on the local file system. Support is provided for both UNIX- and Windows-style file masks. The unit includes utility functions to compare one or more file names to a given mask, including: MatchesMask, MatchesWindowsMask, MatchesMaskList, and MatchesWindowsMaskList.

Represents character types used in a mask.

Used in the implementation of TMaskChar.

Masks Overview Represents a UTF-8-encoded character value. Represents a character in a set value. Represents any valid single character. Represents any valid text. Contains options which can be enabled or disabled in TMask comparisons. Masks Overview Enables case sensitive comparison. Disables set processing; "[" and "]" are treated as literal characters. Set type used to store values from the TMaskOption enumeration. Masks Overview Defines a set for Char types. Defines a pointer to a TCharSet type. Alias for the String type used for a UTF-8-encoded character.

TUtf8Char is an alias for a String type with a length of 7 bytes. A UTF-8-encoded character value may need as many as 7 bytes to represent a given codepoint in the encoding.

Exception raised for an invalid character in TMask.

EMaskError is a EConvertError descendant representing the exception raised when an invalid character is found in a value passed to the TMask.Create constructor.

Mask specifications in TMask are limited to the single-byte code points in the UTF-8 character set. EMaskError is raised when a value with a muti-byte code point is encountered.

EConvertError lrsInvalidCharSet Represents details for mask character types in the TMaskCharType enumeration.

TMaskChar is a variant record type with members used to represent details for mask character types in the TMaskCharType enumeration. TMaskChar is used to implement the Chars member in the TMaskString record type.

Masks Overview Identifies the mask character type. UTF-8 character value for the mask character. True when the "not" operator (!) is included in the character set expression in a mask. Contains the values used in a character set expression in a mask. Represent characters and symbols in a mask.

TMaskString is a record type with members representing the characters or symbols in a mask, and the minimum and maximum length for the string. TMaskString is used in the implementation of methods in TMask.

Masks Overview Minimum length for a value that matches a mask. Maximum length for a value that matches a mask. Array with the TMaskChar information for a mask. The TMask class represents a mask and performs comparisons.

A mask is a comparison pattern built using wildcards, sets and/or literal characters. The mask is limited to the single-byte code points in the UTF-8 encoding. Using multi-byte code points in TMask causes an EMaskError exception to be raised.

Each literal character must match a single character in the string. Case sensitivity requires the value moCaseSensitive in the options passed to the constructor.

A set starts with "[" and ends with "]". Each element of a set is a literal character and or a range. A range is defined as a first-to-last literal character string. One character of a set must match a single character in the string. A set [!...] matches if the character is not in the set. The option value moDisableSets passed to the constructor disables set processing and treats the brackets as literal characters.

Wildcards are the * and ? characters. An asterisk matches any number of characters. A question mark matches a single character.

For example: 'Hello world' matches to the mask 'H?ll[xoy] w*d'.

Masks Overview Initializes the internal TMaskString instance used in the class. Frees resources allocated in the internal TMaskString instance. Constructor for the class instance.

Create is the overloaded constructor for the class instance. Overloaded variants are provided with parameter values that are used to configure the class instance.

AValue contains the pattern compared to a given file name in methods for the class. While defined as a String type, AValue is limited to the single-byte code points in the UTF-8 encoding. Using a multi-byte UTF-8 code point in AValue causes an EMaskError exception to be raised.

Each UTF-8 code point in AValue is examined, and the internal TMaskString is updated to reflect how the mask character is applied. For example:

'*' includes the value mcAnyText in the characters for the mask.
'?' includes the value mcAnyChar in the characters for the mask.
'[' includes the value mcCharSet in the characters for the mask when sets have not been disabled. Otherwise, the value mcChar is added to the characters for the mask.
All other values are literal characters and cause the value mcChar to be added to the characters for the mask.

CaseSensitive indicates if case sensitivity is used when comparing a file name to the mask value.

AOptions contains zero or more TMaskOption values which enable or disable features in the methods for the class instance.

Create calls the private InitMaskString method to initialize the internal TMaskString instance used in the class.

The overloaded variant which does not have an AOptions parameter has been deprecated. It will be removed in a future Lazarus version. lrsInvalidCharSet Mask value for the class instance. True if case sensitivity is used when comparing a file name to the mask value. Contains options enabled or disabled in the class instance. Destructor for the class instance.

Destroy is the overridden destructor for the class instance. Destroy call ClearMaskString to free resources allocated in the internal TMaskString instance. Destroy calls the inherited destructor prior to exiting from the method.

Determines whether the specified file name matches the mask value.

Matches is a Boolean function used to determine whether the specified file name matches the mask value in the class instance. Matches converts the value in AFileName to lowercase when case sensitivity is omitted from the TMaskOptions for the class instance.

Matches examines each of the UTF-8 code points in the AFileName argument, and compares the code points to the character types defined in the internal mask string. The return value is False when:

AFileName contains invalid UTF-8 code point(s).
The mask has an assigned expression and AFileName does not match the minimum or maximum length for the expression.
AFileName does not match the mask expression.

The return value is True when AFileName satisfies the mask expression using the options for the class instance.

Pass values for the mask expression and its options to the constructor for the class instance.

Masks Overview True when the file name matches the mask in the class instance. File name compared to the mask value in the method. Determines whether a filename matches the mask using Windows file system masks.

Determines whether a filename matches the mask value. Implements some special rules for a Windows© file system file masks and comparisons. It is assumed that the initial mask value passed to the constructor uses Windows-specific notation, such as:

foo*.*: Matches all files starting with 'foo' regardless of the file extension. Same as foo* using the Matches method.
foo*.: Matches foo* but must not include a file extension.
*.: Matches any file name, but must not include a file extension.
foo.: Matches foo but not foo.txt.
foo.*: Matches foo, foo.txt, or foo.bar.
*.*: Matches any file name with an extension.

This is done by converting the Windows-specific file mask to the equivalent notation normally used in the class instance. MatchesWindowsMask calls ClearMaskString and InitMaskString using the altered mask value, and calls the Matches method to perform the comparison. When a Windows-specific file mask is not found, the Matches method is called using the original mask value.

The return value is True when the value in AFileName satisfies the Windows-specific mask expression.

Masks Overview True when the file name matches the mask value in the class instance. File name examined in the method. The TParseStringList class is used to parse text into the list of strings.

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.

TSringList Creates new string list by parsing the specified text using the separators argument.

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.

Text examine and parsed in the method. String with the separators used to delimit lines in the text argument. Implements a list for masks.

TMaskList is a class used to maintain a list with mask expressions. Parameter values passed to the constructor are used to create and store the TMask instances in the list.

TMaskList is used in the implementation of the MatchesMaskList function.

Masks Overview Gets the value for the Count property. Value for the property. Gets the value for the indexed Items property. Value for the property. Ordinal position for the TMask instance in the property value. Creates new list of masks using the specified delimited mask values and options.

Create is the overloaded constructor for the class instance. Create allocates resources for the internal object list in the class instance. Arguments passed to the constructor are used to configure and populate the values in the Items property.

The overloaded variant which does not include an Options parameter has been deprecated. It will be removed in a future Lazarus version. Mask value(s) stored in the internal object list. Delimiter used to delimit mask values in AValue. Indicates if case sensitivity is used for masks. Contains the options enabled for the mask instances. Destructor for the class instance.

Destroy is the overridden destructor for the class instance. Destroy ensures that the internal object list for the class instance is freed. Destroy calls the inherited destructor prior to exiting from the method.

Determines whether the specified file name matches a mask in the list.

Matches is a Boolean function used to determine if the specified file name matches one of the file masks in the list.

AFileName contains the file name examined in the method.

Matches uses the TMask instances in Items to perform the file name comparison. Each TMask instance in Items is used to call its Matches method until a match is found, or until all of the masks have been visited.

The return value is True when a mask is found that matches the file name.

True when the file name matches one of the mask items. File name examined in the method. Tests whether the file name matches a mask in the list using Windows file system masks.

Tests whether the file name matches at least one of the mask items in the list. Implements some special rules for a Windows© file system comparison.

True if the file name matches one the masks in the list. File name examined in the method. The number of mask items in the list.

Count is a read-only Integer property with the number of TMask instances stored in the Items for the list.

The mask items in the list.

Items is a read-only indexed TMask property which contains the mask instances in the list.

Index specifies the ordinal position in the list for the TMask instance in the property. The property value is cast to a TMask instance when it is retrieved from the internal object list.

Values in the Items property are created in the Create constructor. A TMask instance is created and stored in Items for each of the mask values passed an argument to the method.

Use the Count property to determine the number of masks stored in Items.

Ordinal position for the value in the indexed property. Indicates whether the file name matches the specified mask.

MatchesMask is an overloaded Boolean function used to determine if the file name specified in FileName matches the specified Mask.

CaseSensitive indicates whether case sensitivity is used when comparing the file name to the mask value.

Options contains a set of zero or more TMaskOption values enabled for the comparison. The Options argument allows enabling or disabling set notation in the mask value. Specifying moDisableSets in the Options parameter will disable interpreting the ' [' character as the beginning of a set in the specified mask. Use an empty set (' []') when options from the TMaskOption enumeration are not needed.

For example:

MatchesMask('[x]','[x]',[moDisableSets]); // returns True

MatchesMask creates a TMask instance which is used to compare the file name to the mask using the specified options. Values in Mask and Options are passed as arguments the TMask constructor. The Matches method in the instance is called using FileName as an argument, and gets the return value for the function.

The overloaded variant which does not include a TMaskOptions parameter has been marked as deprecated. It will be removed in a future Lazarus version. Masks Overview True when the file name matches the mask value using the specified options. File name compared to the mask value. Mask used to perform the comparison. True when case sensitivity should be used in the comparison. Set of options enabled for the comparison. Indicates whether the file name matches the specified Windows-style file system mask.

MatchesWindowsMask is an overloaded Boolean function used to determine if the file name specified in FileName matches the specified Mask. Mask can contain a Windows-style file mask which uses the following wildcards:

foo*.*: Matches all files starting with 'foo' regardless of the file extension. Same as foo* using the Matches method.
foo*.: Matches foo* but must not include a file extension.
*.: Matches any file name, but must not include a file extension.
foo.: Matches foo but not foo.txt.
foo.*: Matches foo, foo.txt, or foo.bar.
*.*: Matches any file name with an extension.

CaseSensitive indicates whether case sensitivity is used when comparing the file name to the mask value.

For example:

MatchesWindowsMask('[x]','[x]',[moDisableSets]); // returns True

MatchesWindowsMask creates a TMask instance which is used to compare the file name to the mask using the specified options. Values in Mask and Options are passed as arguments the TMask constructor. The MatchesWindowsMask method in the TMask instance is called using FileName as an argument, and gets the return value for the function.

The overloaded variant which does not include a TMaskOptions parameter has been marked as deprecated. It will be removed in a future Lazarus version. Masks Overview True when the file name matches the mask value using the specified options. File name compared to the mask value. Mask used to perform the comparison. True when case sensitivity should be used in the comparison. Set of options enabled for the comparison. Determine whether the specified file name matches at least one of the specified masks.

MatchesMaskList is an overloaded Boolean function used to determine whether the specified file name matches at least one of the specified masks. MatchesMaskList is similar to MatchesWindowsMaskList, but uses Unix-style mask expressions. This includes use of the following:

foo*: Matches all files starting with 'foo' regardless of the file extension. Same as foo*.* using MatchesWindowsMaskList.
foo*.: Matches foo* but must not include a file extension.
*.: Matches any file name, but must not include a file extension.
foo.: Matches foo but not foo.txt.
foo.*: Matches foo, foo.txt, or foo.bar.
*: Matches any file name including those with an optional extension.

Overloaded variants of the routine provide arguments and configuration settings, including:

Filename: File name compared to the file masks in Mask.
Mask: Contains one or more file mask expressions separated by one of the values in Separator.
Separator: Contains the character(s) used as a separator between mask expressions in Mask. The default separator is the SemiColon (;) character.
Options: Contains TMaskOption values which enable or disable features in the comparison. The default value is an empty set ([]).
CaseSensitive: Indicates whether the file name to mask comparison is case sensitive.

The overloaded variant which includes the CaseSensitive argument has been deprecated. Use the variant that includes the TMaskOptions argument.

MatchesMaskList creates a TMaskList instance which uses the values in the Mask, Separator and Options parameters. Its Matches method is called to compare the value in Filename to the mask values in the list.

The return value is True when Filename matches at least one of the masks in the list.

Masks Overview True when Filename matches at least one of the masks in the list. File name compared to the file masks in Mask. one or more file mask expressions separated by one of the values in Separator. Character(s) used as a separator between mask expressions in Mask. True if the file name to mask comparison is case sensitive. TMaskOption values which enable or disable features in the comparison. Determine whether the specified file name matches at least one of the specified masks.

MatchesWindowsMaskList is an overloaded Boolean function used to determine whether the specified file name matches at least one of the specified masks. MatchesWindowsMaskList is similar to MatchesMaskList, but provides support for Windows-style file system masks in the Mask argument. This includes use of the following:

foo*.*: Matches all files starting with 'foo' regardless of the file extension. Same as foo* using MatchesMaskList.
foo*.: Matches foo* but must not include a file extension.
*.: Matches any file name, but must not include a file extension.
foo.: Matches foo but not foo.txt.
foo.*: Matches foo, foo.txt, or foo.bar.
*.*: Matches any file name with an extension.

Overloaded variants of the routine provide arguments and configuration settings, including:

Filename: File name compared to the file masks in Mask.
Mask: Contains one or more file mask expressions separated by one of the values in Separator.
Separator: Contains the character(s) used as a separator between mask expressions in Mask. The default separator is the SemiColon (;) character.
Options: Contains TMaskOption values which enable or disable features in the comparison. The default value is an empty set ([]).
CaseSensitive: Indicates whether the file name to mask comparison is case sensitive.

The overloaded variant which includes the CaseSensitive argument has been deprecated. Use the variant that includes the TMaskOptions argument.

MatchesWindowsMaskList creates a TMaskList instance which uses the values in the Mask, Separator and Options parameters. Its MatchesWindowsMask method is called to compare the value in Filename to the Windows-style masks in the list.

The return value is True when Filename matches at least one of the masks in the list.

Masks Overview True when Filename matches at least one of the masks in the list. File name compared to the file masks in Mask. one or more file mask expressions separated by one of the values in Separator. Character(s) used as a separator between mask expressions in Mask. True if the file name to mask comparison is case sensitive. TMaskOption values which enable or disable features in the comparison. Masks Overview.

What is a Mask

A mask is an expression composed of literal characters, character sets, and wildcards. A mask is used in TMask and related routines to determine if a string containing a specific value matches the mask expression.

Literal Characters

Each literal character corresponds to a single character in a compared value.

Character Sets

A character set begins with an opening Square Bracket character ([) and ends with a closing Square Bracket character (]). Values between the brackets represent literal characters or a range of characters which are included in (or excluded from) the character set.

A range is defined using a starting character, a dash (-), and an ending character. The character set matches a single character in a compared value. When an Exclamation Point character (!) is found after the first bracket, the values in the character set are excluded from matches using the mask.

For example, an alpha-numeric character set could be represented using the following:

[a-zA-Z0-9]

And, a character set which excludes numeric values could be represented using the following:

[!0-9]

Wildcard Characters

Wildcard characters allow one or more literal characters to be considered as a match in the mask value, and includes the ? and * characters. ? matches a single character (regardless of its value). * matches any number of characters (regrardless of their values).

Mask Examples

abc.ext: Matches a single file named "abc.ext".
a[blt]c.ext: Matches "abc.ext", "alc.ext", or "atc.ext".
a[b-d]c.ext: Matches "abc.ext", "acc.ext", or "adc.ext".
foo*: Matches any file that starts with "foo", including those with a file extension.
*: Matches any file, including those with a file extension.
*.: Matches any file that does not have an extension.
ab??ef.txt: Matches abcdef.txt and abrtef.txt.

Using Masks

Mask values are normally passed as an argument to new instances of TMask, or passed as an argument to routines like MatchesMask, MatchesMaskList, et. al. In general, the mask is used to find file names that match the mask expression. But they are not limited that single use case. They can be used to determine if any string value matches a valid mask expression. They are like regular expressions without all of the complexity (and most of the functionality).

Mask values as used in TMask are not related to the mask values used in the TMaskEdit control. Although both compare string values to determine if they match a particular pattern, they use different symbols and syntax.