NAME

Fret - Font REporting Tool

SYNOPSIS

use Font::Fret;
fret('', @ARGV);

or

package myFret;
use Font::Fret;
@ISA = qw(Font::Fret::Default);
fret('myFret', @ARGV);

DESCRIPTION

Fret is a font reporting tool system which allows for different reports to be written. A report is a package on which calls are made to give specific information for a specific report. The rest of Fret does the housekeeping of generating the report in PDF format.

The function fret which is imported when the Fret moduled is 'use'd, takes two arguments: the name of the report package and the command line array. Fret does all the work of parsing the command line, etc. and just makes call-backs into the package it is asked to use.

Fret.pm comes with its own default report package (called Font::Fret::Default) which may be subclassed to generate other reports.

The overall structure of the interaction between Fret and the reporting package is that Fret will ask the package for a list of character ids in the order in which those characters should appear in the report. For each character, Fret will ask the package to create a glyph id for that character. This allows a double layer of indirection in arriving at the list of glyph ids to process, allowing a glyph to appear twice in the report with different information about it each time.

There are two important areas in a report: inside the glyph box (where there are four corners in which information may be displayed) and the report area, which consists of two independent rows of information for each glyph. Each row type is columnated independently across all the glyphs on a page.

In addition to where the report information is displayed, there is also a mechanism which allows a limited level of formatting of the information. The text may be justified left, right or centre and the font styling may be adjusted between regular, bold, italic and bold italic and the colour of the text may be changed. Notice that the font face may not be changed or the font size or anything else. A formatted string consists of formatting information separated from the string by |. If a string needs to contain a | it should be escaped thus: \| (notice that there is no need to escape \ or any other character).

The formatting is structured as a comma separated list of 3 elements: justification, font styling and then colour.

justification

The values are r: right justified; c: centred and the default of l: left justified

font styling

The values are r: regular (by default); i: italic; b: bold; bi: bold-italic

colour

The colour is a string of 6 hex digits corresponding to 8-bits of Red, Green and Blue information

METHODS

make_cids

This subroutine is called to ask for a list of character ids, which will be used to generate glyph ids and thence glyphs. The returned list is rendered in the order of the list.

The first item on the returned list is used to display the type of report in the box header. This string may not be formatted.

This allows a FRET report writer to generate any sequence of glyphs in their report (e.g. Unicode based, pass/fail conditions, etc.)

cid_gid

This is called to convert a character id into a glyph id for rendering.

boxhdr

This subroutine is called to ask the report for the headings for the four items displayed in a box. The headings appear in the box header. The order of the returned list of string is: bottom left, bottom right, top left, top right. The strings may not be formatted in any way.

topdat

This subroutine returns the two strings that constitute what should be displayed in the top of a glyph box. The two strings allow for per glyph formatting. Notice that the default action is to render the right hand element (the second element) right justified.

lowdat

This subroutine returns two elements for the two elements displayed at the bottom of a glyph box. The elements may be formatted for colour, etc. and the second should be right formatted.

row1hdr

This returns the heading information for the first report row. The value returned is a list of formatted items, which will be used to head the columns in row 1 of the report area. These will be combined in the column width calculations.

row2hdr

Returns a list of formatted items corresponding to the column headers for row 2 of the report area.

row1

This subroutine is called for each glyph to return the content of each column in row 1 as a list of formatted items. The values passed in are:

cid     character id as passed to cid_gid
gid     glyph id as returned from cid_gid and is an index into the font
        for such tables as hmtx.
glyph   the glyph object from the font i.e. $font->{'loca'}{glyphs}[$gid]
uid     unicode reverse lookup of the gid. This is the lowest Unicode value
        which maps to this gid
font    the font object corresponding to this font

Each element in the returned list corresponds to an element in the returned list for row1hdr

row2

As per row 1 for row 2

label

Given:

Glyph
Point number
[x, y] point co-ordinates
path number
on or off point
font

Returns a simple string for the label for the point

cpanm Font::Fret

perl -MCPAN -e shell
install Font::Fret