PDF::Kit - A collection of subroutines for PDF::API2.
This document refers to PDF::Kit version v1.0.5
use PDF::Kit;
A collection of subroutines to be used with PDF::API2.
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
@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.' );
@points = in2pts( @inches ); $points = in2pts( @inches );
Convert inches to points.
List of numbers in inches.
Single value in points.
List of values in points.
@points = cm2pts( @cm ); $points = cm2pts( @cm );
Convert centimetres to points.
List of numbers in centimetres.
@points = mm2pts( @mm ); $points = mm2pts( @mm );
Convert millimetres to points.
List of numbers in millimetres.
@y_values = baselines( $height, $size; $spacing, $bottom );
Compute the Y values for the baselines.
The height of the box.
Size of the font.
Optional line spacing. Typical values are 1.0, 1.5, 2.0. Default is 1.0.
Optional bottom margin; will be added to the Y values.
List of Y values.
\@blocks = column_blocks( \@block, $columns; $gap );
Calculate the block of the column that fit in the given block
[ min_x, min_y, max_x, max_y ]
Number of columns
Gap between columns; optional, default is 0 (zero).
List of columns
\@mut = small_caps( $size, $factor, @text );
Convert the text to small caps.
Size of resulting text.
The relative size of the lowercase characters. Recommended factors are from 0.65 to 0.75.
List of text items.
See "Mark-up Text".
\@flattened = flatten( @attributed_text );
Change nested attributed text into flatten attributed text.
nested attributed text
flatten attributed text
$text = as_text( @mut );
Convert nested attributed text to regular text.
List of "Mark-up Text" items.
Its text.
( \@lines, \@mut ) = format_paragraph( \%paragraph_options, @mut );
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.
m{ \s+ }msx
\x{a0}
Text will formatted with a single space character between each word unless the -two_spaces option is used.
-two_spaces
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.
\%options
Also, the following options are set:
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.
Mark-up options for the paragraph. See "Mark-up Text" for details.
Required options are -width and -compute_length.
-width
-compute_length
The -indent option must occur before any text element; if used, it should be placed here.
-indent
All other options may be placed here.
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.
This callback subroutine to determine the length of the text. See "Compute Length Subroutine" for details. This option is required.
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).
The maximum number of lines to format. If 0 (zero), then no limit. Default is 0 (zero).
If TRUE, treat all text items as though they have leading whitespace. Default is FALSE.
If TRUE, treat all text items as though they have trailing whitespace. Default is FALSE.
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).
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.
"Mark-up Text" to format.
A list of formatted lines. Each element of the list is a hash with:
The total length of the text in the line. If the -indent was negative, the first line may be greater than the given -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.
-length
Set to 1 (one) if it's the last line of the paragraph.
This is a list of hashes, one for each segment of the line. Each contain the mark-up for the segment and the following:
The offset from the left. May be negative if the -indent mark-up option was negative.
The length of the segment.
The text of the segment.
Leftover mut that did not fit into the paragraph. These may be used, as is, in another "format_paragraph()" call.
align_lines( $alignment, $lines );
Change the offsets in the lines outputted by "format_paragraph()" to align the paragraph.
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.
Output from "format_paragraph()".
none
justify_lines( $word_spacing_weight, $character_spacing_weight, $horizontal_scaling_weight, $lines );
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:
See "5.2.1 Character Spacing" in PDF Reference.
See "5.2.2 Word Spacing" in PDF Reference.
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.
\xA0
This subroutine adds the following options to the $lines:
$lines
This is the $spacing to be used with PDF::API2::Content wordspace() method when printing the line.
$spacing
wordspace()
This is the $spacing to be used with PDF::API2::Content charspace() method when printing the line.
charspace()
This is the $spacing to be used with PDF::API2::Content hspace() method when printing the line.
hspace()
It adds the option -joffset to each segment of $lines which is the offset for justification.
-joffset
The weight of the adjustment for word spacing.
The weight of the adjustment for character spacing.
The weight of the adjustment for horizontal scaling.
The output of "format_paragraph()".
( \@y_values, $lines ) = print_lines( $left, \@y_values, $lines );
Print the lines created by "format_paragraph()".
Left offset for the lines.
A list of baselines for the lines.
Formatted lines.
Left over baselines.
Left over lines.
( $bottom, \@mut ) = print_paragraph( \%print_options, \%paragraph_options, @mut );
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.
$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.
The X coordinate where the text starts.
The Y coordinate where the text starts (its baseline).
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.
The following options are required:
The block into which to print: [ left, bottom, right, top ]
The application specified "Print Text Subroutine".
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.
-spacing
The following options are optional:
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.
-size
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.
The weight of the adjustment for word spacing of justification of the paragraph.
The weight of the adjustment for character spacing of justification of the paragraph.
The weight of the adjustment for horizontal scaling of justification of the paragraph.
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.
"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.
-max_lines
A list of mut to print with "Mark-up Text".
The bottom of the paragraph. Can be used as the top of the next.
A list of mut that did not fit into the paragraph.
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.
32
160
(none)
PDF::API2
The PDF Reference Manual
Available from Adobe http://abode.com/.
Shawn H. Corey shawnhcorey@gmail.com
(Insert your name here if you modified this program or its documentation. Do not remove this comment.)
Copyright 2009 by Shawn H. Corey. All rights reserved.
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
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
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.