1 #

     2 # Copyright (C) 1999 Ken MacLeod

     3 # XML::Handler::XMLWriter is free software; you can redistribute it and/or

     4 # modify it under the same terms as Perl itself.

     5 #

     6 # $Id: Subs.pm,v 1.2 1999/12/22 21:15:00 kmacleod Exp $

     7 #

     8 

     9 use strict;

    10 

    11 package XML::Handler::Subs;

    12 

    13 use UNIVERSAL;

    14 

    15 use vars qw{ $VERSION };

    16 

    17 # will be substituted by make-rel script

    18 $VERSION = "0.07";

    19 

    20 sub new {

    21     my $type = shift;

    22     my $self = ($#_ == 0) ? { %{ (shift) } } : { @_ };

    23 

    24     return bless $self, $type;

    25 }

    26 

    27 sub start_document {

    28     my ($self, $document) = @_;

    29 

    30     $self->{Names} = [];

    31     $self->{Nodes} = [];

    32 }

    33 

    34 sub end_document {

    35     my ($self, $document) = @_;

    36 

    37     delete $self->{Names};

    38     delete $self->{Nodes};

    39 

    40     return();

    41 }

    42 

    43 sub start_element {

    44     my ($self, $element) = @_;

    45 

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

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

    48 

    49     my $el_name = "s_" . $element->{Name};

    50     $el_name =~ s/[^a-zA-Z0-9_]/_/g;

    51     if ($self->can($el_name)) {

    52 	$self->$el_name($element);

    53 	return 1;

    54     }

    55 

    56     return 0;

    57 }

    58 

    59 sub end_element {

    60     my ($self, $element) = @_;

    61 

    62     my $called_sub = 0;

    63     my $el_name = "e_" . $element->{Name};

    64     $el_name =~ s/[^a-zA-Z0-9_]/_/g;

    65     if ($self->can(${el_name})) {

    66 	$self->$el_name($element);

    67 	$called_sub = 1;

    68     }

    69 

    70     pop @{$self->{Names}};

    71     pop @{$self->{Nodes}};

    72 

    73     return $called_sub;

    74 }

    75 

    76 sub in_element {

    77     my ($self, $name) = @_;

    78 

    79     return ($self->{Names}[-1] eq $name);

    80 }

    81 

    82 sub within_element {

    83     my ($self, $name) = @_;

    84 

    85     my $count = 0;

    86     foreach my $el_name (@{$self->{Names}}) {

    87 	$count ++ if ($el_name eq $name);

    88     }

    89 

    90     return $count;

    91 }

    92 

    93 1;

    94 

    95 __END__

    96 

    97 =head1 NAME

    98 

    99 XML::Handler::Subs - a PerlSAX handler base class for calling user-defined subs

   100 

   101 =head1 SYNOPSIS

   102 

   103  use XML::Handler::Subs;

   104 

   105  package MyHandlers;

   106  use vars qw{ @ISA };

   107 

   108  sub s_NAME { my ($self, $element) = @_ };

   109  sub e_NAME { my ($self, $element) = @_ };

   110 

   111  $self->{Names};    # an array of names

   112  $self->{Nodes};    # an array of $element nodes

   113 

   114  $handler = MyHandlers->new();

   115  $self->in_element($name);

   116  $self->within_element($name);

   117 

   118 =head1 DESCRIPTION

   119 

   120 C<XML::Handler::Subs> is a base class for PerlSAX handlers.

   121 C<XML::Handler::Subs> is subclassed to implement complete behavior and

   122 to add element-specific handling.

   123 

   124 Each time an element starts, a method by that name prefixed with `s_'

   125 is called with the element to be processed.  Each time an element

   126 ends, a method with that name prefixed with `e_' is called.  Any

   127 special characters in the element name are replaced by underscores.

   128 

   129 Subclassing XML::Handler::Subs in this way is similar to

   130 XML::Parser's Subs style.

   131 

   132 XML::Handler::Subs maintains a stack of element names,

   133 `C<$self->{Names}', and a stack of element nodes, `C<$self->{Nodes}>'

   134 that can be used by subclasses.  The current element is pushed on the

   135 stacks before calling an element-name start method and popped off the

   136 stacks after calling the element-name end method.  The

   137 `C<in_element()>' and `C<within_element()>' calls use these stacks.

   138 

   139 If the subclass implements `C<start_document()>', `C<end_document()>',

   140 `C<start_element()>', and `C<end_element()>', be sure to use

   141 `C<SUPER::>' to call the the superclass methods also.  See perlobj(1)

   142 for details on SUPER::.  `C<SUPER::start_element()>' and

   143 `C<SUPER::end_element()>' return 1 if an element-name method is

   144 called, they return 0 if no method was called.

   145 

   146 XML::Handler::Subs does not implement any other PerlSAX handlers.

   147 

   148 XML::Handler::Subs supports the following methods:

   149 

   150 =over 4

   151 

   152 =item new( I<OPTIONS> )

   153 

   154 A basic `C<new()>' method.  `C<new()>' takes a list of key, value

   155 pairs or a hash and creates and returns a hash with those options; the

   156 hash is blessed into the subclass.

   157 

   158 =item in_element($name)

   159 

   160 Returns true if `C<$name>' is equal to the name of the innermost

   161 currently opened element.

   162 

   163 =item within_element($name)

   164 

   165 Returns the number of times the `C<$name>' appears in Names.

   166 

   167 =back

   168 

   169 =head1 AUTHOR

   170 

   171 Ken MacLeod, ken@bitsko.slc.ut.us

   172 

   173 =head1 SEE ALSO

   174 

   175 perl(1), PerlSAX.pod(3)

   176 

   177 =cut