"Complete matching"

  Subject    Pattern

  "aaabb"    qr /a+b+/     # Considered ok
  "aaabb"    qr /a+/       # Not considered ok

For efficiency reasons, when the matching is performed the pattern is actually anchored at the start. It's not anchored at the end as that would potentially influence the matching.

UTF8 matching

Number of tests

It is therefore recommended to use "use Text::Regexp tests => 'no_plan';". In a later version, "Test::Regexp" will use a version of "Test::Builder" that allows for nested tests.

Details

The number of tests is as follows:

If no match is expected ("no_match => 0", or "no_match" is used), only one test is performed.

Otherwise (we are expecting a match), if "pattern" is used, there will be three tests.

For "keep_pattern", there will be four tests, plus one tests for each capture, an additional test for each named capture, and a test for each name used in the set of named captures. So, if there are "N" captures, there will be at least "4 + N" tests, and at most "4 + 3 * N" tests.

If both "pattern" and "keep_pattern" are used, the number of tests add up.

If "Test::Regexp" decides to upgrade or downgrade, the number of tests double.

"use" options

"tests => 'no_plan'", "tests => 123"

The number of tests you are going to run. Since takes some work to figure out how many tests will be run, for now the recommendation is to use "tests => 'no_plan'".

"import => [methods]"

By default, the subroutines "match" and "no_match" are exported. If you want to import a subset, use the "import" tag, and give it an arrayref with the names of the subroutines to import.

"match"

"subject => STRING"

The string against which the pattern is tested is passed to "match" using the "subject" option. It's an error to not pass in a subject.

"pattern => PATTERN", "keep_pattern => PATTERN"

A pattern (aka regular expression) to test can be passed with one of "pattern" or "keep_pattern". The former should be used if the pattern does not have any matching parenthesis; the latter if the pattern does have capturing parenthesis. If both "pattern" and "keep_pattern" are provided, the subject is tested against both. It's an error to not give either "pattern" or "keep_pattern".

"captures => [LIST]"

If a regular expression is passed with "keep_pattern" you should pass in a list of captures using the "captures" option.

This list should contain all the captures, in order. For unnamed captures, this should just be the string matched by the capture; for a named capture, this should be a two element array, the first element being the name of the capture, the second element the capture. Named and unnamed captures may be mixed, and the same name for a capture may be repeated.

Example:

 match  subject      =>  "Eland Wapiti Caribou",
        keep_pattern =>  qr /(\w+)\s+(?<a>\w+)\s+(\w+)/,
        captures     =>  ["Eland", [a => "Wapiti"], "Caribou"];
    

"name => NAME"

The "name" of the test. It's being used in the test comment.

"comment => NAME"

An alternative for "name". If both are present, "comment" is used.

"utf8_upgrade => 0", "utf8_downgrade => 0"

As explained in "UTF8 matching", "Test::Regexp" detects whether a subject may provoke different matching depending on its UTF8 flag, and then it "utf8::upgrades" or "utf8::downgrades" the subject string and runs the test again. Setting "utf8_upgrade" to 0 prevents "Test::Regexp" from downgrading the subject string, while setting "utf8_upgrade" to 0 prevents "Test::Regexp" from upgrading the subject string.

"match => BOOLEAN"

By default, "match" assumes the pattern should match. But it also important to test which strings do not match a regular expression. This can be done by calling "match" with "match => 0" as parameter. (Or by calling "no_match" instead of "match"). In this case, the test is a failure if the pattern completely matches the subject string. A "captures" argument is ignored.

"reason => STRING"

If the match is expected to fail (so, when "match => 0" is passed, or if "no_match" is called), a reason may be provided with the "reason" option. The reason is then printed in the comment of the test.

"test => STRING"

If the match is expected to pass (when "match" is called, without "match" being false), and this option is passed, a message is printed indicating what this specific test is testing (the argument to "test").

"todo => STRING"

If the "todo" parameter is used (with a defined value), the tests are assumed to be TODO tests. The argument is used as the TODO message.

"full_text => BOOL"

By default, long test messages are truncated; if a true value is passed, the message will not get truncated.

"escape => INTEGER"

Controls how non-ASCII and non-printables are displayed in generated test messages:

"no_keep_message => BOOL"

If matching against a keeping pattern, a message "(with -Keep)" is added to the comment. Setting this parameter suppresses this message. Mostly useful for "Regexp::Common510".

"no_match"

OO interface

To construct and initialize the object, call the following:

 my $checker = Test::Regexp -> new -> init (
    pattern      => qr  /PATTERN/,
    keep_pattern => qr /(PATTERN)/,
    ...
 );

"init" takes exactly the same arguments as "match", with the exception of "subject" and "captures". To perform a match, all "match" (or "no_match") on the object. The first argument should be the subject the pattern should match against (see the "subject" argument of "match" discussed above). If there is a match against a capturing pattern, the second argument is a reference to an array with the matches (see the "captures" argument of "match" discussed above).

Both "match" and "no_match" can take additional (named) arguments, identical to the none-OO "match" and "no_match" routines.