.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "PostScript::File::Metrics 3pm" .TH PostScript::File::Metrics 3pm "2012-02-11" "perl v5.14.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" PostScript::File::Metrics \- Metrics for PostScript fonts .SH "VERSION" .IX Header "VERSION" This document describes version 2.11 of PostScript::File::Metrics, released February 11, 2012 as part of PostScript-File version 2.20. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use PostScript::File; \& \& my $ps = PostScript::File\->new(reencode => \*(Aqcp1252\*(Aq); \& \& my $metrics = $ps\->get_metrics(\*(AqHelvetica\-iso\*(Aq, 9); \& \& my $upos = $metrics\->underline_position; \& \& my $width = $metrics\->width(\*(AqHello, World!\*(Aq); \& \& my @lines = $metrics\->wrap( 72, # wrap it into 1 inch lines \& \*(AqThis is a long string that will not fit on just one line of text.\*(Aq \& ); .Ve .SH "DESCRIPTION" .IX Header "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 \s-1AFM\s0 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 \s-1AFM\s0 files are not very standardized, which makes configuring Font::AFM quite difficult. .PP PostScript::File::Metrics includes pre-compiled metrics for the 13 standard PostScript fonts: .PP .Vb 5 \& Courier Helvetica Times\-Roman \& Courier\-Bold Helvetica\-Bold Times\-Bold \& Courier\-BoldOblique Helvetica\-BoldOblique Times\-BoldItalic \& Courier\-Oblique Helvetica\-Oblique Times\-Italic \& Symbol .Ve .PP If you need metrics for a font not in that list, you'll need to have Font::AFM installed and configured. (You can modify \&\fIexamples/generate_metrics.pl\fR to create additional pre-compiled modules, but you'll still have to get Font::AFM working on one system.) .SH "ATTRIBUTES" .IX Header "ATTRIBUTES" All attributes are read-only, except for \f(CW\*(C`auto_hyphen\*(C'\fR and \f(CW\*(C`size\*(C'\fR, which can be set using the corresponding \f(CW\*(C`set_\*(C'\fR methods. .SS "size" .IX Subsection "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. .SS "auto_hyphen" .IX Subsection "auto_hyphen" If true, the \f(CW\*(C`width\*(C'\fR and \f(CW\*(C`wrap\*(C'\fR methods will do hyphen-minus processing as described in \*(L"Hyphens and Minus Signs\*(R" in PostScript::File, but only if the encoding is \f(CW\*(C`cp1252\*(C'\fR or \f(CW\*(C`iso\-8859\-1\*(C'\fR. .SS "full_name" .IX Subsection "full_name" Unique, human-readable name for an individual font, for instance \&\*(L"Times Roman\*(R". .SS "family" .IX Subsection "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 \f(CW\*(C`family\*(C'\fR. Example of a family name is \&\*(L"Times\*(R". .SS "weight" .IX Subsection "weight" Human-readable name for the weight, or \*(L"boldness\*(R", attribute of a font. Examples are \f(CW\*(C`Roman\*(C'\fR, \f(CW\*(C`Bold\*(C'\fR, \f(CW\*(C`Medium\*(C'\fR. .SS "italic_angle" .IX Subsection "italic_angle" Angle in degrees counterclockwise from the vertical of the dominant vertical strokes of the font. (This is normally <= 0.) .SS "fixed_pitch" .IX Subsection "fixed_pitch" 1 if the font is a fixed-pitch (monospaced) font. 0 otherwise. .SS "font_bbox" .IX Subsection "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. .SS "cap_height" .IX Subsection "cap_height" Usually the y\-value of the top of the capital H. Some fonts, like Symbol, may not define this attribute. .SS "x_height" .IX Subsection "x_height" Typically the y\-value of the top of the lowercase x. Some fonts, like Symbol, may not define this attribute. .SS "ascender" .IX Subsection "ascender" Typically the y\-value of the top of the lowercase d. Some fonts, like Symbol, may not define this attribute. .SS "descender" .IX Subsection "descender" Typically the y\-value of the bottom of the lowercase p. Some fonts, like Symbol, may not define this attribute. .SS "underline_position" .IX Subsection "underline_position" Recommended distance from the baseline for positioning underline strokes. This number is the y coordinate of the center of the stroke. .SS "underline_thickness" .IX Subsection "underline_thickness" Recommended stroke width for underlining. .SS "version" .IX Subsection "version" Version number of the font. .SH "METHODS" .IX Header "METHODS" .SS "new" .IX Subsection "new" .Vb 1 \& $metrics = PostScript::File::Metrics\->new($font, [$size, [$encoding]]) .Ve .PP You would normally use \*(L"get_metrics\*(R" in PostScript::File to construct a Metrics object (because it can get the \f(CW$encoding\fR from the document), but it is possible to construct one directly. .PP \&\f(CW$size\fR is the font size in points, and defaults to 1000. .PP \&\f(CW$encoding\fR is the character encoding used by \*(L"width\*(R" and \*(L"wrap\*(R". Valid choices are \f(CW\*(C`std\*(C'\fR, \f(CW\*(C`sym\*(C'\fR, \f(CW\*(C`cp1252\*(C'\fR, and \f(CW\*(C`iso\-8859\-1\*(C'\fR. The default is \f(CW\*(C`std\*(C'\fR, meaning PostScript's StandardEncoding (unless the \&\f(CW$font\fR is Symbol, which uses \f(CW\*(C`sym\*(C'\fR, meaning PostScript's SymbolEncoding). Neither \f(CW\*(C`std\*(C'\fR nor \f(CW\*(C`sym\*(C'\fR does any character set translation. .PP The \f(CW\*(C`auto_hyphen\*(C'\fR attribute is always set to true when character translation is enabled. .SS "set_auto_hyphen( translate )" .IX Subsection "set_auto_hyphen( translate )" If translate is a true value, then \f(CW\*(C`width\*(C'\fR and \f(CW\*(C`wrap\*(C'\fR will do automatic hyphen-minus translation as described in \&\*(L"Hyphens and Minus Signs\*(R" in PostScript::File. .SS "set_size" .IX Subsection "set_size" .Vb 1 \& $metrics\->set_size($new_size) .Ve .PP 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. .SS "set_wrap_chars" .IX Subsection "set_wrap_chars" .Vb 1 \& $metrics\->set_wrap_chars($new_chars) .Ve .PP 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 \&\f(CW$new_chars\fR, which \fIshould not\fR include whitespace. Whitespace is always a valid breakpoint. If \f(CW$new_chars\fR is omitted or \f(CW\*(C`undef\*(C'\fR, restores the default wrap characters, which means \f(CW\*(C`\-/\*(C'\fR and (if using cp1252) both en and em dashes. It returns the Metrics object, so you can chain to the next method. .SS "width" .IX Subsection "width" .Vb 1 \& $width = $metrics\->width($string, [$already_encoded]) .Ve .PP This calculates the width of \f(CW$string\fR (in points) when displayed in this font at the current size. If \f(CW$string\fR has the \s-1UTF8\s0 flag set, it is translated into the font's encoding. Otherwise, the \f(CW$string\fR is expected to be in the correct character set already. \f(CW$string\fR should not contain newlines. .PP If optional parameter \f(CW$already_encoded\fR is true, then \f(CW$string\fR is assumed to be already encoded in the document's character set. This also prevents any hyphen-minus processing. .SS "wrap" .IX Subsection "wrap" .Vb 1 \& @lines = $metrics\->wrap($width, $text, [\e%param]) .Ve .PP This wraps \f(CW$text\fR into lines of no more than \f(CW$width\fR points. If \&\f(CW$text\fR contains newlines, they will also cause line breaks. If \&\f(CW$text\fR has the \s-1UTF8\s0 flag set, it is translated into the font's encoding. Otherwise, the \f(CW$text\fR is expected to be in the correct character set already. .PP If the \f(CW\*(C`auto_hyphen\*(C'\fR attribute is true, then any HYPHEN-MINUS (U+002D) characters in \f(CW$text\fR will be converted to either \s-1HYPHEN\s0 (U+2010) or \s-1MINUS\s0 \s-1SIGN\s0 (U+2212) in the returned strings. .PP The characters after which a line can wrap (other than space and tab, which are always valid line breaks) can be set with the \&\f(CW\*(C`set_wrap_chars\*(C'\fR method. In addition, \f(CW$text\fR may contain \s-1ZERO\s0 \&\s-1WIDTH\s0 \s-1SPACE\s0 (U+200B) characters to indicate potential line breaks. All \s-1ZWSP\s0 characters and CRs will be removed from the returned strings. \&\f(CW$text\fR may also contain NO-BREAK \s-1SPACE\s0 (U+00A0) characters, which indicate whitespace without a potential line break. .PP The optional \f(CW\*(C`\e%param\*(C'\fR (introduced in version 2.11) allows additional control over the wrapping. It may contain the following keys: .IP "chars" 4 .IX Item "chars" This overrides the line-breaking characters normally set by the \&\f(CW\*(C`set_wrap_chars\*(C'\fR method. The value has the same meaning as for \&\f(CW\*(C`set_wrap_chars\*(C'\fR. .IP "maxlines" 4 .IX Item "maxlines" The maximum number of lines to return. The final line will contain all the remaining text, even if that exceeds \f(CW$width\fR or contains newline characters. .IP "quiet" 4 .IX Item "quiet" If true, do not warn about words that are too wide to fit in the specified \f(CW$width\fR. .IP "warnings" 4 .IX Item "warnings" If present, must be an arrayref. Warning messages about words that are too wide to fit in the specified \f(CW$width\fR will be pushed onto the array. You should also pass \f(CW\*(C`quiet\ =>\ 1\*(C'\fR if you don't want the warnings printed to \s-1STDERR\s0. .SH "CONFIGURATION AND ENVIRONMENT" .IX Header "CONFIGURATION AND ENVIRONMENT" PostScript::File::Metrics requires no configuration files or environment variables. .SH "INCOMPATIBILITIES" .IX Header "INCOMPATIBILITIES" None reported. .SH "BUGS AND LIMITATIONS" .IX Header "BUGS AND LIMITATIONS" No bugs have been reported. .SH "AUTHOR" .IX Header "AUTHOR" Christopher J. Madsen \f(CW\*(C`\*(C'\fR .PP Please report any bugs or feature requests to \f(CW\*(C`\*(C'\fR or through the web interface at http://rt.cpan.org/Public/Bug/Report.html?Queue=PostScript\-File . .PP You can follow or contribute to PostScript-File's development at http://github.com/madsen/postscript\-file . .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2012 by Christopher J. Madsen. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. .SH "DISCLAIMER OF WARRANTY" .IX Header "DISCLAIMER OF WARRANTY" \&\s-1BECAUSE\s0 \s-1THIS\s0 \s-1SOFTWARE\s0 \s-1IS\s0 \s-1LICENSED\s0 \s-1FREE\s0 \s-1OF\s0 \s-1CHARGE\s0, \s-1THERE\s0 \s-1IS\s0 \s-1NO\s0 \s-1WARRANTY\s0 \&\s-1FOR\s0 \s-1THE\s0 \s-1SOFTWARE\s0, \s-1TO\s0 \s-1THE\s0 \s-1EXTENT\s0 \s-1PERMITTED\s0 \s-1BY\s0 \s-1APPLICABLE\s0 \s-1LAW\s0. \s-1EXCEPT\s0 \s-1WHEN\s0 \&\s-1OTHERWISE\s0 \s-1STATED\s0 \s-1IN\s0 \s-1WRITING\s0 \s-1THE\s0 \s-1COPYRIGHT\s0 \s-1HOLDERS\s0 \s-1AND/OR\s0 \s-1OTHER\s0 \s-1PARTIES\s0 \&\s-1PROVIDE\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \*(L"\s-1AS\s0 \s-1IS\s0\*(R" \s-1WITHOUT\s0 \s-1WARRANTY\s0 \s-1OF\s0 \s-1ANY\s0 \s-1KIND\s0, \s-1EITHER\s0 \&\s-1EXPRESSED\s0 \s-1OR\s0 \s-1IMPLIED\s0, \s-1INCLUDING\s0, \s-1BUT\s0 \s-1NOT\s0 \s-1LIMITED\s0 \s-1TO\s0, \s-1THE\s0 \s-1IMPLIED\s0 \&\s-1WARRANTIES\s0 \s-1OF\s0 \s-1MERCHANTABILITY\s0 \s-1AND\s0 \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0. \s-1THE\s0 \&\s-1ENTIRE\s0 \s-1RISK\s0 \s-1AS\s0 \s-1TO\s0 \s-1THE\s0 \s-1QUALITY\s0 \s-1AND\s0 \s-1PERFORMANCE\s0 \s-1OF\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1IS\s0 \s-1WITH\s0 \&\s-1YOU\s0. \s-1SHOULD\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1PROVE\s0 \s-1DEFECTIVE\s0, \s-1YOU\s0 \s-1ASSUME\s0 \s-1THE\s0 \s-1COST\s0 \s-1OF\s0 \s-1ALL\s0 \&\s-1NECESSARY\s0 \s-1SERVICING\s0, \s-1REPAIR\s0, \s-1OR\s0 \s-1CORRECTION\s0. .PP \&\s-1IN\s0 \s-1NO\s0 \s-1EVENT\s0 \s-1UNLESS\s0 \s-1REQUIRED\s0 \s-1BY\s0 \s-1APPLICABLE\s0 \s-1LAW\s0 \s-1OR\s0 \s-1AGREED\s0 \s-1TO\s0 \s-1IN\s0 \s-1WRITING\s0 \&\s-1WILL\s0 \s-1ANY\s0 \s-1COPYRIGHT\s0 \s-1HOLDER\s0, \s-1OR\s0 \s-1ANY\s0 \s-1OTHER\s0 \s-1PARTY\s0 \s-1WHO\s0 \s-1MAY\s0 \s-1MODIFY\s0 \s-1AND/OR\s0 \&\s-1REDISTRIBUTE\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1AS\s0 \s-1PERMITTED\s0 \s-1BY\s0 \s-1THE\s0 \s-1ABOVE\s0 \s-1LICENSE\s0, \s-1BE\s0 \&\s-1LIABLE\s0 \s-1TO\s0 \s-1YOU\s0 \s-1FOR\s0 \s-1DAMAGES\s0, \s-1INCLUDING\s0 \s-1ANY\s0 \s-1GENERAL\s0, \s-1SPECIAL\s0, \s-1INCIDENTAL\s0, \&\s-1OR\s0 \s-1CONSEQUENTIAL\s0 \s-1DAMAGES\s0 \s-1ARISING\s0 \s-1OUT\s0 \s-1OF\s0 \s-1THE\s0 \s-1USE\s0 \s-1OR\s0 \s-1INABILITY\s0 \s-1TO\s0 \s-1USE\s0 \&\s-1THE\s0 \s-1SOFTWARE\s0 (\s-1INCLUDING\s0 \s-1BUT\s0 \s-1NOT\s0 \s-1LIMITED\s0 \s-1TO\s0 \s-1LOSS\s0 \s-1OF\s0 \s-1DATA\s0 \s-1OR\s0 \s-1DATA\s0 \s-1BEING\s0 \&\s-1RENDERED\s0 \s-1INACCURATE\s0 \s-1OR\s0 \s-1LOSSES\s0 \s-1SUSTAINED\s0 \s-1BY\s0 \s-1YOU\s0 \s-1OR\s0 \s-1THIRD\s0 \s-1PARTIES\s0 \s-1OR\s0 A \&\s-1FAILURE\s0 \s-1OF\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1TO\s0 \s-1OPERATE\s0 \s-1WITH\s0 \s-1ANY\s0 \s-1OTHER\s0 \s-1SOFTWARE\s0), \s-1EVEN\s0 \s-1IF\s0 \&\s-1SUCH\s0 \s-1HOLDER\s0 \s-1OR\s0 \s-1OTHER\s0 \s-1PARTY\s0 \s-1HAS\s0 \s-1BEEN\s0 \s-1ADVISED\s0 \s-1OF\s0 \s-1THE\s0 \s-1POSSIBILITY\s0 \s-1OF\s0 \&\s-1SUCH\s0 \s-1DAMAGES\s0.