-
+ It is fast and optimized, and fully supports Unicode. Also supports DOS/Windows compatible masks which behave differently from standard masks. +
+
+ This file is part of the
+ Author: José Mejuto +
++ Changes and improvements by: Juha Manninen and Bart Broersma.
- Used in the implementation of TMaskChar. + 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: +
++ 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. +
+- 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. -
-- EMaskError is a EConvertError descendant representing the exception raised when an invalid character is found in a value passed to the TMask.Create constructor. + 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.
- 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. + Please note that TMaskBase does not capture, compile or store the mask expression. Those actions are performed in a descendent class.
- 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. + 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. +
++ In TMaskBase, Compile simply sets values for members in the class instance. Descendent classes implement additional functionality needed for a specific platform. +
++ 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: +
++ TMaskUTF8 provides an overridden Compile method which examines and converts the Mask expression into a list of op codes needed in Matches and MatchesWindowsMask. +
+- 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. + 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 an overridden 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. +
+- 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. + TMask is an alias for the TMaskUTF8 class. Provided for compatibility with previous LazUtils versions.
- 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'. + Use TWindowsMaskUTF8 or TWindowsMask for mask expressions using DOS/Windows-specific notation and file system conventions.
- 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: -
-- 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. -
-- 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. -
-- 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: -
-- 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. -
-- 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: + 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:
- 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. + 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. @@ -346,11 +1324,14 @@
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.
@@ -367,11 +1348,12 @@
- 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 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.
@@ -379,11 +1361,21 @@
- 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.
+ Used in the Create constructor to set the value for an internal member in the class instance.
+ Parses mask expression in AValue using the delimiter in ASeparator. A new TMaskClass instance is created and stored for each of the mask expressions using the settings in CaseSensitive and AOpcodesAllowed.
+
+ AddMasksToList is called from the Create constructor to populate the list using the mask expression(s) and settings passed as arguments to the method. It is also called when a new value is assigned to the Mask property.
+
+ 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 by calling the AddMasksToList method. Values in the arguments are also assigned to the CaseSensitive and MaskOpCodes properties.
+
+ Mask can contain one or more mask expressions separated by the separator character passed as an argument to the Create constructor. The default separator character is ';' (Semicolon).
+
+ Setting a new value for the Mask property causes the internal list of TMask instances to be cleared and recreated using the values in the CaseSensitive and MaskOpCodes properties.
+
+ MaskOpCodes is a TMaskOpCodes property with the set of mask op codes enabled in the class instance. It contains values from the TMaskOpCode enumeration, and is initially set from arguments passed to the Create constructor. Setting a new value for the property causes each of the TMask instances in Items to be updated with the new value for the property.
+
+ 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 the corresponding property in each of the Items in the list to be updated. This causes Compile in the TMask instance to be called when it executes its Matches method.
+
+ CaseSensitive is a Boolean property which indicates whether Mask expressions in the list are case sensitive. The default value for the property is set using an argument passed to the overloaded constructor. It can be specified using the CaseSensitive argument, or by including / excluding moCaseSensitive in the TMaskOptions argument.
+
+ Changing the value for the property causes the corresponding property to be updated for each of the Items in the list.
+
+ The property value is used when a new value is assigned to the Mask property. It is passed as an argument to the AddMasksToList method called to re-populate the Items in the list.
+
+ TWindowsMaskList is a TMaskList descendant which implements a list used to maintain a list with TWindowsMask instances for mask expressions. Parameter values passed to the constructor are used when mask instances are created and stored in the list.
+
+ TWindowsMaskList is used in the implementation of the MatchesWindowsMaskList function.
+
+ Create is the overloaded constructor for the class instance. Create ensures that arguments passed to the constructor are stored in internal members for use in the class instance. An alternate constructor allows configuration settings to be derived from a set of TMaskOption values.
+
+ MatchesWindowsMask is deprecated in version 2.3, and will be removed in version 2.5. Use the Matches method instead.
+
+ The initial value for the property is set using an argument passed to the Create constructor.
+
+ Changing the value for the property causes the internal TObjectList instance for the masks to be cleared. The AddMasksToList method is called to re-populate the internal list. The delimiter character, case sensitivity, and op codes provided to the constructor are used when re-creating the TWindowsMask instances in the Items property.
+
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.
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 return value is True when Filename matches at least one of the masks in the list.
@@ -756,11 +2021,11 @@
The return value is True when Filename matches at least one of the masks in the list.
++ DbgS is a overloaded String function used to get a formatted message which can be displayed in the debugger. Values from the type passed as an argument are converted to their string representation and used in the return value for the routine. In the masks.pas unit, TMaskOpCodes and TWindowsQuirks types are allowed as parameter values. Both types result in a String with the set notation needed to represent enumeration values in the argument. For example: +
+- 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. + 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 corresponds to a single character in a compared value. + 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.
- Character Sets + Sets of Characters
- 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 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'.
- 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. + Ranges of Characters
- 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 + 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]'.
- 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). + Negated Sets and Ranges
- Mask Examples + 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: +
+
+
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 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.