view release on metacpan or  search on metacpan

Data/Stag.pm  view on Meta::CPAN

is placed back into the tree

For example, for a a parser/generator that fires events with the
following tree form

  <person>
    <name>foo</name>
    ...
  </person>

we can create a handler that writes person/name like this:

  $h = Data::Stag->makehandler(
                               person => sub { my ($self,$stag) = @_;
                                               print $stag->name;
                                               return $stag; # dont change tree
                                             });
  $stag = Data::Stag->parse(-str=>"(...)", -handler=>$h)

See L<Data::Stag::BaseHandler> for details on handlers
  
=head3 getformathandler

       Title: getformathandler

        Args: format str OR L<Data::Stag::BaseHandler>
     Returns: L<Data::Stag::BaseHandler>
     Example: $h = Data::Stag->getformathandler('xml');
              $h->file("my.xml");
              Data::Stag->parse(-fn=>$fn, -handler=>$h);

Creates a Stag event handler - this handler can be passed to an event
generator / parser. Built in handlers include:

=over

=item xml

Generates xml tags from events

=item sxpr

Generates S-Expressions from events

=item itext

Generates itext format from events

=item indent

Generates indent format from events

=back

All the above are kinds of L<Data::Stag::Writer>

=head3 chainhandler

       Title: chainhandler

        Args: blocked events - str or str[]
              initial handler - handler object
              final handler - handler object
     Returns: 
     Example: $h = Data::Stag->chainhandler('foo', $processor, 'xml')

chains handlers together - for example, you may want to make
transforms on an event stream, and then pass the event stream to
another handler - for example, and xml handler

  $processor = Data::Stag->makehandler(
				       a => sub { my ($self,$stag) = @_;
						  $stag->set_foo("bar");
                                                  return $stag
                                                },
				       b => sub { my ($self,$stag) = @_;
						  $stag->set_blah("eek");
                                                  return $stag
                                                },
                                       );
  $chainh = Data::Stag->chainhandler(['a', 'b'], $processor, 'xml');
  $stag = Data::Stag->parse(-str=>"(...)", -handler=>$chainh)

If the inner handler has a method CONSUMES(), this method will
determine the blocked events if none are specified.

see also the script B<stag-handle.pl>


=head2  RECURSIVE SEARCHING


=head3 find (f)

       Title: find
     Synonym: f

        Args: element str
     Returns: node[] or ANY
     Example: @persons = stag_find($struct, 'person');
     Example: @persons = $struct->find('person');

recursively searches tree for all elements of the given type, and
returns all nodes or data elements found.

if the element found is a non-terminal node, will return the node
if the element found is a terminal (leaf) node, will return the data value

the element argument can be a path

  @names = $struct->find('department/person/name');

will find name in the nested structure below:

  (department
   (person
    (name "foo")))


=head3 findnode (fn)

       Title: findnode
     Synonym: fn

        Args: element str
     Returns: node[]
     Example: @persons = stag_findnode($struct, 'person');
     Example: @persons = $struct->findnode('person');

recursively searches tree for all elements of the given type, and
returns all nodes found.

paths can also be used (see B<find>)

=head3 findval (fv)

       Title: findval
     Synonym: fv

        Args: element str
     Returns: ANY[] or ANY
     Example: @names = stag_findval($struct, 'name');
     Example: @names = $struct->findval('name');
     Example: $firstname = $struct->findval('name');