package XML::Essex;
$VERSION = 0.000_1;
=head1 NAME
XML::Essex - Essex XML processing primitives
=head1 SYNOPSIS
TODO
=head1 DESCRIPTION
=head2 Result Value
The return value will be returned to the caller. For handlers, this is
usually a "1" for success or some other value, such as a data
structure that has been built or the result of a query.
For generators and filters, it is important that the result of the next
filter's end_document() is returned at the end of your Essex script, so
that it may be used upstream of such modules as XML::Simple.
Errors should be reported using die().
=cut
#=head2 A short word on abbreviations
#
#A goal of essex is to allow code to be as terse or verbose as
#appropriate for the job at hand. So almost every object may be
#abbreviated. For instance, C<start_element> may be abbreviated as
#C<start_elt> when using L<C<isa()>|/isa> to check o.
#
#Most of the examples use the abbreviated form, though you can spell
#them out longhand if you like. Here's a list of abbreviations:
#
# document doc
# element elt
# characters chars
# processing instruction pi
# namespace ns
# attribute attr
#
#Class names, functions, and parameters to the Essex C<isa()>
#function/method are all encouraged to use these abbreviations.
=head2 Result Values
=for Document maintainers: if you edit this section, copy and paste it
over the first section of lib/XML/Essex/ResultValues.pod. Thanks.
Essex is designed to Do The Right Thing for the vast majority of
uses, so it manages result values automatically unless you take
control. Below is a set of detailed rules for how it manages
the result value for a filter's processing run, but the overview is:
=over
=item *
Filters normally do not need to manage a result. The result from the
next filter downstream will be returned automatically, or an exception
will be thrown if an incomplete document is sent downstream.
=item *
Generators act like filters mostly, except that if a generator decides
not to send any results downstream, it should either set a result value
by calling C<result()> with it, or C<return> that result normally, just
like a handler.
=item *
Handlers should either set a result value
by calling C<result()> with it, or C<return> that result normally.
=item *
Generators, filters and handlers should all die() on unexpected
conditions and most error conditions (a FALSE or undefined result is not
necessarily an error condition for a handler).
Generators and filters generally should not return a value of their own
because this will surprise calling code which is expecting a return
value of the type that the final SAX handler returns.
=for Document maintainers: if you edit this section, copy and paste it
over the first section of lib/XML/Essex/ResultValues.pod. Thanks.
=cut
use Carp;
use Exporter;
use Filter::Util::Call;
use UNIVERSAL;
use strict;
use vars qw( %EXPORT_TAGS @EXPORT ); ## Set by the controlling process
use XML::Essex::Constants qw( EOD );
sub EOL() { "XML::Essex: End of last document" }
{
%EXPORT_TAGS = (
read => [qw(
get
read_from
parse_doc
isa
next_event
path
type
xeof
)],
rules => [qw(
on
xvalue
xpush
xpop
xset
xadd
)],
write => [qw(
put
write_to
push_output_filters
characters
chars
end_document
end_doc
end_element
end_elt
start_document
start_doc
start_element
start_elt
xml_decl
)],
);
my %seen;
$EXPORT_TAGS{filter} = [
grep !$seen{$_}++,
map @$_,
@EXPORT_TAGS{qw( read write )}
];
%seen = ();
@EXPORT = grep !$seen{$_}++, map @$_, values %EXPORT_TAGS;
$EXPORT_TAGS{all} = \@EXPORT;
}
sub import {
my ( undef, @args ) = @_;
## Figure out whether to read, write, or do both.
my %exports;
$exports{$_} = 1 for
@args
? map s/^://
? exists $EXPORT_TAGS{$_}
? @{$EXPORT_TAGS{$_}}
: croak "Unkown export tag ':$_' for ", __PACKAGE__
: $_, @args
: @EXPORT;
my $is_reader = exists $exports{get} || exists $exports{on} || exists $exports{parse_doc};
my $is_writer = exists $exports{put};
croak "XML::Essex not used as a reader (with :read, get(), :rules or on()) or a writer (with :write put())\n"
unless $is_reader || $is_writer;
my $sax_processor_type =
! $is_reader ? "XML::Generator::Essex" :
! $is_writer ? "XML::Handler::Essex" :
"XML::Filter::Essex";
my $state = 0; # 0=init; 1=code; 2=pod; 3=EOF
filter_add(
sub {
if ( $state == 0 ) {
$_ = join '',
"XML::Essex::_init '",
$sax_processor_type,
"'; XML::Essex::_cleanup eval {";
++$state;
return 1;
}
return 0 if $state > 2;
my $status = filter_read;
if ( $status > 0 && substr( $_, 0, 1 ) eq "=" ) {
if ( $state == 1 ) { $state = 2 }
elsif ( substr( $_, 0, 4 ) eq "=cut" ) { $state = 1 }
}
return $status if $status != 0;
$_ .= "\n\n=cut\n" if $state == 2;
$_ .= "\n;1};";
$state = 3;
return 1;
},
);
goto \&Exporter::import;
}
my @self_stack;
sub _init_new {
my ( $sax_processor_type ) = @_;
push @self_stack, $XML::Essex::Base::self;
my $self = $XML::Essex::Base::self = $sax_processor_type->new;
$self->{NoExecute} = 1;
## The first part of XML::Essex::Base::execute();
$self->reset;
}
sub _init {
my ( $sax_processor_type ) = @_;
eval "require $sax_processor_type" or croak $@;
_init_new $sax_processor_type;
};
sub _cleanup {
my ( $ok ) = @_;
my $self = $XML::Essex::Base::self;
my $x = $@;
## The last part of XML::Essex::Base::execute();
my ( $ok2, $result, $result_set ) = eval {
( 1, $self->finish( $ok, $x ) );
};
$XML::Essex::Base::self = pop @self_stack;
die $@ unless $ok2;
return $result if $result_set;
return 1;
}
sub _reinit {
my $type = ref $XML::Essex::Base::self;
_cleanup 1;
_init_new $type;
}
=back
=head1 Exported Functions
These are exported by default, use the C<use XML::Essex ();> syntax to
avoid exporting any of these or export only the ones you want.
The following export tags are also defined:
:read get read_from parse_doc isa next_event path type xeof
:rules on
:write put write_to start_doc end_doc start_elt chars ...
so you can
use XML::Essex qw( :read :rules );
for an Essex script that just handles input and uses some rules, or
even:
use XML::Essex qw( parse_doc :rules );
for a purely rule-based script.
Importing only what you need is a little quicker and more memory
efficient, but it cal also allow XML::Essex to run more efficiently. If
you don't import any output functions (see C<:write> above), it will not
load the output routines. Same for the input and rule based APIs.
=over
=item get
my $e = get;
Returns the next SAX event. Sets $_ as an EXPERIMENTAL feature.
Throws an exception (which is silently caught outside the main code)
on end of input.
See C<isa()> and C<type()> functions and method (in
L<XML::Essex::Object>) for how to test what was just gotten.
=cut
sub get {
my $self = $XML::Essex::Base::self;
$self->_read_from_default unless $self->{Reader};
$XML::Essex::Base::self->get( @_ );
}
=item read_from
read_from \*STDIN; ## From a filehandle
read_from "-"; ## From \*STDIN
read_from "foo.xml"; ## From a file or URI (URI support is parser dependant)
read_from \$xml_string; ## From a string.
read_from undef; ## STDIN or files named in @ARGV, as appropriate
Tells the next get() or parse_doc() to read from the indicated source.
Calling read_from automatically disassembles the current processing chain
and builds a new one (just like Perl's open() closes an already open
filehandle).
=cut
sub XML::Essex::Base::_read_from_default {
my $self = shift;
if ( @ARGV || $self->{FromARGV} ) {
$self->{FromARGV} = 1;
die EOL."\n" unless @ARGV;
read_from( shift @ARGV );
}
else {
read_from( \*STDIN );
}
}
## TODO: move this in to XML::Handler::Essex as a set of standard
## SAX parse_foo() APIs.
sub read_from {
## Shut down the old processing chain if it a Reader was already
## created.
## NOTE: This ASSumes that there is only one instance of the Essex
## scripting env. in play at once. This is ok for now, but it does
## contradict the idea of @self_stack. Perhaps having the source
## filter set a secretly named global to point us to the right
## $self would help. The goal is to enable handling of multiple
## inputs at the same time: get from this, get from that.
_reinit if $XML::Essex::Base::self->{Reader};
my $self = $XML::Essex::Base::self;
my ( $what ) = @_;
if ( ! defined $what ) {
return delete $self->{Reader};
}
$self->{Reader} = sub {
require XML::SAX::PurePerl; ## ugh. need XML::LibXMl to support SAX2
my $p = XML::SAX::PurePerl->new( Handler => $self );
my $type = ref $what;
## This is purely a non-threading implementation.
## TODO: build the parser and save the reference to be parsed, then
## use an appropriate driver for the parser that is called when
## there are no more events in @{$self->{Events}}.
if ( ! $type ) {
$what eq "-"
? $p->parse_file( \*STDIN )
: $p->parse_uri( $what );
}
elsif ( $type eq "GLOB" || UNIVERSAL::isa( $what, "IO::Handle" ) ) {
$p->parse_file( $what );
}
elsif ( $type eq "SCALAR" ) {
$p->parse_string( $$what );
}
else {
croak "Don't know how to read from a $type";
}
};
}
=item push_output_filters
Adds an output filter to the end of the current list (and before the
eventual writer). Can be a class name (which will be C<require()>ed
unless the class can already new()) or a reference to a filter.
=cut
sub push_output_filters {
my $self = $XML::Essex::Base::self;
push @{$self->{OutputFilters}}, @_;
}
=item parse_doc
Parses a single document from the current input. Morally equivalent to C<get()
while 1;> but exits normally (as opposed to throwing an exception) when the
end of document is reached. Also slightly faster now and hopefully moreso
when optimizations can be made.
Used to read to the end of a document, primarily in rule-based processing
(L</on>).
TODO: Allow parse_doc to take rules.
=cut
sub parse_doc {
my $self = $XML::Essex::Base::self;
$self->_read_from_default unless $self->{Reader};
write_to( \*STDOUT ) unless $self->{Writer};
## The result is undocumented; what should be returned is the
## normal XML::Filter::Dispatcher
my $result;
eval {
$result = $self->get while 1; ## I did say I<slightly> ;)
};
die $@ unless $@ eq EOD . "\n";
return $result;
}
=item put
Output one or more events. Usually these events are created by
constructors like C<start_elt()> (see
L<XML::Generator::Essex|XML::Generator::Essex> for details) or
are objects returned C<get()> method.
=cut
sub put {
my $self = $XML::Essex::Base::self;
write_to( \*STDOUT ) unless $self->{Writer};
$self->put( @_ );
}
=item write_to
write_to \*STDOUT; ## To a filehandle
write_to "-"; ## To \*STDOUT
write_to "foo.xml"; ## To a file or URI (URI support is parser dependant)
write_to \$xml_string; ## To a string.
Tells the next put() to write the indicated source.
=cut
sub write_to {
my $self = $XML::Essex::Base::self;
my ( $what ) = @_;
croak "Can't write to an undefined output" unless defined $what;
require XML::SAX::Writer;
$self->{Writer} = sub {
my $h = XML::SAX::Writer->new( Output => $what );
for ( reverse @{$self->{OutputFilters} || [] } ) {
unless ( ref $_ ) {
eval "require $_" or die $@ unless $_->can( "new" );
$_ = $_->new( Handler => $h );
}
else {
$_->set_handler( $h );
}
$h = $_;
}
return $h;
};
}
=back
=head2 Miscellaneous
=over
=item isa
get until isa "start_elt" and $_->name eq "foo";
$r = get until isa $r, "start_elt" and $_->name eq "foo";
Returns true if the parameter is of the indicated object type. Tests $_
unless more than one parameter is passed.
=cut
sub isa($) {
local $_ = shift if @_ >= 2;
UNIVERSAL::can( $_, "isa" )
? $_->isa( @_ )
: UNIVERSAL::isa( $_, @_ );
}
=item next_event
Like C<get()> (see L<below|/get>), but does not remove the next event
from the input stream.
get "start_document::*";
get if next_event->isa( "xml_decl" );
...process remainder of document...
=cut
sub next_event {
my $self = $XML::Essex::Base::self;
die "No XML input defined\n" unless $self->{Reader};
$self->{Reader}->peek;
}
=item path
get "start_element::*" until path eq "/path/to/foo:bar"
Returns the path to the current element as a string.
=cut
sub path {
my $self = $XML::Essex::Base::self;
return join "/", "", map $_->name, @{$self->{Stack}};
}
=for import XML::Generator::Essex/put
=item type
get until type eq "start_document";
$r = get until type $r eq "start_document";
Return the type name of the object. This is the class name with a
leading XML::Essex:: stripped off. This is a wrapper around the
event's C<type()> method.
=cut
sub type {
my $self = $XML::Essex::Base::self;
$self->type( @_ );
}
=item xeof
Return TRUE if the last event has been read.
=cut
sub xeof {
my $self = $XML::Essex::Base::self;
die "No XML input defined\n" unless $self->{Reader};
$self->{Reader}->eof;
}
=back
=head2 Namespaces
If this section doesn't make any sense, see
L<http://www.jclark.com/xml/xmlns.htm|http://www.jclark.com/xml/xmlns.htm>
for your next dose of XML koolaid. If it still doesn't make any sense
then ding me for writing gibberish.
Element names, attribute names, and PI targets returned by Essex are
generated in one of three forms, depending on whether the named item
has a namespace URI associated with it and whether the filter program
has mapped that namespace URI to a prefix. You may also use any of
these three forms when passing a name to Essex:
=over
=item "id"
If an attribute has no NamespaceURI or an empty string for a
NamespaceURI, it will be returned as a simple string.
TODO: Add an option to enable this for the default namespace or
for attrs in the element's namespace.
=item "foo:id"
If the attribute is in a namespace and there is a namespace -> prefix
mapping has been declared by the filter
=item "{http://foo/}id"
If the attribute is in a namespace with no prefix mapped to it by
the filter.
=back
Namespace prefixes from the source document are ignored; there's no
telling what prefix somebody might have used. Intercept the
start_prefix_mapping and end_prefix_mapping events to follow the weave
of source document namespace mappings.
When outputting events that belong to a namespace not in the source
document, you need to C<put()> the start_prefix_mapping and
end_prefix_mapping events manually, and be careful avoid existing
prefixes from the document if need be while doing so. Future additions
to Essex should make this easier and perhaps automatic.
Essex lets you manage namespace mappings by mapping, hiding, and
destroying ( $namespace => $prefix ) pairs using the functions:
=over
=cut
=item namespace_map
aka: ns_map
my $map = ns_map(
$ns1 => $prefix1,
$ns2 => $prefix2,
...
);
Creates a new set of mappings in addition to any that are already in
effect. If a namespace is mapped to multiple prefixes, the last one
created is used. The mappings stay in effect until the map objected
referred to by C<$map> is destroyed.
=cut
sub ns_map {
my $self = $XML::Essex::Base::self;
return $self->new( @_ );
}
=back
=head2 Rule Based Processing
It is often advantageous to declare exceptional events that should
be processed as they occur in the stream rather than testing for them
explicitly everywhere they might occur in the script. This is done
using the "on" function.
=cut
=over
=item on
on(
"start_document::*" => sub { warn "start of document reached" },
"end_document::*" => sub { warn "end of document reached" },
);
=for TODO
my $rule = on $pat1 => sub { ... }, ...;
...time passes with rules in effect...
disable_rule $rule;
...time passes with rules I<not> in effect...
enable_rule $rule;
...time passes with rules in effect again...
This declares that a rule should be in effect until the end of the
document
=for TODO or it is disabled.
=for TODO Returns a handle that may be used to enable or disable all
rules passed in.
For now, this must be called before the first get() for predictable
results.
Rules remain in effect after the main() routine has exited to facilitate
pure rule based processing.
=cut
sub on {
my $self = $XML::Essex::Base::self;
$self->on( @_ );
}
=item xvalue
Returns the result of the expression that fired an action. Valid only
within rules.
=cut
sub xvalue {
my $self = $XML::Essex::Base::self;
$self->xvalue;
}
=item xpush
Returns the result of the expression that fired an action. Valid only
within rules.
=item xpop
Returns the result of the expression that fired an action. Valid only
within rules.
=item xset
Returns the result of the expression that fired an action. Valid only
within rules.
=item xadd
Returns the result of the expression that fired an action. Valid only
within rules.
=cut
sub xpush { XML::Filter::Dispatcher::xpush( @_ ) }
sub xpop { XML::Filter::Dispatcher::xpop( @_ ) }
sub xadd { XML::Filter::Dispatcher::xadd( @_ ) }
sub xset { XML::Filter::Dispatcher::xset( @_ ) }
=back
=head2 Event Constructors
These are exported by :write (in addition to being available individually).
=over
=cut
no warnings "once";
=item chars
aka: characters
=cut
sub characters {
XML::Essex::Event::characters->new( @_ );
}
*chars = \&characters;
=item end_doc
aka: end_document
=cut
sub end_document {
XML::Essex::Event::end_doc->new( @_ );
}
*end_doc = \&end_document;
=item end_elt
aka: end_element
=cut
sub end_element {
XML::Essex::Event::end_element->new( @_ );
}
*end_elt = \&end_element;
=item start_doc
aka: start_document
=cut
sub start_document {
XML::Essex::Event::start_document->new( @_ );
}
*start_doc = \&start_document;
=item start_elt
aka: start_element
=cut
sub start_element {
XML::Essex::Event::start_element->new( @_ );
}
*start_elt = \&start_element;
=item xml_decl
=cut
sub xml_decl {
XML::Essex::Event::xml_decl->new( @_ );
}
=back
=head1 IMPLEMENTATION NOTES
XML::Essex is a source filter that wraps from the C<use> line to the
end of the file in an eval { ... } block.
=head1 LIMITATIONS
Stay tuned.
=head1 COPYRIGHT
Copyright 2002, R. Barrie Slaymaker, Jr., All Rights Reserved
=head1 LICENSE
You may use this module under the terms of the BSD, Artistic, oir GPL licenses,
any version.
=head1 AUTHOR
Barrie Slaymaker <barries@slaysys.com>
=cut
1;