File Coverage

blib/lib/XML/Filter/Dispatcher/Ops.pm

Criterion	Covered	Total	%
statement	205	983	20.8
branch	55	324	16.9
condition	16	87	18.3
subroutine	43	334	12.8
pod			n/a
total	319	1728	18.4

package XML::Filter::Dispatcher::Ops;

=head1 NAME

XML::Filter::Dispatcher::Ops - The Syntax Tree

=head1 SYNOPSIS

    None.  Used by XML::Filter::Dispatcher.

=cut

## TODO: Replace XFD:: with XML::Filter::Dispatcher

## TODO: "helper" subs.  functions?  dunno.
## as-structure() EventPath function
## emit XML chunk (well balanced, not wf)
## as_document

## TODO: use context->{PossibleEventTypes} to
## reduce the amount of downstream test code and
## perhaps the amount of currying.  No need to test
## for EventType if we know only one node type is
## possible :).

package XFD;

use Carp qw( confess );  ## NOT croak: this module must die "...\n".

use constant is_tracing => defined $Devel::TraceSAX::VERSION;

# Devel::TraceSAX does not work with perl5.8.0
#use constant is_tracing => 1;
#sub emit_trace_SAX_message { warn @_ };

## Some debugging aids
*_ev = \&XML::Filter::Dispatcher::_ev;
*_po = \&XML::Filter::Dispatcher::_po;

BEGIN {
    eval( is_tracing
        ? 'use Devel::TraceSAX qw( emit_trace_SAX_message ); 1'
        : 'sub emit_trace_SAX_message; 1'
    ) or die $@;

}

use strict;

use vars (
    '$dispatcher',        ## The X::F::D that we're doing the parse for.
);

=begin private

=head1 Precursors and Postponment

NOTE: in this blurb, nodes occur in alphabetical order in the document
being processed.

level 0 expressions are able to be evaluated using only the current
event and it's 'ancestor events' and, when the match succeeds, the
action is executed in the current event's context.  The path '/a/b[@c]'
is level 0 can be evaluated using just the start_document event and the
start_element events for , , and .  So are the paths
'/a[@a]/b[@b]/c' and '/a[b]/b[c]/c'.

The paths '/a[b]' is not level 0; it requires some evaluation to occur
when the start_element event for '/a' is seen and other evaluation when
the start_element event for '/a/b' is seen; and when it does match
(which will occur in the start event for the first '/a/b'), the action's
execution context must be '/a', not '/a/b'.  In this case, the match
must proceed in stages and the action is postponed until all stages are
satisfied.

This is implemented in this code by converting level 1 expressions in to
precursors ('/a' and './b' in /a's context in our example) and
postponing the main expression (which just fires the action in this
case) using an object called a "postponement session" until enough
precursors are satisfied.  Once enough precursors are satisfied, the
action is executed and the postponement is destroyed.

The phrase "enough precursors are satisfied" is used rather than "all
precursors are satisfied" because expressions like 'a[ b or c ]' does
not need both the './b' or './c' precursors; either one will suffice.

A postponement session has a value slot for each precursor and a slot for
the result context.  Each precursor fills is it's slot when it matches,
and the primary precursor sets the main expression / action context.  As
each precursor fires, it checks to see if enough of the slots are filled
in and fires the action or main expression if so.  Expressions like
'//*[b]' and '/a//b[c]' can cause multiple simultaneous postponement
sessions for the same expression.

For expressions like '/a/b[c]/d', the main expression (or result)
context may not be set when some of the precursors match: /a/b/c will
match before /a/b/d.  The precursor for '/a/b/d' is called the primary
precursor and sets the result context.

The action (or main expression in an expression line '/a[concat(b,c)]') is
evaluated in the result context ('/a' in this case).

The main expression (or action) should be executed once per primary
precursor match in the document where the entire expression is true.
So a rule with a pattern '/a/b[c]/d[e]' would fire once for every /a/b/d
node in the document where the entire match is true.

//a[b]/c and //a[c]/b

The first precursor to match must create a postponement session.

Q: How do we associate the precursors with their appropriate
postponement sessions?

In expressions like 'concat( /a, /b )', the precursors '/a' and '/b' are
numbered 0 and 1 and there is a "main expression" of 'concat(
PRECURSOR_0, PRECURSOR_1)', where the PRECURSOR_# is the result of the
indicated precursor.  The main expression which is computed before
firing the action.  The action context is "/".

Expressions like 'concat( a, b )' are similar except that the action
context is the parent of the  and  elements that match.

In '/a[concat( b, c )]' the precursors are './b', './c' and 'a[concat(
PRECURSOR_0, PRECURSOR_1 )]', and the action can only fire when
PRECURSOR_2 becomes defined.  The action contexst is '/a'.

Each time a context-setting precursor matches, all presursor sessions
that it affects become "eligible" for firing.  A precursor session fires
as soon as enough precursors are satisfied.

=head2 Firing Policy

This does not apply to level 0 patterns.

An application may support multiple policies controlling when a
postponed expression is finally completely evaluated (ie matches, fails
to match, or returns a result).

A "prompt evaluation policy" describes implementations where postponed
expressions match the first time enough predicates are
satisified (when the  start_element() arrives, in this case).  This
is useful to minimize memory and recognize conditions as rapidly as
possible.

A "delayed evaluation policy" describes implementations where postponed
expressions are evaluated during the end_...() event for the node
deepest in the hierarchy for which an un-postponed test was true.  For
example, rules with these patterns must fire their actions before the
 if at all: '/a[b]', '/z/a/[b]'.   This may make some
implementations easier but is discouraged unless necessary.

An application must be apply a consistent firing policy policy prompt,

An application may also provide for

An application must detail whether it supports modes other than "prompt
firing" or not and all applications

=end private

=cut

###############################################################################
##
## Boolean Singletons
##

## These are not used internally; 1 and 0 are.  These are used when passing
## boolean values in / out to Perl code, so they may be differentiated from
## numeric ones.
sub true()  { \"true"  }
sub false() { \"false" }


###############################################################################
##
## Helpers
##
sub _looks_numeric($)  { $_[0] =~ /^[ \t\r\n]*-?(?:\d+(?:\.\d+)?|\.\d+)[ \t\r\n]*$/ }

sub _looks_literal($)  { $_[0] =~ /^(?:'[^']*'|"[^"]*")(?!\n)\Z/       }

sub _indentomatic() { 1 }  ## Turning this off shaves a little parse time.
                           ## I leave it on for more readable error
                           ## messages, and it's key for debugging since
                           ## is so much more readable; in fact, messed
                           ## up indenting can indicate serious problems

sub _indent { Carp::confess "undef" unless defined $_[0]; $_[0] =~ s/^/  /mg; }

sub _is_rel_path($) {
    my $path = shift;

    return 0
        if $path->isa( "XFD::PathTest" )
            && $path->isa( "XFD::doc_node" )                  ## /... paths
            && ! $path->isa( "XFD::union" ); ## (a|b), union called this already.

    return 1;
}


###############################################################################
##
## Postponement Records
##
## When the current location step or operator/function call
## in an expression can't be calculated because it needs some
## future information, it must be postponed.  The portions of
## the expression that can't yet be calculated are called
## precursors; only when enough of them are calculated can
## this expression be calculated.
##
## A Postponement record contains:
##
## - A list of contexts for which this postponement eventually
##   becomes valid.
## - A pointer to the parent postponement
## - A set of results one for each precursor.
##
## A postponement record is a simple array with a few set data fields
## in the first elements; the remaining elements are used to hold
## precursor results.
##
## This could be an object, but we don't need any inheritence.
##
sub _p_parent_postponement() { 0 }
sub _p_contexts()            { 1 }
sub _p_first_precursor ()    { 2 }

###############################################################################
##
## expr_as_incr_code
##

##
## Precursors
## ==========
##
## A precursor is something (so far always a location path sub-expr) that
## (usually) needs to be dealt with before a pattern can be evaluated.
## A precursor is known as "defined" if it's been evaluated and returned
## some result (number, string, boolean, or node).
##
## The only time a pattern can be fully evaluated in the face of undefined
## precursor is when the precursor is supposed to return a node and the
## precursor result is being turned in to a boolean.  Booleans accept
## empty node sets as false values.  Right now, all precursors happen to
## return node sets of 0 or 1 nodes.
##
## The precursor values are stored in $ctx because I'm afraid of leaky
## closure in older perl.  I haven't tested them in this case, but have been
## bit before.

sub _replace_NEXT {
    my $what_next = "";
    $what_next = pop if @_ > 2;
    my $next_code = pop;
    $_[0] =~ s{(^[ \t]*)?$what_next}{
        if ( _indentomatic && defined $1 ) {
            _indent $next_code for 1..(length( $1 ) / 2 );
        }
        $next_code
    }gme;
}


###############################################################################
##
## Parse tree node base class
##
## This is used for all of the pieces of location paths axis tests, name
## and type tests, predicates.  It is also used by a few functions
## that act on the result of a location path (which is effectively a
## node set with just the current node in it).
##
sub XFD::Op::new {
    my $class = shift;
    return bless [ @_ ], $class;
}


sub XFD::Op::op_type { ( my $type = ref shift ) =~ s/.*:// ; $type }

## The optimizer combines common expressions in some cases (it should
## do more, right now it only does common leading op codes).  To do this
## it needs to know the type of the operator and its arguments, if any.
## By default, the signature is this op's reference id, which makes each
## op look different to the optimizer.
sub XFD::Op::optim_signature { int shift }


sub XFD::Op::is_constant {
    my $self = shift;
    return ! grep ! $_->is_constant, @$self;
}

## fixup is called on a freshly parsed op tree just before it's
## compiled to convert expression like 'A' to be like '//A'.
## TODO: Perhaps move this to an XML::Filter::Dispatcher::_fixup(),
## like _optimize().
sub XFD::Op::fixup {
    my $self = shift;
    my ( $context ) = @_;

    for ( @$self ) {
        if ( defined && UNIVERSAL::isa( $_, "XFD::Op" ) ) {
            if ( ! $context->{BelowRoot}
                && ( $_->isa( "XFD::Axis::child" )
                    || $_->isa( "XFD::Axis::attribute" )
                    || $_->isa( "XFD::Axis::start_element" )
                    || $_->isa( "XFD::Axis::end_element" )
#                    || $_->isa( "XFD::Axis::end" )
                )
            ) {
                ## The miniature version of XPath used in
                ## XSLT's