NAME

SIRTX::Font - module for working with SIRTX font files

VERSION

version v0.06

SYNOPSIS

use SIRTX::Font;

my SIRTX::Font $font = SIRTX::Font->new;

$font->read('cool-font.sf');
$font->write('cool-font.sf');

if ($font->has_codepoint(0x1234)) { ... }

printf("%ux%u\@%u\n", $font->width, $font->height, $font->bits);

$font->glyph_for(0x1234, $font->import_glyph('U+1234.png'));

This module implements an interface to SIRTX font files.

All methods in this module die on error unless documented otherwise.

CHARACTER LISTS

This module includes a few methods that use named character lists. There refer to one or more of the build-in charater lists.

Currently defined:

ascii: All printable ASCII characters.
dec-mcs: All printable characters in DEC-MCS (Multinational Character Set).
dec-sg: All printable characters in DEC-SG (Special Graphics).
dec-tech: All printable characters in DEC Technical.
sirtx-characters: All characters in the SIRTX character list (provided by SIRTX on old non-Unicode terminals that support DLLCS).
important: Characters that are considered important in the context of SIRTX. Each base font SHOULD provide at least those characters. This also includes entries from at least dec-mcs, dec-sg, and sirtx-characters, but may contain more.
cp-850: Code page 850 (often used on classic DOS systems).
cp-858: Code page 858 (often used on more modern DOS systems).
cp-437: Code page 437 (original IBM PC character set).

METHODS

new

my SIRTX::Font $font = SIRTX::Font->new;

Creates a new font object. No parameters are supported.

gc

$font->gc;

(experimental, since v0.01)

Takes the trash out. This will remove unused glyphs and deduplicate glyphs that are still in use.

Note: After a call to this all glyph numbers become invalid.

width

$font->width($width);

my $width = $font->width;

Sets or gets the width of character cells.

height

$font->height($height);

my $height = $font->height;

Sets or gets the height of character cells.

bits

$font->bits($bits);

my $bits = $font->bits;

Sets or gets the bits per pixel of character cells.

list_attributes

my @attributes = $font->list_attributes;

(experimental, since v0.06)

Lists known attribute keys. The returned list may depend on the currently loaded font. Keys may be returned for attributes that are currently unset. Keys are returned for attributes that are currently set.

Note: This method will most likely be removed soon.

get_attribute

my $value = $font->get_attribute($key);

(experimental, since v0.06)

Returns an attribute value or dies if it is unset.

set_attribute

$font->set_attribute($key => $value);

(experimental, since v0.06)

Sets an attribute. Will die if the value does not validate.

codepoints

my $codepoints = $font->codepoints;

Returns the number of known code points.

Note: Must be called in scalar context.

glyphs

my $glyphs = $font->glyphs;

Returns the number of known glyphs.

Note: This is not the number of glyphs that is exported on write, as unused glyphs might be skipped.

Note: Must be called in scalar context.

has_codepoint

my $bool = $font->has_codepoint($codepoint);

Returns a true value if the code point is knowm, otherwise return a false value.

remove_codepoint

$font->remove_codepoint(0x1234);

Removes a code point from the font. This will not remove the glyph.

If the code point is not known this method will do nothing.

has_all_codepoints_from

my $bool = $font->has_all_codepoints_from( @lists );
# e.g.:
my $bool = $font->has_all_codepoints_from('important');
my $bool = $font->has_all_codepoints_from(qw(dec-mcs dec-sg));

Returns a true value if all code points from the given lists are included, otherwise false.

Note: This is faster than calling "missing_codepoints_from" and checking if it returned any items.

missing_codepoints_from

my @codepoints = $font->missing_codepoints_from( @lists );
# e.g.:
my @codepoints = $font->missing_codepoints_from('important');

Returns the code points missing from the given lists that are missing in this font.

Note: If you only want to check if all code points are included use "has_all_codepoints_from" which is faster.

remove_codepoint_not_in

$font->remove_codepoint_not_in( @lists );
# e.g.:
$font->remove_codepoint_not_in('dec-mcs');

Removes all code points from the current font that are not in the given lists. This can be used to strip a larger font to a subset efficiently.

Note: This will only remove the code points, not the glyphs as per "remove_codepoint".

glyph_for

my $glyph = $font->glyph_for($codepoint); # $codepoint is 0x1234 or 'U+1234'

$font->glyph_for($codepoint => $glyph);

Sets or gets the glyph for a given code point.

default_glyph_for

$glyph = $font->default_glyph_for($codepoint => $glyph);

Sets the glyph for the code point if it has no glyph set so far. Returns the new glyph (if the code point was modified) or the old (if it was already set).

alias_glyph

$font->alias_glyph($from, $to);

Aliases the glyph for code point $from to the same as code point $to.

default_alias_glyph

$font->default_alias_glyph($from, $to);

Aliases the glyph for code point $from to the same as code point $to if $from has no glyph set.

add_default_aliases

$font->add_default_aliases;
# or:
$font->add_default_aliases($level);

(experimental, since v0.02)

Adds aliases as per "default_alias_glyph" for known homoglyphs.

The following levels are supported:

common-small: A set if code point aliases that are both likely homoglyphs as well as hard to pick up by rendering engines.
common-large: A set of code point aliases that are likely homoglyphs, some might be picked up by rendering engines. This includes the aliases from common-small.
common-all: A set of code point aliases that are likely homoglyphs, including those that should be picked up by rendering engines. This includes the aliases from common-small, and common-large.

Note: This operation cannot easly be undone.

Note: The levels are not yet stable in this version. Future versions might use different sets of code points aliases.

read

$font->read($handle);

Reads a font file into memory. If any data is already loaded the data is merged.

write

$font->write($handle);

Writes the current font in the SIRTX format to the given handle.

import_glyph

my $glyph = $font->import_glyph($filename);

Imports a glyph from a file. The glyph index is returned.

The supported formats depend on the installed modules. See also Image::Magick.

import_alias_map

$font->import_alias_map($filename);

(experimental, since v0.04)

Imports an alias map from the given file.

The format is one alias group per line. Each line is formatted into two sections. The first section lists all the code points that are aliased to each other. The second part (seperated by a --) lists all the code points that are only aliased to (that is they will share the glyph from the first part, but the code points from the first part will not share glyph with the second part).

Each part is a list of codepoints in U+NNNN format, seperated by space, comma or both.

This method will ignore if a mapped glyph does not exists alike "default_glyph_for".

import_psf

$font->import_psf($filename);

(experimental since v0.06)

Imports a PC Screen Font (PSF) file into the font.

Supports PSF1, and PSF2 files at this point.

Note that files without a Unicode table might import incorrectly.

import_directory

$font->import_directory($filename [, %opts ]);

(experimental, since v0.02)

Imports a directory into the font. The directory contains of files with a name of the code point plus the extention png or wbmp (e.g. U+1F981.png).

There is one option supported: incremental. If set to a true value it will cause mappings for already known code points to be skipped. This can result in a massive speedup. Only use if you are sure no entries have been altered.

Note: All rules of "import_glyph" apply. Entries are merged, data already present in the font is not cleared.

Note: In order to deduplicate entries a call to "gc" might be considered.

export_glyph_as_image_magick

my Image::Magick $image = $font->export_glyph_as_image_magick($glyph);

(experimental, since v0.01)

Exports a single glyph as a image object.

export_alias_map

$font->export_alias_map($filename);

(experimental, since v0.04)

Exports the map of all aliases found in the font. This is the inverse of "import_alias_map".

Note: This method cannot know which code points are aliases one way and which are aliased both ways. This information is not included in the binary format. Therefore this method exports all aliases as both way aliases. This is the same behaviour as known from hardlinks.

make_up_glyphs

$font->make_up_glyphs;

(experimental since v0.06)

Makes up glyphs for the font. This will create glyphs that can be easily calculated, such as the space character (all blank).

The exact list of characters that can be made up depend on the version of this module and the available font data. Therefore this should be called late in processing a font, so that as much data is available to the algorithm as possible.

"add_default_aliases" should be called after this step if called at all. "gc" should be called after this step, as this step might generate glyphs that are in fact unused.

Note: This step can not easily be undone. It should be used with care on font files that a meant to be edited.

Note: Code points are added as per "default_glyph_for".

analyse

$font->analyse;

(experimental, since v0.06)

Analyses the font to find additional attributes automatically.

This can be useful specifically when importing pre-existing fonts.

However the result should be manually checked as the values might not reflect reality.

render

my Image::Magick $image = $font->render($string);
# e.g.:
my Image::Magick $image = $font->render("Hello World!");
$image->Transparent(color => 'white'); # transparent background
$image->Write('hello.png');

(experimental, since v0.03)

Renders a text using the loaded font.

AUTHOR

Philipp Schafft <lion@cpan.org>

COPYRIGHT AND LICENSE

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)

To install SIRTX::Font, copy and paste the appropriate command in to your terminal.

cpanm

cpanm SIRTX::Font

CPAN shell

perl -MCPAN -e shell
install SIRTX::Font

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

CHARACTER LISTS

METHODS

new

gc

width

height

bits

list_attributes

get_attribute

set_attribute

codepoints

glyphs

has_codepoint

remove_codepoint

has_all_codepoints_from

missing_codepoints_from

remove_codepoint_not_in

glyph_for

default_glyph_for

alias_glyph

default_alias_glyph

add_default_aliases

read

write

import_glyph

import_alias_map

import_psf

import_directory

export_glyph_as_image_magick

export_alias_map

make_up_glyphs

analyse

render

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions