Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Test::Regexp(3)	      User Contributed Perl Documentation      Test::Regexp(3)

NAME
       Test::Regexp - Test your	regular	expressions

SYNOPSIS
	use Test::Regexp 'no_plan';

	match	 subject      => "Foo",
		 pattern      => qr /\w+/;

	match	 subject      => "Foo bar",
		 keep_pattern => qr /(?<first_word>\w+)\s+(\w+)/,
		 captures     => [[first_word => 'Foo'], ['bar']];

	no_match subject      => "Baz",
		 pattern      => qr /Quux/;

	$checker = Test::Regexp	-> new -> init (
	   keep_pattern	=> qr /(\w+)\s+\g{-1}/,
	   name		=> "Double word	matcher",
	);

	$checker -> match    ("foo foo", ["foo"]);
	$checker -> no_match ("foo bar");

DESCRIPTION
       This module is intended to test your regular expressions. Given a
       subject string and a regular expression (aka pattern), the module not
       only tests whether the regular expression complete matches the subject
       string, it performs a "utf8::upgrade" or	"utf8::downgrade" on the
       subject string and performs the tests again, if necessary. Furthermore,
       given a pattern with capturing parenthesis, it checks whether all
       captures	are present, and in the	right order. Both named	and unnamed
       captures	are checked.

       By default, the module exports two subroutines, "match" and "no_match".
       The latter is actually a	thin wrapper around "match", calling it	with
       "match => 0".

   "Complete matching"
       A match is only considered to successfully match	if the entire string
       is matched - that is, if	$& matches the subject string. So:

	 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
       Certain regular expression constructs match differently depending on
       whether UTF8 matching is	in effect or not. This is only relevant	if the
       subject string has characters with code points between 128 and 255, and
       no characters above 255 -- in such a case, matching may be different
       depending on whether the	subject	string has the UTF8 flag on or not.
       "Test::Regexp" detects such a case, and will then run the tests twice;
       once with the subject string "utf8::downgraded",	and once with the
       subject string "utf8::upgraded".

   Number of tests
       There's no fixed	number of tests	that is	run. The number	of tests
       depends on the number of	captures, the number of	different names	of
       captures, and whether there is the need to up- or downgrade the subject
       string.

       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
       When using "Test::Regexp", there	are a few options you can give it.

       "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"
       The subroutine "match" is the workhorse of the module. It takes a
       number of named arguments, most of them optional, and runs one or more
       tests. It returns 1 if all tests	were run successfully, and 0 if	one or
       more tests failed. The following	options	are available:

       "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:

	   0 No	characters are escape, everything is displayed as is.

	   1 Show newlines, linefeeds and tabs using their usual escape
	     sequences ("\n", "\r", and	"\t").

	   2 Show any character	outside	of the printable ASCII characters as
	     named escapes ("\N{UNICODE	NAME}"), or a hex escape if the
	     unicode name is not found ("\x{XX}"). This	is the default if
	     "-CO" is not in effect ("${^UNICODE}" is false).

	     Newlines, linefeeds and tabs are displayed	as above.

	   3 Show any character	outside	of the printable ASCII characters as
	     hext escapes ("\x{XX}").

	     Newlines, linefeeds and tabs are displayed	as above.

	   4 Show the non-printable ASCII characters as	hex escapes
	     ("\x{XX}"); any non-ASCII character is displayed as is. This is
	     the default if "-CO" is in	effect ("${^UNICODE}" is true).

	     Newlines, linefeeds and tabs are displayed	as above.

       "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"
       Similar to "match", except that it tests	whether	a pattern does not
       match a string. Accepts the same	arguments as "match", except for
       "match".

   OO interface
       Since one typically checks a pattern with multiple strings, and it can
       be tiresome to repeatedly call "match" or "no_match" with the same
       arguments, there's also an OO interface.	Using a	pattern, one
       constructs an object and	can then repeatedly call the object to match a
       string.

       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.

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

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

AUTHOR
       Abigail <mailto:test-regexp@abigail.be>.

COPYRIGHT and LICENSE
       Copyright (C) 2009 by Abigail

       Permission is hereby granted, free of charge, to	any person obtaining a
       copy of this software and associated documentation files	(the
       "Software"), to deal in the Software without restriction, including
       without limitation the rights to	use, copy, modify, merge, publish,
       distribute, sublicense, and/or sell copies of the Software, and to
       permit persons to whom the Software is furnished	to do so, subject to
       the following conditions:

       The above copyright notice and this permission notice shall be included
       in all copies or	substantial portions of	the Software.

       THE SOFTWARE IS PROVIDED	"AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
       OR IMPLIED, INCLUDING BUT NOT LIMITED TO	THE WARRANTIES OF
       MERCHANTABILITY,	FITNESS	FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
       IN NO EVENT SHALL THE AUTHORS OR	COPYRIGHT HOLDERS BE LIABLE FOR	ANY
       CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN	ACTION OF CONTRACT,
       TORT OR OTHERWISE, ARISING FROM,	OUT OF OR IN CONNECTION	WITH THE
       SOFTWARE	OR THE USE OR OTHER DEALINGS IN	THE SOFTWARE.

INSTALLATION
       To install this module, run, after unpacking the	tar-ball, the
       following commands:

	  perl Makefile.PL
	  make
	  make test
	  make install

perl v5.32.1			  2017-04-01		       Test::Regexp(3)

NAME | SYNOPSIS | DESCRIPTION | RATIONALE | DEVELOPMENT | AUTHOR | COPYRIGHT and LICENSE | INSTALLATION

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Test::Regexp&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help