mirror of
https://gitlab.com/freepascal.org/lazarus/lazarus.git
synced 2025-07-22 15:45:57 +02:00
861 lines
42 KiB
XML
861 lines
42 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<fpdoc-descriptions>
|
|
<package name="lazutils">
|
|
<!--
|
|
====================================================================
|
|
Masks
|
|
====================================================================
|
|
-->
|
|
<module name="Masks">
|
|
<short>Contains classes for matching file names to file masks.</short>
|
|
<descr>
|
|
<p>
|
|
<file>masks.pas</file> 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.
|
|
</p>
|
|
</descr>
|
|
<!-- unresolved external references -->
|
|
<element name="Classes"/>
|
|
<element name="SysUtils"/>
|
|
<element name="Contnrs"/>
|
|
<element name="LazUtilsStrConsts"/>
|
|
<element name="LazUtf8"/>
|
|
<element name="TMaskCharType">
|
|
<short>Represents character types used in a mask.</short>
|
|
<descr>
|
|
<p>
|
|
Used in the implementation of TMaskChar.
|
|
</p>
|
|
</descr>
|
|
<seealso>
|
|
<link id="#lazutils.masks.MasksOverview">Masks Overview</link>
|
|
</seealso>
|
|
</element>
|
|
<element name="TMaskCharType.mcChar">
|
|
<short>Represents a UTF-8-encoded character value.</short>
|
|
</element>
|
|
<element name="TMaskCharType.mcCharSet">
|
|
<short>Represents a character in a set value.</short>
|
|
</element>
|
|
<element name="TMaskCharType.mcAnyChar">
|
|
<short>Represents any valid single character.</short>
|
|
</element>
|
|
<element name="TMaskCharType.mcAnyText">
|
|
<short>Represents any valid text.</short>
|
|
</element>
|
|
<element name="TMaskOption">
|
|
<short>Contains options which can be enabled or disabled in TMask comparisons.</short>
|
|
<seealso>
|
|
<link id="#lazutils.masks.MasksOverview">Masks Overview</link>
|
|
</seealso>
|
|
</element>
|
|
<element name="TMaskOption.moCaseSensitive">
|
|
<short>Enables case sensitive comparison.</short>
|
|
</element>
|
|
<element name="TMaskOption.moDisableSets">
|
|
<short>Disables set processing; "[" and "]" are treated as literal characters.</short>
|
|
</element>
|
|
<element name="TMaskOptions">
|
|
<short>Set type used to store values from the TMaskOption enumeration.</short>
|
|
<seealso>
|
|
<link id="#lazutils.masks.MasksOverview">Masks Overview</link>
|
|
</seealso>
|
|
</element>
|
|
<element name="TCharSet">
|
|
<short>Defines a set for Char types.</short>
|
|
<descr/>
|
|
<seealso/>
|
|
</element>
|
|
<element name="PCharSet">
|
|
<short>Defines a pointer to a TCharSet type.</short>
|
|
<descr/>
|
|
<seealso/>
|
|
</element>
|
|
|
|
<element name="EMaskError">
|
|
<short>Exception raised for an invalid character in TMask.</short>
|
|
<descr>
|
|
<p>
|
|
<var>EMaskError</var> is a <var>EConvertError</var> descendant representing the exception raised when an invalid character is found in a value passed to the <var>TMask.Create</var> constructor.
|
|
</p>
|
|
<p>
|
|
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.
|
|
</p>
|
|
</descr>
|
|
<seealso>
|
|
<link id="TMask.Create"/>
|
|
<link id="#rtl.sysutils.EConvertError">EConvertError</link>
|
|
<link id="#lazutils.lazutilsstrconsts.lrsInvalidCharSet">lrsInvalidCharSet</link>
|
|
</seealso>
|
|
</element>
|
|
|
|
<element name="TMaskChar">
|
|
<short>Represents details for mask character types in the TMaskCharType enumeration.</short>
|
|
<descr>
|
|
<p>
|
|
<var>TMaskChar</var> is a variant record type with members used to represent details for mask character types in the <var>TMaskCharType</var> enumeration. TMaskChar is used to implement the <var>Chars</var> member in the <var>TMaskString</var> record type.
|
|
</p>
|
|
</descr>
|
|
<seealso>
|
|
<link id="TMaskCharType"/>
|
|
<link id="#lazutils.masks.MasksOverview">Masks Overview</link>
|
|
</seealso>
|
|
</element>
|
|
<element name="TMaskChar.CharType">
|
|
<short>Identifies the mask character type.</short>
|
|
<descr/>
|
|
<seealso/>
|
|
</element>
|
|
<element name="TMaskChar.CharValue">
|
|
<short>UTF-8 character value for the mask character.</short>
|
|
<descr/>
|
|
<seealso/>
|
|
</element>
|
|
<element name="TMaskChar.Negative">
|
|
<short>True when the "not" operator (!) is included in the character set expression in a mask.
|
|
</short>
|
|
<descr/>
|
|
<seealso/>
|
|
</element>
|
|
<element name="TMaskChar.SetValue ">
|
|
<short>Contains the values used in a character set expression in a mask.</short>
|
|
<descr/>
|
|
<seealso/>
|
|
</element>
|
|
<element name="TMaskString">
|
|
<short>Represent characters and symbols in a mask.</short>
|
|
<descr>
|
|
<p>
|
|
<var>TMaskString</var> 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 <var>TMask</var>.
|
|
</p>
|
|
</descr>
|
|
<seealso>
|
|
<link id="TMask.Matches"/>
|
|
<link id="TMask.MatchesWindowsMask"/>
|
|
<link id="#lazutils.masks.MasksOverview">Masks Overview</link>
|
|
</seealso>
|
|
</element>
|
|
<element name="TMaskString.MinLength">
|
|
<short>Minimum length for a value that matches a mask.</short>
|
|
<descr/>
|
|
<seealso/>
|
|
</element>
|
|
<element name="TMaskString.MaxLength">
|
|
<short>Maximum length for a value that matches a mask.</short>
|
|
<descr/>
|
|
<seealso/>
|
|
</element>
|
|
<element name="TMaskString.Chars">
|
|
<short>Array with the TMaskChar information for a mask.</short>
|
|
<descr/>
|
|
<seealso/>
|
|
</element>
|
|
|
|
<element name="TMask">
|
|
<short>The TMask class represents a mask and performs comparisons.</short>
|
|
<descr>
|
|
<p>
|
|
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 <var>EMaskError</var> exception to be raised.
|
|
</p>
|
|
<p>
|
|
Each <b>literal character</b> must match a single character in the string. Case sensitivity requires the value <link id="TMaskOption">moCaseSensitive</link> in the options passed to the constructor.
|
|
</p>
|
|
<p>
|
|
A <b>set</b> starts with "<b>[</b>" and ends with "<b>]</b>". 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 <link id="TMaskOption">moDisableSets</link> passed to the constructor disables set processing and treats the brackets as literal characters.
|
|
</p>
|
|
<p>
|
|
<b>Wildcards</b> are the <b>*</b> and <b>?</b> characters. An asterisk matches any number of characters. A question mark matches a single character.
|
|
</p>
|
|
<p>
|
|
For example: 'Hello world' matches to the mask 'H?ll[xoy] w*d'.
|
|
</p>
|
|
</descr>
|
|
<seealso>
|
|
<link id="EMaskError"/>
|
|
<link id="#lazutils.masks.MasksOverview">Masks Overview</link>
|
|
</seealso>
|
|
</element>
|
|
|
|
<element name="TMask.FMask"/>
|
|
<element name="TMask.FInitialMask"/>
|
|
<element name="TMask.FOptions"/>
|
|
|
|
<element name="TMask.InitMaskString">
|
|
<short>Initializes the internal TMaskString instance used in the class.</short>
|
|
</element>
|
|
|
|
<element name="TMask.ClearMaskString">
|
|
<short>Frees resources allocated in the internal TMaskString instance.</short>
|
|
</element>
|
|
|
|
<element name="TMask.Create">
|
|
<short>Constructor for the class instance.</short>
|
|
<descr>
|
|
<p>
|
|
<var>Create</var> is the overloaded constructor for the class instance. Overloaded variants are provided with parameter values that are used to configure the class instance.
|
|
</p>
|
|
<p>
|
|
<var>AValue</var> contains the pattern compared to a given file name in methods for the class. While defined as a <var>String</var> 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 <var>EMaskError</var> exception to be raised.
|
|
</p>
|
|
<p>
|
|
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:
|
|
</p>
|
|
<ul>
|
|
<li>'*' includes the value mcAnyText in the characters for the mask.</li>
|
|
<li>'?' includes the value mcAnyChar in the characters for the mask.</li>
|
|
<li>
|
|
'[' 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.
|
|
</li>
|
|
<li>
|
|
All other values are literal characters and cause the value mcChar to be added to the characters for the mask.
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
<var>CaseSensitive</var> indicates if case sensitivity is used when comparing a file name to the mask value.
|
|
</p>
|
|
<p>
|
|
<var>AOptions</var> contains zero or more TMaskOption values which enable or disable features in the methods for the class instance.
|
|
</p>
|
|
<p>
|
|
Create calls the private <var>InitMaskString</var> method to initialize the internal <var>TMaskString</var> instance used in the class.
|
|
</p>
|
|
<remark>
|
|
The overloaded variant which does not have an AOptions parameter has been deprecated. It will be removed in a future Lazarus version.
|
|
</remark>
|
|
</descr>
|
|
<seealso>
|
|
<link id="TMaskString"/>
|
|
<link id="TMaskOptions"/>
|
|
<link id="TMaskOption"/>
|
|
<link id="EMaskError"/>
|
|
<link id="#lazutils.lazutilsstrconsts.lrsInvalidCharSet">lrsInvalidCharSet</link>
|
|
</seealso>
|
|
</element>
|
|
<element name="TMask.Create.AValue">
|
|
<short>Mask value for the class instance.</short>
|
|
</element>
|
|
<element name="TMask.Create.CaseSensitive">
|
|
<short>True if case sensitivity is used when comparing a file name to the mask value.</short>
|
|
</element>
|
|
<element name="TMask.Create.AOptions">
|
|
<short>Contains options enabled or disabled in the class instance.</short>
|
|
</element>
|
|
<element name="TMask.Destroy">
|
|
<short>Destructor for the class instance.</short>
|
|
<descr>
|
|
<p>
|
|
<var>Destroy</var> is the overridden destructor for the class instance. Destroy call <var>ClearMaskString</var> to free resources allocated in the internal <var>TMaskString</var> instance. Destroy calls the inherited destructor prior to exiting from the method.
|
|
</p>
|
|
</descr>
|
|
<seealso>
|
|
<link id="TMaskString"/>
|
|
</seealso>
|
|
</element>
|
|
<element name="TMask.Matches">
|
|
<short>Determines whether the specified file name matches the mask value.</short>
|
|
<descr>
|
|
<p>
|
|
<var>Matches</var> is a <var>Boolean</var> function used to determine whether the specified file name matches the mask value in the class instance. Matches converts the value in <var>AFileName</var> to lowercase when case sensitivity is omitted from the <var>TMaskOptions</var> for the class instance.
|
|
</p>
|
|
<p>
|
|
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 <b>False</b> when:
|
|
</p>
|
|
<ul>
|
|
<li>AFileName contains invalid UTF-8 code point(s).</li>
|
|
<li>
|
|
The mask has an assigned expression and AFileName does not match the minimum or maximum length for the expression.
|
|
</li>
|
|
<li>AFileName does not match the mask expression.</li>
|
|
</ul>
|
|
<p>
|
|
The return value is <b>True</b> when AFileName satisfies the mask expression using the options for the class instance.
|
|
</p>
|
|
<p>
|
|
Pass values for the mask expression and its options to the constructor for the class instance.
|
|
</p>
|
|
</descr>
|
|
<seealso>
|
|
<link id="TMask.Create"/>
|
|
<link id="TMaskOptions"/>
|
|
<link id="TMaskOption"/>
|
|
<link id="#lazutils.masks.MasksOverview">Masks Overview</link>
|
|
</seealso>
|
|
</element>
|
|
<element name="TMask.Matches.Result">
|
|
<short>True when the file name matches the mask in the class instance.</short>
|
|
</element>
|
|
<element name="TMask.Matches.AFileName">
|
|
<short>File name compared to the mask value in the method.</short>
|
|
</element>
|
|
<element name="TMask.MatchesWindowsMask">
|
|
<short>Determines whether a filename matches the mask using Windows file system masks.
|
|
</short>
|
|
<descr>
|
|
<p>
|
|
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:
|
|
</p>
|
|
<dl>
|
|
<dt>foo*.*</dt>
|
|
<dd>
|
|
Matches all files starting with 'foo' regardless of the file extension. Same as foo* using the Matches method.
|
|
</dd>
|
|
<dt>foo*.</dt>
|
|
<dd>Matches foo* but must not include a file extension.</dd>
|
|
<dt>*.</dt>
|
|
<dd>Matches any file name, but must not include a file extension.</dd>
|
|
<dt>foo.</dt>
|
|
<dd>Matches foo but not foo.txt.</dd>
|
|
<dt>foo.*</dt>
|
|
<dd>Matches foo, foo.txt, or foo.bar.</dd>
|
|
<dt>*.*</dt>
|
|
<dd>Matches any file name with an extension.</dd>
|
|
</dl>
|
|
<p>
|
|
This is done by converting the Windows-specific file mask to the equivalent notation normally used in the class instance. MatchesWindowsMask calls <var>ClearMaskString</var> and <var>InitMaskString</var> using the altered mask value, and calls the <var>Matches</var> method to perform the comparison. When a Windows-specific file mask is not found, the Matches method is called using the original mask value.
|
|
</p>
|
|
<p>
|
|
The return value is <b>True</b> when the value in <var>AFileName</var> satisfies the Windows-specific mask expression.
|
|
</p>
|
|
</descr>
|
|
<seealso>
|
|
<link id="TMask.Matches"/>
|
|
<link id="#lazutils.masks.MasksOverview">Masks Overview</link>
|
|
</seealso>
|
|
</element>
|
|
<element name="TMask.MatchesWindowsMask.Result">
|
|
<short>True when the file name matches the mask value in the class instance.</short>
|
|
</element>
|
|
<element name="TMask.MatchesWindowsMask.AFileName">
|
|
<short>File name examined in the method.</short>
|
|
</element>
|
|
<element name="TParseStringList">
|
|
<short>The TParseStringList class is used to parse text into the list of strings.</short>
|
|
<descr>
|
|
<p>
|
|
<var>TParseStringList</var> is a <var>TStringList</var> 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.
|
|
</p>
|
|
<p>
|
|
TParseStringList is used to get a list of file masks from a string value in the <var>TMaskList.Create</var> method.
|
|
</p>
|
|
</descr>
|
|
<seealso>
|
|
<link id="TMaskList.Create"/>
|
|
<link id="#rtl.classes.TStringList">TSringList</link>
|
|
</seealso>
|
|
</element>
|
|
<element name="TParseStringList.Create">
|
|
<short>Creates new string list by parsing the specified text using the separators argument.</short>
|
|
<descr>
|
|
<p>
|
|
<var>Create</var> is constructor for the class instance. Values in the <var>AText</var> and <var>ASeparator</var> 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.
|
|
</p>
|
|
<p>
|
|
Each line in the string list represents a single mask value from AText.
|
|
</p>
|
|
</descr>
|
|
<seealso/>
|
|
</element>
|
|
<element name="TParseStringList.Create.AText">
|
|
<short>Text examine and parsed in the method.</short>
|
|
</element>
|
|
<element name="TParseStringList.Create.ASeparators">
|
|
<short>String with the separators used to delimit lines in the text argument.</short>
|
|
</element>
|
|
<element name="TMaskList">
|
|
<short>Implements a list for masks.</short>
|
|
<descr>
|
|
<p>
|
|
<var>TMaskList</var> 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.
|
|
</p>
|
|
<p>
|
|
TMaskList is used in the implementation of the <var>MatchesMaskList</var> function.
|
|
</p>
|
|
</descr>
|
|
<seealso>
|
|
<link id="TMask"/>
|
|
<link id="MatchesMaskList"/>
|
|
<link id="#lazutils.masks.MasksOverview">Masks Overview</link>
|
|
</seealso>
|
|
</element>
|
|
<element name="TMaskList.FMasks"/>
|
|
<element name="TMaskList.GetCount">
|
|
<short>Gets the value for the Count property.</short>
|
|
<descr/>
|
|
<seealso>
|
|
<link id="TMaskList.Count"/>
|
|
</seealso>
|
|
</element>
|
|
<element name="TMaskList.GetCount.Result">
|
|
<short>Value for the property.</short>
|
|
</element>
|
|
<element name="TMaskList.GetItem">
|
|
<short>Gets the value for the indexed Items property.</short>
|
|
<descr/>
|
|
<seealso>
|
|
<link id="TMaskList.Items"/>
|
|
</seealso>
|
|
</element>
|
|
<element name="TMaskList.GetItem.Result">
|
|
<short>Value for the property.</short>
|
|
</element>
|
|
<element name="TMaskList.GetItem.Index">
|
|
<short>Ordinal position for the TMask instance in the property value.</short>
|
|
</element>
|
|
<element name="TMaskList.Create">
|
|
<short>
|
|
Creates new list of masks using the specified delimited mask values and options.
|
|
</short>
|
|
<descr>
|
|
<p>
|
|
<var>Create</var> 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 <var>Items</var> property.
|
|
</p>
|
|
<remark>
|
|
The overloaded variant which does <b>not</b> include an <var>Options</var> parameter has been <b>deprecated</b>. It will be removed in a future Lazarus version.
|
|
</remark>
|
|
</descr>
|
|
<seealso>
|
|
<link id="TMaskList.Items"/>
|
|
<link id="TMaskOption"/>
|
|
<link id="TMaskOptions"/>
|
|
</seealso>
|
|
</element>
|
|
<element name="TMaskList.Create.AValue">
|
|
<short>Mask value(s) stored in the internal object list.</short>
|
|
</element>
|
|
<element name="TMaskList.Create.ASeparator">
|
|
<short>Delimiter used to delimit mask values in AValue.</short>
|
|
</element>
|
|
<element name="TMaskList.Create.CaseSensitive">
|
|
<short>Indicates if case sensitivity is used for masks.</short>
|
|
</element>
|
|
<element name="TMaskList.Create.Options">
|
|
<short>Contains the options enabled for the mask instances.</short>
|
|
</element>
|
|
<element name="TMaskList.Destroy">
|
|
<short>Destructor for the class instance.</short>
|
|
<descr>
|
|
<p>
|
|
<var>Destroy</var> 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.
|
|
</p>
|
|
</descr>
|
|
<seealso/>
|
|
</element>
|
|
<element name="TMaskList.Matches">
|
|
<short>Determines whether the specified file name matches a mask in the list.</short>
|
|
<descr>
|
|
<p>
|
|
<var>Matches</var> is a <var>Boolean</var> function used to determine if the specified file name matches one of the file masks in the list.
|
|
</p>
|
|
<p>
|
|
<var>AFileName</var> contains the file name examined in the method.
|
|
</p>
|
|
<p>
|
|
Matches uses the <var>TMask</var> instances in <var>Items</var> to perform the file name comparison. Each TMask instance in Items is used to call its <var>Matches</var> method until a match is found, or until all of the masks have been visited.
|
|
</p>
|
|
<p>
|
|
The return value is <b>True</b> when a mask is found that matches the file name.
|
|
</p>
|
|
</descr>
|
|
<seealso>
|
|
<link id="TMaskList.Items"/>
|
|
<link id="TMaskList.Count"/>
|
|
<link id="TMask.Matches"/>
|
|
</seealso>
|
|
</element>
|
|
<element name="TMaskList.Matches.Result">
|
|
<short>True when the file name matches one of the mask items.</short>
|
|
</element>
|
|
<element name="TMaskList.Matches.AFileName">
|
|
<short>File name examined in the method.</short>
|
|
</element>
|
|
<element name="TMaskList.MatchesWindowsMask">
|
|
<short>
|
|
Tests whether the file name matches a mask in the list using Windows file system masks.
|
|
</short>
|
|
<descr>
|
|
<p>
|
|
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.
|
|
</p>
|
|
</descr>
|
|
<errors/>
|
|
<seealso/>
|
|
</element>
|
|
<element name="TMaskList.MatchesWindowsMask.Result">
|
|
<short>True if the file name matches one the masks in the list.</short>
|
|
</element>
|
|
<element name="TMaskList.MatchesWindowsMask.AFileName">
|
|
<short>File name examined in the method.</short>
|
|
</element>
|
|
<element name="TMaskList.Count">
|
|
<short>The number of mask items in the list.</short>
|
|
<descr>
|
|
<p>
|
|
<var>Count</var> is a read-only <var>Integer</var> property with the number of <var>TMask</var> instances stored in the <var>Items</var> for the list.
|
|
</p>
|
|
</descr>
|
|
<seealso>
|
|
<link id="TMaskList.Items"/>
|
|
</seealso>
|
|
</element>
|
|
<element name="TMaskList.Items">
|
|
<short>The mask items in the list.</short>
|
|
<descr>
|
|
<p>
|
|
<var>Items</var> is a read-only indexed <var>TMask</var> property which contains the mask instances in the list.
|
|
</p>
|
|
<p>
|
|
<var>Index</var> 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.
|
|
</p>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
Use the Count property to determine the number of masks stored in Items.
|
|
</p>
|
|
</descr>
|
|
<seealso>
|
|
<link id="TMaskList.Create"/>
|
|
<link id="TMask"/>
|
|
</seealso>
|
|
</element>
|
|
<element name="TMaskList.Items.Index">
|
|
<short>Ordinal position for the value in the indexed property.</short>
|
|
</element>
|
|
<element name="MatchesMask">
|
|
<short>Indicates whether the file name matches the specified mask.</short>
|
|
<descr>
|
|
<p>
|
|
<var>MatchesMask</var> is an overloaded <var>Boolean</var> function used to determine if the file name specified in <var>FileName</var> matches the specified <var>Mask</var>.
|
|
</p>
|
|
<p>
|
|
<var>CaseSensitive</var> indicates whether case sensitivity is used when comparing the file name to the mask value.
|
|
</p>
|
|
<p>
|
|
<var>Options</var> 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 <var>moDisableSets</var> in the Options parameter will disable interpreting the ' <b>[</b>' character as the beginning of a set in the specified mask. Use an empty set (' <b>[]</b>') when options from the <var>TMaskOption</var> enumeration are not needed.
|
|
</p>
|
|
<p>
|
|
For example:
|
|
</p>
|
|
<code>MatchesMask('[x]','[x]',[moDisableSets]); // returns True</code>
|
|
<p>
|
|
MatchesMask creates a <var>TMask</var> 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 <var>Matches</var> method in the instance is called using FileName as an argument, and gets the return value for the function.
|
|
</p>
|
|
<remark>
|
|
The overloaded variant which does <b>not</b> include a TMaskOptions parameter has been marked as deprecated. It will be removed in a future Lazarus version.
|
|
</remark>
|
|
</descr>
|
|
<seealso>
|
|
<link id="TMask"/>
|
|
<link id="TMaskOption"/>
|
|
<link id="TMaskOptions"/>
|
|
<link id="#lazutils.masks.MasksOverview">Masks Overview</link>
|
|
</seealso>
|
|
</element>
|
|
<element name="MatchesMask.Result">
|
|
<short>True when the file name matches the mask value using the specified options.</short>
|
|
</element>
|
|
<element name="MatchesMask.FileName">
|
|
<short>File name compared to the mask value.</short>
|
|
</element>
|
|
<element name="MatchesMask.Mask">
|
|
<short>Mask used to perform the comparison.</short>
|
|
</element>
|
|
<element name="MatchesMask.CaseSensitive">
|
|
<short>True when case sensitivity should be used in the comparison.</short>
|
|
</element>
|
|
<element name="MatchesMask.Options">
|
|
<short>Set of options enabled for the comparison.</short>
|
|
</element>
|
|
<element name="MatchesWindowsMask">
|
|
<short>
|
|
Indicates whether the file name matches the specified Windows-style file system mask.
|
|
</short>
|
|
<descr>
|
|
<p>
|
|
<var>MatchesWindowsMask</var> is an overloaded <var>Boolean</var> function used to determine if the file name specified in <var>FileName</var> matches the specified <var>Mask</var>. Mask can contain a Windows-style file mask which uses the following wildcards:
|
|
</p>
|
|
<dl>
|
|
<dt>foo*.*</dt>
|
|
<dd>
|
|
Matches all files starting with 'foo' regardless of the file extension. Same as foo* using the Matches method.
|
|
</dd>
|
|
<dt>foo*.</dt>
|
|
<dd>Matches foo* but must not include a file extension.</dd>
|
|
<dt>*.</dt>
|
|
<dd>Matches any file name, but must not include a file extension.</dd>
|
|
<dt>foo.</dt>
|
|
<dd>Matches foo but not foo.txt.</dd>
|
|
<dt>foo.*</dt>
|
|
<dd>Matches foo, foo.txt, or foo.bar.</dd>
|
|
<dt>*.*</dt>
|
|
<dd>Matches any file name with an extension.</dd>
|
|
</dl>
|
|
<p>
|
|
<var>CaseSensitive</var> indicates whether case sensitivity is used when comparing the file name to the mask value.
|
|
</p>
|
|
<p>
|
|
<var>Options</var> 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 <var>moDisableSets</var> in the Options parameter will disable interpreting the ' <b>[</b>' character as the beginning of a set in the specified mask. Use an empty set (' <b>[]</b>') when options from the <var>TMaskOption</var> enumeration are not needed.
|
|
</p>
|
|
<p>
|
|
For example:
|
|
</p>
|
|
<code>MatchesWindowsMask('[x]','[x]',[moDisableSets]); // returns True</code>
|
|
<p>
|
|
MatchesWindowsMask creates a <var>TMask</var> 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 <var>MatchesWindowsMask</var> method in the TMask instance is called using FileName as an argument, and gets the return value for the function.
|
|
</p>
|
|
<remark>
|
|
The overloaded variant which does <b>not</b> include a TMaskOptions parameter has been marked as deprecated. It will be removed in a future Lazarus version.
|
|
</remark>
|
|
</descr>
|
|
<seealso>
|
|
<link id="TMask.MatchesWindowsMask"/>
|
|
<link id="TMaskOption"/>
|
|
<link id="TMaskOptions"/>
|
|
<link id="#lazutils.masks.MasksOverview">Masks Overview</link>
|
|
</seealso>
|
|
</element>
|
|
<element name="MatchesWindowsMask.Result">
|
|
<short>True when the file name matches the mask value using the specified options.</short>
|
|
</element>
|
|
<element name="MatchesWindowsMask.FileName">
|
|
<short>File name compared to the mask value.</short>
|
|
</element>
|
|
<element name="MatchesWindowsMask.Mask">
|
|
<short>Mask used to perform the comparison.</short>
|
|
</element>
|
|
<element name="MatchesWindowsMask.CaseSensitive">
|
|
<short>True when case sensitivity should be used in the comparison.</short>
|
|
</element>
|
|
<element name="MatchesWindowsMask.Options">
|
|
<short>Set of options enabled for the comparison.</short>
|
|
</element>
|
|
<element name="MatchesMaskList">
|
|
<short>
|
|
Determine whether the specified file name matches at least one of the specified masks.
|
|
</short>
|
|
<descr>
|
|
<p>
|
|
<var>MatchesMaskList</var> is an overloaded <var>Boolean</var> function used to determine whether the specified file name matches at least one of the specified masks. MatchesMaskList is similar to <var>MatchesWindowsMaskList</var>, but uses Unix-style mask expressions. This includes use of the following:
|
|
</p>
|
|
<dl>
|
|
<dt>foo*</dt>
|
|
<dd>
|
|
Matches all files starting with 'foo' regardless of the file extension. Same as foo*.* using MatchesWindowsMaskList.
|
|
</dd>
|
|
<dt>foo*.</dt>
|
|
<dd>Matches foo* but must not include a file extension.</dd>
|
|
<dt>*.</dt>
|
|
<dd>Matches any file name, but must not include a file extension.</dd>
|
|
<dt>foo.</dt>
|
|
<dd>Matches foo but not foo.txt.</dd>
|
|
<dt>foo.*</dt>
|
|
<dd>Matches foo, foo.txt, or foo.bar.</dd>
|
|
<dt>*</dt>
|
|
<dd>Matches any file name including those with an optional extension.</dd>
|
|
</dl>
|
|
<p>
|
|
Overloaded variants of the routine provide arguments and configuration settings, including:
|
|
</p>
|
|
<dl>
|
|
<dt>Filename</dt>
|
|
<dd>File name compared to the file masks in Mask.</dd>
|
|
<dt>Mask</dt>
|
|
<dd>Contains one or more file mask expressions separated by one of the values in Separator.</dd>
|
|
<dt>Separator</dt>
|
|
<dd>
|
|
Contains the character(s) used as a separator between mask expressions in Mask. The default separator is the SemiColon (;) character.
|
|
</dd>
|
|
<dt>Options</dt>
|
|
<dd>
|
|
Contains TMaskOption values which enable or disable features in the comparison. The default value is an empty set ([]).
|
|
</dd>
|
|
<dt>CaseSensitive</dt>
|
|
<dd>Indicates whether the file name to mask comparison is case sensitive.</dd>
|
|
</dl>
|
|
<remark>
|
|
The overloaded variant which includes the <var>CaseSensitive</var> argument has been deprecated. Use the variant that includes the <var>TMaskOptions</var> argument.
|
|
</remark>
|
|
<p>
|
|
MatchesMaskList creates a <var>TMaskList</var> instance which uses the values in the Mask, Separator and Options parameters. Its <var>Matches</var> method is called to compare the value in Filename to the mask values in the list.
|
|
</p>
|
|
<p>
|
|
The return value is <b>True</b> when Filename matches at least one of the masks in the list.
|
|
</p>
|
|
</descr>
|
|
<seealso>
|
|
<link id="MatchesWindowsMaskList"/>
|
|
<link id="TMaskOption"/>
|
|
<link id="TMaskList"/>
|
|
<link id="#lazutils.masks.MasksOverview">Masks Overview</link>
|
|
</seealso>
|
|
</element>
|
|
<element name="MatchesMaskList.Result">
|
|
<short>True when Filename matches at least one of the masks in the list.</short>
|
|
</element>
|
|
<element name="MatchesMaskList.FileName">
|
|
<short>File name compared to the file masks in Mask.</short>
|
|
</element>
|
|
<element name="MatchesMaskList.Mask">
|
|
<short>one or more file mask expressions separated by one of the values in Separator.</short>
|
|
</element>
|
|
<element name="MatchesMaskList.Separator">
|
|
<short>Character(s) used as a separator between mask expressions in Mask.</short>
|
|
</element>
|
|
<element name="MatchesMaskList.CaseSensitive">
|
|
<short>True if the file name to mask comparison is case sensitive.</short>
|
|
</element>
|
|
<element name="MatchesMaskList.Options">
|
|
<short>TMaskOption values which enable or disable features in the comparison.</short>
|
|
</element>
|
|
<element name="MatchesWindowsMaskList">
|
|
<short>
|
|
Determine whether the specified file name matches at least one of the specified masks.
|
|
</short>
|
|
<descr>
|
|
<p>
|
|
<var>MatchesWindowsMaskList</var> is an overloaded <var>Boolean</var> function used to determine whether the specified file name matches at least one of the specified masks. MatchesWindowsMaskList is similar to <var>MatchesMaskList</var>, but provides support for Windows-style file system masks in the Mask argument. This includes use of the following:
|
|
</p>
|
|
<dl>
|
|
<dt>foo*.*</dt>
|
|
<dd>
|
|
Matches all files starting with 'foo' regardless of the file extension. Same as foo* using MatchesMaskList.
|
|
</dd>
|
|
<dt>foo*.</dt>
|
|
<dd>Matches foo* but must not include a file extension.</dd>
|
|
<dt>*.</dt>
|
|
<dd>Matches any file name, but must not include a file extension.</dd>
|
|
<dt>foo.</dt>
|
|
<dd>Matches foo but not foo.txt.</dd>
|
|
<dt>foo.*</dt>
|
|
<dd>Matches foo, foo.txt, or foo.bar.</dd>
|
|
<dt>*.*</dt>
|
|
<dd>Matches any file name with an extension.</dd>
|
|
</dl>
|
|
<p>
|
|
Overloaded variants of the routine provide arguments and configuration settings, including:
|
|
</p>
|
|
<dl>
|
|
<dt>Filename</dt>
|
|
<dd>File name compared to the file masks in Mask.</dd>
|
|
<dt>Mask</dt>
|
|
<dd>Contains one or more file mask expressions separated by one of the values in Separator.</dd>
|
|
<dt>Separator</dt>
|
|
<dd>
|
|
Contains the character(s) used as a separator between mask expressions in Mask. The default separator is the SemiColon (;) character.
|
|
</dd>
|
|
<dt>Options</dt>
|
|
<dd>
|
|
Contains TMaskOption values which enable or disable features in the comparison. The default value is an empty set ([]).
|
|
</dd>
|
|
<dt>CaseSensitive</dt>
|
|
<dd>Indicates whether the file name to mask comparison is case sensitive.</dd>
|
|
</dl>
|
|
<remark>
|
|
The overloaded variant which includes the <var>CaseSensitive</var> argument has been deprecated. Use the variant that includes the <var>TMaskOptions</var> argument.
|
|
</remark>
|
|
<p>
|
|
MatchesWindowsMaskList creates a <var>TMaskList</var> instance which uses the values in the Mask, Separator and Options parameters. Its <var>MatchesWindowsMask</var> method is called to compare the value in Filename to the Windows-style masks in the list.
|
|
</p>
|
|
<p>
|
|
The return value is <b>True</b> when Filename matches at least one of the masks in the list.
|
|
</p>
|
|
</descr>
|
|
<seealso>
|
|
<link id="MatchesMaskList"/>
|
|
<link id="TMaskOption"/>
|
|
<link id="TMaskList"/>
|
|
<link id="#lazutils.masks.MasksOverview">Masks Overview</link>
|
|
</seealso>
|
|
</element>
|
|
<element name="MatchesWindowsMaskList.Result">
|
|
<short>
|
|
<b>True</b> when Filename matches at least one of the masks in the list.</short>
|
|
</element>
|
|
<element name="MatchesWindowsMaskList.FileName">
|
|
<short>File name compared to the file masks in Mask.</short>
|
|
</element>
|
|
<element name="MatchesWindowsMaskList.Mask">
|
|
<short>one or more file mask expressions separated by one of the values in Separator.</short>
|
|
</element>
|
|
<element name="MatchesWindowsMaskList.Separator">
|
|
<short>Character(s) used as a separator between mask expressions in Mask.</short>
|
|
</element>
|
|
<element name="MatchesWindowsMaskList.CaseSensitive">
|
|
<short>True if the file name to mask comparison is case sensitive.</short>
|
|
</element>
|
|
<element name="MatchesWindowsMaskList.Options">
|
|
<short>TMaskOption values which enable or disable features in the comparison.</short>
|
|
</element>
|
|
<topic name="MasksOverview">
|
|
<short>Masks Overview.</short>
|
|
<descr>
|
|
<p>
|
|
<b>What is a Mask</b>
|
|
</p>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
<b>Literal Characters</b>
|
|
</p>
|
|
<p>
|
|
Each literal character corresponds to a single character in a compared value.
|
|
</p>
|
|
<p>
|
|
<b>Character Sets</b>
|
|
</p>
|
|
<p>
|
|
A character set begins with an opening Square Bracket character (<b>[</b>) and ends with a closing Square Bracket character (<b>]</b>). Values between the brackets represent literal characters or a range of characters which are included in (or excluded from) the character set.
|
|
</p>
|
|
<p>
|
|
A range is defined using a starting character, a dash (<b>-</b>), and an ending character. The character set matches a single character in a compared value. When an Exclamation Point character (<b>!</b>) is found after the first bracket, the values in the character set are excluded from matches using the mask.
|
|
</p>
|
|
<p>
|
|
For example, an alpha-numeric character set could be represented using the following:
|
|
</p>
|
|
<code>[a-zA-Z0-9]</code>
|
|
<p>
|
|
And, a character set which excludes numeric values could be represented using the following:
|
|
</p>
|
|
<code>[!0-9]</code>
|
|
<p>
|
|
<b>Wildcard Characters</b>
|
|
</p>
|
|
<p>
|
|
Wildcard characters allow one or more literal characters to be considered as a match in the mask value, and includes the <b>?</b> and <b>*</b> characters. <b>?</b> matches a single character (regardless of its value). <b>*</b> matches any number of characters (regrardless of their values).
|
|
</p>
|
|
<p>
|
|
<b>Mask Examples</b>
|
|
</p>
|
|
<!-- TODO: Add more mask examples -->
|
|
<dl>
|
|
<dt>abc.ext</dt>
|
|
<dd>Matches a single file named "abc.ext".</dd>
|
|
<dt>a[blt]c.ext</dt>
|
|
<dd>Matches "abc.ext", "alc.ext", or "atc.ext".</dd>
|
|
<dt>a[b-d]c.ext</dt>
|
|
<dd>Matches "abc.ext", "acc.ext", or "adc.ext".</dd>
|
|
<dt>foo*</dt>
|
|
<dd>Matches any file that starts with "foo", including those with a file extension.</dd>
|
|
<dt>*</dt>
|
|
<dd>Matches any file, including those with a file extension.</dd>
|
|
<dt>*.</dt>
|
|
<dd>Matches any file that does not have an extension.</dd>
|
|
<dt>ab??ef.txt</dt>
|
|
<dd>Matches abcdef.txt and abrtef.txt.</dd>
|
|
</dl>
|
|
<p>
|
|
<b>Using Masks</b>
|
|
</p>
|
|
<p>
|
|
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).
|
|
</p>
|
|
<remark>
|
|
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.
|
|
</remark>
|
|
</descr>
|
|
</topic>
|
|
</module>
|
|
<!-- Masks -->
|
|
</package>
|
|
</fpdoc-descriptions>
|