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
1 POD Error
The following errors were encountered while parsing the POD:
- Around line 91:
=over without closing =back