Prima::...le::Pod(3)

📦
version 1.74000 · 5 versions
, in opensuse-leap 16.0

🌸 NAME 🌸

Prima::Drawable::Pod — it's a POD parser and a renderer, bestie. Both. Multi-talented. 💅

✨ 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 🦋

okay so Prima::Drawable::Pod literally contains a formatter (in the perlpod sense, iykyk) and a renderer for POD content. The POD text gets converted into a model — a set of text blocks in the format described over in Prima::Drawable::TextBlock. 🎀

But here's the tea: those model blocks are not directly usable. Nope. They need to be rendered into another set of text blocks, and those are the ones you can actually draw on the screen, a printer, whatever. The module also hands you helper routines for all of this. 🫶

💖 USAGE 💖

The package is made of several logically separated parts, which lowkey slay: file locating and loading, formatting, and navigation. 🌈

📝 Content methods

  • load_pod_content CONTENT, %OPTIONS — the high-level POD content parser. The %OPTIONS are the same ones as in open_read. ✨
  • open_read %OPTIONS — clears whatever content you had and enters reading mode. In this mode you can keep appending content by calling the read method over and over, which pushes the raw POD content into the parser. 🔥
  • read TEXT — feeds the TEXT string to the parser. It parses basic indentation, but the main formatting happens inside add and add_formatted.
fr fr, this must only be called inside the open_read/close_read brackets. 👑
  • add TEXT, STYLE, INDENT — formats the TEXT string using the given STYLE (which is one of the pod::STYLE_XXX constants) with INDENT spaces.
same deal, bestie: 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 the 'text' and 'podview' FORMATs. That 'podview' 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> clause skips all POD input until it's canceled. It's used together with the following command, img, so a POD manpage can serve up both graphic content ('podview', 'html', etc.) and text content ('text'). 💀✨

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

An image inclusion command, where src is a relative or absolute path to an image file. If you need scaling, you can set the width and height options. If the image is a multiframe image, you can set the frame index with the frame option. And there's a special cut option — if it's set to a true value, it activates the cut behavior if (and only if) the image load operation is unsuccessful. This makes simultaneous use of 'podview' and 'text' possible:

            =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 get selected. 😭🎨

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

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

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

⭐ close_read

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

🗂️ Topics

Topics live in the {topics} array, where each one 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 gives you 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 keys fontId, fontSize, fontStyle, color, and backColor — fully analogous to the tb::BLK_DATA_XXX options. This functionality gives you another layer of accessibility to the pod formatter. 🦋

🖨️ Rendering

The model loaded by the read functions is stored internally. It does not care about screen resolution, fonts, colors, etc. — it's independent, main character energy. To render or print it, use these functions:

  • begin_format %OPTIONS — starts a formatting session. The following options are recognized:
    • allow_width_overrun BOOLEAN=1 — if set, allows the resulting block width to overrun the canvas width. If set, you can query the actual width by calling the accumulated_width_overrun method. Otherwise it forcibly breaks blocks that are explicitly marked to be not wrapped.
    • colormap ARRAY — an 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 — a 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 drawing on the given canvas. The block_draw method can be used for the same purpose too. 💜
  • end_format — ends the formatting session.

🖨️ Printing

The print method prints the pod content on a target canvas. It 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 export_blocks method can render the model into a set of blocks that can be reused elsewhere. This functionality is used by Prima::Label, which is able to display the pod content. It returns a Prima::Drawable::PolyTextBlock object — a super-set of text blocks that also contains all the necessary information (fonts, colors, etc.) needed to pass on the block drawing routines and to be suitable as input for the 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 pixels 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, it loads only that section. Returns the success flag. The %OPTIONS are the same as understood by load_pod_file and open_read. 🌟
  • load_pod_file FILE, %OPTIONS — the high-level POD file reader. The %OPTIONS are the same as in open_read.
  • parse_link LINK — accepts text in the format of a perlpod L<> link: manpage/section. Returns a hash with up to two items, file and topic. If file is set, then the link contains a file reference. If topic is set, then the link topic matches the currently loaded set of topics. 🔍
note: if the requested file isn't loaded — f.ex. by load_pod_file — then topic will not be matched. Issue another call to parse_link to match the topic if file is set. iykyk 🙈

👀 SEE ALSO 👀

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

🫶 AUTHOR 🫶

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

💖 and that's the whole page, bestie — this was Prima::Drawable::Pod, page Prima::...le::Pod(3), from perl v5.42.0, dated 2024-08-20. slay, go read some POD ✨🎀💅

📦 where this page comes from