Masks Overview.

What is a Mask

A mask is an expression composed of literal characters, sets or ranges or characters, and wildcards. It is commonly used to match file or directory names against the pattern in the mask expression.

Literal Characters

Each literal character in a mask corresponds to a single character in a compared value. For instance, 'abc.def' would match a file with that exact name and nothing else.

Sets of Characters

A set begins with an opening Square Bracket character ([) and ends with a closing Square Bracket character (]). Values between the brackets represent the characters which are considered a match in that position. For example: 'a[bcd]e.txt' would match 'abe.txt', 'ace.txt', or 'ade.txt'. It would not match 'afe.txt'.

Ranges of Characters

A range begins with an opening Square Bracket character ([) and ends with a closing Square Bracket character (]) like set notation. Character values in the range are defined using a starting and ending values separated by a '-' character. For example: 'abc[0-9].ext'. Any character in the range is allowed in that position. An alpha-numeric range could be represented using '[a-zA-Z0-9]'.

Negated Sets and Ranges

When using set or range notation, character values can be excluded using negation. This is expressed using an Exclamation Point character (!) in front of the set or range specification. For example: '[!0-9]' or '[!0123456789]'. In both examples, any character at the given position except the values in the set or range would be considered a match.

Wildcards

Wildcards allow one or more characters to be considered as a match for a value in the mask. The wildcard characters are '?' and '*'. ? matches a single character (regardless of its value). * matches any number of characters (regardless of their values).

Platform-specific Behaviors

While the syntax and notation for mask expressions is the same for different platforms, there are some platform-specific behaviors.

The TMask and TWindowsMask classes are used to isolate and implement those platform-specific behaviors. TMask conforms the to conventions used for UNIX-like file systems. TWindowsMask implements the conventions used for Windows-based file systems.

Most differences between the platforms center on the implementation of the "any file" mask. This is the notation used to match any file or directory name, regardless of the presence of a file extension. For UNIX file systems (TMask), the notation used is '*'. For Windows file systems (TWindowsMask), the notation '*.*' is used.

They are other Windows-specific behaviors originating from its CP/M and MS DOS heritage. These are implemented in TWindowsMask as Quirks, and can be enabled or disabled in the class instance.

Please refer to the documentation for the TMask and TWindowsMask for more information about mask expressions and their usage in the respective classes.

Configurable Settings

The Mask classes also contain configurable settings which can affect their behavior in their Matches method. For example: CaseSensitive, AutoReverseRange, EscapeChar, and MaskOpCodes. The initial value for these settings can be passed as arguments to the class constructors, or they can be specified using properties in the class instances. MaskOpCodes is particularly important; it determines the behavior of wildcards and escape characters in the mask expression.

Mask Expression Examples

The following FPC unit test program is provided which demonstrates the mask expressions allowed in TMaskUTF8 and TWindowsMaskUTF8 class instances:

$(LazarusDir)/components/lazutils/test/testmasks.lpr

Using Masks

Mask expressions are typically passed as an argument to new instances of TMask or TWindowsMask. It can also be passed as an argument to routines like MatchesMask, MatchesMaskList, MatchesWindowsMask, or MatchesWindowsMaskList. The expression can be assigned to the Mask property in an existing mask class instance. In general, the mask is used to find file names that match the mask expression. But they are not limited to 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 focused on specific functionality.