--- /dev/null
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sh \" Subsection heading
+.br
+.if t .Sp
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings. \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote. | will give a
+.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
+.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
+.\" expand to `' in nroff, nothing in troff, for use with C<>.
+.tr \(*W-|\(bv\*(Tr
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+. ds -- \(*W-
+. ds PI pi
+. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
+. ds L" ""
+. ds R" ""
+. ds C` ""
+. ds C' ""
+'br\}
+.el\{\
+. ds -- \|\(em\|
+. ds PI \(*p
+. ds L" ``
+. ds R" ''
+'br\}
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.if \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.\"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.hy 0
+.if n .na
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear. Run. Save yourself. No user-serviceable parts.
+. \" fudge factors for nroff and troff
+.if n \{\
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
+.\}
+.if t \{\
+. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
+.\}
+. \" simple accents for nroff and troff
+.if n \{\
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds /
+.\}
+.if t \{\
+. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+. \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+. \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+. \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds : e
+. ds 8 ss
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "TAP::Parser::Grammar 3"
+.TH TAP::Parser::Grammar 3 "2009-05-05" "perl v5.8.7" "User Contributed Perl Documentation"
+.SH "NAME"
+TAP::Parser::Grammar \- A grammar for the Test Anything Protocol.
+.SH "VERSION"
+.IX Header "VERSION"
+Version 3.17
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 6
+\& use TAP::Parser::Grammar;
+\& my $grammar = $self\->make_grammar({
+\& stream => $tap_parser_stream,
+\& parser => $tap_parser,
+\& version => 12,
+\& });
+.Ve
+.PP
+.Vb 1
+\& my $result = $grammar\->tokenize;
+.Ve
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+\&\f(CW\*(C`TAP::Parser::Grammar\*(C'\fR tokenizes lines from a \s-1TAP\s0 stream and constructs
+TAP::Parser::Result subclasses to represent the tokens.
+.PP
+Do not attempt to use this class directly. It won't make sense. It's mainly
+here to ensure that we will be able to have pluggable grammars when \s-1TAP\s0 is
+expanded at some future date (plus, this stuff was really cluttering the
+parser).
+.SH "METHODS"
+.IX Header "METHODS"
+.Sh "Class Methods"
+.IX Subsection "Class Methods"
+\fI\f(CI\*(C`new\*(C'\fI\fR
+.IX Subsection "new"
+.PP
+.Vb 5
+\& my $grammar = TAP::Parser::Grammar\->new({
+\& stream => $stream,
+\& parser => $parser,
+\& version => $version,
+\& });
+.Ve
+.PP
+Returns TAP::Parser grammar object that will parse the specified stream.
+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
+it defaults to \f(CW12\fR (see \*(L"set_version\*(R" for more details).
+.Sh "Instance Methods"
+.IX Subsection "Instance Methods"
+\fI\f(CI\*(C`set_version\*(C'\fI\fR
+.IX Subsection "set_version"
+.PP
+.Vb 1
+\& $grammar\->set_version(13);
+.Ve
+.PP
+Tell the grammar which \s-1TAP\s0 syntax version to support. The lowest
+supported version is 12. Although '\s-1TAP\s0 version' isn't valid version 12
+syntax it is accepted so that higher version numbers may be parsed.
+.PP
+\fI\f(CI\*(C`tokenize\*(C'\fI\fR
+.IX Subsection "tokenize"
+.PP
+.Vb 1
+\& my $token = $grammar\->tokenize;
+.Ve
+.PP
+This method will return a TAP::Parser::Result object representing the
+current line of \s-1TAP\s0.
+.PP
+\fI\f(CI\*(C`token_types\*(C'\fI\fR
+.IX Subsection "token_types"
+.PP
+.Vb 1
+\& my @types = $grammar\->token_types;
+.Ve
+.PP
+Returns the different types of tokens which this grammar can parse.
+.PP
+\fI\f(CI\*(C`syntax_for\*(C'\fI\fR
+.IX Subsection "syntax_for"
+.PP
+.Vb 1
+\& my $syntax = $grammar\->syntax_for($token_type);
+.Ve
+.PP
+Returns a pre-compiled regular expression which will match a chunk of \s-1TAP\s0
+corresponding to the token type. For example (not that you should really pay
+attention to this, \f(CW\*(C`$grammar\->syntax_for('comment')\*(C'\fR will return
+\&\f(CW\*(C`qr/^#(.*)/\*(C'\fR.
+.PP
+\fI\f(CI\*(C`handler_for\*(C'\fI\fR
+.IX Subsection "handler_for"
+.PP
+.Vb 1
+\& my $handler = $grammar\->handler_for($token_type);
+.Ve
+.PP
+Returns a code reference which, when passed an appropriate line of \s-1TAP\s0,
+returns the lexed token corresponding to that line. As a result, the basic
+\&\s-1TAP\s0 parsing loop looks similar to the following:
+.PP
+.Vb 13
+\& my @tokens;
+\& my $grammar = TAP::Grammar\->new;
+\& LINE: while ( defined( my $line = $parser\->_next_chunk_of_tap ) ) {
+\& foreach my $type ( $grammar\->token_types ) {
+\& my $syntax = $grammar\->syntax_for($type);
+\& if ( $line =~ $syntax ) {
+\& my $handler = $grammar\->handler_for($type);
+\& push @tokens => $grammar\->$handler($line);
+\& next LINE;
+\& }
+\& }
+\& push @tokens => $grammar\->_make_unknown_token($line);
+\& }
+.Ve
+.SH "TAP GRAMMAR"
+.IX Header "TAP GRAMMAR"
+\&\fB\s-1NOTE:\s0\fR This grammar is slightly out of date. There's still some discussion
+about it and a new one will be provided when we have things better defined.
+.PP
+The TAP::Parser does not use a formal grammar because \s-1TAP\s0 is essentially a
+stream-based protocol. In fact, it's quite legal to have an infinite stream.
+For the same reason that we don't apply regexes to streams, we're not using a
+formal grammar here. Instead, we parse the \s-1TAP\s0 in lines.
+.PP
+For purposes for forward compatability, any result which does not match the
+following grammar is currently referred to as
+TAP::Parser::Result::Unknown. It is \fInot\fR a parse error.
+.PP
+A formal grammar would look similar to the following:
+.PP
+.Vb 4
+\& (*
+\& For the time being, I'm cheating on the EBNF by allowing
+\& certain terms to be defined by POSIX character classes by
+\& using the following syntax:
+.Ve
+.PP
+.Vb 1
+\& digit ::= [:digit:]
+.Ve
+.PP
+.Vb 4
+\& As far as I am aware, that's not valid EBNF. Sue me. I
+\& didn't know how to write "char" otherwise (Unicode issues).
+\& Suggestions welcome.
+\& *)
+.Ve
+.PP
+.Vb 3
+\& tap ::= version? { comment | unknown } leading_plan lines
+\& |
+\& lines trailing_plan {comment}
+.Ve
+.PP
+.Vb 1
+\& version ::= 'TAP version ' positiveInteger {positiveInteger} "\en"
+.Ve
+.PP
+.Vb 1
+\& leading_plan ::= plan skip_directive? "\en"
+.Ve
+.PP
+.Vb 1
+\& trailing_plan ::= plan "\en"
+.Ve
+.PP
+.Vb 1
+\& plan ::= '1..' nonNegativeInteger
+.Ve
+.PP
+.Vb 1
+\& lines ::= line {line}
+.Ve
+.PP
+.Vb 1
+\& line ::= (comment | test | unknown | bailout ) "\en"
+.Ve
+.PP
+.Vb 1
+\& test ::= status positiveInteger? description? directive?
+.Ve
+.PP
+.Vb 1
+\& status ::= 'not '? 'ok '
+.Ve
+.PP
+.Vb 1
+\& description ::= (character \- (digit | '#')) {character \- '#'}
+.Ve
+.PP
+.Vb 1
+\& directive ::= todo_directive | skip_directive
+.Ve
+.PP
+.Vb 1
+\& todo_directive ::= hash_mark 'TODO' ' ' {character}
+.Ve
+.PP
+.Vb 1
+\& skip_directive ::= hash_mark 'SKIP' ' ' {character}
+.Ve
+.PP
+.Vb 1
+\& comment ::= hash_mark {character}
+.Ve
+.PP
+.Vb 1
+\& hash_mark ::= '#' {' '}
+.Ve
+.PP
+.Vb 1
+\& bailout ::= 'Bail out!' {character}
+.Ve
+.PP
+.Vb 1
+\& unknown ::= { (character \- "\en") }
+.Ve
+.PP
+.Vb 1
+\& (* POSIX character classes and other terminals *)
+.Ve
+.PP
+.Vb 4
+\& digit ::= [:digit:]
+\& character ::= ([:print:] \- "\en")
+\& positiveInteger ::= ( digit \- '0' ) {digit}
+\& nonNegativeInteger ::= digit {digit}
+.Ve
+.SH "SUBCLASSING"
+.IX Header "SUBCLASSING"
+Please see \*(L"\s-1SUBCLASSING\s0\*(R" in TAP::Parser for a subclassing overview.
+.PP
+If you \fIreally\fR want to subclass TAP::Parser's grammar the best thing to
+do is read through the code. There's no easy way of summarizing it here.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+TAP::Object,
+TAP::Parser,
+TAP::Parser::Iterator,
+TAP::Parser::Result,
projects / catagits/Gitalist.git / blobdiff