local-lib5/man/man3/Carp::Assert::More.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 "More 3"
 127 .TH More 3 "2005-10-14" "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 Carp::Assert::More \- convenience wrappers around Carp::Assert
 134 .SH "VERSION"
 135 .IX Header "VERSION"
 136 Version 1.12
 137 .SH "SYNOPSIS"
 138 .IX Header "SYNOPSIS"
 139 .Vb 1
 140 \&    use Carp::Assert::More;
 141 \&
 142 \&    my $obj = My::Object;
 143 \&    assert_isa( $obj, \*(AqMy::Object\*(Aq, \*(AqGot back a correct object\*(Aq );
 144 .Ve
 145 .SH "DESCRIPTION"
 146 .IX Header "DESCRIPTION"
 147 Carp::Assert::More is a set of wrappers around the Carp::Assert functions
 148 to make the habit of writing assertions even easier.
 149 .PP
 150 Everything in here is effectively syntactic sugar.  There's no technical
 151 reason to use
 152 .PP
 153 .Vb 1
 154 \&    assert_isa( $foo, \*(AqHTML::Lint\*(Aq );
 155 .Ve
 156 .PP
 157 instead of
 158 .PP
 159 .Vb 2
 160 \&    assert( defined $foo );
 161 \&    assert( ref($foo) eq \*(AqHTML::Lint\*(Aq );
 162 .Ve
 163 .PP
 164 other than readability and simplicity of the code.
 165 .PP
 166 My intent here is to make common assertions easy so that we as programmers
 167 have no excuse to not use them.
 168 .SH "CAVEATS"
 169 .IX Header "CAVEATS"
 170 I haven't specifically done anything to make Carp::Assert::More be
 171 backwards compatible with anything besides Perl 5.6.1, much less back
 172 to 5.004.  Perhaps someone with better testing resources in that area
 173 can help me out here.
 174 .SH "SIMPLE ASSERTIONS"
 175 .IX Header "SIMPLE ASSERTIONS"
 176 .ie n .SS "assert_is( $string, $match [,$name] )"
 177 .el .SS "assert_is( \f(CW$string\fP, \f(CW$match\fP [,$name] )"
 178 .IX Subsection "assert_is( $string, $match [,$name] )"
 179 Asserts that \fI\f(CI$string\fI\fR matches \fI\f(CI$match\fI\fR.
 180 .ie n .SS "assert_isnt( $string, $unmatch [,$name] )"
 181 .el .SS "assert_isnt( \f(CW$string\fP, \f(CW$unmatch\fP [,$name] )"
 182 .IX Subsection "assert_isnt( $string, $unmatch [,$name] )"
 183 Asserts that \fI\f(CI$string\fI\fR does \s-1NOT\s0 match \fI\f(CI$unmatch\fI\fR.
 184 .ie n .SS "assert_like( $string, qr/regex/ [,$name] )"
 185 .el .SS "assert_like( \f(CW$string\fP, qr/regex/ [,$name] )"
 186 .IX Subsection "assert_like( $string, qr/regex/ [,$name] )"
 187 Asserts that \fI\f(CI$string\fI\fR matches \fIqr/regex/\fR.
 188 .ie n .SS "assert_defined( $this [, $name] )"
 189 .el .SS "assert_defined( \f(CW$this\fP [, \f(CW$name\fP] )"
 190 .IX Subsection "assert_defined( $this [, $name] )"
 191 Asserts that \fI\f(CI$this\fI\fR is defined.
 192 .ie n .SS "assert_nonblank( $this [, $name] )"
 193 .el .SS "assert_nonblank( \f(CW$this\fP [, \f(CW$name\fP] )"
 194 .IX Subsection "assert_nonblank( $this [, $name] )"
 195 Asserts that \fI\f(CI$this\fI\fR is not blank and not a reference.
 196 .SH "NUMERIC ASSERTIONS"
 197 .IX Header "NUMERIC ASSERTIONS"
 198 .ie n .SS "assert_integer( $this [, $name ] )"
 199 .el .SS "assert_integer( \f(CW$this\fP [, \f(CW$name\fP ] )"
 200 .IX Subsection "assert_integer( $this [, $name ] )"
 201 Asserts that \fI\f(CI$this\fI\fR is an integer, which may be zero or negative.
 202 .PP
 203 .Vb 3
 204 \&    assert_integer( 0 );    # pass
 205 \&    assert_integer( \-14 );  # pass
 206 \&    assert_integer( \*(Aq14.\*(Aq );  # FAIL
 207 .Ve
 208 .ie n .SS "assert_nonzero( $this [, $name ] )"
 209 .el .SS "assert_nonzero( \f(CW$this\fP [, \f(CW$name\fP ] )"
 210 .IX Subsection "assert_nonzero( $this [, $name ] )"
 211 Asserts that the numeric value of \fI\f(CI$this\fI\fR is not zero.
 212 .PP
 213 .Vb 3
 214 \&    assert_nonzero( 0 );    # FAIL
 215 \&    assert_nonzero( \-14 );  # pass
 216 \&    assert_nonzero( \*(Aq14.\*(Aq );  # pass
 217 .Ve
 218 .PP
 219 Asserts that the numeric value of \fI\f(CI$this\fI\fR is not zero.
 220 .ie n .SS "assert_positive( $this [, $name ] )"
 221 .el .SS "assert_positive( \f(CW$this\fP [, \f(CW$name\fP ] )"
 222 .IX Subsection "assert_positive( $this [, $name ] )"
 223 Asserts that the numeric value of \fI\f(CI$this\fI\fR is greater than zero.
 224 .PP
 225 .Vb 3
 226 \&    assert_positive( 0 );    # FAIL
 227 \&    assert_positive( \-14 );  # FAIL
 228 \&    assert_positive( \*(Aq14.\*(Aq );  # pass
 229 .Ve
 230 .ie n .SS "assert_nonnegative( $this [, $name ] )"
 231 .el .SS "assert_nonnegative( \f(CW$this\fP [, \f(CW$name\fP ] )"
 232 .IX Subsection "assert_nonnegative( $this [, $name ] )"
 233 Asserts that the numeric value of \fI\f(CI$this\fI\fR is greater than or equal
 234 to zero.  Since non-numeric strings evaluate to zero, this means that
 235 any non-numeric string will pass.
 236 .PP
 237 .Vb 4
 238 \&    assert_nonnegative( 0 );    # pass
 239 \&    assert_nonnegative( \-14 );  # FAIL
 240 \&    assert_nonnegative( \*(Aq14.\*(Aq );  # pass
 241 \&    assert_nonnegative( \*(Aqdog\*(Aq );  # pass
 242 .Ve
 243 .ie n .SS "assert_negative( $this [, $name ] )"
 244 .el .SS "assert_negative( \f(CW$this\fP [, \f(CW$name\fP ] )"
 245 .IX Subsection "assert_negative( $this [, $name ] )"
 246 Asserts that the numeric value of \fI\f(CI$this\fI\fR is less than zero.
 247 .PP
 248 .Vb 3
 249 \&    assert_negative( 0 );       # FAIL
 250 \&    assert_negative( \-14 );     # pass
 251 \&    assert_negative( \*(Aq14.\*(Aq );   # FAIL
 252 .Ve
 253 .ie n .SS "assert_nonzero_integer( $this [, $name ] )"
 254 .el .SS "assert_nonzero_integer( \f(CW$this\fP [, \f(CW$name\fP ] )"
 255 .IX Subsection "assert_nonzero_integer( $this [, $name ] )"
 256 Asserts that the numeric value of \fI\f(CI$this\fI\fR is not zero, and that \fI\f(CI$this\fI\fR
 257 is an integer.
 258 .PP
 259 .Vb 3
 260 \&    assert_nonzero_integer( 0 );    # FAIL
 261 \&    assert_nonzero_integer( \-14 );  # pass
 262 \&    assert_nonzero_integer( \*(Aq14.\*(Aq );  # FAIL
 263 .Ve
 264 .ie n .SS "assert_positive_integer( $this [, $name ] )"
 265 .el .SS "assert_positive_integer( \f(CW$this\fP [, \f(CW$name\fP ] )"
 266 .IX Subsection "assert_positive_integer( $this [, $name ] )"
 267 Asserts that the numeric value of \fI\f(CI$this\fI\fR is greater than zero, and
 268 that \fI\f(CI$this\fI\fR is an integer.
 269 .PP
 270 .Vb 4
 271 \&    assert_positive_integer( 0 );     # FAIL
 272 \&    assert_positive_integer( \-14 );   # FAIL
 273 \&    assert_positive_integer( \*(Aq14.\*(Aq ); # FAIL
 274 \&    assert_positive_integer( \*(Aq14\*(Aq );  # pass
 275 .Ve
 276 .ie n .SS "assert_nonnegative_integer( $this [, $name ] )"
 277 .el .SS "assert_nonnegative_integer( \f(CW$this\fP [, \f(CW$name\fP ] )"
 278 .IX Subsection "assert_nonnegative_integer( $this [, $name ] )"
 279 Asserts that the numeric value of \fI\f(CI$this\fI\fR is not less than zero, and
 280 that \fI\f(CI$this\fI\fR is an integer.
 281 .PP
 282 .Vb 3
 283 \&    assert_nonnegative_integer( 0 );    # pass
 284 \&    assert_nonnegative_integer( \-14 );  # pass
 285 \&    assert_nonnegative_integer( \*(Aq14.\*(Aq );  # FAIL
 286 .Ve
 287 .ie n .SS "assert_negative_integer( $this [, $name ] )"
 288 .el .SS "assert_negative_integer( \f(CW$this\fP [, \f(CW$name\fP ] )"
 289 .IX Subsection "assert_negative_integer( $this [, $name ] )"
 290 Asserts that the numeric value of \fI\f(CI$this\fI\fR is less than zero, and that
 291 \&\fI\f(CI$this\fI\fR is an integer.
 292 .PP
 293 .Vb 3
 294 \&    assert_negative_integer( 0 );    # FAIL
 295 \&    assert_negative_integer( \-14 );  # pass
 296 \&    assert_negative_integer( \*(Aq14.\*(Aq );  # FAIL
 297 .Ve
 298 .SH "REFERENCE ASSERTIONS"
 299 .IX Header "REFERENCE ASSERTIONS"
 300 .ie n .SS "assert_isa( $this, $type [, $name ] )"
 301 .el .SS "assert_isa( \f(CW$this\fP, \f(CW$type\fP [, \f(CW$name\fP ] )"
 302 .IX Subsection "assert_isa( $this, $type [, $name ] )"
 303 Asserts that \fI\f(CI$this\fI\fR is an object of type \fI\f(CI$type\fI\fR.
 304 .ie n .SS "assert_nonempty( $this [, $name ] )"
 305 .el .SS "assert_nonempty( \f(CW$this\fP [, \f(CW$name\fP ] )"
 306 .IX Subsection "assert_nonempty( $this [, $name ] )"
 307 \&\fI\f(CI$this\fI\fR must be a ref to either a hash or an array.  Asserts that that
 308 collection contains at least 1 element.  Will assert (with its own message,
 309 not \fI\f(CI$name\fI\fR) unless given a hash or array ref.   It is \s-1OK\s0 if \fI\f(CI$this\fI\fR has
 310 been blessed into objecthood, but the semantics of checking an object to see
 311 if it has keys (for a hashref) or returns >0 in scalar context (for an array
 312 ref) may not be what you want.
 313 .PP
 314 .Vb 7
 315 \&    assert_nonempty( 0 );       # FAIL
 316 \&    assert_nonempty( \*(Aqfoo\*(Aq );   # FAIL
 317 \&    assert_nonempty( undef );   # FAIL
 318 \&    assert_nonempty( {} );      # FAIL
 319 \&    assert_nonempty( [] );      # FAIL
 320 \&    assert_nonempty( {foo=>1} );# pass
 321 \&    assert_nonempty( [1,2,3] ); # pass
 322 .Ve
 323 .ie n .SS "assert_nonref( $this [, $name ] )"
 324 .el .SS "assert_nonref( \f(CW$this\fP [, \f(CW$name\fP ] )"
 325 .IX Subsection "assert_nonref( $this [, $name ] )"
 326 Asserts that \fI\f(CI$this\fI\fR is not undef and not a reference.
 327 .ie n .SS "assert_hashref( $ref [,$name] )"
 328 .el .SS "assert_hashref( \f(CW$ref\fP [,$name] )"
 329 .IX Subsection "assert_hashref( $ref [,$name] )"
 330 Asserts that \fI\f(CI$ref\fI\fR is defined, and is a reference to a (possibly empty) hash.
 331 .PP
 332 \&\fB\s-1NB:\s0\fR This method returns \fIfalse\fR for objects, even those whose underlying
 333 data is a hashref. This is as it should be, under the assumptions that:
 334 .IP "(a)" 4
 335 .IX Item "(a)"
 336 you shouldn't rely on the underlying data structure of a particular class, and
 337 .IP "(b)" 4
 338 .IX Item "(b)"
 339 you should use \f(CW\*(C`assert_isa\*(C'\fR instead.
 340 .ie n .SS "assert_listref( $ref [,$name] )"
 341 .el .SS "assert_listref( \f(CW$ref\fP [,$name] )"
 342 .IX Subsection "assert_listref( $ref [,$name] )"
 343 Asserts that \fI\f(CI$ref\fI\fR is defined, and is a reference to a (possibly empty) list.
 344 .PP
 345 \&\fB\s-1NB:\s0\fR The same caveat about objects whose underlying structure is a
 346 hash (see \f(CW\*(C`assert_hashref\*(C'\fR) applies here; this method returns false
 347 even for objects whose underlying structure is an array.
 348 .SH "SET AND HASH MEMBERSHIP"
 349 .IX Header "SET AND HASH MEMBERSHIP"
 350 .ie n .SS "assert_in( $string, \e@inlist [,$name] );"
 351 .el .SS "assert_in( \f(CW$string\fP, \e@inlist [,$name] );"
 352 .IX Subsection "assert_in( $string, @inlist [,$name] );"
 353 Asserts that \fI\f(CI$string\fI\fR is defined and matches one of the elements
 354 of \fI\e@inlist\fR.
 355 .PP
 356 \&\fI\e@inlist\fR must be an array reference of defined strings.
 357 .ie n .SS "assert_exists( \e%hash, $key [,$name] )"
 358 .el .SS "assert_exists( \e%hash, \f(CW$key\fP [,$name] )"
 359 .IX Subsection "assert_exists( %hash, $key [,$name] )"
 360 .SS "assert_exists( \e%hash, \e@keylist [,$name] )"
 361 .IX Subsection "assert_exists( %hash, @keylist [,$name] )"
 362 Asserts that \fI\f(CI%hash\fI\fR is indeed a hash, and that \fI\f(CI$key\fI\fR exists in
 363 \&\fI\f(CI%hash\fI\fR, or that all of the keys in \fI\f(CI@keylist\fI\fR exist in \fI\f(CI%hash\fI\fR.
 364 .PP
 365 .Vb 1
 366 \&    assert_exists( \e%custinfo, \*(Aqname\*(Aq, \*(AqCustomer has a name field\*(Aq );
 367 \&
 368 \&    assert_exists( \e%custinfo, [qw( name addr phone )],
 369 \&                            \*(AqCustomer has name, address and phone\*(Aq );
 370 .Ve
 371 .ie n .SS "assert_lacks( \e%hash, $key [,$name] )"
 372 .el .SS "assert_lacks( \e%hash, \f(CW$key\fP [,$name] )"
 373 .IX Subsection "assert_lacks( %hash, $key [,$name] )"
 374 .SS "assert_lacks( \e%hash, \e@keylist [,$name] )"
 375 .IX Subsection "assert_lacks( %hash, @keylist [,$name] )"
 376 Asserts that \fI\f(CI%hash\fI\fR is indeed a hash, and that \fI\f(CI$key\fI\fR does \s-1NOT\s0 exist
 377 in \fI\f(CI%hash\fI\fR, or that none of the keys in \fI\f(CI@keylist\fI\fR exist in \fI\f(CI%hash\fI\fR.
 378 .PP
 379 .Vb 1
 380 \&    assert_lacks( \e%users, \*(Aqroot\*(Aq, \*(AqRoot is not in the user table\*(Aq );
 381 \&
 382 \&    assert_lacks( \e%users, [qw( root admin nobody )], \*(AqNo bad usernames found\*(Aq );
 383 .Ve
 384 .SH "UTILITY ASSERTIONS"
 385 .IX Header "UTILITY ASSERTIONS"
 386 .SS "assert_fail( [$name] )"
 387 .IX Subsection "assert_fail( [$name] )"
 388 Assertion that always fails.  \f(CW\*(C`assert_fail($msg)\*(C'\fR is exactly the same
 389 as calling \f(CW\*(C`assert(0,$msg)\*(C'\fR, but it eliminates that case where you
 390 accidentally use \f(CW\*(C`assert($msg)\*(C'\fR, which of course never fires.
 391 .SH "COPYRIGHT"
 392 .IX Header "COPYRIGHT"
 393 Copyright (c) 2005 Andy Lester. All rights reserved. This program is
 394 free software; you can redistribute it and/or modify it under the same
 395 terms as Perl itself.
 396 .SH "ACKNOWLEDGEMENTS"
 397 .IX Header "ACKNOWLEDGEMENTS"
 398 Thanks to
 399 Bob Diss,
 400 Pete Krawczyk,
 401 David Storrs,
 402 Dan Friedman,
 403 and Allard Hoeve
 404 for code and fixes.