1Test::Regexp(3)       User Contributed Perl Documentation      Test::Regexp(3)
2
3
4

NAME

6       Test::Regexp - Test your regular expressions
7

SYNOPSIS

9        use Test::Regexp 'no_plan';
10
11        match    subject      => "Foo",
12                 pattern      => qr /\w+/;
13
14        match    subject      => "Foo bar",
15                 keep_pattern => qr /(?<first_word>\w+)\s+(\w+)/,
16                 captures     => [[first_word => 'Foo'], ['bar']];
17
18        no_match subject      => "Baz",
19                 pattern      => qr /Quux/;
20
21        $checker = Test::Regexp -> new -> init (
22           keep_pattern => qr /(\w+)\s+\g{-1}/,
23           name         => "Double word matcher",
24        );
25
26        $checker -> match    ("foo foo", ["foo"]);
27        $checker -> no_match ("foo bar");
28

DESCRIPTION

30       This module is intended to test your regular expressions. Given a
31       subject string and a regular expression (aka pattern), the module not
32       only tests whether the regular expression complete matches the subject
33       string, it performs a "utf8::upgrade" or "utf8::downgrade" on the
34       subject string and performs the tests again, if necessary. Furthermore,
35       given a pattern with capturing parenthesis, it checks whether all
36       captures are present, and in the right order. Both named and unnamed
37       captures are checked.
38
39       By default, the module exports two subroutines, "match" and "no_match".
40       The latter is actually a thin wrapper around "match", calling it with
41       "match => 0".
42
43   "Complete matching"
44       A match is only considered to successfully match if the entire string
45       is matched - that is, if $& matches the subject string. So:
46
47         Subject    Pattern
48
49         "aaabb"    qr /a+b+/     # Considered ok
50         "aaabb"    qr /a+/       # Not considered ok
51
52       For efficiency reasons, when the matching is performed the pattern is
53       actually anchored at the start. It's not anchored at the end as that
54       would potentially influence the matching.
55
56   UTF8 matching
57       Certain regular expression constructs match differently depending on
58       whether UTF8 matching is in effect or not. This is only relevant if the
59       subject string has characters with code points between 128 and 255, and
60       no characters above 255 -- in such a case, matching may be different
61       depending on whether the subject string has the UTF8 flag on or not.
62       "Test::Regexp" detects such a case, and will then run the tests twice;
63       once with the subject string "utf8::downgraded", and once with the
64       subject string "utf8::upgraded".
65
66   Number of tests
67       There's no fixed number of tests that is run. The number of tests
68       depends on the number of captures, the number of different names of
69       captures, and whether there is the need to up- or downgrade the subject
70       string.
71
72       It is therefore recommended to use "use Text::Regexp tests =>
73       'no_plan';".  In a later version, "Test::Regexp" will use a version of
74       "Test::Builder" that allows for nested tests.
75
76       Details
77
78       The number of tests is as follows:
79
80       If no match is expected ("no_match => 0", or "no_match" is used), only
81       one test is performed.
82
83       Otherwise (we are expecting a match), if "pattern" is used, there will
84       be three tests.
85
86       For "keep_pattern", there will be four tests, plus one tests for each
87       capture, an additional test for each named capture, and a test for each
88       name used in the set of named captures. So, if there are "N" captures,
89       there will be at least "4 + N" tests, and at most "4 + 3 * N" tests.
90
91       If both "pattern" and "keep_pattern" are used, the number of tests add
92       up.
93
94       If "Test::Regexp" decides to upgrade or downgrade, the number of tests
95       double.
96
97   "use" options
98       When using "Test::Regexp", there are a few options you can give it.
99
100       "tests => 'no_plan'", "tests => 123"
101           The number of tests you are going to run. Since takes some work to
102           figure out how many tests will be run, for now the recommendation
103           is to use "tests => 'no_plan'".
104
105       "import => [methods]"
106           By default, the subroutines "match" and "no_match" are exported. If
107           you want to import a subset, use the "import" tag, and give it an
108           arrayref with the names of the subroutines to import.
109
110   "match"
111       The subroutine "match" is the workhorse of the module. It takes a
112       number of named arguments, most of them optional, and runs one or more
113       tests. It returns 1 if all tests were run successfully, and 0 if one or
114       more tests failed. The following options are available:
115
116       "subject => STRING"
117           The string against which the pattern is tested is passed to "match"
118           using the "subject" option. It's an error to not pass in a subject.
119
120       "pattern => PATTERN", "keep_pattern => PATTERN"
121           A pattern (aka regular expression) to test can be passed with one
122           of "pattern" or "keep_pattern". The former should be used if the
123           pattern does not have any matching parenthesis; the latter if the
124           pattern does have capturing parenthesis. If both "pattern" and
125           "keep_pattern" are provided, the subject is tested against both.
126           It's an error to not give either "pattern" or "keep_pattern".
127
128       "captures => [LIST]"
129           If a regular expression is passed with "keep_pattern" you should
130           pass in a list of captures using the "captures" option.
131
132           This list should contain all the captures, in order. For unnamed
133           captures, this should just be the string matched by the capture;
134           for a named capture, this should be a two element array, the first
135           element being the name of the capture, the second element the
136           capture. Named and unnamed captures may be mixed, and the same name
137           for a capture may be repeated.
138
139           Example:
140
141            match  subject      =>  "Eland Wapiti Caribou",
142                   keep_pattern =>  qr /(\w+)\s+(?<a>\w+)\s+(\w+)/,
143                   captures     =>  ["Eland", [a => "Wapiti"], "Caribou"];
144
145       "name => NAME"
146           The "name" of the test. It's being used in the test comment.
147
148       "comment => NAME"
149           An alternative for "name". If both are present, "comment" is used.
150
151       "utf8_upgrade => 0", "utf8_downgrade => 0"
152           As explained in "UTF8 matching", "Test::Regexp" detects whether a
153           subject may provoke different matching depending on its UTF8 flag,
154           and then it "utf8::upgrades" or "utf8::downgrades" the subject
155           string and runs the test again. Setting "utf8_upgrade" to 0
156           prevents "Test::Regexp" from downgrading the subject string, while
157           setting "utf8_upgrade" to 0 prevents "Test::Regexp" from upgrading
158           the subject string.
159
160       "match => BOOLEAN"
161           By default, "match" assumes the pattern should match. But it also
162           important to test which strings do not match a regular expression.
163           This can be done by calling "match" with "match => 0" as parameter.
164           (Or by calling "no_match" instead of "match"). In this case, the
165           test is a failure if the pattern completely matches the subject
166           string. A "captures" argument is ignored.
167
168       "reason => STRING"
169           If the match is expected to fail (so, when "match => 0" is passed,
170           or if "no_match" is called), a reason may be provided with the
171           "reason" option. The reason is then printed in the comment of the
172           test.
173
174       "test => STRING"
175           If the match is expected to pass (when "match" is called, without
176           "match" being false), and this option is passed, a message is
177           printed indicating what this specific test is testing (the argument
178           to "test").
179
180       "todo => STRING"
181           If the "todo" parameter is used (with a defined value), the tests
182           are assumed to be TODO tests. The argument is used as the TODO
183           message.
184
185       "full_text => BOOL"
186           By default, long test messages are truncated; if a true value is
187           passed, the message will not get truncated.
188
189       "escape => INTEGER"
190           Controls how non-ASCII and non-printables are displayed in
191           generated test messages:
192
193           0 No characters are escape, everything is displayed as is.
194
195           1 Show newlines, linefeeds and tabs using their usual escape
196             sequences ("\n", "\r", and "\t").
197
198           2 Show any character outside of the printable ASCII characters as
199             named escapes ("\N{UNICODE NAME}"), or a hex escape if the
200             unicode name is not found ("\x{XX}"). This is the default if
201             "-CO" is not in effect ("${^UNICODE}" is false).
202
203             Newlines, linefeeds and tabs are displayed as above.
204
205           3 Show any character outside of the printable ASCII characters as
206             hext escapes ("\x{XX}").
207
208             Newlines, linefeeds and tabs are displayed as above.
209
210           4 Show the non-printable ASCII characters as hex escapes
211             ("\x{XX}"); any non-ASCII character is displayed as is. This is
212             the default if "-CO" is in effect ("${^UNICODE}" is true).
213
214             Newlines, linefeeds and tabs are displayed as above.
215
216       "no_keep_message => BOOL"
217           If matching against a keeping pattern, a message "(with -Keep)" is
218           added to the comment. Setting this parameter suppresses this
219           message.  Mostly useful for "Regexp::Common510".
220
221   "no_match"
222       Similar to "match", except that it tests whether a pattern does not
223       match a string. Accepts the same arguments as "match", except for
224       "match".
225
226   OO interface
227       Since one typically checks a pattern with multiple strings, and it can
228       be tiresome to repeatedly call "match" or "no_match" with the same
229       arguments, there's also an OO interface. Using a pattern, one
230       constructs an object and can then repeatedly call the object to match a
231       string.
232
233       To construct and initialize the object, call the following:
234
235        my $checker = Test::Regexp -> new -> init (
236           pattern      => qr  /PATTERN/,
237           keep_pattern => qr /(PATTERN)/,
238           ...
239        );
240
241       "init" takes exactly the same arguments as "match", with the exception
242       of "subject" and "captures". To perform a match, all "match" (or
243       "no_match") on the object. The first argument should be the subject the
244       pattern should match against (see the "subject" argument of "match"
245       discussed above). If there is a match against a capturing pattern, the
246       second argument is a reference to an array with the matches (see the
247       "captures" argument of "match" discussed above).
248
249       Both "match" and "no_match" can take additional (named) arguments,
250       identical to the none-OO "match" and "no_match" routines.
251

RATIONALE

253       The reason "Test::Regexp" was created is to aid testing for the rewrite
254       of "Regexp::Common".
255

DEVELOPMENT

257       The current sources of this module are found on github,
258       <git://github.com/Abigail/Test-Regexp.git>.
259

AUTHOR

261       Abigail <mailto:test-regexp@abigail.be>.
262
264       Copyright (C) 2009 by Abigail
265
266       Permission is hereby granted, free of charge, to any person obtaining a
267       copy of this software and associated documentation files (the
268       "Software"), to deal in the Software without restriction, including
269       without limitation the rights to use, copy, modify, merge, publish,
270       distribute, sublicense, and/or sell copies of the Software, and to
271       permit persons to whom the Software is furnished to do so, subject to
272       the following conditions:
273
274       The above copyright notice and this permission notice shall be included
275       in all copies or substantial portions of the Software.
276
277       THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
278       OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
279       MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
280       IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
281       CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
282       TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
283       SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
284

INSTALLATION

286       To install this module, run, after unpacking the tar-ball, the
287       following commands:
288
289          perl Makefile.PL
290          make
291          make test
292          make install
293
294
295
296perl v5.36.0                      2022-07-22                   Test::Regexp(3)
Impressum