=head1 NAME OODoc::Parser - base class for all OODoc parsers. =head1 INHERITANCE OODoc::Parser is an 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 OVERLOADED =head1 METHODS =head2 Constructors OODoc::Parser-E<gt>B<new>(OPTIONS) =over 4 See L<OODoc::Object/"Constructors"> =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 =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 I<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. I<Warning:> Unknown option $name You have used the option with $name, which is not defined with the instantiation (the C<new> method) of this object. I<Warning:> Unknown options @names You have used more than one option which is not defined to instantiate the object. I<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">. =head1 SEE ALSO This module is part of OODoc distribution version 1.00, built on June 14, 2007. Website: F<http://perl.overmeer.net/oodoc/> =head1 LICENSE Copyrights 2003-2007 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>