local-lib5/man/man3/Test::LongString.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "Test::LongString 3"
 127 .TH Test::LongString 3 "2006-11-08" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 Test::LongString \- tests strings for equality, with more helpful failures
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 3
 137 \&    use Test::More tests => 1;
 138 \&    use Test::LongString;
 139 \&    like_string( $html, qr/(perl|cpan)\e.org/ );
 140 \&
 141 \&    #     Failed test (html\-test.t at line 12)
 142 \&    #          got: "<!DOCTYPE HTML PUBLIC "\-//W3C//DTD HTML 4.01 Trans"...
 143 \&    #       length: 58930
 144 \&    #     doesn\*(Aqt match \*(Aq(?\-xism:(perl|cpan)\e.org)\*(Aq
 145 .Ve
 146 .SH "DESCRIPTION"
 147 .IX Header "DESCRIPTION"
 148 This module provides some drop-in replacements for the string
 149 comparison functions of Test::More, but which are more suitable
 150 when you test against long strings.  If you've ever had to search
 151 for text in a multi-line string like an \s-1HTML\s0 document, or find
 152 specific items in binary data, this is the module for you.
 153 .SH "FUNCTIONS"
 154 .IX Header "FUNCTIONS"
 155 .ie n .SS "is_string( $string, $expected [, $label ] )"
 156 .el .SS "is_string( \f(CW$string\fP, \f(CW$expected\fP [, \f(CW$label\fP ] )"
 157 .IX Subsection "is_string( $string, $expected [, $label ] )"
 158 \&\f(CW\*(C`is_string()\*(C'\fR is equivalent to \f(CW\*(C`Test::More::is()\*(C'\fR, but with more
 159 helpful diagnostics in case of failure.
 160 .IP "\(bu" 4
 161 It doesn't print the entire strings in the failure message.
 162 .IP "\(bu" 4
 163 It reports the lengths of the strings that have been compared.
 164 .IP "\(bu" 4
 165 It reports the length of the common prefix of the strings.
 166 .IP "\(bu" 4
 167 In the diagnostics, non-ASCII characters are escaped as \f(CW\*(C`\ex{xx}\*(C'\fR.
 168 .PP
 169 For example:
 170 .PP
 171 .Vb 1
 172 \&    is_string( $soliloquy, $juliet );
 173 \&
 174 \&    #     Failed test (soliloquy.t at line 15)
 175 \&    #          got: "To be, or not to be: that is the question:\ex{0a}Whether"...
 176 \&    #       length: 1490
 177 \&    #     expected: "O Romeo, Romeo,\ex{0a}wherefore art thou Romeo?\ex{0a}Deny thy"...
 178 \&    #       length: 154
 179 \&    #     strings begin to differ at char 1
 180 .Ve
 181 .ie n .SS "is_string_nows( $string, $expected [, $label ] )"
 182 .el .SS "is_string_nows( \f(CW$string\fP, \f(CW$expected\fP [, \f(CW$label\fP ] )"
 183 .IX Subsection "is_string_nows( $string, $expected [, $label ] )"
 184 Like \f(CW\*(C`is_string()\*(C'\fR, but removes whitepace (in the \f(CW\*(C`\es\*(C'\fR sense) from the
 185 arguments before comparing them.
 186 .ie n .SS "like_string( $string, qr/regex/ [, $label ] )"
 187 .el .SS "like_string( \f(CW$string\fP, qr/regex/ [, \f(CW$label\fP ] )"
 188 .IX Subsection "like_string( $string, qr/regex/ [, $label ] )"
 189 .ie n .SS "unlike_string( $string, qr/regex/ [, $label ] )"
 190 .el .SS "unlike_string( \f(CW$string\fP, qr/regex/ [, \f(CW$label\fP ] )"
 191 .IX Subsection "unlike_string( $string, qr/regex/ [, $label ] )"
 192 \&\f(CW\*(C`like_string()\*(C'\fR and \f(CW\*(C`unlike_string()\*(C'\fR are replacements for
 193 \&\f(CW\*(C`Test::More:like()\*(C'\fR and \f(CW\*(C`unlike()\*(C'\fR that only print the beginning
 194 of the received string in the output.  Unfortunately, they can't
 195 print out the position where the regex failed to match.
 196 .PP
 197 .Vb 1
 198 \&    like_string( $soliloquy, qr/Romeo|Juliet|Mercutio|Tybalt/ );
 199 \&
 200 \&    #     Failed test (soliloquy.t at line 15)
 201 \&    #          got: "To be, or not to be: that is the question:\ex{0a}Whether"...
 202 \&    #       length: 1490
 203 \&    #     doesn\*(Aqt match \*(Aq(?\-xism:Romeo|Juliet|Mercutio|Tybalt)\*(Aq
 204 .Ve
 205 .ie n .SS "contains_string( $string, $substring [, $label ] )"
 206 .el .SS "contains_string( \f(CW$string\fP, \f(CW$substring\fP [, \f(CW$label\fP ] )"
 207 .IX Subsection "contains_string( $string, $substring [, $label ] )"
 208 \&\f(CW\*(C`contains_string()\*(C'\fR searches for \fI\f(CI$substring\fI\fR in \fI\f(CI$string\fI\fR.  It's
 209 the same as \f(CW\*(C`like_string()\*(C'\fR, except that it's not a regular
 210 expression search.
 211 .PP
 212 .Vb 1
 213 \&    contains_string( $soliloquy, "Romeo" );
 214 \&
 215 \&    #     Failed test (soliloquy.t at line 10)
 216 \&    #         searched: "To be, or not to be: that is the question:\ex{0a}Whether"...
 217 \&    #   and can\*(Aqt find: "Romeo"
 218 .Ve
 219 .ie n .SS "lacks_string( $string, $substring [, $label ] )"
 220 .el .SS "lacks_string( \f(CW$string\fP, \f(CW$substring\fP [, \f(CW$label\fP ] )"
 221 .IX Subsection "lacks_string( $string, $substring [, $label ] )"
 222 \&\f(CW\*(C`lacks_string()\*(C'\fR makes sure that \fI\f(CI$substring\fI\fR does \s-1NOT\s0 exist in
 223 \&\fI\f(CI$string\fI\fR.  It's the same as \f(CW\*(C`like_string()\*(C'\fR, except that it's not a
 224 regular expression search.
 225 .PP
 226 .Vb 1
 227 \&    lacks_string( $soliloquy, "slings" );
 228 \&
 229 \&    #     Failed test (soliloquy.t at line 10)
 230 \&    #         searched: "To be, or not to be: that is the question:\ex{0a}Whether"...
 231 \&    #        and found: "slings"
 232 \&    #      at position: 147
 233 .Ve
 234 .SH "CONTROLLING OUTPUT"
 235 .IX Header "CONTROLLING OUTPUT"
 236 By default, only the first 50 characters of the compared strings
 237 are shown in the failure message.  This value is in
 238 \&\f(CW$Test::LongString::Max\fR, and can be set at run-time.
 239 .PP
 240 You can also set it by specifying an argument to \f(CW\*(C`use\*(C'\fR:
 241 .PP
 242 .Vb 1
 243 \&    use Test::LongString max => 100;
 244 .Ve
 245 .PP
 246 When the compared strings begin to differ after a large prefix,
 247 Test::LongString will not print them from the beginning, but will start at the
 248 middle, more precisely at \f(CW$Test::LongString::Context\fR characters before the
 249 first difference. By default this value is 10 characters. If you want
 250 Test::LongString to always print the beginning of compared strings no matter
 251 where they differ, undefine \f(CW$Test::LongString::Context\fR.
 252 .SH "AUTHOR"
 253 .IX Header "AUTHOR"
 254 Written by Rafael Garcia-Suarez. Thanks to Mark Fowler (and to Joss Whedon) for
 255 the inspirational Acme::Test::Buffy. Thanks to Andy Lester for lots of patches.
 256 .PP
 257 This program is free software; you may redistribute it and/or modify it under
 258 the same terms as Perl itself.
 259 .SH "SEE ALSO"
 260 .IX Header "SEE ALSO"
 261 Test::Builder, Test::Builder::Tester, Test::More.