view release on metacpan or  search on metacpan

lib/XML/PatAct/ToObjects.pm  view on Meta::CPAN

sub start_document {
    my ($self, $document) = @_;

    $self->{Matcher}->initialize($self);
    $self->{Parents} = [ { Contents => [  ] } ];
    $self->{ActionStack} = [ ];
    $self->{States} = [ 'normal' ];
    $self->{Document} = $document;
    $self->{Names} = [ ];
    $self->{Nodes} = [ ];
    $self->{Data} = undef;
    $self->{SourceIsGrove} = UNIVERSAL::isa($document, 'Data::Grove');
    if (!defined $self->{CharacterDataType}) {
	require Data::Grove;
	import Data::Grove;
	$self->{CharacterDataType} = 'Data::Grove::Characters';
    }
}

sub end_document {
    my ($self, $document) = @_;

    $self->{Matcher}->finalize();
    # FIXME check to make sure no other fields were assigned to
    my $value = $self->{Parents}[0]{Contents};

    # release all the info that is just used during event handling
    $self->{Matcher} = $self->{Parents} = $self->{ActionStack} = undef;
    $self->{States} = $self->{Document} = $self->{Names} = undef;
    $self->{Nodes} = $self->{Data} = $self->{SourceIsGrove} = undef;

    return $value;
}

sub start_element {
    my ($self, $element) = @_;

    push @{$self->{Names}}, $element->{Name};
    push @{$self->{Nodes}}, $element;

    my $index = $self->{Matcher}->match($element,
					$self->{Names},
					$self->{Nodes});

    my $action;
    if (!defined $index) {
	$action = undef;
    } else {
	$action = $self->{Actions}[$index];
    }

    push @{$self->{ActionStack}}, $action;

    my $state = $self->{States}[-1];
    push @{$self->{States}}, $state;

    if (($state eq 'as-grove') and !$self->{SourceIsGrove}) {
	$self->{GroveBuilder}->start_element($element);
    }

    return if (($state ne 'normal') && ($state ne 'pcdata'));

    if (defined($action) and defined($action->{PCData})) {
	$self->{States}[-1] = 'pcdata';
    }

    if (!defined($action) or $action->{Holder}) {
	# ignore this element but continue processing below
	return;
    }

    if ($action->{Ignore} or $action->{FieldValue}) {
	# ignore (discard) this element and it's children
	$self->{States}[-1] = 'discarding';
	return;
    }

    if ($action->{AsString}) {
	$self->{Data} = [ ];
	$self->{States}[-1] = 'as-string';
	return;
    }

    if ($action->{AsGrove}) {
	$self->{States}[-1] = 'as-grove';
	if (!$self->{SourceIsGrove}) {
	    $self->{GroveBuilder}->start_document( { } );
	    $self->{GroveBuilder}->start_element($element);
	}
	return;
    }

    if (defined $action->{Make}) {
	my @args;
	if (defined $element->{Attributes}) {
	    if (defined $self->{CopyAttributes}) {
		push @args, %{$element->{Attributes}};
	    } elsif ($self->{CopyId} && defined($element->{Attributes}{ID})) {
		# FIXME use code from XML::Grove::IDs
		push (@args, ID => $element->{Attributes}{ID});
	    }
	}

	if (defined $action->{Args}) {
	    eval 'push (@args, (' . $action->{Args} . '))';
	    if ($@) {
		warn "$@\nwhile processing pattern/action #$index\n";
	    }
	}

	if ($action->{Make} eq 'HASH') {
	    push @{$self->{Parents}}, { @args };
	} else {
	    my $is_defined = 0;
	    #eval "\$is_defined = defined %{$action->{Make}" . "::}";
	    if ($is_defined) {
		push @{$self->{Parents}}, $action->{Make}->new( @args );
	    } else {
		push (@{$self->{Parents}},
		      bless ({ @args }, $action->{Make}));
	    }
	}

	if ($action->{ContentsAsGrove}) {

lib/XML/PatAct/ToObjects.pm  view on Meta::CPAN

    my $action = pop @{$self->{ActionStack}};
    my $state = pop @{$self->{States}};

    if ($state eq 'as-grove' and !$self->{SourceIsGrove}) {
	$self->{GroveBuilder}->end_element($end_element);
    }

    if (!defined($action) or $action->{Holder}) {
	return;
    }

    if ($action->{Ignore}) {
	return;
    }

    my $value;

    if ($action->{AsString}) {
	$value = join("", @{$self->{Data}});
    } elsif ($action->{AsGrove}) {
	if ($self->{SourceIsGrove}) {
	    $value = $element;
	} else {
	    # get just the root element of the document fragment
	    $value = $self->{GroveBuilder}->end_document({ })->{Contents}[0];
	}
    } elsif (defined $action->{FieldValue}) {
	$value = $action->{FieldValue};
	$value =~ s/%\{($name_re)\}/$element->{Attributes}{$1}/ge;
    } elsif (defined $action->{Make}) {
	$value = pop @{$self->{Parents}};
	if ($action->{ContentsAsGrove}) {
	    if ($self->{SourceIsGrove}) {
		$value->{Contents} = $element->{Contents};
	    } else {
		$value->{Contents} =
		    $self->{GroveBuilder}->end_document({ })->{Contents};
	    }
	}
    } else {
	$value = pop(@{$self->{Parents}})->{Contents};
    }

    if ($action->{FieldIsArray}) {
	push @{$self->{Parents}[-1]{$action->{Field}}}, $value;
    } elsif (defined $action->{Field}) {
	$self->{Parents}[-1]{$action->{Field}} = $value;
    } else {
	push @{$self->{Parents}[-1]{Contents}}, $value;
    }
}

sub characters {
    my ($self, $characters) = @_;

    my $state = $self->{States}[-1];
    if ($state eq 'as-string') {
	push @{$self->{Data}}, $characters->{Data};
    } elsif ($state eq 'as-grove' and !$self->{SourceIsGrove}) {
	$self->{GroveBuilder}->characters($characters);
    } elsif ($state eq 'pcdata') {
	push (@{$self->{Parents}[-1]{Contents}},
	      $self->{CharacterDataType}->new(%$characters));
    }
}

# we ignore processing instructions and ignorable whitespace by not
# defining those functions

###
### private functions
###

sub _parse_action {
    my $self = shift; my $source = shift;

    my $action = {};

    while ($#$source > -1) {
	my $option = shift @$source;
	if ($option eq '-holder') {
	    $action->{Holder} = 1;
	} elsif ($option eq '-make') {
	    $action->{Make} = shift @$source;
	} elsif ($option eq '-args') {
	    my $args = shift @$source;
	    $args =~ s/%\{($name_re)\}/(\$element->{Attributes}{'$1'})/g;
	    $action->{Args} = $args;
	} elsif ($option eq '-field') {
	    $action->{Field} = shift @$source;
	} elsif ($option eq '-push-field') {
	    $action->{Field} = shift @$source;
	    $action->{FieldIsArray} = 1;
	} elsif ($option eq '-as-string') {
	    $action->{AsString} = 1;
	} elsif ($option eq '-value') {
	    $action->{FieldValue} = shift @$source;
	} elsif ($option eq '-grove') {
	    $self->{GroveBuilder} = 1;
	    $action->{AsGrove} = 1;
	} elsif ($option eq '-grove-contents') {
	    $self->{GroveBuilder} = 1;
	    $action->{ContentsAsGrove} = 1;
	} elsif ($option eq '-ignore') {
	    $action->{Ignore} = 1;
	} elsif ($option eq '-pcdata') {
	    $action->{PCData} = 1;
	} else {
	    die "$option: undefined option\n";
	}
    }

    return $action;
}

1;

__END__

=head1 NAME

XML::PatAct::ToObjects - An action module for creating Perl objects

=head1 SYNOPSIS

 use XML::PatAct::ToObjects;

 my $patterns = [ PATTERN => [ OPTIONS ],
		  PATTERN => "PERL-CODE",
		  ... ];

 my $matcher = XML::PatAct::ToObjects->new( Patterns => $patterns,
					    Matcher => $matcher,
					    CopyId => 1,
					    CopyAttributes => 1 );


=head1 DESCRIPTION

XML::PatAct::ToObjects is a PerlSAX handler for applying
pattern-action lists to XML parses or trees.  XML::PatAct::ToObjects
creates Perl objects of the types and contents of the action items you
define.

New XML::PatAct::ToObject instances are creating by calling `new()'.
Parameters can be passed as a list of key, value pairs or a hash.
`new()' requires the Patterns and Matcher parameters, the rest are
optional:

=over 4

=item Patterns

The pattern-action list to apply.

=item Matcher

An instance of the pattern or query matching module.

=item CopyId

Causes the `ID' attribute, if any, in a source XML element to be
copied to an `ID' attribute in newly created objects.  Note that IDs
may be lost of no pattern matches that element or an object is not
created (C<-make>) for that element.

=item CopyAttributes

Causes all attributes of the element to be copied to the newly created
objects.

=back

Each action can either be a list of options defined below or a string
containing a fragment of Perl code.  If the action is a string of Perl
code then simple then some simple substitutions are made as described
further below.

Options that can be used in an action item containing an option-list:

=over 4

=item B<-holder>

Ignore this element, but continue processing it's children (compare to
B<-ignore>).  C<-pcdata> may be used with this option.

=item B<-ignore>

Ignore (discard) this element and it's children (compare to B<-holder>).

=item B<-pcdata>

Character data in this element should be copied to the C<Contents>
field.

=item B<-make> I<PACKAGE>

Create an object blessed into I<PACKAGE>, and continue processing this
element and it's children.  I<PACKAGE> may be the type `C<HASH>' to
simply create an anonyous hash.

=item B<-args> I<ARGUMENTS>

Use I<ARGUMENTS> in creating the object specified by B<-make>.  This
is commonly used to copy element attributes into fields in the newly
created object.  For example:

  -make => 'HASH', -args => 'URL => %{href}'

would copy the `C<href>' attribute in an element to the `C<URL>' field
of the newly created hash.

=item B<-field> I<FIELD>

Store this element, object, or children of this element in the parent
object's field named by I<FIELD>.

=item B<-push-field> I<FIELD>

Similar to B<-field>, except that I<FIELD> is an array and the
contents are pushed onto that array.

=item B<-value> I<VALUE>

Use I<VALUE> as a literal value to store in I<FIELD>, otherwise
ignoring this element and it's children.  Only valid with B<-field> or
B<-push-field>.  `C<%{I<ATTRIBUTE>}>' notation can be used to
substitute the value of an attribute into the literal value.

=item B<-as-string>

Convert the contents of this element to a string (as in
C<XML::Grove::AsString>) and store in I<FIELD>.  Only valid with
B<-field> or B<-push-field>.

=item B<-grove>

Copy this element to I<FIELD> without further processing.  The element
can then be processed later as the Perl objects are manipulated.  Only
valid with B<-field> or B<-push-field>.  If ToObjects is used with
PerlSAX, this will use XML::Grove::Builder to build the grove element.

=item B<-grove-contents>

Used with B<-make>, B<-grove-contents> creates an object but then
takes all of the content of that element and stores it in Contents.

=back

If an action item is a string, that string is treated as a fragment of
Perl code.  The following simple substitutions are performed on the