Masks: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		This page describes the Masks unit as per Lazarus version 2.3
2	2
3	3		UNDER CONSTRUCTION
4	4
5	5		## Overview
6	6
7	7		The masks unit provides classes and functions for pattern matching using wildcards, sets/ranges and/or literal characters.\
8	8
9	9		## Controlling how the mask is interpreted
10	10
11	11		### TMaskOpcodes
12	12
13	13		TMaskOpcodes is defined as set of TMaskOpcode.\
14	14		The TMaskOpcode enumeration type consist of:
15	15
16		-	~~<table>~~
17	16		<thead>
18		-	~~<tr>~~
19		-	~~<th>Name</th>~~
20		-	~~<th>Interpretation</th>~~
21		-	~~</tr>~~
	17	+
22	18		</thead>
23	19		<tbody>
24		-	~~<tr>~~
25		-	~~<td>mocAnyChar</td>~~
26		-	~~<td>Treat ? as a wildcard to match exactly one char</td>~~
27		-	~~</tr>~~
28		-	~~<tr>~~
29		-	~~<td>mocAnyCharOrNone</td>~~
30		-	~~<td>Treat [?] to match any char or the absence of a char</td>~~
31		-	~~</tr>~~
32		-	~~<tr>~~
33		-	~~<td>mocAnyText</td>~~
34		-	~~<td>Treat * as a wildcard to mach zero or any mumber of chars</td>~~
35		-	~~</tr>~~
36		-	~~<tr>~~
37		-	~~<td>mocRange</td>~~
38		-	~~<td>Treat [a-z] to match any character in the range from 'a' up to and including 'z'.<br />~~
	20	+
39	21		A '-' is treated as a range indicator and it's presence is required (unless mocSet is also enabled).<br />
40	22		To have a literal '-' in a range definition, you must escape it with EscapeChar.</td>
41		-	~~</tr>~~
42		-	~~<tr>~~
43		-	~~<td>mocSet</td>~~
44		-	~~<td>Treat [a-z] to match either 'a', '-' or 'z'<br />~~
	23	+
45	24		Notice that when mocRange is also enabled, an unescaped '-' will always be treated as a range indicator.</td>
46		-	~~</tr>~~
47		-	~~<tr>~~
48		-	~~<td>mocNegateGroup</td>~~
49		-	~~<td>Treat [!a-c] to not match 'a', 'b', or 'c', but match any other char. Requires mocRange and/or mocSet</td>~~
50		-	~~</tr>~~
51		-	~~<tr>~~
52		-	~~<td>mocEscapeChar</td>~~
53		-	~~<td>Treat EscapeChar (defaults to '\') to take the next char as a literal, so '' is treated as a literal ''.</td>~~
54		-	~~</tr>~~
	25	+
55	26		</tbody>
56		-	~~</table>~~
57	27
58	28		#### Predefined MaskOpcodes
59	29
60	30		The masks unit has some predefined MaskOpcodes constants.\
61	31
62	32		\| Name \| Interpretation \|
63	33		\|----\|----\|
64	34		\| AllMaskOpCodes \| Self explanatory. \|
65	35		\| MaskOpCodesDisableRange \| Do not interpret \[ as the start of a range or set. \|
66	36		\| MaskOpCodesNoEscape \| Interpret \[?\] as a set with a literal question mark instead of 0..1 chars wildcard. Disable escaping. \|
67	37		\| DefaultMaskOpCodes \| Equals to MaskOpCodesNoEscape. \|
68	38		\| \| \|
69	39
70	40		If no TMaskOpcodes parameter is supplied to one of the Matches methods or functions, DefaultMaskOpCodes is assumed.
71	41
72	42		### Specific Windows Quirks
73	43
74	44		Windows mask works in a different mode than regular masks, it has many quirks and corner cases inherited from CP/M, then adapted to DOS (8.3) file names and adapted again for long file names.
75	45
76	46		TWindowsQuirks is defined as set of TWindowsQuirks.\
77	47		The TWindowsQuirk enumeration type consists of:
78	48
79	49		\| Name \| Example mask \| Interpretation \|
80	50		\|----\|----\|----\|
81	51		\| wqAnyExtension \| Anything. \| The filename is not required to have an extension \|
82	52		\| wqFilenameEnd \| Anything??.abc \| The '?' matches 1 or 0 chars (except '.') \|
83	53		\| wqExtension3More \| Anything.abc \| Matches Anything.abc but also Anything.abc* (so '*.pas' also matches with 'file.pas.bak') \|
84	54		\| wqEmptyIsAny \| \| Empty string matches anything, so acts like '*' \|
85	55		\| wqAllByExtension \| .abc \| Is treated as *.abc \|
86	56		\| wqNoExtension \| Anything. \| Matches Anything without extension \|
87	57
88	58		TWindowsQuirks can only be used in the Windows specfic classses and functions.
89	59
90	60		#### Predefined TWindowsQuirks
91	61
92	62		The masks unit has some predefined WindowsQuirks constants.\
93	63
94	64		\| Name \| Interpretation \|
95	65		\|----\|----\|
96	66		\| AllWindowsQuirks \| Self explanatory. \|
97	67		\| DefaultWindowsQuirks \| Equals to \[wqAnyExtension,wqEmptyIsAny,wqNoExtension\] \|
98	68		\| \| \|
99	69
100	70		If no TWindowsQuirks parameter is supplied to one of the Windows specific Matches methods or functions, DefaultWindowsQuirks is assumed.
101	71
102	72		### TMask classes
103	73
104	74		All pattern matching is done by the TMask classes.\
105	75		The convenience functions like MatchesMask() internally use an instance of a TMask class.\
106	76		Not all of the properties of the TMask classes are exposed in these convenience functions, so when you need more control over how the mask is interpreted, you should use a TMask class directly.\
107	77		This also makes sense if you do multiple calls to a matching routine, this avoids repetetive creating of a TMask class instance.
108	78
109	79		#### TMask
110	80
111	81		Does pattern matching unix style (or should one say "non-Windows" style).\
112	82		The mask '.' requires that there must be at least one period ('.') in the filename to match.\
113	83		The following properties of TMask (and all other TMask classes) are not exposed in the aforementioned convenience functions:
114	84
115		-	~~<table>~~
116	85		<thead>
117		-	~~<tr>~~
118		-	~~<th>Name</th>~~
119		-	~~<th>Type</th>~~
120		-	~~<th>Default value</th>~~
121		-	~~<th>Meaning</th>~~
122		-	~~</tr>~~
	86	+
123	87		</thead>
124	88		<tbody>
125		-	~~<tr>~~
126		-	~~<td>AutoReverseRange</td>~~
127		-	~~<td>Boolean</td>~~
128		-	~~<td>True</td>~~
129		-	~~<td>When True, it interprets the range [z-a] as [a-z], otherwise as an empty range.<br />~~
	89	+
130	90		Requires mocRange enabled.</td>
131		-	~~</tr>~~
132		-	~~<tr>~~
133		-	~~<td>EscapeChar</td>~~
134		-	~~<td>Char</td>~~
135		-	~~<td>'\'</td>~~
136		-	~~<td>The char used to escape characters that would otherwise have special meaning. E.g. '' will be interpreted as a literal ''.<br />~~
	91	+
137	92		The value of EscapeChar must be in the range #0..#127 (so 7-bit ASCII), otherwise an exception is raised.<br />
138	93		The use of EscapeChar requires mocEscapeChar to be enabled.</td>
139		-	~~</tr>~~
140		-	~~<tr>~~
141		-	~~<td></td>~~
142		-	~~<td></td>~~
143		-	~~<td></td>~~
144		-	~~<td></td>~~
145		-	~~</tr>~~
	94	+
146	95		</tbody>
147		-	~~</table>~~
148	96
149	97		To maintain backwards compatibility the TMask class provides the method MatchesWindowsMask(), but this hase been deprecated in favour of the direct use of the Matches method of TWindowsMask. This method will be removed in a future release.
150	98
151	99		#### TWindowsMask
152	100
153	101		Does pattern matching in Windows style.\
154	102		So (by default) the mask '.' wil match any string of any (including zero) length, with or withoud a period it.\
155	103		Notice that \#0 is not allowed as a character in the Mask in TWindowsMask (and therefore \#0 can also not be used as EscapeChar).\
156	104		If you set it's property Quirks to \[\] (empty set), it will behave just like TMask.
157	105
158	106		#### TMaskList and TWindowsMaskList
159	107
160	108		These classes support pattarn matching against a list of patterns separated by a Separator (which defaults to ';').\
161	109		Typically it will be used to match e.g. a list of filename extensions: '.pas;.pp;*.inc'.\
162		-	\
	110	+
163	111		Like TMask, the TMaskList class provides the method MatchesWindowsMask() for backwards compatibility. It's fate will be the same...
164	112
165	113		## Code examples
166	114
167	115		ToDo
168	116
169	117		---
170	118		From the Free Pascal wiki, page "Masks", as it stood on 2022-01-02 after a change by Bart, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).

Back to history