NAME

Perldoc::Sender - a description of how to `send' parse events

SYNOPSIS

  # get a sender from a sub-class constructor, like a Parser
  my $reader = Perldoc::Reader->new( file => $filename );
  my $sender = Perldoc::Parser->new( reader => $reader );
  my $receiver = Perldoc::DOM->new();

  # either plumb it up first;
  $sender->receiver($receiver);
  $sender->send_all;

  $sender->restart;

  1 while $sender->send_one;

  # or specify the receiver immediately
  $sender->send_all_to($receiver);

  1 while $sender->send_one_to($receiver);

DESCRIPTION

This class provides utility functions and defines the API for `sending' Perldoc parse events.

Minimally, all a Sender sub-class has to define is the send_one method (plus whatever it needs to get the source of information). It is up to the sub-class how many events are actually sent; however a filter could easily marshall these event bursts to single events if absolutely required.

Senders are always started with the send_all method.

If you use the sub-class API provided in this module, then the events you send will automatically be correctly balanced. This does mean that send_one() might actually send more that one event at a time as those extra events are inserted into the event stream.

Also, the utility functions provided by this module do not give you a re-entrant sender. Even the send_all method cannot be safely used re-entrantly. That means you must not try to use the same object in more than one stream simultaneously; wait for it to finish, you impatient lout! :)

Of course, you don't need to use this module to successfully send events to Perldoc::Receiver classes. See Perldoc::Receiver for more.

This module requires Spiffy, and uses Spiffy to create accessors - but does not turn sub-classes of this module into Spiffy sub-classes.

METHODS

receiver($object)

Sends all events to the specified place. $object must be a (->isa) Perldoc::Receiver. Sub-classes should provide this method.

send_all([$from])

This sends all events that this sender can possibly send. If $from is passed, the events will appear to come from that object.

SUB-CLASS API

$self->send_one([$from])

This message asks the sender to send one event. If $from is passed, the events will appear to come from that object (this is important, as only one sender's "send state" can be active at one time).

$self->send($event, @args)

The below method is used by sub-classes of this module to send events to the receiver.

Sends an event to the configured receiver.

Allowable events are;

$self->sendpad([$int])

This method returns a temporary scratch area, which is preserved while the current parent node remains the same. As new elements are output, new scratch areas will be made, and they are closed off, the previous elements' scratch areas are available.

You may optionally pass sendpad() an integer, which tells it to look that many levels up, or return an empty hash that is discarded if you go beyond the "top".

You must have sent at least one element to use sendpad().

This method is most useful for stream-based filters, that need to remember small pieces of state at each logical level and output events accordingly.

start_document({})

This should start the stream. pass a hash of options.

end_document

start_element(name, { name = "foo", ...})>

Start a POD::DOM::Element. name must be set. Note that the

end_element(name)

Close a POD::DOM::Element.

characters(text)

processing_instruction({})

ignorable_whitespace(text)

comment