NAME

OODoc::Export - base-class for exporters

INHERITANCE

OODoc::Export
  is an OODoc::Object

OODoc::Export is extended by
  OODoc::Export::JSON

SYNOPSIS

my $doc = OODoc->new(...);
$doc->export('json');

DESCRIPTION

This base-class organizes export transformations which can be shared between serialization formats.

Current serialization formats:

OODoc::Export::JSON

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
 markup      <required>
 serializer  <required>

markup => $markup: Specifies the markup style for the output. At the moment, only markup in 'html' is supported. See accessor markupStyle().
serializer => $name: At the moment, only serializer 'json' is supported.

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

Atributes

$obj->format()
$obj->markupStyle()
$obj->parser()
$obj->serializer(): The label for this serializer.

Output

$obj->boolean(BOOL)

$obj->markup(STRING)

The source string is to be considered as foreign to the input markup format, so no (pseudo-)POD.

$obj->markupBlock($text, %args)

Convert a block of text, which still contains markup.

$obj->markupString($string, %args)

Convert a line of text, which still contains markup. This sometimes as some differences with a markupBlock().

$obj->podChapters($pod)

$obj->processingManual($manual|undef)

Manual pages may be written in different syntaxes. In the document tree, the main structure is parsed, but the text blocks are not: they are only processed at output time. Calling this method sets the interpretation mode for text blocks.

$obj->tree($doc, %options)

Convert the documentation data in a beautiful tree.

-Option       --Default
 distributions  +{}
 exporter       <required>
 manuals        undef
 meta           +{}
 podtail        undef

distributions => HASH: Name to MYMETA.json content mappings of project and used distributions.
exporter => OODoc::Export-object: Manages the conversion from source markup for text into the requested markup (f.i. "markov" into "html").
manuals => ARRAY: Include only information for the manuals (specified as names).
meta => HASH: Key/string pairs with interesting additional data.
podtail => POD: The last chapters of any produced manual page, in POD syntax.

DETAILS

The exporters will each create the same data tree, but implement different serializations.

In the following examples, magnifactured JSON dumps are shown. Be aware the JSON does not sort fields, so your output looks less organized.

the Tree

The data-structure refers to a few capitalized comments:

MARKUP: The output markup used for text. Currently only "html" is supported.
META: Distribution meta-data, as provided by its MYMETA.json.
SAFE: No HTML, but does never contain any HTML conflicting data. Is does not contain links.

root

The root:

{ "project": "MailBox",                      # MARKUP
  "distribution": "Mail-Box",                # SAFE
  "version": "4.01_12",                      # SAFE

  "generated_by" : {
     "program": "oodist",                    # SAFE
     "program_version": "3.14",              # SAFE
     "oodoc_version": "3.00",                # SAFE
     "created": "2025-07-27 16:30"           # SAFE
  },
  "distributions": {
     "Mail-Box": { ... },                    # META
     "Mail-Message": { ... }                 # META
  },
  "manuals": {
     "Mail::Message": "id42",                # REF
     "Mail::Message::Field": "id1023"        # REF
  },
  "index": {
     "id42": { ... },
     "id1023": { ... }
  }
}

Distributions

Each HASH in the distributions, is a full copy of the MYMETA.json for a distribution which belongs to the project or is used by any distribution which is part of the project.

Some of the important fields:

{ "name": "Mail-Box",                        # SAFE
  "abstract": "Manage a mailbox",            # MARKUP
  "version": "3.14"                          # SAFE
}

Take a look at the MYMETA.json or META.json for any module which is produced with OODoc, for instance OODoc itself at https://metacpan.org/XXX

Manual

{ "id": REF,
  "name": "Mail::Box",                       # MARKUP
  "version": "3.14",                         # or undef
  "title": "Manage a mailbox",               # MARKUP
  "package": "lib/Mail/Box.pm",              # SAFE
  "distribution": "Mail-Box",                # SAFE
  "is_pure_pod": false,                      # BOOLEAN
  "inheritance": \%interitance,              # see below
  "chapters": [ REF, ... ]
}

The chapters are sorted logically, as they appear in traditional unix manual pages, with a few extensions.

Inheritance

The manual contains a details inheritance relationship structure, which MAY use the following fields:

{ "extends": [ CLASS, ... ],                 # parent class(es)
  "extended_by": [ CLASS, ... ],             # extension class(es)
  "extra_code_for": PACKAGE,                 # package != filename
  "extra_code_in": [ PACKAGE, ... ],         # dynamically loaded code
  "realizes": CLASS,                         # see Object::Realize::Later
  "realized_by": [ CLASS, ... ],             #   "
}

Objects which extend Object::Realize::Later are placeholders, which can become real objects when they are used. It's a beautiful trick, hence supported here.

One of the most extensive uses of this structure is Mail::Message::Body.

Nested blocks of text

Manuals are a collection of chapters, which can contain sections, which may have subsections, which on their turn can carry subsubsections. So: the manuals are a list of nested blocks.

Each (text) block has same features:

{ "id": REF,                                 # SAFE
  "name": "Constructors",                    # MARKUP
  "level": 2,                                # SAFE
  "type": "section",                         # SAFE
  "extends": REFERENCE,                      #XXX TODO
  "intro": "Intro to this section.",         # MARKUP
  "examples": [ REF, ... ],
  "subroutines": [ REF, ... ],
  "nest": [ REF, ... ],                      # sub-blocks
}

The examples, subroutines and nested blocks are to be kept in their order.

The description and examples are about the content of the whole block. Subroutines will also have specific descriptions and examples.

Subroutines

There are a few types of subroutines:

function, the classical 'sub'
i_method, instance method (in the docs also as =method)
c_method, class method
ci_method, both usable as class or instance method
overload, describes overloading
tie, tied interface

Each subroutine looks like this:

{ "id": REF,                               # SAFE
  "name": "producePages",                  # MARKUP
  "call": "$obj->producePages()" ],        # MARKUP
  "type": "i_method",                      # MARKUP
  "intro": "Create the manual ...",        # MARKUP
  "examples": [ REF, ... ],
  "options: [ REF, ... ],
  "diagnostics": [ REF, ... ],
}

Options

Most subroutine forms can have options. They are passed as list sorted by name.

{ "id": REF,                               # SAFE
  "name": "beautify",                      # MARKUP
  "type": "option",                        # SAFE
  "params": "true|false",                  # MARKUP
  "intro": "Make the output better"        # MARKUP
}

The defaults look like this:

{ "id": REF,                               # SAFE
  "name": "beautify",                      # MARKUP
  "type": "default",                       # SAFE
  "value": "<true>",                       # MARKUP
}

The option is required when the default value is <required>.

Examples

Every block of text, and every subroutine can have a number of examples. Examples do not always have a name.

{ "id": REF,                               # SAFE
  "name": "how to produce pages",          # MARKUP
  "type": "example",                       # SAFE
  "intro": "Like this"                     # MARKUP
}

Diagnostics

Most subroutine forms can have a list of diagnostics, which are sorted errors first, then by description text. Other types of diagnostics will be added soon, to match the levels offered by Log::Report.

{ "id": REF,                               # SAFE
  "type": "error"/"warning"/"info"...,     # SAFE
  "name": "Missing ...",                   # MARKUP
  "intro: "This error is shown when...",   # MARKUP
  "subroutine": REF,
}

DIAGNOSTICS

Error: exporter $name has compilation errors: $err
Error: exporter serializer '$name' is unknown.
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().
Error: only HTML markup is currently supported.

LICENSE

For contributors see file ChangeLog.

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

To install OODoc, copy and paste the appropriate command in to your terminal.

cpanm

cpanm OODoc

CPAN shell

perl -MCPAN -e shell
install OODoc

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)