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

print_lines

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.

print_paragraph

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.

Print Text Subroutine

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

\%print_options

The following options are required:

-block: The block into which to print: [ left, bottom, right, top ]
-print_text: 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)

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

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

To install PDF::Kit, copy and paste the appropriate command in to your terminal.

cpanm

cpanm PDF::Kit

CPAN shell

perl -MCPAN -e shell
install PDF::Kit

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)