local-lib5/man/man3/TAP::Parser::Result.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "TAP::Parser::Result 3"
 132 .TH TAP::Parser::Result 3 "2009-05-05" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 TAP::Parser::Result \- Base class for TAP::Parser output objects
 135 .SH "VERSION"
 136 .IX Header "VERSION"
 137 Version 3.17
 138 .SH "SYNOPSIS"
 139 .IX Header "SYNOPSIS"
 140 .Vb 2
 141 \&  # abstract class \- not meany to be used directly
 142 \&  # see TAP::Parser::ResultFactory for preferred usage
 143 .Ve
 144 .PP
 145 .Vb 4
 146 \&  # directly:
 147 \&  use TAP::Parser::Result;
 148 \&  my $token  = {...};
 149 \&  my $result = TAP::Parser::Result\->new( $token );
 150 .Ve
 151 .Sh "\s-1DESCRIPTION\s0"
 152 .IX Subsection "DESCRIPTION"
 153 This is a simple base class used by TAP::Parser to store objects that
 154 represent the current bit of test output data from \s-1TAP\s0 (usually a single
 155 line).  Unless you're subclassing, you probably won't need to use this module
 156 directly.
 157 .Sh "\s-1METHODS\s0"
 158 .IX Subsection "METHODS"
 159 \fI\f(CI\*(C`new\*(C'\fI\fR
 160 .IX Subsection "new"
 161 .PP
 162 .Vb 1
 163 \&  # see TAP::Parser::ResultFactory for preferred usage
 164 .Ve
 165 .PP
 166 .Vb 2
 167 \&  # to use directly:
 168 \&  my $result = TAP::Parser::Result\->new($token);
 169 .Ve
 170 .PP
 171 Returns an instance the appropriate class for the test token passed in.
 172 .Sh "Boolean methods"
 173 .IX Subsection "Boolean methods"
 174 The following methods all return a boolean value and are to be overridden in
 175 the appropriate subclass.
 176 .ie n .IP "* ""is_plan""" 4
 177 .el .IP "* \f(CWis_plan\fR" 4
 178 .IX Item "is_plan"
 179 Indicates whether or not this is the test plan line.
 180 .Sp
 181 .Vb 1
 182 \& 1..3
 183 .Ve
 184 .ie n .IP "* ""is_pragma""" 4
 185 .el .IP "* \f(CWis_pragma\fR" 4
 186 .IX Item "is_pragma"
 187 Indicates whether or not this is a pragma line.
 188 .Sp
 189 .Vb 1
 190 \& pragma +strict
 191 .Ve
 192 .ie n .IP "* ""is_test""" 4
 193 .el .IP "* \f(CWis_test\fR" 4
 194 .IX Item "is_test"
 195 Indicates whether or not this is a test line.
 196 .Sp
 197 .Vb 1
 198 \& ok 1 Is OK!
 199 .Ve
 200 .ie n .IP "* ""is_comment""" 4
 201 .el .IP "* \f(CWis_comment\fR" 4
 202 .IX Item "is_comment"
 203 Indicates whether or not this is a comment.
 204 .Sp
 205 .Vb 1
 206 \& # this is a comment
 207 .Ve
 208 .ie n .IP "* ""is_bailout""" 4
 209 .el .IP "* \f(CWis_bailout\fR" 4
 210 .IX Item "is_bailout"
 211 Indicates whether or not this is bailout line.
 212 .Sp
 213 .Vb 1
 214 \& Bail out! We're out of dilithium crystals.
 215 .Ve
 216 .ie n .IP "* ""is_version""" 4
 217 .el .IP "* \f(CWis_version\fR" 4
 218 .IX Item "is_version"
 219 Indicates whether or not this is a \s-1TAP\s0 version line.
 220 .Sp
 221 .Vb 1
 222 \& TAP version 4
 223 .Ve
 224 .ie n .IP "* ""is_unknown""" 4
 225 .el .IP "* \f(CWis_unknown\fR" 4
 226 .IX Item "is_unknown"
 227 Indicates whether or not the current line could be parsed.
 228 .Sp
 229 .Vb 1
 230 \& ... this line is junk ...
 231 .Ve
 232 .ie n .IP "* ""is_yaml""" 4
 233 .el .IP "* \f(CWis_yaml\fR" 4
 234 .IX Item "is_yaml"
 235 Indicates whether or not this is a \s-1YAML\s0 chunk.
 236 .PP
 237 \fI\f(CI\*(C`raw\*(C'\fI\fR
 238 .IX Subsection "raw"
 239 .PP
 240 .Vb 1
 241 \&  print $result\->raw;
 242 .Ve
 243 .PP
 244 Returns the original line of text which was parsed.
 245 .PP
 246 \fI\f(CI\*(C`type\*(C'\fI\fR
 247 .IX Subsection "type"
 248 .PP
 249 .Vb 1
 250 \&  my $type = $result\->type;
 251 .Ve
 252 .PP
 253 Returns the \*(L"type\*(R" of a token, such as \f(CW\*(C`comment\*(C'\fR or \f(CW\*(C`test\*(C'\fR.
 254 .PP
 255 \fI\f(CI\*(C`as_string\*(C'\fI\fR
 256 .IX Subsection "as_string"
 257 .PP
 258 .Vb 1
 259 \&  print $result\->as_string;
 260 .Ve
 261 .PP
 262 Prints a string representation of the token.  This might not be the exact
 263 output, however.  Tests will have test numbers added if not present, \s-1TODO\s0 and
 264 \&\s-1SKIP\s0 directives will be capitalized and, in general, things will be cleaned
 265 up.  If you need the original text for the token, see the \f(CW\*(C`raw\*(C'\fR method.
 266 .PP
 267 \fI\f(CI\*(C`is_ok\*(C'\fI\fR
 268 .IX Subsection "is_ok"
 269 .PP
 270 .Vb 1
 271 \&  if ( $result\->is_ok ) { ... }
 272 .Ve
 273 .PP
 274 Reports whether or not a given result has passed.  Anything which is \fBnot\fR a
 275 test result returns true.  This is merely provided as a convenient shortcut.
 276 .PP
 277 \fI\f(CI\*(C`passed\*(C'\fI\fR
 278 .IX Subsection "passed"
 279 .PP
 280 Deprecated.  Please use \f(CW\*(C`is_ok\*(C'\fR instead.
 281 .PP
 282 \fI\f(CI\*(C`has_directive\*(C'\fI\fR
 283 .IX Subsection "has_directive"
 284 .PP
 285 .Vb 3
 286 \&  if ( $result\->has_directive ) {
 287 \&     ...
 288 \&  }
 289 .Ve
 290 .PP
 291 Indicates whether or not the given result has a \s-1TODO\s0 or \s-1SKIP\s0 directive.
 292 .PP
 293 \fI\f(CI\*(C`has_todo\*(C'\fI\fR
 294 .IX Subsection "has_todo"
 295 .PP
 296 .Vb 3
 297 \& if ( $result\->has_todo ) {
 298 \&     ...
 299 \& }
 300 .Ve
 301 .PP
 302 Indicates whether or not the given result has a \s-1TODO\s0 directive.
 303 .PP
 304 \fI\f(CI\*(C`has_skip\*(C'\fI\fR
 305 .IX Subsection "has_skip"
 306 .PP
 307 .Vb 3
 308 \& if ( $result\->has_skip ) {
 309 \&     ...
 310 \& }
 311 .Ve
 312 .PP
 313 Indicates whether or not the given result has a \s-1SKIP\s0 directive.
 314 .PP
 315 \fI\f(CI\*(C`set_directive\*(C'\fI\fR
 316 .IX Subsection "set_directive"
 317 .PP
 318 Set the directive associated with this token. Used internally to fake
 319 \&\s-1TODO\s0 tests.
 320 .SH "SUBCLASSING"
 321 .IX Header "SUBCLASSING"
 322 Please see \*(L"\s-1SUBCLASSING\s0\*(R" in TAP::Parser for a subclassing overview.
 323 .PP
 324 Remember: if you want your subclass to be automatically used by the parser,
 325 you'll have to register it with \*(L"register_type\*(R" in TAP::Parser::ResultFactory.
 326 .PP
 327 If you're creating a completely new result \fItype\fR, you'll probably need to
 328 subclass TAP::Parser::Grammar too, or else it'll never get used.
 329 .Sh "Example"
 330 .IX Subsection "Example"
 331 .Vb 1
 332 \&  package MyResult;
 333 .Ve
 334 .PP
 335 .Vb 2
 336 \&  use strict;
 337 \&  use vars '@ISA';
 338 .Ve
 339 .PP
 340 .Vb 1
 341 \&  @ISA = 'TAP::Parser::Result';
 342 .Ve
 343 .PP
 344 .Vb 2
 345 \&  # register with the factory:
 346 \&  TAP::Parser::ResultFactory\->register_type( 'my_type' => __PACKAGE__ );
 347 .Ve
 348 .PP
 349 .Vb 1
 350 \&  sub as_string { 'My results all look the same' }
 351 .Ve
 352 .SH "SEE ALSO"
 353 .IX Header "SEE ALSO"
 354 TAP::Object,
 355 TAP::Parser,
 356 TAP::Parser::ResultFactory,
 357 TAP::Parser::Result::Bailout,
 358 TAP::Parser::Result::Comment,
 359 TAP::Parser::Result::Plan,
 360 TAP::Parser::Result::Pragma,
 361 TAP::Parser::Result::Test,
 362 TAP::Parser::Result::Unknown,
 363 TAP::Parser::Result::Version,
 364 TAP::Parser::Result::YAML,