local-lib5/man/man3/TAP::Parser::Grammar.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::Grammar 3"
 132 .TH TAP::Parser::Grammar 3 "2009-05-05" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 TAP::Parser::Grammar \- A grammar for the Test Anything Protocol.
 135 .SH "VERSION"
 136 .IX Header "VERSION"
 137 Version 3.17
 138 .SH "SYNOPSIS"
 139 .IX Header "SYNOPSIS"
 140 .Vb 6
 141 \&  use TAP::Parser::Grammar;
 142 \&  my $grammar = $self\->make_grammar({
 143 \&    stream  => $tap_parser_stream,
 144 \&    parser  => $tap_parser,
 145 \&    version => 12,
 146 \&  });
 147 .Ve
 148 .PP
 149 .Vb 1
 150 \&  my $result = $grammar\->tokenize;
 151 .Ve
 152 .SH "DESCRIPTION"
 153 .IX Header "DESCRIPTION"
 154 \&\f(CW\*(C`TAP::Parser::Grammar\*(C'\fR tokenizes lines from a \s-1TAP\s0 stream and constructs
 155 TAP::Parser::Result subclasses to represent the tokens.
 156 .PP
 157 Do not attempt to use this class directly.  It won't make sense.  It's mainly
 158 here to ensure that we will be able to have pluggable grammars when \s-1TAP\s0 is
 159 expanded at some future date (plus, this stuff was really cluttering the
 160 parser).
 161 .SH "METHODS"
 162 .IX Header "METHODS"
 163 .Sh "Class Methods"
 164 .IX Subsection "Class Methods"
 165 \fI\f(CI\*(C`new\*(C'\fI\fR
 166 .IX Subsection "new"
 167 .PP
 168 .Vb 5
 169 \&  my $grammar = TAP::Parser::Grammar\->new({
 170 \&      stream  => $stream,
 171 \&      parser  => $parser,
 172 \&      version => $version,
 173 \&  });
 174 .Ve
 175 .PP
 176 Returns TAP::Parser grammar object that will parse the specified stream.
 177 Both \f(CW\*(C`stream\*(C'\fR and \f(CW\*(C`parser\*(C'\fR are required arguments.  If \f(CW\*(C`version\*(C'\fR is not set
 178 it defaults to \f(CW12\fR (see \*(L"set_version\*(R" for more details).
 179 .Sh "Instance Methods"
 180 .IX Subsection "Instance Methods"
 181 \fI\f(CI\*(C`set_version\*(C'\fI\fR
 182 .IX Subsection "set_version"
 183 .PP
 184 .Vb 1
 185 \&  $grammar\->set_version(13);
 186 .Ve
 187 .PP
 188 Tell the grammar which \s-1TAP\s0 syntax version to support. The lowest
 189 supported version is 12. Although '\s-1TAP\s0 version' isn't valid version 12
 190 syntax it is accepted so that higher version numbers may be parsed.
 191 .PP
 192 \fI\f(CI\*(C`tokenize\*(C'\fI\fR
 193 .IX Subsection "tokenize"
 194 .PP
 195 .Vb 1
 196 \&  my $token = $grammar\->tokenize;
 197 .Ve
 198 .PP
 199 This method will return a TAP::Parser::Result object representing the
 200 current line of \s-1TAP\s0.
 201 .PP
 202 \fI\f(CI\*(C`token_types\*(C'\fI\fR
 203 .IX Subsection "token_types"
 204 .PP
 205 .Vb 1
 206 \&  my @types = $grammar\->token_types;
 207 .Ve
 208 .PP
 209 Returns the different types of tokens which this grammar can parse.
 210 .PP
 211 \fI\f(CI\*(C`syntax_for\*(C'\fI\fR
 212 .IX Subsection "syntax_for"
 213 .PP
 214 .Vb 1
 215 \&  my $syntax = $grammar\->syntax_for($token_type);
 216 .Ve
 217 .PP
 218 Returns a pre-compiled regular expression which will match a chunk of \s-1TAP\s0
 219 corresponding to the token type.  For example (not that you should really pay
 220 attention to this, \f(CW\*(C`$grammar\->syntax_for('comment')\*(C'\fR will return
 221 \&\f(CW\*(C`qr/^#(.*)/\*(C'\fR.
 222 .PP
 223 \fI\f(CI\*(C`handler_for\*(C'\fI\fR
 224 .IX Subsection "handler_for"
 225 .PP
 226 .Vb 1
 227 \&  my $handler = $grammar\->handler_for($token_type);
 228 .Ve
 229 .PP
 230 Returns a code reference which, when passed an appropriate line of \s-1TAP\s0,
 231 returns the lexed token corresponding to that line.  As a result, the basic
 232 \&\s-1TAP\s0 parsing loop looks similar to the following:
 233 .PP
 234 .Vb 13
 235 \& my @tokens;
 236 \& my $grammar = TAP::Grammar\->new;
 237 \& LINE: while ( defined( my $line = $parser\->_next_chunk_of_tap ) ) {
 238 \&     foreach my $type ( $grammar\->token_types ) {
 239 \&         my $syntax  = $grammar\->syntax_for($type);
 240 \&         if ( $line =~ $syntax ) {
 241 \&             my $handler = $grammar\->handler_for($type);
 242 \&             push @tokens => $grammar\->$handler($line);
 243 \&             next LINE;
 244 \&         }
 245 \&     }
 246 \&     push @tokens => $grammar\->_make_unknown_token($line);
 247 \& }
 248 .Ve
 249 .SH "TAP GRAMMAR"
 250 .IX Header "TAP GRAMMAR"
 251 \&\fB\s-1NOTE:\s0\fR  This grammar is slightly out of date.  There's still some discussion
 252 about it and a new one will be provided when we have things better defined.
 253 .PP
 254 The TAP::Parser does not use a formal grammar because \s-1TAP\s0 is essentially a
 255 stream-based protocol.  In fact, it's quite legal to have an infinite stream.
 256 For the same reason that we don't apply regexes to streams, we're not using a
 257 formal grammar here.  Instead, we parse the \s-1TAP\s0 in lines.
 258 .PP
 259 For purposes for forward compatability, any result which does not match the
 260 following grammar is currently referred to as
 261 TAP::Parser::Result::Unknown.  It is \fInot\fR a parse error.
 262 .PP
 263 A formal grammar would look similar to the following:
 264 .PP
 265 .Vb 4
 266 \& (*
 267 \&     For the time being, I'm cheating on the EBNF by allowing
 268 \&     certain terms to be defined by POSIX character classes by
 269 \&     using the following syntax:
 270 .Ve
 271 .PP
 272 .Vb 1
 273 \&       digit ::= [:digit:]
 274 .Ve
 275 .PP
 276 .Vb 4
 277 \&     As far as I am aware, that's not valid EBNF.  Sue me.  I
 278 \&     didn't know how to write "char" otherwise (Unicode issues).
 279 \&     Suggestions welcome.
 280 \& *)
 281 .Ve
 282 .PP
 283 .Vb 3
 284 \& tap            ::= version? { comment | unknown } leading_plan lines
 285 \&                    |
 286 \&                    lines trailing_plan {comment}
 287 .Ve
 288 .PP
 289 .Vb 1
 290 \& version        ::= 'TAP version ' positiveInteger {positiveInteger} "\en"
 291 .Ve
 292 .PP
 293 .Vb 1
 294 \& leading_plan   ::= plan skip_directive? "\en"
 295 .Ve
 296 .PP
 297 .Vb 1
 298 \& trailing_plan  ::= plan "\en"
 299 .Ve
 300 .PP
 301 .Vb 1
 302 \& plan           ::= '1..' nonNegativeInteger
 303 .Ve
 304 .PP
 305 .Vb 1
 306 \& lines          ::= line {line}
 307 .Ve
 308 .PP
 309 .Vb 1
 310 \& line           ::= (comment | test | unknown | bailout ) "\en"
 311 .Ve
 312 .PP
 313 .Vb 1
 314 \& test           ::= status positiveInteger? description? directive?
 315 .Ve
 316 .PP
 317 .Vb 1
 318 \& status         ::= 'not '? 'ok '
 319 .Ve
 320 .PP
 321 .Vb 1
 322 \& description    ::= (character \- (digit | '#')) {character \- '#'}
 323 .Ve
 324 .PP
 325 .Vb 1
 326 \& directive      ::= todo_directive | skip_directive
 327 .Ve
 328 .PP
 329 .Vb 1
 330 \& todo_directive ::= hash_mark 'TODO' ' ' {character}
 331 .Ve
 332 .PP
 333 .Vb 1
 334 \& skip_directive ::= hash_mark 'SKIP' ' ' {character}
 335 .Ve
 336 .PP
 337 .Vb 1
 338 \& comment        ::= hash_mark {character}
 339 .Ve
 340 .PP
 341 .Vb 1
 342 \& hash_mark      ::= '#' {' '}
 343 .Ve
 344 .PP
 345 .Vb 1
 346 \& bailout        ::= 'Bail out!' {character}
 347 .Ve
 348 .PP
 349 .Vb 1
 350 \& unknown        ::= { (character \- "\en") }
 351 .Ve
 352 .PP
 353 .Vb 1
 354 \& (* POSIX character classes and other terminals *)
 355 .Ve
 356 .PP
 357 .Vb 4
 358 \& digit              ::= [:digit:]
 359 \& character          ::= ([:print:] \- "\en")
 360 \& positiveInteger    ::= ( digit \- '0' ) {digit}
 361 \& nonNegativeInteger ::= digit {digit}
 362 .Ve
 363 .SH "SUBCLASSING"
 364 .IX Header "SUBCLASSING"
 365 Please see \*(L"\s-1SUBCLASSING\s0\*(R" in TAP::Parser for a subclassing overview.
 366 .PP
 367 If you \fIreally\fR want to subclass TAP::Parser's grammar the best thing to
 368 do is read through the code.  There's no easy way of summarizing it here.
 369 .SH "SEE ALSO"
 370 .IX Header "SEE ALSO"
 371 TAP::Object,
 372 TAP::Parser,
 373 TAP::Parser::Iterator,
 374 TAP::Parser::Result,