=encoding utf8

=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> (markov)

The Markov parser understands standard POD, but adds logical markup tags
and C<M> and C<P> links.

=back

Extends L<"DESCRIPTION" in OODoc::Object|OODoc::Object/"DESCRIPTION">.

=head1 OVERLOADED

Extends L<"OVERLOADED" in OODoc::Object|OODoc::Object/"OVERLOADED">.

=over 4

=item overload: B<'==' and '!=' (numeric comparison)>

Inherited, see L<OODoc::Object/"OVERLOADED">

=item overload: B<'bool'>

Inherited, see L<OODoc::Object/"OVERLOADED">

=back

=head1 METHODS

Extends L<"METHODS" in OODoc::Object|OODoc::Object/"METHODS">.

=head2 Constructors

Extends L<"Constructors" in OODoc::Object|OODoc::Object/"Constructors">.

=over 4

=item $class-E<gt>B<new>(%options)

Inherited, see L<OODoc::Object/"Constructors">

 -Option    --Default
  skip_links  undef
  syntax      'markov'

=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.

=item syntax => PACKAGE|$name

=back

=back

=head2 Attributes

Extends L<"Attributes" in OODoc::Object|OODoc::Object/"Attributes">.

=over 4

=item $obj-E<gt>B<unique>()

Inherited, see L<OODoc::Object/"Attributes">

=back

=head2 Manual Repository

Extends L<"Manual Repository" in OODoc::Object|OODoc::Object/"Manual Repository">.

=over 4

=item $obj-E<gt>B<addManual>($manual)

Inherited, see L<OODoc::Object/"Manual Repository">

=item $obj-E<gt>B<findManual>($name)

Inherited, see L<OODoc::Object/"Manual Repository">

=item $obj-E<gt>B<mainManual>($name)

Inherited, see L<OODoc::Object/"Manual Repository">

=item $obj-E<gt>B<manuals>()

Inherited, see L<OODoc::Object/"Manual Repository">

=item $obj-E<gt>B<manualsForPackage>($name)

Inherited, see L<OODoc::Object/"Manual Repository">

=item $obj-E<gt>B<packageNames>()

Inherited, see L<OODoc::Object/"Manual Repository">

=item $obj-E<gt>B<publicationIndex>()

Inherited, see L<OODoc::Object/"Manual Repository">

=item $obj-E<gt>B<publish>(\%options)

Inherited, see L<OODoc::Object/"Manual Repository">

=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 => $file

The name of the input C<$file>.

=item output => $file

Where to write the produced code to.  If no C<$file> is specified, the
platform dependend black hole is used (F</dev/null> on UNIX).

=back

=back

=head2 Producing manuals

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<cleanupPod()|OODoc::Parser/"Producing manuals"> or L<cleanupHtml()|OODoc::Parser/"Producing manuals"> is called
for the final touch for the requested output markup.

=over 4

=item $obj-E<gt>B<cleanupHtml>($manual, $text, %options)

Translate the C<$text> block, which is written in the parser specific
syntax into HTML.  This is a better quality HTML than the HTML
produced from POD, as f.i. metacpan displays.

 -Option     --Default
  create_link  <required>
  is_html      false

=over 2

=item create_link => CODE

See L<OODoc::Format::cleanup(create_link)|OODoc::Format/"Page generation">.

=item is_html => BOOLEAN

Some changes will not be made when C<is_html> is C<true>, for instance,
a "E<lt>" will stay that way, not being translated in a "E<amp>lt;".

=back

=item $obj-E<gt>B<cleanupPod>($manual, $text, %options)

Translate the C<$text> block, which is written in the parser specific
syntax (which may resemble native Perl POD) into real Perl POD.

 -Option     --Default
  create_link  <required>

=over 2

=item create_link => CODE

See L<OODoc::Format::cleanup(create_link)|OODoc::Format/"Page generation">.

=back

=item $obj-E<gt>B<finalizeManual>($manual, %options)

[3.01] The parser gets a last chance to work on C<$manual> documentation,
after all documents have been collected and intergrated.

=item $obj-E<gt>B<skipManualLink>($package)

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

=back

=head1 DIAGNOSTICS

=over 4

=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 version 3.02,
built on August 15, 2025. Website: F<https://perl.overmeer.net/oodoc/>

=head1 LICENSE

For contributors see file ChangeLog.

This software is copyright (c) 2003-2025 by Mark Overmeer.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

