NAME

Perldoc::Parser - parse Perldoc input documents to events

SYNOPSIS

  use Perldoc::Parser;

  my $parser = Perldoc::Parser->create_parser("kwid");

  my $dom = Perldoc::DOM->new();
  $parser->receiver($dom);

  my $reader = Perldoc::Reader->new();
  $parser->reader($reader);

  $parser->send_all;   # or ->parse()

DESCRIPTION

A Perldoc parser is something that uses a reader to send events.

SKELETON SUB-CLASS API

To make a sub-class of the Perldoc parser that parses an arbitrary file format, just define send_one() in your sub-class (see Perldoc::Sender). This method should read characters from $self->reader, and put back anything it doesn't consume.

PERLDOC SUB-CLASS API

However, to be a true Perldoc dialect, it should do a little more than that. Perldoc documents support nested parsers and dialects, but the Perldoc::Sender API requires that only a single object is used to send events.

In this case, you would define just parse_one()

__PACKAGE__->register($type)

This registers the type of your parser with the Perldoc::Parser parser factory. This should be called when the module for your dialect loads.

This can be called explicitly as;

  Perldoc::Parser::register($package, $type)

In that case, the $package will be automatically required the first time a document or fragment of that type is processed.

->parser_class($type)

Returns what package is registered to the passed type, if any.

->create_parser($type, @newopts)

This constructor, which may be called as a class or object method, creates a new Parser of the designated type.

Anything after the $type is passed to the constructor of the new parser.

->child_parser($type, @newopts)

A variant on the above constructor, this one automatically marks the new parser as being a child of this one, and passes through the reader. It also sets the new parser as being the current recipient for receiving events.

This is only available as an object method. This is typically used when switching dialects.

->resign()

This causes a child parser to finish parsing and pass control to the parent parser's send_one() method.