NAME

Pod::InputObjects - objects representing POD input streams, paragraphs, etc.

SYNOPSIS

use Pod::InputObjects;

REQUIRES

perl5.003, Exporter, Carp

EXPORTS

Nothing.

DESCRIPTION

This module defines some basic input objects used by Pod::Parser when reading and parsing POD text from an input source. The following objects are defined:

Pod::InputSource

An object corresponding to a source of POD input text. It is mostly a wrapper around a filehandle or IO::Handle-type object (or anything that implements the getline() method) which keeps track of some additional information relevant to the parsing of PODs.

Pod::Paragraph

An object corresponding to a paragraph of POD input text. It may be a plain paragraph, a verbatim paragraph, or a command paragraph (see perlpod).

Pod::InteriorSequence

An object corresponding to an interior sequence command from the POD input text (see perlpod).

Each of these input objects are described in further detail in the sections which follow.

Pod::InputSource

This object corresponds to an input source or stream of POD documentation. When parsing PODs, it is necessary to associate and store certain context information with each input source. All of this information is kept together with the stream itself in one of these Pod::InputSource objects. Each such object is merely a wrapper around an IO::Handle object of some kind (or at least something that implements the getline() method). They have the following methods/attributes:

new()

my $pod_input1 = Pod::InputSource->new(-handle => $filehandle);
my $pod_input2 = new Pod::InputSource(-handle => $filehandle,
                                      -name   => $name);
my $pod_input3 = new Pod::InputSource(-handle => \*STDIN);
my $pod_input4 = Pod::InputSource->new(-handle => \*STDIN,
                                       -name => "(STDIN)");

This is a class method that constructs a Pod::InputSource object and returns a reference to the new input source object. It takes one or more keyword arguments in the form of a hash. The keyword -handle is required and designates the corresponding input handle. The keyword -name is optional and specifies the name associated with the input handle (typically a file name).

getline()

my $textline = $pod_input->getline();

This method behaves exactly like the getline() function for an IO::Handle or FileHandle object. See IO::Handle and FileHandle for more details.

name()

my $filename = $pod_input->name();
$pod_input->name($new_filename_to_use);

This method gets/sets the name of the input source (usually a filename). If no argument is given, it returns a string containing the name of the input source; otherwise it sets the name of the input source to the contents of the given argument.

handle()

my $handle = $pod_input->handle();

Returns a reference to the handle object from which input is read (the one used to contructed this input source object).

num_lines()

my $line_number = $pod_input->num_lines();

Returns the number of input lines read from input source object (since the time it was contructed).

was_cutting()

print "Yes.\n" if ($pod_input->was_cutting());

The value of the cutting state (that the cutting() method would have returned) immediately before any input was read from this input stream. After all input from this stream has been read, the cutting state is restored to this value.

Pod::Paragraph

An object representing a paragraph of POD input text. It has the following methods/attributes:

new()

my $pod_para1 = Pod::Paragraph->new(-text => $text);
my $pod_para2 = Pod::Paragraph->new(-name => $cmd,
                                    -text => $text);
my $pod_para3 = new Pod::Paragraph(-text => $text);
my $pod_para2 = new Pod::Paragraph(-name => $cmd,
                                   -text => $text);

This is a class method that constructs a Pod::Paragraph object and returns a reference to the new paragraph object. It may be given one or two keyword arguments. The -text keyword indicates the corresponding text of the POD paragraph. The -name keyword indicates the name of the corresponding POD command, such as head1 or item (it should not contain the = prefix); this is needed only if the POD paragraph corresponds to a command paragraph.

cmd_name()

my $para_cmd = $pod_para->cmd_name();

If this paragraph is a command paragraph, then this method will return the name of the command (without any leading = prefix).

text()

my $para_text = $pod_para->text();

This method will return the corresponding text of the paragraph.

raw_text()

my $raw_pod_para = $pod_para->raw_text();

This method will return the raw text of the POD paragraph, exactly as it appeared in the input.

cmd_prefix()

my $prefix = $pod_para->cmd_prefix();

If this paragraph is a command paragraph, then this method will return the prefix used to denote the command (which should be the string "=").

cmd_separator()

my $separator = $pod_para->cmd_separator();

If this paragraph is a command paragraph, then this method will return the text used to separate the command name from the rest of the paragraph (if any).

Pod::InteriorSequence

An object representing a POD interior sequence command. It has the following methods/attributes:

new()

my $pod_seq1 = Pod::InteriorSequence->new(-name => $cmd,
                                          -text => $text);
my $pod_seq2 = new Pod::InteriorSequence(-name => $cmd,
                                         -text => $text);

This is a class method that constructs a Pod::InteriorSequence object and returns a reference to the new interior sequence object. It should be given two keyword arguments. The -text keyword indicates the corresponding text of the POD paragraph, The -name keyword indicates the name of the corresponding interior sequence command, such as I or B or C.

cmd_name()

my $seq_cmd = $pod_seq->cmd_name();

The name of the interior sequence command.

text()

my $seq_text = $pod_seq->text();

The text of the interior sequence (this is what the command will modify or massage in some manner).

list()

  my $seq_ref  = $pod_seq->list();
or
  my @seq_list = $pod_seq->list();

The list of things in the interior sequence (this is what the command will modify or massage in some manner).

raw_text()

my $seq_raw_text = $pod_seq->raw_text();

This method will return the raw text of the POD interior sequence, exactly as it appeared in the input.

left_delimiter()

my $ldelim = $pod_seq->left_delimiter();

The leftmost delimiter beginning the argument text to the interior sequence (should be "<").

right_delimiter()

The rightmost delimiter beginning the argument text to the interior sequence (should be ">").

SEE ALSO

See Pod::Parser, Pod::Select, and Pod::Callbacks.

AUTHOR

Brad Appleton <bradapp@enteract.mot.com>