view release on metacpan or  search on metacpan

README  view on Meta::CPAN

           Title: makehandler

            Args: hash of CODEREFs keyed by element name
                  OR a string containing the name of a module
         Returns: L<Data::Stag::BaseHandler>
         Example: $h = Data::Stag->makehandler(%subs);
         Example: $h = Data::Stag->makehandler("My::FooHandler");

    This creates a Stag event handler. The argument is a hash of subroutines
    keyed by element/node name. After each node is fired by the
    parser/generator, the subroutine is called, passing the handler object
    and the stag node as arguments. whatever the subroutine returns 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 the Data::Stag::BaseHandler manpage for details on handlers

   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:

    xml Generates xml tags from events

    sxpr
        Generates S-Expressions from events

    itext
        Generates indented text from events

    All the above are kinds of the Data::Stag::Writer manpage

   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)

    chains together two handlers (see also the script stag-handle.pl)

  RECURSIVE SEARCHING

   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")))

   findnode (fn)

           Title: findnode
         Synonym: fn

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