=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<>> links.
=back
=head1 METHODS
=head2 Constructors
=over 4
=item OODoc::Parser-E<gt>B<new>(OPTIONS)
-Option --Default
skip_links undef
=over 2
=item skip_links => ARRAY|REGEXP|STRING
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
=over 4
=item $obj-E<gt>B<extends>([OBJECT])
See L<OODoc::Object/"Inheritance knowledge">
=back
=head2 Parsing a file
=over 4
=item $obj-E<gt>B<parse>(OPTIONS)
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>
=over 2
=item input => FILENAME
The name of the input file.
=item output => FILENAME
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.
=over 4
=item $obj-E<gt>B<cleanup>(FORMATTER, MANUAL, STRING)
=item $obj-E<gt>B<skipManualLink>(PACKAGE)
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
=over 4
=item $obj-E<gt>B<filenameToPackage>(FILENAME)
=item OODoc::Parser-E<gt>B<filenameToPackage>(FILENAME)
See L<OODoc::Object/"Commonly used functions">
=item $obj-E<gt>B<mkdirhier>(DIRECTORY)
=item OODoc::Parser-E<gt>B<mkdirhier>(DIRECTORY)
See L<OODoc::Object/"Commonly used functions">
=back
=head2 Manual Repository
=over 4
=item $obj-E<gt>B<addManual>(MANUAL)
See L<OODoc::Object/"Manual Repository">
=item $obj-E<gt>B<mainManual>(NAME)
See L<OODoc::Object/"Manual Repository">
=item $obj-E<gt>B<manual>(NAME)
See L<OODoc::Object/"Manual Repository">
=item $obj-E<gt>B<manuals>()
See L<OODoc::Object/"Manual Repository">
=item $obj-E<gt>B<manualsForPackage>(NAME)
See L<OODoc::Object/"Manual Repository">
=item $obj-E<gt>B<packageNames>()
See L<OODoc::Object/"Manual Repository">
=back
=head1 DIAGNOSTICS
=over 4
=item Error: The formatter type $class is not known for cleanup
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.
=item Error: manual definition requires manual object
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 2.00,
built on January 11, 2013. Website: F<http://perl.overmeer.net/oodoc/>
=head1 LICENSE
Copyrights 2003-2013 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>