/ 
OODoc-3.02
River stage zero No dependents
/ OODoc::Parser

NAME

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

INHERITANCE

OODoc::Parser
  is an OODoc::Object

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

SYNOPSIS

# Never instantiated directly.

DESCRIPTION

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

Currently distributed parsers:

  • OODoc::Parser::Markov (markov)

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

Extends "DESCRIPTION" in OODoc::Object.

OVERLOADED

Extends "OVERLOADED" in OODoc::Object.

overload: '==' and '!=' (numeric comparison)

Inherited, see "OVERLOADED" in OODoc::Object

overload: 'bool'

Inherited, see "OVERLOADED" in OODoc::Object

METHODS

Extends "METHODS" in OODoc::Object.

Constructors

Extends "Constructors" in OODoc::Object.

$class->new(%options)

Inherited, see "Constructors" in OODoc::Object

-Option    --Default
 skip_links  undef
 syntax      'markov'

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.

syntax => PACKAGE|$name

Attributes

Extends "Attributes" in OODoc::Object.

$obj->unique()

Inherited, see "Attributes" in OODoc::Object

Manual Repository

Extends "Manual Repository" in OODoc::Object.

$obj->addManual($manual)

Inherited, see "Manual Repository" in OODoc::Object

$obj->findManual($name)

Inherited, see "Manual Repository" in OODoc::Object

$obj->mainManual($name)

Inherited, see "Manual Repository" in OODoc::Object

$obj->manuals()

Inherited, see "Manual Repository" in OODoc::Object

$obj->manualsForPackage($name)

Inherited, see "Manual Repository" in OODoc::Object

$obj->packageNames()

Inherited, see "Manual Repository" in OODoc::Object

$obj->publicationIndex()

Inherited, see "Manual Repository" in OODoc::Object

$obj->publish(\%options)

Inherited, see "Manual Repository" in OODoc::Object

Parsing a file

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

The name of the input $file.

output => $file

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

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 parse(), but the text blocks not yet. This is because the transformations which are needed are context dependent.

For each text section cleanupPod() or cleanupHtml() is called for the final touch for the requested output markup.

$obj->cleanupHtml($manual, $text, %options)

Translate the $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

See OODoc::Format::cleanup(create_link).

is_html => BOOLEAN

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

$obj->cleanupPod($manual, $text, %options)

Translate the $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>

See OODoc::Format::cleanup(create_link).

$obj->finalizeManual($manual, %options)

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

$obj->skipManualLink($package)

Returns true if the $package name matches one of the links to be skipped, set by new(skip_links).

DIAGNOSTICS

Error: manual definition requires manual object

A call to addManual() expects a new manual object (a OODoc::Manual), however an incompatible thing was passed. Usually, intended was a call to manualsForPackage() or mainManual().

SEE ALSO

This module is part of OODoc version 3.02, built on August 15, 2025. Website: https://perl.overmeer.net/oodoc/

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.