Provided by: libpostscript-file-perl_2.20+dfsg-1_all bug

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.