Author: Jay Bonci <jaybonci@debian.org>
Description: Patch from Era Eriksson to clean up some manpage language
Bug: #322351
--- a/Warn.pm
+++ b/Warn.pm
@@ -9,13 +9,13 @@ Test::Warn - Perl extension to test meth
warning_is {foo(-dri => "/")} "Unknown Parameter 'dri'", "dri != dir gives warning";
warnings_are {bar(1,1)} ["Width very small", "Height very small"];
- warning_is {add(2,2)} undef, "No warning to calc 2+2"; # or
- warnings_are {add(2,2)} [], "No warning to calc 2+2"; # what reads better :-)
+ warning_is {add(2,2)} undef, "No warning for calc 2+2"; # or
+ warnings_are {add(2,2)} [], "No warning for calc 2+2"; # what reads better :-)
warning_like {foo(-dri => "/")} qr/unknown param/i, "an unknown parameter test";
warnings_like {bar(1,1)} [qr/width.*small/i, qr/height.*small/i];
- warning_is {foo()} {carped => "didn't found the right parameters"};
+ warning_is {foo()} {carped => "didn't find the right parameters"};
warnings_like {foo()} [qr/undefined/,qr/undefined/,{carped => qr/no result/i}];
warning_like {foo(undef)} 'uninitialized';
@@ -31,9 +31,9 @@ Test::Warn - Perl extension to test meth
A good style of Perl programming calls for a lot of diverse regression tests.
-This module provides a few convenience methods for testing warning based code.
+This module provides a few convenience methods for testing warning-based code.
-If you are not already familiar with the Test::More manpage
+If you are not already familiar with the Test::More manpage,
now would be the time to go take a look.
=head2 FUNCTIONS
@@ -42,29 +42,29 @@ now would be the time to go take a look.
=item warning_is BLOCK STRING, TEST_NAME
-Tests that BLOCK gives exactly the one specificated warning.
-The test fails if the BLOCK warns more then one times or doesn't warn.
+Tests that BLOCK gives exactly the one specified warning.
+The test fails if the BLOCK warns more than one time or doesn't warn.
If the string is undef,
then the tests succeeds if the BLOCK doesn't give any warning.
-Another way to say that there aren't any warnings in the block,
-is C<warnings_are {foo()} [], "no warnings in">.
+Another way to say that there aren't any warnings in the block
+is C<warnings_are {foo()} [], "no warnings">.
-If you want to test for a warning given by carp,
-You have to write something like:
+If you want to test for a warning given by carp
+you have to write something like:
C<warning_is {carp "msg"} {carped =E<gt> 'msg'}, "Test for a carped warning">.
-The test will fail,
+The test will fail
if a "normal" warning is found instead of a "carped" one.
Note: C<warn "foo"> would print something like C<foo at -e line 1>.
This method ignores everything after the at. That means, to match this warning
you would have to call C<warning_is {warn "foo"} "foo", "Foo succeeded">.
If you need to test for a warning at an exactly line,
-try better something like C<warning_like {warn "foo"} qr/at XYZ.dat line 5/>.
+try something like C<warning_like {warn "foo"} qr/at XYZ.dat line 5/>.
warning_is and warning_are are only aliases to the same method.
So you also could write
C<warning_is {foo()} [], "no warning"> or something similar.
-I decided to give two methods to have some better readable method names.
+I decided to give two methods to have some more readable method names.
A true value is returned if the test succeeds, false otherwise.
@@ -74,32 +74,32 @@ The test name is optional, but recommend
=item warnings_are BLOCK ARRAYREF, TEST_NAME
Tests to see that BLOCK gives exactly the specificated warnings.
-The test fails if the BLOCK warns a different number than the size of the ARRAYREf
-would have expected.
+The test fails if the warnings from BLOCK are not exactly the ones in ARRAYREF.
If the ARRAYREF is equal to [],
then the test succeeds if the BLOCK doesn't give any warning.
Please read also the notes to warning_is as these methods are only aliases.
-If you want more than one tests for carped warnings look that way:
+If you want more than one test for carped warnings, try this:
C<warnings_are {carp "c1"; carp "c2"} {carped => ['c1','c2'];> or
C<warnings_are {foo()} ["Warning 1", {carped => ["Carp 1", "Carp 2"]}, "Warning 2"]>.
-Note that C<{carped => ...}> has always to be a hash ref.
+Note that C<{carped => ...}> always has to be a hash ref.
=item warning_like BLOCK REGEXP, TEST_NAME
-Tests that BLOCK gives exactly one warning and it can be matched to the given regexp.
+Tests that BLOCK gives exactly one warning and it can be matched by
+the given regexp.
If the string is undef,
then the tests succeeds iff the BLOCK doesn't give any warning.
-The REGEXP is matched after the whole warn line,
-which consists in general of "WARNING at __FILE__ line __LINE__".
-So you can check for a warning in at File Foo.pm line 5 with
+The REGEXP is matched sagainst the whole warning line,
+which in general has the form "WARNING at __FILE__ line __LINE__".
+So you can check for a warning in the file Foo.pm on line 5 with
C<warning_like {bar()} qr/at Foo.pm line 5/, "Testname">.
-I don't know whether it's sensful to do such a test :-(
-However, you should be prepared as a matching with 'at', 'file', '\d'
+Perhaps it isn't sensible to perform such a test;
+however, you should be aware that matching on a sweeping regular expression
or similar will always pass.
-Think to the qr/^foo/ if you want to test for warning "foo something" in file foo.pl.
+Consider qr/^foo/ if you want to test for warning "foo something" in file foo.pl.
You can also write the regexp in a string as "/.../"
instead of using the qr/.../ syntax.
@@ -107,7 +107,7 @@ Note that the slashes are important in t
as strings without slashes are reserved for warning categories
(to match warning categories as can be seen in the perllexwarn man page).
-Similar to C<warning_is>,
+As with C<warning_is>,
you can test for warnings via C<carp> with:
C<warning_like {bar()} {carped => qr/bar called too early/i};>
@@ -123,17 +123,19 @@ The test name is optional, but recommend
Tests whether a BLOCK gives exactly one warning of the passed category.
The categories are grouped in a tree,
like it is expressed in perllexwarn.
-Note, that they have the hierarchical structure from perl 5.8.0,
-wich has a little bit changed to 5.6.1 or earlier versions
-(You can access the internal used tree with C<$Test::Warn::Categorization::tree>,
+Note that they have the hierarchical structure from perl 5.8.0,
+u can access the internal hierarchy with
+C<$Test::Warn::Categorization::tree>,
+although it isn't recommended).
+
although I wouldn't recommend it)
Thanks to the grouping in a tree,
-it's simple possible to test for an 'io' warning,
-instead for testing for a 'closed|exec|layer|newline|pipe|unopened' warning.
+it's possible to test simply for an 'io' warning,
+instead of testing for a 'closed|exec|layer|newline|pipe|unopened' warning.
-Note, that warnings occuring at compile time,
-can only be catched in an eval block. So
+Note that compile-time warnings
+can only be caught in an eval block. So
warning_like {eval q/"$x"; $x;/}
[qw/void uninitialized/],
@@ -142,9 +144,8 @@ can only be catched in an eval block. So
will work,
while it wouldn't work without the eval.
-Note, that it isn't possible yet,
-to test for own categories,
-created with warnings::register.
+Note also that it isn't yet possible
+to test for categories you created yourself with C<warnings::register>.
=item warnings_like BLOCK ARRAYREF, TEST_NAME
@@ -164,7 +165,7 @@ and for warning categories, too:
{carped => qr/bar warning/i},
'io'
],
- "I hope, you'll never have to write a test for so many warnings :-)";
+ "I hope you'll never have to write a test for so many warnings :-)";
=item warnings_exist BLOCK STRING|ARRAYREF, TEST_NAME
@@ -190,27 +191,28 @@ C<warnings_exist> by default.
=head1 BUGS
Please note that warnings with newlines inside are making a lot of trouble.
-The only sensible way to handle them is to use are the C<warning_like> or
-C<warnings_like> methods. Background for these problems is that there is no
-really secure way to distinguish between warnings with newlines and a tracing
+The only sensible way to handle them is to use the C<warning_like> or
+C<warnings_like> methods.
+The background for these problems is that there is no
+really secure way to distinguish between warnings with newlines and a triling
stacktrace.
-If a method has it's own warn handler,
+If a method has its own warn handler,
overwriting C<$SIG{__WARN__}>,
my test warning methods won't get these warnings.
-The C<warning_like BLOCK CATEGORY, TEST_NAME> method isn't extremely tested.
-Please use this calling style with higher attention and
-tell me if you find a bug.
+The C<warning_like BLOCK CATEGORY, TEST_NAME> method isn't fully tested.
+Please pay attention if you use this this calling style,
+and report any bugs you find.
=head1 TODO
Improve this documentation.
The code has some parts doubled - especially in the test scripts.
-This is really awkward and has to be changed.
+This is really awkward and must be changed.
-Please feel free to suggest me any improvements.
+Please feel free to suggest improvements.
=head1 SEE ALSO
@@ -407,7 +409,7 @@ sub _diag_found_warning {
$Tester->diag( "found warning: $_" );
}
}
- $Tester->diag( "didn't found a warning" ) unless @_;
+ $Tester->diag( "didn't find a warning" ) unless @_;
}
sub _diag_exp_warning {
--- a/t/warning_is.t
+++ b/t/warning_is.t
@@ -77,7 +77,7 @@ sub _found_warn_msg {
__FILE__,
"line",
WARN_LINE . ".") )
- : "didn't found a warning";
+ : "didn't find a warning";
}
sub _exp_warn_msg {
@@ -94,7 +94,7 @@ sub _found_carp_msg {
__FILE__,
"line",
CARP_LINE) ) # Note the difference, that carp msg
- : "didn't found a warning"; # aren't finished by '.'
+ : "didn't find a warning"; # aren't finished by '.'
}
sub _exp_carp_msg {
--- a/t/warning_like.t
+++ b/t/warning_like.t
@@ -80,7 +80,7 @@ sub _found_warn_msg {
__FILE__,
"line",
WARN_LINE . ".") )
- : "didn't found a warning";
+ : "didn't find a warning";
}
sub _exp_warn_msg {
@@ -97,7 +97,7 @@ sub _found_carp_msg {
__FILE__,
"line",
CARP_LINE) ) # Note the difference, that carp msg
- : "didn't found a warning"; # aren't finished by '.'
+ : "didn't find a warning"; # aren't finished by '.'
}
sub _exp_carp_msg {
--- a/t/warnings_are.t
+++ b/t/warnings_are.t
@@ -81,12 +81,12 @@ sub test_warnings_are {
sub _found_warn_msg {
@_ ? map({"found warning: $_ at ". __FILE__ . " line " . WARN_LINE . "." } @_)
- : "didn't found a warning";
+ : "didn't find a warning";
}
sub _found_carp_msg {
@_ ? map({"found carped warning: $_ at ". __FILE__ . " line " . CARP_LINE} @_)
- : "didn't found a warning";
+ : "didn't find a warning";
}
--- a/t/warnings_like.t
+++ b/t/warnings_like.t
@@ -84,12 +84,12 @@ sub test_warnings_like {
sub _found_warn_msg {
@_ ? map({"found warning: $_ at ". __FILE__ . " line " . WARN_LINE . "." } @_)
- : "didn't found a warning";
+ : "didn't find a warning";
}
sub _found_carp_msg {
@_ ? map({"found carped warning: $_ at ". __FILE__ . " line " . CARP_LINE} @_)
- : "didn't found a warning";
+ : "didn't find a warning";
}
