.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.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.  \*(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-
.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" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" 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 "DBIx::MyParsePP::Rule 3"
.TH DBIx::MyParsePP::Rule 3 "2007-08-18" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
DBIx::MyParsePP::Rule \- Access individual elements from the DBIx::MyParsePP parse tree
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&        use DBIx::MyParsePP;
\&        use DBIx::MyParsePP::Rule;
\&
\&        my $parser = DBIx::MyParsePP\->new();
\&
\&        my $query = $parser\->parse("SELECT 1"); # $query is a DBIx::MyParsePP::Rule object
\&        my $root = $query\->root();
\&        print $root\->name();                    # prints \*(Aqquery\*(Aq, the top\-level grammar rule
\&
\&        my @children = $root\->chilren();        #
\&        print $children[0]\->name();             # prints \*(Aqverb_clause\*(Aq, the second\-level rule
\&
\&        print ref($chilren[1]);                 # prints \*(AqDBIx::MyParsePP::Token\*(Aq
\&        print $chilren[1]\->type();              # prints END_OF_INPUT
\&
\&        print [[[$root\->chilren()]\->[0]\->chilren()]\->[0]\->chilren()]\->[0]\->name(); # Prints \*(Aqselect\*(Aq
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
DBIx::MyParsePP uses the \f(CW\*(C`sql_yacc.yy\*(C'\fR grammar from the MySQL source to parse \s-1SQL\s0 strings. A
parse tree is produced which contains one branch for every rule encountered during parsing. This means
that very deep trees can be produced where only certain branches are important.
.SH "METHODS"
.IX Header "METHODS"
\&\f(CW\*(C`new($rule_name, @chilren)\*(C'\fR constructs a new rule
.PP
\&\f(CW\*(C`name()\*(C'\fR and \f(CW\*(C`getName()\*(C'\fR returns the name of the rule
.PP
\&\f(CW\*(C`chilren()\*(C'\fR and \f(CW\*(C`getChildren()\*(C'\fR return (as array) the right-side items that were matched for that rule, e.g.
its \*(L"child branches\*(R" in the parse tree.
.PP
\&\f(CW\*(C`toString()\*(C'\fR converts the parse tree back into \s-1SQL\s0 by walking the tree and gathering all tokens in sequence.
.SH "EXTRACTING PARTS"
.IX Header "EXTRACTING PARTS"
\&\f(CW\*(C`extract(@names)\*(C'\fR can be used to walk the tree and extract relevant parts. The method returns undef if no
part of the tree matched, a DBIx::MyParse::Rule or a DBIx::MyParse::Token object if a sigle match
was made, or a reference to an array of such objects if several parts matched. Names to the front of the
\&\f(CW@names\fR list are matched first.
.PP
\&\f(CW\*(C`getFields()\*(C'\fR or \f(CW\*(C`fields()\*(C'\fR can be used to obtain all fields referenced in a parse tree or a part of it. Those functions
will return <undef> if no fields were referenced or a reference to an array containing \f(CW\*(C`Rule\*(C'\fR objects for each field.
The Rule object can contain several 'ident' subrules if a database and/or a table name was specified for the given field.
.PP
\&\f(CW\*(C`getTables()\*(C'\fR or \f(CW\*(C`tables()\*(C'\fR can be used in the same manner to obtain all tables referenced in the parse tree.
.SH "SHRINKING THE TREE"
.IX Header "SHRINKING THE TREE"
The raw tree produced by DBIx::MyParsePP contains too many branches, many of them not containing any useful information.
The \f(CW\*(C`shrink($flags)\*(C'\fR method is used to convert the tree into a more manageable form. \f(CW$flags\fR can contain the
following constants joined by \f(CW\*(C`|\*(C'\fR:
.PP
\&\f(CW\*(C`MYPARSEPP_SHRINK_IDENTICAL\*(C'\fR if a parent and a child node are of the same type, they will be merged together. This way
expressions such as \f(CW\*(C`1 + 1 + 1\*(C'\fR or \f(CW\*(C`col1, col2, col3\*(C'\fR will be converted from a nested tree with one item per branch
into a single Rule containing a list of all the items and the tokens between them (e.g. \f(CW\*(C`+\*(C'\fR or \f(CW\*(C`,\*(C'\fR). Expressions
such as \f(CW\*(C`1 + 2 * 3\*(C'\fR will remain as a tree because multiplication and addition have different precedence.
.PP
\&\f(CW\*(C`MYPARSEPP_SHRINK_LEAFS\*(C'\fR will remove any Rules that have no children.
.PP
\&\f(CW\*(C`MYPARSEPP_SHRINK_SINGLES\*(C'\fR will remove any Rules that have just a single child, linking the child directly
to the upper-level Rule.
.PP
\&\f(CW\*(C`MYPARSEPP_SHRINK_CHILDREN\*(C'\fR will apply \f(CW\*(C`schrink()\*(C'\fR recursively for all children.
.PP
If no flags are specified, all listed transformations are applied recursively.