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(...);
my $tree = $doc->export('json');

my $export = OODoc::Export::JSON->new(markup => 'html');
my $export = OODoc::Export->new(serializer => 'json', markup => 'html');
my $tree   = $export->tree;
$export->write("a.json", $tree, pretty_print => 1);

DESCRIPTION

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

Current serialization formats:

OODoc::Export::JSON

At the moment, there is one application which can be used to read these dumps: Tuyan Tatliparmak implemented the document viewer, downloadable at GitHub.

Extends "DESCRIPTION" in OODoc::Object.

OVERLOADED

Extends "OVERLOADED" in OODoc::Object.

overload: '!=' (numeric different): Inherited, see "OVERLOADED" in OODoc::Object
overload: '==' (numeric equivalent): 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->format()
$obj->manual(): Inherited, see "Attributes" in OODoc::Object
$obj->markupStyle()
$obj->parser()
$obj->serializer(): The label for this serializer.
$obj->unique(): Inherited, see "Attributes" in OODoc::Object

Collected

Extends "Collected" in OODoc::Object.

$obj->publish(\%options): Inherited, see "Collected" in OODoc::Object

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 shows some different markup compared to the output of 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->referTo($manual, $object)

[3.05] Let the parser produce a piece of text which it would use to refer to the $object when used in the $manual.

$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 Document 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.
REF; refers to a node in the index by name.

Tree 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, SAFE
  "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.

Class 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,
  "type": "section",                         # SAFE
  "name": "Constructors",                    # MARKUP
  "level": 2,                                # SAFE
  "extends": REF,
  "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.

[3.05] When the extends field is set, then this block is included in the tree to indicate that the element was inherited from the super-class. The intro text will contain something like "inherited from location.". In this case, the id looks like id1519-id2852 which means: id1519 is the full description base node, and in this case we use it in manual page id2852. The extends field will contain id1519, and can be used by the viewer to show the full object text.

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,
  "type": "i_method",                      # MARKUP
  "name": "producePages",                  # MARKUP
  "call": "$obj->producePages()" ],        # 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,
  "type": "option",                        # SAFE
  "name": "beautify",                      # MARKUP
  "params": "true|false",                  # MARKUP
  "intro": "Make the output better"        # MARKUP
}

The defaults look like this:

{ "id": REF,
  "type": "default",                       # SAFE
  "name": "beautify",                      # MARKUP
  "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,
  "type": "example",                       # SAFE
  "name": "how to produce pages",          # MARKUP
  "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,
  "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: Cast by new()
Error: exporter serializer '$name' is unknown.: Cast by new()
Error: only HTML markup is currently supported, found $style.: Cast by new()

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)