Prima::Drawable::Pod(3)

User Contributed Perl Documentation

Prima::Drawable::Pod(3)

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
trim_footer BOOLEAN: Prunes empty newlines
width INTEGER: Desired render width in pixels

load_link LINK, %OPTIONS: 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".
parse_link LINK: 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.

AUTHOR¶

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

2024-08-20

perl v5.40.0