=head1 NAME

OODoc::Parser - base class for all OODoc parsers.

=head1 INHERITANCE

 OODoc::Parser
   is a OODoc::Object

 OODoc::Parser is extended by
   OODoc::Parser::Markov

=head1 SYNOPSIS

 # Never instantiated directly.

=head1 DESCRIPTION

A parser is used to process files which contain POD or contain code:
their filename extension is C<pod>, C<pm>, or C<pl> (actually, this
can be configured).

Currently distributed parsers:

=over 4

=item * L<OODoc::Parser::Markov|OODoc::Parser::Markov>

The Markov parser understands standard POD, but adds logical markup tags
and the C<M&lt;&gt;> links.

=back

=head1 OVERLOADED

=head1 METHODS

=head2 Constructors

OODoc::Parser-E<gt>B<new>(OPTIONS)

=over 4

 Option    --Default
 skip_links  undef

. skip_links => ARRAY|REGEXP|STRING

=over 4

The parser should not attempt to load modules which match the REGEXP
or are equal or sub-namespace of STRING.  More than one of these
can be passed in an ARRAY.

=back

=back

=head2 Inheritance knowledge

$obj-E<gt>B<extends>([OBJECT])

=over 4

See L<OODoc::Object/"Inheritance knowledge">

=back

=head2 Parsing a file

$obj-E<gt>B<parse>(OPTIONS)

=over 4

Parse the specified input file into a code file and an object tree which
describes the pod.  Returned is a list of package objects which contain
the docs found in this file.

 Option--Default
 input   <required>
 output  <black hole>

. input => FILENAME

=over 4

The name of the input file.

=back

. output => FILENAME

=over 4

Where to write the produced code to.  If no filename is specified, the
platform dependend black hole is used (/dev/null on UNIX).

=back

=back

=head2 Formatting text pieces

After the manuals have been parsed into objects, the information can
be formatted in various ways, for instance into POD and HTML.  However,
the parsing is not yet complete: the structure has been decomposed 
with L<parse()|OODoc::Parser/"Parsing a file">, but the text blocks not yet.  This is because the
transformations which are needed are context dependent.  For each
text section L<cleanup()|OODoc::Parser/"Formatting text pieces"> is called for the final touch.

$obj-E<gt>B<cleanup>(FORMATTER, MANUAL, STRING)

=over 4

=back

$obj-E<gt>B<skipManualLink>(PACKAGE)

=over 4

Returns true is the PACKAGE name matches one of the links to be
skipped, set by L<new(skip_links)|OODoc::Parser/"Constructors">.

=back

=head2 Commonly used functions

$obj-E<gt>B<filenameToPackage>(FILENAME)

OODoc::Parser-E<gt>B<filenameToPackage>(FILENAME)

=over 4

See L<OODoc::Object/"Commonly used functions">

=back

$obj-E<gt>B<mkdirhier>(DIRECTORY)

OODoc::Parser-E<gt>B<mkdirhier>(DIRECTORY)

=over 4

See L<OODoc::Object/"Commonly used functions">

=back

=head2 Manual Repository

$obj-E<gt>B<addManual>(MANUAL)

=over 4

See L<OODoc::Object/"Manual Repository">

=back

$obj-E<gt>B<mainManual>(NAME)

=over 4

See L<OODoc::Object/"Manual Repository">

=back

$obj-E<gt>B<manual>(NAME)

=over 4

See L<OODoc::Object/"Manual Repository">

=back

$obj-E<gt>B<manuals>

=over 4

See L<OODoc::Object/"Manual Repository">

=back

$obj-E<gt>B<manualsForPackage>(NAME)

=over 4

See L<OODoc::Object/"Manual Repository">

=back

$obj-E<gt>B<packageNames>

=over 4

See L<OODoc::Object/"Manual Repository">

=back

=head1 DIAGNOSTICS

Error: The formatter type $class is not known for cleanup

=over 4

Text blocks have to get the finishing touch in the final formatting
phase.  The parser has to fix the text block segments to create a
formatter dependent output.  Only a few formatters are predefined.

=back

Error: manual definition requires manual object

=over 4

A call to L<addManual()|OODoc::Object/"Manual Repository"> expects a new manual object (a L<OODoc::Manual|OODoc::Manual>),
however an incompatible thing was passed.  Usually, intended was a call
to L<manualsForPackage()|OODoc::Object/"Manual Repository"> or L<mainManual()|OODoc::Object/"Manual Repository">.

=back

=head1 SEE ALSO

This module is part of OODoc distribution version 1.05,
built on January 26, 2009. Website: F<http://perl.overmeer.net/oodoc/>

=head1 LICENSE

Copyrights 2003-2009 by Mark Overmeer. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See F<http://www.perl.com/perl/misc/Artistic.html>