++ed by:
Shawn H Corey

NAME

PDF::Kit - A collection of subroutines for PDF::API2.

VERSION

This document refers to PDF::Kit version v1.0.5

SYNOPSIS

  use PDF::Kit;

DESCRIPTION

A collection of subroutines to be used with PDF::API2.

Mark-up Text

Mark-up Text (mut) is a list of items. If an element is a scalar, it's text to be formatted. If it's a hash reference, it contains mark-up options that apply to remainder of the current list. If it's an array reference, it's a sub-list. For a sub-list, the current mark-up context is preserved and restored after the sub-list is processed. That way, any mark-up in the sub-list will apply only to the sub-list.

Examples of @mut:

  @mut = ( { size=>12, -space_after=>1, -compute_length=>\&compute_length, },
    'This is plain text.',
    { bold=>1 }, 'This is bold text.',
    { italic=>1 }, 'This is bold-italic text.',
    { bold=>0 }, 'This is italic text.',
    { italic=>0 }, 'This is plain text.',
  );

  @mut = ( { size=>12, -space_after=>1, -compute_length=>\&compute_length, },
    'This is plain text.',
    [ { bold=>1 }, 'This is bold text.' ],
    [ { italic=>1 }, 'This is italic text.' ],
    [ { bold=>1, italic=>1 }, 'This is bold-italic text.' ],
    'This is plain text.',
  );

  @mut = ( { size=>12, -compute_length=>\&compute_length, },
    'This is really ',
    [ { size=>24 }, 'BIG' ],
    '. ',
    "This is not. ",
    [ { typeface=>'sans-serif' }, ":(" ],
  );

You can directly dispatch to the computing subroutine:

  @mut = ( { size=>12, -space_after=>1, },
    { -compute_length=>\&compute_plain, }, 'This is plain text.',
    [ { bold=>1, -compute_length=>\&compute_bold, }, 'This is bold text.' ],
    [ { italic=>1, -compute_length=>\&compute_italic, }, 'This is italic text.' ],
    [ { bold=>1, italic=>1, -compute_length=>\&compute_bolditalic, }, 'This is bold-italic text.' ],
    'This is plain text.',
  );

You can mark-up by tags:

  @mut = ( { size=>12, -space_after=>1, -compute_length=>\&compute_length, },
    'On',
    [{ tag=>'date', epoch=>'-14198400', strftime=>'%B %e, %Y', }, 'July 20, 1969', ],
    'man first walked on the moon.'
  );

SUBROUTINES

in2pts

Usage

  @points = in2pts( @inches );
  $points = in2pts( @inches );

Purpose

Convert inches to points.

Parameters

@inches

List of numbers in inches.

Returns

$points

Single value in points.

@points

List of values in points.

cm2pts

Usage

  @points = cm2pts( @cm );
  $points = cm2pts( @cm );

Purpose

Convert centimetres to points.

Parameters

@cm

List of numbers in centimetres.

Returns

$points

Single value in points.

@points

List of values in points.

mm2pts

Usage

  @points = mm2pts( @mm );
  $points = mm2pts( @mm );

Purpose

Convert millimetres to points.

Parameters

@mm

List of numbers in millimetres.

Returns

$points

Single value in points.

@points

List of values in points.

baselines

Usage

  @y_values = baselines( $height, $size; $spacing, $bottom );

Purpose

Compute the Y values for the baselines.

Parameters

$height

The height of the box.

$size

Size of the font.

$spacing

Optional line spacing. Typical values are 1.0, 1.5, 2.0. Default is 1.0.

$bottom

Optional bottom margin; will be added to the Y values.

Returns

@y_values

List of Y values.

column_blocks

Usage

  \@blocks = column_blocks( \@block, $columns; $gap );

Purpose

Calculate the block of the column that fit in the given block

Parameters

\@block

[ min_x, min_y, max_x, max_y ]

$columns

Number of columns

$gap

Gap between columns; optional, default is 0 (zero).

Returns

\@blocks

List of columns

small_caps

Usage

  \@mut = small_caps( $size, $factor, @text );

Purpose

Convert the text to small caps.

Parameters

$size

Size of resulting text.

$factor

The relative size of the lowercase characters. Recommended factors are from 0.65 to 0.75.

@text

List of text items.

Returns

\@mut

See "Mark-up Text".

flatten

Usage

  \@flattened = flatten( @attributed_text );

Purpose

Change nested attributed text into flatten attributed text.

Parameters

@attributed_text

nested attributed text

Returns

\@flattened

flatten attributed text

as_text

Usage

  $text = as_text( @mut );

Purpose

Convert nested attributed text to regular text.

Parameters

@mut

List of "Mark-up Text" items.

Returns

$text

Its text.

format_paragraph

Usage

  ( \@lines, \@mut ) = format_paragraph( \%paragraph_options, @mut );

Purpose

Format the "Mark-up Text" to fit into a paragraph. Items may be text, sub-lists, or mark-up options. Text is broken into words via whitespace, m{ \s+ }msx. Use the UTF character \x{a0} for non-breaking spaces. Leading whitespace in the first text item is ignored.

Text will formatted with a single space character between each word unless the -two_spaces option is used.

Compute Length Subroutine

Usage:

  $length = compute_length( \%options, $text );

This callback subroutine computes the length of the text string. The \%options contain all the mark-up options currently in effect. These can be use to determine how to do the computation.

Also, the following options are set:

-print

Set to 0 (zero). By checking this option, the application can use the same subroutine for the "Print Text Subroutine".

Note that "format_paragraph()" reserves all options that start with a minus sign for itself.

Parameters

\%paragraph_options

Mark-up options for the paragraph. See "Mark-up Text" for details.

Required options are -width and -compute_length.

The -indent option must occur before any text element; if used, it should be placed here.

All other options may be placed here.

-width

The width of the paragraph. This option is required. If the -indent is greater than the -width, then the first line is blank. Except for the above, this algorithm places at least one word per line regardless of the -width. Long words may exceed the paragraph boundaries.

-compute_length

This callback subroutine to determine the length of the text. See "Compute Length Subroutine" for details. This option is required.

-indent

First line indentation. If negative, the first line will be to the left of the paragraph boundary. If greater than -width, the first line will be blank. Default is 0 (zero).

-max_lines

The maximum number of lines to format. If 0 (zero), then no limit. Default is 0 (zero).

-space_before

If TRUE, treat all text items as though they have leading whitespace. Default is FALSE.

-space_after

If TRUE, treat all text items as though they have trailing whitespace. Default is FALSE.

-two_spaces

A compiled regular expression (see "Quote and Quote-like Operators" in perlop). If a word matches, then when formatted it will have two spaces between it and the next text item (unless it's at the end of a line).

any

The application may set any option to communicate with the "Compute Length Subroutine". "format_paragraph()" reserves options that start with a minus sign for itself. The application may use any other option name. It is up to the application to pass sufficient parameters so that the correct calculations can be done.

@mut

"Mark-up Text" to format.

Returns

\@lines

A list of formatted lines. Each element of the list is a hash with:

-length

The total length of the text in the line. If the -indent was negative, the first line may be greater than the given -width.

-width

The width of the line. Its -length should be less than or equal to this unless -indent is negative and it is the first line.

-last_line

Set to 1 (one) if it's the last line of the paragraph.

-segments

This is a list of hashes, one for each segment of the line. Each contain the mark-up for the segment and the following:

-offset

The offset from the left. May be negative if the -indent mark-up option was negative.

-length

The length of the segment.

-text

The text of the segment.

\@mut

Leftover mut that did not fit into the paragraph. These may be used, as is, in another "format_paragraph()" call.

align_lines

Usage

  align_lines( $alignment, $lines );

Purpose

Change the offsets in the lines outputted by "format_paragraph()" to align the paragraph.

Parameters

$alignment

A value of 0.0 will left align; a value of 0.5 will center align; a value of 1.0 will right align. Other values will create weird, special effects.

$lines

Output from "format_paragraph()".

Returns

none

justify_lines

Usage

  justify_lines( $word_spacing_weight, $character_spacing_weight, $horizontal_scaling_weight, $lines );

Purpose

Modify the output of "format_paragraph()" so that the lines are fully justified.

PDF offers three text state parameters to adjust the text so it can be justified. They are:

character spacing

See "5.2.1 Character Spacing" in PDF Reference.

word spacing

See "5.2.2 Word Spacing" in PDF Reference.

horizontal scaling

See "5.2.3 Horizontal Scaling" in PDF Reference.

This subroutine allows you to specify how much of each will be done to achieve justification. The first three parameters of this subroutine are the weights for each. The weights will be normalized before they are applied. Their sum must not be 0 (zero).

If the width of the paragraph is very narrow or the text has non-breaking spaces, \xA0, then the word spacing may have no effect. To make justification possible, at least one of the other two weight should be non-zero.

This subroutine adds the following options to the $lines:

-wordspace

This is the $spacing to be used with PDF::API2::Content wordspace() method when printing the line.

-charspace

This is the $spacing to be used with PDF::API2::Content charspace() method when printing the line.

-hspace

This is the $spacing to be used with PDF::API2::Content hspace() method when printing the line.

It adds the option -joffset to each segment of $lines which is the offset for justification.

Parameters

$word_spacing_weight

The weight of the adjustment for word spacing.

$character_spacing_weight

The weight of the adjustment for character spacing.

$horizontal_scaling_weight

The weight of the adjustment for horizontal scaling.

$lines

The output of "format_paragraph()".

Returns

none

Usage

  ( \@y_values, $lines ) = print_lines( $left, \@y_values, $lines );

Purpose

Print the lines created by "format_paragraph()".

Parameters

$left

Left offset for the lines.

\@y_values

A list of baselines for the lines.

$lines

Formatted lines.

Returns

\@y_values

Left over baselines.

$lines

Left over lines.

Usage

  ( $bottom, \@mut ) = print_paragraph( \%print_options, \%paragraph_options, @mut );

Purpose

Print the paragraph. This subroutine uses "format_paragraph()" to format the paragraph and then determines where each segment of text should go. It uses the application specified print routine to print it.

Usage:

  $length = print_text( \%options, $text );

This callback subroutine prints the text string and returns its length. The \%options contain all the mark-up options currently in effect. These can be use to determine how to do the printing.

Also, the following options are set:

-x

The X coordinate where the text starts.

-y

The Y coordinate where the text starts (its baseline).

-print

Set to 1 (one). By checking this option, the application can use the same subroutine for the "Compute Length Subroutine".

Note that "print_paragraph()" reserves all options that start with a minus sign for itself.

Parameters

The following options are required:

-block

The block into which to print: [ left, bottom, right, top ]

The application specified "Print Text Subroutine".

-size

The nominal size of the text. The size multiplied by the -spacing should be greater than or equal to the largest font size used int the paragraph.

The following options are optional:

    -spacing

    The line spacing of the paragraph. Typical values are 1.0, 1.5 and 2.0. Default is 1.0. The -size multiplied by the -spacing should be greater than or equal to the largest font size used int the paragraph.

    -alignment

    How to align the paragraph. A value of 0.0 will left align the paragraph; a value of 0.5 will center align it; a value of 1.0 will right align it.

    -justify_word

    The weight of the adjustment for word spacing of justification of the paragraph.

    -justify_char

    The weight of the adjustment for character spacing of justification of the paragraph.

    -justify_scale

    The weight of the adjustment for horizontal scaling of justification of the paragraph.

    any

    The application may set any options to be passed to the Print Text Subroutine. This subroutine reserves any option that starts with a minus sign for future use.

\%paragraph_options

"Mark-up Text" for the paragraph. The option -compute_length, a subroutine to compute the length of a string, is required. The -width and -max_lines options will be ignored.

@mut

A list of mut to print with "Mark-up Text".

Returns

$bottom

The bottom of the paragraph. Can be used as the top of the next.

\@mut

A list of mut that did not fit into the paragraph.

DIAGNOSTICS

CONFIGURATION AND ENVIRONMENT

DEPENDENCIES

INCOMPATIBILITIES

BUGS AND LIMITATIONS

Limitations

  • The word spacing (see "5.2.2 Word Spacing" in PDF Reference) only applies to the space character, ASCII code 32. If you use non-breaking spaces, ASCII code 160, the words will NOT be spaced out with this. This is part of how Adobe implemented PDF and cannot be change in Perl.

Known Bugs

    (none)

SEE ALSO

ORIGINAL AUTHOR

Shawn H. Corey shawnhcorey@gmail.com

Contributing Authors

(Insert your name here if you modified this program or its documentation. Do not remove this comment.)

COPYRIGHT & LICENCES

Copyright 2009 by Shawn H. Corey. All rights reserved.

Software Licence

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

Document Licence

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with the Invariant Sections being ORIGINAL AUTHOR, COPYRIGHT & LICENCES, Software Licence, and Document Licence.

You should have received a copy of the GNU Free Documentation Licence along with this document; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

ACKNOWLEDGEMENTS




Hosting generously
sponsored by Bytemark