PostSc...Metrics(3pm)

📦
version 2.23 · 3 versions
, in ubuntu noble, ubuntu resolute, ubuntu stonking

✨ PostScript::File::Metrics — metrics for PostScript fonts ✨

okay bestie, this is a Perl manpage (3pm section, iykyk) and it's literally about measuring fonts. yes. fonts. we're measuring fonts. stay with me 💅

💖 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 🦋

So PostScript::File::Metrics hands you a subset of the metrics you'd get from Font::AFM. But like… why does it even exist? Because it lets you pre-compile the AFM files into Perl modules. Which means loading them is way more efficient — but more importantly, it means you don't have to install (or configure) Font::AFM at all. And that matters, because the locations and filenames of AFM files are not very standardized 😭 which makes configuring Font::AFM genuinely difficult. iconic of AFM honestly.

PostScript::File::Metrics comes with 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 that's not in that list, you're gonna need 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. there's no way around it bestie.)

👑 ATTRIBUTES 👑

Every attribute here is read-only, except for auto_hyphen and size, which you can set using the corresponding set_ methods. periodt.

🎀 size

The current font size, in points. real talk: this isn't an attribute of the font, it's an attribute of this Metrics object. The attributes that describe the font's dimensions get adjusted according to this value.

🎀 auto_hyphen

If it's 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

A unique, human-readable name for an individual font. For instance, "Times Roman".

🎀 family

A 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. An example of a family name is "Times".

🎀 weight

A human-readable name for the weight (or "boldness") attribute of a font. Examples are "Roman", "Bold", "Medium".

🎀 italic_angle

The 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 that encloses the shape you'd get 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

The recommended distance from the baseline for positioning underline strokes. This number is the y coordinate of the center of the stroke.

🎀 underline_thickness

The recommended stroke width for underlining.

🎀 version

The version number of the font. (not the version of the module, bestie — the font. keep up 💅)

💅 METHODS 💅

🌈 new

$metrics = PostScript::File::Metrics->new($font, [$size, [$encoding]])

Normally you'd use get_metrics in PostScript::File to construct a Metrics object (because that can grab the $encoding from the document for you), but yeah — you can construct one directly if you want to be like that.

$size is the font size in points, and it defaults to 1000.

$encoding is the character encoding used by width and wrap. The valid choices are std, sym, cp1252, and iso-8859-1. The default is std, meaning PostScript's StandardEncoding — unless $font is Symbol, in which case it's sym, meaning PostScript's SymbolEncoding. Neither std nor sym does any character set translation at all.

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). It influences the attributes that concern dimensions and the string width calculations. It returns the Metrics object, so you can chain straight into the next method. slay.

🌈 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 anyway. If $new_chars is omitted or undef, it 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 it's displayed in this font at the current size. If $string has the UTF8 flag set, it gets translated into the font's encoding. Otherwise, $string is expected to already be in the correct character set. $string should not contain newlines.

If the optional parameter $already_encoded is true, then $string is assumed to already be 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, those will also cause line breaks. If $text has the UTF8 flag set, it gets translated into the font's encoding. Otherwise, $text is expected to already be in the correct character set.

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. On top of that, $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) gives you extra control over the wrapping. It may contain the following keys:

  • chars — overrides the line-breaking characters that would normally be set by the set_wrap_chars method. The value has the same meaning as it does 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, don't 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. blessed and unbothered fr fr.

💀 INCOMPATIBILITIES 💀

None reported. 🫶

😭 BUGS AND LIMITATIONS 😭

No bugs have been reported. (we love a clean slate ✨)

💜 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.

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 🔥

bestie. listen. this is the legally-mandated ALL CAPS section and it is entirely serious, so I'm not gonna play with it.

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.

okay that's the whole page 🫶 this one came bundled with perl v5.36.0 and the doc itself is dated 2022-10-14. go measure some glyphs bestie 💖✨

📦 where this page comes from