plucky (3) PostScript::File::Metrics.3pm.gz
NAME
PostScript::File::Metrics - Metrics for PostScript fonts
VERSION
This document describes version 2.11 of PostScript::File::Metrics, released October 10, 2015 as part of
PostScript-File version 2.23.
SYNOPSIS
use PostScript::File;
my $ps = PostScript::File->new(reencode => 'cp1252');
my $metrics = $ps->get_metrics('Helvetica-iso', 9);
my $upos = $metrics->underline_position;
my $width = $metrics->width('Hello, World!');
my @lines = $metrics->wrap( 72, # wrap it into 1 inch lines
'This is a long string that will not fit on just one line of text.'
);
DESCRIPTION
PostScript::File::Metrics provides a subset of the metrics available from Font::AFM. Its reason for
existence is that it allows you to pre-compile the AFM files into Perl modules. This makes loading them
more efficient, but more importantly, it means you don't have to install (or configure) Font::AFM.
That's important because the locations and filenames of AFM files are not very standardized, which makes
configuring Font::AFM quite difficult.
PostScript::File::Metrics includes pre-compiled metrics for the 13 standard PostScript fonts:
Courier Helvetica Times-Roman
Courier-Bold Helvetica-Bold Times-Bold
Courier-BoldOblique Helvetica-BoldOblique Times-BoldItalic
Courier-Oblique Helvetica-Oblique Times-Italic
Symbol
If you need metrics for a font not in that list, you'll need to have Font::AFM installed and configured.
(You can modify examples/generate_metrics.pl to create additional pre-compiled modules, but you'll still
have to get Font::AFM working on one system.)
ATTRIBUTES
All attributes are read-only, except for "auto_hyphen" and "size", which can be set using the
corresponding "set_" methods.
size
The current font size in points. This is not an attribute of the font, but of this Metrics object. The
attributes that describe the font's dimensions are adjusted according to this value.
auto_hyphen
If true, the "width" and "wrap" methods will do hyphen-minus processing as described in "Hyphens and
Minus Signs" in PostScript::File, but only if the encoding is "cp1252" or "iso-8859-1".
full_name
Unique, human-readable name for an individual font, for instance "Times Roman".
family
Human-readable name for a group of fonts that are stylistic variants of a single design. All fonts that
are members of such a group should have exactly the same "family". Example of a family name is "Times".
weight
Human-readable name for the weight, or "boldness", attribute of a font. Examples are "Roman", "Bold",
"Medium".
italic_angle
Angle in degrees counterclockwise from the vertical of the dominant vertical strokes of the font. (This
is normally <= 0.)
fixed_pitch
1 if the font is a fixed-pitch (monospaced) font. 0 otherwise.
font_bbox
An arrayref of four numbers giving the lower-left x, lower-left y, upper-right x, and upper-right y of
the font bounding box. The font bounding box is the smallest rectangle enclosing the shape that would
result if all the characters of the font were placed with their origins coincident at (0,0), and then
painted. You must not modify the returned arrayref.
cap_height
Usually the y-value of the top of the capital H. Some fonts, like Symbol, may not define this attribute.
x_height
Typically the y-value of the top of the lowercase x. Some fonts, like Symbol, may not define this
attribute.
ascender
Typically the y-value of the top of the lowercase d. Some fonts, like Symbol, may not define this
attribute.
descender
Typically the y-value of the bottom of the lowercase p. Some fonts, like Symbol, may not define this
attribute.
underline_position
Recommended distance from the baseline for positioning underline strokes. This number is the y coordinate
of the center of the stroke.
underline_thickness
Recommended stroke width for underlining.
version
Version number of the font.
METHODS
new
$metrics = PostScript::File::Metrics->new($font, [$size, [$encoding]])
You would normally use "get_metrics" in PostScript::File to construct a Metrics object (because it can
get the $encoding from the document), but it is possible to construct one directly.
$size is the font size in points, and defaults to 1000.
$encoding is the character encoding used by "width" and "wrap". Valid choices are "std", "sym",
"cp1252", and "iso-8859-1". The default is "std", meaning PostScript's StandardEncoding (unless the
$font is Symbol, which uses "sym", meaning PostScript's SymbolEncoding). Neither "std" nor "sym" does
any character set translation.
The "auto_hyphen" attribute is always set to true when character translation is enabled.
set_auto_hyphen( translate )
If translate is a true value, then "width" and "wrap" will do automatic hyphen-minus translation as
described in "Hyphens and Minus Signs" in PostScript::File.
set_size
$metrics->set_size($new_size)
This method sets the font size (in points). This influences the attributes that concern dimensions and
the string width calculations. It returns the Metrics object, so you can chain to the next method.
set_wrap_chars
$metrics->set_wrap_chars($new_chars)
This method (introduced in version 2.11) sets the characters after which a word can be wrapped. A line
can wrap after any character in $new_chars, which should not include whitespace. Whitespace is always a
valid breakpoint. If $new_chars is omitted or "undef", restores the default wrap characters, which means
"-/" and (if using cp1252) both en and em dashes. It returns the Metrics object, so you can chain to the
next method.
width
$width = $metrics->width($string, [$already_encoded])
This calculates the width of $string (in points) when displayed in this font at the current size. If
$string has the UTF8 flag set, it is translated into the font's encoding. Otherwise, the $string is
expected to be in the correct character set already. $string should not contain newlines.
If optional parameter $already_encoded is true, then $string is assumed to be already encoded in the
document's character set. This also prevents any hyphen-minus processing.
wrap
@lines = $metrics->wrap($width, $text, [\%param])
This wraps $text into lines of no more than $width points. If $text contains newlines, they will also
cause line breaks. If $text has the UTF8 flag set, it is translated into the font's encoding.
Otherwise, the $text is expected to be in the correct character set already.
If the "auto_hyphen" attribute is true, then any HYPHEN-MINUS (U+002D) characters in $text will be
converted to either HYPHEN (U+2010) or MINUS SIGN (U+2212) in the returned strings.
The characters after which a line can wrap (other than space and tab, which are always valid line breaks)
can be set with the "set_wrap_chars" method. In addition, $text may contain ZERO WIDTH SPACE (U+200B)
characters to indicate potential line breaks. All ZWSP characters and CRs will be removed from the
returned strings. $text may also contain NO-BREAK SPACE (U+00A0) characters, which indicate whitespace
without a potential line break.
The optional "\%param" (introduced in version 2.11) allows additional control over the wrapping. It may
contain the following keys:
chars
This overrides the line-breaking characters normally set by the "set_wrap_chars" method. The value
has the same meaning as for "set_wrap_chars".
maxlines
The maximum number of lines to return. The final line will contain all the remaining text, even if
that exceeds $width or contains newline characters.
quiet
If true, do not warn about words that are too wide to fit in the specified $width.
warnings
If present, must be an arrayref. Warning messages about words that are too wide to fit in the
specified $width will be pushed onto the array. You should also pass "quiet => 1" if you don't want
the warnings printed to STDERR.
CONFIGURATION AND ENVIRONMENT
PostScript::File::Metrics requires no configuration files or environment variables.
INCOMPATIBILITIES
None reported.
BUGS AND LIMITATIONS
No bugs have been reported.
AUTHOR
Christopher J. Madsen "<perl AT cjmweb.net>"
Please report any bugs or feature requests to "<bug-PostScript-File AT rt.cpan.org>" or through the web
interface at <http://rt.cpan.org/Public/Bug/Report.html?Queue=PostScript-File>.
You can follow or contribute to PostScript-File's development at
<https://github.com/madsen/postscript-file>.
COPYRIGHT AND LICENSE
This software is copyright (c) 2015 by Christopher J. Madsen.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5
programming language system itself.
DISCLAIMER OF WARRANTY
BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT
PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE
SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY
OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE LIABLE
TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF
THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE
WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES.