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;

1 while $sender->send_one;

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

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

METHODS

send_to($object)

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

$object straight away, or pass the next events it receives.

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.

SUB-CLASS API

The below method is used for sending by sub-classes of this module.

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

Sends an event to the configured receiver.

Allowable events are;

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