The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Prima-1.72
River stage two • 17 direct dependents • 19 total dependents
43 ++
/ Prima::Drawable::Pod

NAME

Prima::Drawable::Pod - POD parser and renderer

SYNOPSIS

        use Prima::Drawable::Pod;
        use Prima::PS::Printer;

        my $pod = Prima::Drawable::Pod->new;
        $pod-> load_pod_content("=head1 NAME\n\nI'm also a pod!\n\n");

        my $printer = Prima::PS::PDF::File->new( file => 'pod.pdf');
        $printer-> begin_doc or die $@;
        $pod-> print($printer);
        $printer-> end_doc;

DESCRIPTION

Prima::Drawable::Pod contains a formatter ( in terms of perlpod ) and a renderer of the POD content. The POD text is converted in model, a set of text blocks in format described in Prima::Drawable::TextBlock. The model blocks are not directly usable though, and would need to be rendered to another set of text blocks, that in turn can be drawn on the screen, a printer, etc. The module also provides helper routines for these operations.

USAGE

The package consists of several logically separated parts. These include file locating and loading, formatting, and navigation.

Content methods

load_pod_content CONTENT, %OPTIONS

High-level POD content parser. %OPTIONS are same as in open_read.

open_read %OPTIONS

Clears the current content and enters the reading mode. In this mode, the content can be appended by repeatedly calling the read method that pushes the raw POD content to the parser.

read TEXT

Supplies the TEXT string to the parser. Parses basic indentation, but the main formatting is performed inside add and add_formatted.

Must be called only within the open_read/close_read brackets

add TEXT, STYLE, INDENT

Formats the TEXT string of a given STYLE ( one of the pod::STYLE_XXX constants) with the INDENT space.

Must be called only within the open_read/close_read brackets.

add_formatted FORMAT, TEXT

Adds a pre-formatted TEXT with a given FORMAT, supplied by the =begin or =for POD directives. Prima::PodView understands 'text' and 'podview' FORMATs; the latter format is for Prima::PodView itself and contains a small number of commands for rendering images in documents.

The 'podview' commands are:

cut

Example:

        =for podview <cut>

        =for text just text-formatter info

                ....
                text-only info
                ...

        =for podview </cut>

The <cut<gt> clause skips all POD input until canceled. It is used in conjunction with the following command, img, to allow a POD manpage to provide both graphic ('podview', 'html', etc ) and text ( 'text' ) content.

img [src="SRC"] [width="WIDTH"] [height="HEIGHT"] [cut="CUT"] [frame="FRAME"]

An image inclusion command, where src is a relative or an absolute path to an image file. In case scaling is required, width and height options can be set. If the image is a multiframe image, the frame index can be set by the frame option. A special cut option, if set to a true value, activates the cut behavior if ( and only if ) the image load operation is unsuccessful. This makes possible simultaneous use of 'podview' and 'text' :

        =for podview <img src="graphic.gif" cut=1 >

        =begin text

        y     .
        |  .
        |.
        +----- x

        =end text

        =for podview </cut>

In the example above 'graphic.gif' will be shown if it can be found and loaded, otherwise, the poor-man drawings will be selected.

If src is omitted, the image is retrieved from the images array, from the index frame.

It is also possible to embed images in the pod, by using a special src tag for base64-encoded images. The format should preferably be GIF, as this is Prima default format, or BMP for very small images, as it is supported without third-party libraries:

        =for podview <img src="data:base64">
        R0lGODdhAQABAIAAAAAAAAAAACwAAAAAAQABAIAAAAAAAAACAkQBADs=
close_read

Closes the reading mode. Returns undef if there is no POD context, or a hash with topic_id (ID of the first topic containing the content) and the success flag otherwise.

Topics

Topics reside in the {topics} array, where each is an array with the following indices of the pod::T_XXX constants:

        pod::T_MODEL_START - start of topic
        pod::T_MODEL_END   - end of a topic
        pod::T_DESCRIPTION - topic name
        pod::T_STYLE       - pod::STYLE_XXX constant
        pod::T_ITEM_DEPTH  - depth of =item recursion
        pod::T_LINK_OFFSET - offset in the links array

Styles

The ::styles property provides access to the styles, applied to different pod text parts. These styles are:

        pod::STYLE_CODE     - style for C<>
        pod::STYLE_TEXT     - normal text
        pod::STYLE_HEAD_1   - =head1
        pod::STYLE_HEAD_2   - =head2
        pod::STYLE_HEAD_3   - =head3
        pod::STYLE_HEAD_4   - =head4
        pod::STYLE_HEAD_5   - =head5
        pod::STYLE_HEAD_6   - =head6
        pod::STYLE_ITEM     - =item
        pod::STYLE_LINK     - style for L<> text
        pod::STYLE_VERBATIM - style for pre-formatted text

Each style is a hash with the following keys: fontId, fontSize, fontStyle, color, and backColor, fully analogous to the tb::BLK_DATA_XXX options. This functionality provides another layer of accessibility to the pod formatter.

Rendering

The model loaded by the read functions is stored internally. It is independent of screen resolution, fonts, colors, etc. To be rendered or printed, the following functions can be used:

begin_format %OPTIONS

Starts formatting session. The following options are recognized:

allow_width_overrun BOOLEAN=1

If set, allows resulting block width to overrun the canvas width. If set, the actual width can be queried by calling the accumulated_width_overrun method. Otherwise forcibly breaks blocks explicitly marked to be not wrapped.

colormap ARRAY

Array of at least 5 color entries (default foreground color, default background color, link color, verbatime text color, and its background color). If unset, some sensible default values are used.

fontmap ARRAY_OF_HASHES

Set of at least 2 hashes each describing a font to be used for normal text (index 0) and verbatim text (index 1). If unset, some sensible default values are used.

hmargin, vmargin

Target device margins

resolution ARRAY_OF_2

Target device resolution

width, height

Target device size

format_model $MODEL

Renders a model block $MODEL and returns zero or more text blocks suitable for the drawing on the given canvas. Also the block_draw method can be used for the same purpose.

end_format

Ends formatting session

Printing

The method print prints the pod content on a target canvas. Accepts the following options (along with all the other options from begin_format)

canvas OBJECT

The target device

from, to INDEX

Selects the model range to be printed

Block export

The method export_blocks can render the model into a set of blocks that can be reused elsewhere. This functionality is used by Prima::Label that is able to display the pod content. Returns a Prima::Drawable::PolyTextBlock object that is a super-set of text blocks that also contains all necessary information (fonts, colors, etc) needed to pass on the block drawing routines and to be suitable as input for text_out method.

The method accepts the following options (along with all the other options from begin_format):

canvas OBJECT

The target device

from, to INDEX

Selects the model range to be printed

max_height INTEGER

Stops rendering after max_height pixel are occupied by the pod content

trim_header BOOLEAN

If set, removes the topic or page header, so that only the content itself is rendered

Prunes empty newlines

width INTEGER

Desired render width in pixels

Parses and loads POD content from LINK. If the LINK contains a section reference, loads only that section. Returns the success flag.

%OPTIONS are same as understood by the load_pod_file and open_read.

load_pod_file FILE, %OPTIONS

High-level POD file reader. %OPTIONS are same as in open_read.

The method parse_link accepts text in the format of perlpod L<> link: "manpage/section". Returns a hash with up to two items, file and topic. If the file is set, then the link contains a file reference. If the topic is set, then the link topic matches the currently loaded set of topic.

Note: if the file requested is not loaded, f.ex. by load_pod_file, then topic will not me matched. Issue another call to parse_link to match the topic if file is set.

SEE ALSO

Prima::Drawable::TextBlock, Prima::PodView.

AUTHOR

Dmitry Karasik, <dmitry@karasik.eu.org>.