View on GitHub

PDF-Font-Loader-raku

Font loader for the PDF tool-chain

[Raku PDF Project] / [PDF-Font-Loader Module] / PDF::Font::Loader

Name

PDF::Font::Loader

Synopsis

# load a font from a file
use PDF::Font::Loader :&load-font;
use PDF::Content::FontObj;

my PDF::Content::FontObj $deja;
$deja = PDF::Font::Loader.load-font: :file<t/fonts/DejaVuSans.ttf>;
-- or --
$deja = load-font( :file<t/fonts/DejaVuSans.ttf> );

# find/load the best matching system font
# *** requires FontConfig ***
use PDF::Font::Loader :load-font, :find-font;
$deja = load-font( :family<DejaVu>, :slant<italic> );
my Str $file = find-font( :family<DejaVu>, :slant<italic> );
my PDF::Content::FontObj $deja-vu = load-font: :$file;

# use the font to add text to a PDF
use PDF::Lite;
my PDF::Lite $pdf .= new;
$pdf.add-page.text: {
   .font = $deja, 12;
   .text-position = [10, 600];
   .say: 'Hello, world';
}
$pdf.save-as: "/tmp/example.pdf";

Description

This module provides font loading and handling for PDF::Lite, PDF::API6 and other PDF modules.

Methods

load-font

A class level method to load a font from a font file, or pattern creating a new PDF::Font::Loader::FontObj object.

multi method load-font(Str:D :$file, Bool :$subset, :$enc, :$dict);

Loads a font from a given font file as a PDF::Font::Loader::FontObj object.

multi method load-font(Bool :$subset, :$enc, :$lang, :$core-font, *%patt);

Finds the best matching font using the find-font method on a pattern and loads it. If :core-font is True and the pattern matches a core-font, it is loaded as a PDF::Content::Font::CoreFont object.

parameters:

multi method load-font(Str :$family, Str :$weight, Str :$stretch, Str :$slant, Bool :$core-font, Bool :$subset, Str :$enc, Str :$lang);

my $vera = PDF::Font::Loader.load-font: :family<vera>;
my $deja = PDF::Font::Loader.load-font: :family<Deja>, :weight<bold>, :stretch<condensed> :slant<italic>);

Finds and loads the best-matching system font via FontConfig.

Note: This method requires the Raku FontConfig module to be installed, unless the :core-font option is used, to load only PDF core fonts.

parameters:

find-font

use PDF::Font::Loader
    :Weight  # thin|extralight|light|book|regular|medium|semibold|bold|extrabold|black|100..900
    :Stretch # normal|[ultra|extra]?[condensed|expanded]
    :Slant   # normal|oblique|italic
;
find-font(Str :$family,     # e.g. :family<vera>
          Weight  :$weight,
          Stretch :$stretch,
          Slant   :$slant,
          Str     :$lang,   # e.g. :lang<jp>
          Bool    :$all,
          UInt    :$best,
          Bool    :$serif,  # serif(True) or sans-serif(False) fonts
          *%pattern,
          );

This method requires the optional FontConfig Raku module to be installed.

Locates, font-files after sorting system fonts using the pattern. Normally the best matching font-file is returned, or multiple font files can be returned using the :best($n) or :all options.

my $file = PDF::Font::Loader.find-font: :family<Deja>, :weight<bold>, :width<condensed>, :slant<italic>, :lang<en>;
say $file;  # /usr/share/fonts/truetype/dejavu/DejaVuSansCondensed-BoldOblique.ttf
my $font = PDF::Font::Loader.load-font: :$file;

The :all option returns a sequence of all fonts, ordered by best to worst matching. This method may be useful, if you wish to apply your own selection criteria.

The :best($n) is similar to :all, but returns at most the $n best matching fonts.

Any additional options are treated as a FontConfig pattern attributes. For example :spacing<mono> will select mono-space fonts.

use PDF::Font::Loader;
use Font::FreeType;
use Font::FreeType::Face;
my Font::FreeType $ft .= new;
my $series = PDF::Font::Loader.find-font(:best(10), :!serif, :weight<bold>,);
my Str @best = $series.Array;
# prefer a font with kerning
my Str $best-font = @best.first: -> $file {
    my Font::FreeType::Face $face = $ft.face: $file;
    $face.has-kerning;
}
# fall-back to best matching font without kerning
$best-font //= @best.head;

note "best font: " ~ $best-font;

can-subset

multi method can-subset returns Bool;

Returns True if PDF::Font::Loader has general font subsetting capability; I.E. the optional HarfBuzz::Subset module has been installed.

multi method can-subset(IO() $font-file) returns Bool;

Returns True if PDF::Font::Loader has font subsetting capability for the particular font.

This will usually be be True for TrueType and OpenType fonts (extensions .ttf, .otf, .ttc, and .otc), if the optional HarfBuzz::Subset module has been installed.