NAME¶
PostScript::File::Metrics - Metrics for PostScript fonts
VERSION¶
This document describes version 2.11 of PostScript::File::Metrics, released
February 11, 2012 as part of PostScript-File version 2.20.
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
<
http://rt.cpan.org/Public/Bug/Report.html?Queue=PostScript-File>.
You can follow or contribute to PostScript-File's development at
http://github.com/madsen/postscript-file
<
http://github.com/madsen/postscript-file>.
COPYRIGHT AND LICENSE¶
This software is copyright (c) 2012 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.