local changes from ve
[librarian.git] / librarian / font-optimizer / ext / Font-TTF / lib / Font / TTF / Font.pm
1 package Font::TTF::Font;
2
3 =head1 NAME
4
5 Font::TTF::Font - Memory representation of a font
6
7 =head1 SYNOPSIS
8
9 Here is the regression test (you provide your own font). Run it once and then
10 again on the output of the first run. There should be no differences between
11 the outputs of the two runs.
12
13     $f = Font::TTF::Font->open($ARGV[0]);
14
15     # force a read of all the tables
16     $f->tables_do(sub { $_[0]->read; });
17
18     # force read of all glyphs (use read_dat to use lots of memory!)
19     # $f->{'loca'}->glyphs_do(sub { $_[0]->read; });
20     $f->{'loca'}->glyphs_do(sub { $_[0]->read_dat; });
21     # NB. no need to $g->update since $f->{'glyf'}->out will do it for us
22
23     $f->out($ARGV[1]);
24     $f->release;            # clear up memory forcefully!
25
26 =head1 DESCRIPTION
27
28 A Truetype font consists of a header containing a directory of tables which
29 constitute the rest of the file. This class holds that header and directory and
30 also creates objects of the appropriate type for each table within the font.
31 Note that it does not read each table into memory, but creates a short reference
32 which can be read using the form:
33
34     $f->{$tablename}->read;
35
36 Classes are included that support many of the different TrueType tables. For
37 those for which no special code exists, the table type C<table> is used, which
38 defaults to L<Font::TTF::Table>. The current tables which are supported are:
39
40     table       Font::TTF::Table      - for unknown tables
41     EBDT        Font::TTF::EBDT
42     EBLC        Font::TTF::EBLC
43     Feat        Font::TTF::GrFeat
44     GDEF        Font::TTF::GDEF
45     GPOS        Font::TTF::GPOS
46     GSUB        Font::TTF::GSUB
47     LTSH        Font::TTF::LTSH
48     OS/2        Font::TTF::OS_2
49     PCLT        Font::TTF::PCLT
50     Sill        Font::TTF::Sill
51     bsln        Font::TTF::Bsln
52     cmap        Font::TTF::Cmap       - see also Font::TTF::OldCmap
53     cvt         Font::TTF::Cvt_
54     fdsc        Font::TTF::Fdsc
55     feat        Font::TTF::Feat
56     fmtx        Font::TTF::Fmtx
57     fpgm        Font::TTF::Fpgm
58     glyf        Font::TTF::Glyf       - see also Font::TTF::Glyph
59     hdmx        Font::TTF::Hdmx
60     head        Font::TTF::Head
61     hhea        Font::TTF::Hhea
62     hmtx        Font::TTF::Hmtx
63     kern        Font::TTF::Kern       - see alternative Font::TTF::AATKern
64     loca        Font::TTF::Loca
65     maxp        Font::TTF::Maxp
66     mort        Font::TTF::Mort       - see also Font::TTF::OldMort
67     name        Font::TTF::Name
68     post        Font::TTF::Post
69     prep        Font::TTF::Prep
70     prop        Font::TTF::Prop
71     vhea        Font::TTF::Vhea
72     vmtx        Font::TTF::Vmtx
73
74 Links are:
75
76 L<Font::TTF::Table> 
77 L<Font::TTF::EBDT> L<Font::TTF::EBLC> L<Font::TTF::GrFeat>
78 L<Font::TTF::GDEF> L<Font::TTF::GPOS> L<Font::TTF::GSUB> L<Font::TTF::LTSH>
79 L<Font::TTF::OS_2> L<Font::TTF::PCLT> L<Font::TTF::Sill> L<Font::TTF::Bsln> L<Font::TTF::Cmap> L<Font::TTF::Cvt_>
80 L<Font::TTF::Fdsc> L<Font::TTF::Feat> L<Font::TTF::Fmtx> L<Font::TTF::Fpgm> L<Font::TTF::Glyf>
81 L<Font::TTF::Hdmx> L<Font::TTF::Head> L<Font::TTF::Hhea> L<Font::TTF::Hmtx> L<Font::TTF::Kern>
82 L<Font::TTF::Loca> L<Font::TTF::Maxp> L<Font::TTF::Mort> L<Font::TTF::Name> L<Font::TTF::Post>
83 L<Font::TTF::Prep> L<Font::TTF::Prop> L<Font::TTF::Vhea> L<Font::TTF::Vmtx> L<Font::TTF::OldCmap>
84 L<Font::TTF::Glyph> L<Font::TTF::AATKern> L<Font::TTF::OldMort>
85
86
87 =head1 INSTANCE VARIABLES
88
89 Instance variables begin with a space (and have lengths greater than the 4
90 characters which make up table names).
91
92 =over
93
94 =item nocsum
95
96 This is used during output to disable the creation of the file checksum in the
97 head table. For example, during DSIG table creation, this flag will be set to
98 ensure that the file checksum is left at zero.
99
100 =item noharmony
101
102 If set, do not harmonize the script and lang trees of GPOS and GSUB tables. See L<Font::TTF::Ttopen> for more info.
103
104 =item fname (R)
105
106 Contains the filename of the font which this object was read from.
107
108 =item INFILE (P)
109
110 The file handle which reflects the source file for this font.
111
112 =item OFFSET (P)
113
114 Contains the offset from the beginning of the read file of this particular
115 font directory, thus providing support for TrueType Collections.
116
117 =back
118
119 =head1 METHODS
120
121 =cut
122
123 use IO::File;
124
125 use strict;
126 use vars qw(%tables $VERSION $dumper);
127 use Symbol();
128
129 require 5.004;
130
131 $VERSION = 0.38;    # MJPH       2-FEB-2008     Add Sill table
132 # $VERSION = 0.37;    # MJPH       7-OCT-2005     Force hhea update if dirty, give more OS/2 stuff in update
133 # $VERSION = 0.36;    # MJPH      19-AUG-2005     Change cmap::reverse api to be opts based
134 # $VERSION = 0.35;    # MJPH       4-MAY-2004     Various fixes to OpenType stuff, separate off scripts
135 # $VERSION = 0.34;    # MJPH      22-MAY-2003     Update PSNames to latest AGL
136 # $VERSION = 0.33;    # MJPH       9-OCT-2002     Support CFF OpenType (just by version=='OTTO'?!)
137 # $VERSION = 0.32;    # MJPH       2-OCT-2002     Bug fixes to TTFBuilder, new methods and some
138 #                                                 extension table support in Ttopen and Coverage
139 # $VERSION = 0.31;    # MJPH       1-JUL-2002     fix read format 12 cmap (bart@cs.pdx.edu) 
140 #                                                 improve surrogate support in ttfremap
141 #                                                 fix return warn to return warn,undef
142 #                                                 ensure correct indexToLocFormat
143 # $VERSION = 0.30;    # MJPH      28-MAY-2002     add updated release
144 # $VERSION = 0.29;    # MJPH       9-APR-2002     update ttfbuilder, sort out surrogates
145 # $VERSION = 0.28;    # MJPH      13-MAR-2002     update ttfbuilder, add Font::TTF::Cmap::ms_enc()
146 # $VERSION = 0.27;    # MJPH       6-FEB-2002     update ttfbuilder, support no fpgm, no more __DATA__
147 # $VERSION = 0.26;    # MJPH      19-SEP-2001     Update ttfbuilder
148 # $VERSION = 0.25;    # MJPH      18-SEP-2001     problems in update of head
149 # $VERSION = 0.24;    # MJPH       1-AUG-2001     Sort out update
150 # $VERSION = 0.23;    # GST       30-MAY-2001     Memory leak fixed
151 # $VERSION = 0.22;    # MJPH      09-APR-2001     Ensure all of AAT stuff included
152 # $VERSION = 0.21;    # MJPH      23-MAR-2001     Improve Opentype support
153 # $VERSION = 0.20;    # MJPH      13-JAN-2001     Add XML output and some of XML input, AAT & OT tables
154 # $VERSION = 0.19;    # MJPH      29-SEP-2000     Add cmap::is_unicode, debug makefile.pl
155 # $VERSION = 0.18;    # MJPH      21-JUL-2000     Debug Utils::TTF_bininfo
156 # $VERSION = 0.17;    # MJPH      16-JUN-2000     Add utf8 support to names
157 # $VERSION = 0.16;    # MJPH      26-APR-2000     Mark read tables as read, tidy up POD
158 # $VERSION = 0.15;    # MJPH       5-FEB-2000     Ensure right versions released
159 # $VERSION = 0.14;    # MJPH      11-SEP-1999     Sort out Unixisms, agian!
160 # $VERSION = 0.13;    # MJPH       9-SEP-1999     Add empty, debug update_bbox
161 # $VERSION = 0.12;    # MJPH      22-JUL-1999     Add update_bbox
162 # $VERSION = 0.11;    # MJPH       7-JUL-1999     Don't store empties in cmaps
163 # $VERSION = 0.10;    # MJPH      21-JUN-1999     Use IO::File
164 # $VERSION = 0.09;    # MJPH       9-JUN-1999     Add 5.004 require, minor tweeks in cmap
165 # $VERSION = 0.08;    # MJPH      19-MAY-1999     Sort out line endings for Unix
166 # $VERSION = 0.07;    # MJPH      28-APR-1999     Get the regression tests to work
167 # $VERSION = 0.06;    # MJPH      26-APR-1999     Start to add to CVS, correct MANIFEST.SKIP
168 # $VERSION = 0.05;    # MJPH      13-APR-1999     See changes for 0.05
169 # $VERSION = 0.04;    # MJPH      13-MAR-1999     Tidy up Tarball
170 # $VERSION = 0.03;    # MJPH       9-MAR-1999     Move to Font::TTF for CPAN
171 # $VERSION = 0.02;    # MJPH      12-FEB-1999     Add support for ' nocsum' for DSIGS
172 # $VERSION = 0.0001;
173
174 %tables = (
175         'table' => 'Font::TTF::Table',
176         'EBDT' => 'Font::TTF::EBDT',
177         'EBLC' => 'Font::TTF::EBLC',
178         'Feat' => 'Font::TTF::GrFeat',
179         'GDEF' => 'Font::TTF::GDEF',
180         'GPOS' => 'Font::TTF::GPOS',
181         'GSUB' => 'Font::TTF::GSUB',
182         'LTSH' => 'Font::TTF::LTSH',
183         'OS/2' => 'Font::TTF::OS_2',
184         'PCLT' => 'Font::TTF::PCLT',
185         'Sill' => 'Font::TTF::Sill',
186         'bsln' => 'Font::TTF::Bsln',
187         'cmap' => 'Font::TTF::Cmap',
188         'cvt ' => 'Font::TTF::Cvt_',
189         'fdsc' => 'Font::TTF::Fdsc',
190         'feat' => 'Font::TTF::Feat',
191         'fmtx' => 'Font::TTF::Fmtx',
192         'fpgm' => 'Font::TTF::Fpgm',
193         'glyf' => 'Font::TTF::Glyf',
194         'hdmx' => 'Font::TTF::Hdmx',
195         'head' => 'Font::TTF::Head',
196         'hhea' => 'Font::TTF::Hhea',
197         'hmtx' => 'Font::TTF::Hmtx',
198         'kern' => 'Font::TTF::Kern',
199         'loca' => 'Font::TTF::Loca',
200         'maxp' => 'Font::TTF::Maxp',
201         'mort' => 'Font::TTF::Mort',
202         'name' => 'Font::TTF::Name',
203         'post' => 'Font::TTF::Post',
204         'prep' => 'Font::TTF::Prep',
205         'prop' => 'Font::TTF::Prop',
206         'vhea' => 'Font::TTF::Vhea',
207         'vmtx' => 'Font::TTF::Vmtx',
208           );
209
210 # This is special code because I am fed up of every time I x a table in the debugger
211 # I get the whole font printed. Thus substitutes my 3 line change to dumpvar into
212 # the debugger. Clunky, but nice. You are welcome to a copy if you want one.
213           
214 BEGIN {
215     my ($p);
216
217     foreach $p (@INC)
218     {
219         if (-f "$p/mydumpvar.pl")
220         {
221             $dumper = 'mydumpvar.pl';
222             last;
223         }
224     }
225     $dumper ||= 'dumpvar.pl';
226 }
227
228 sub main::dumpValue
229 { do $dumper; &main::dumpValue; }
230     
231
232 =head2 Font::TTF::Font->AddTable($tablename, $class)
233
234 Adds the given class to be used when representing the given table name. It also
235 'requires' the class for you.
236
237 =cut
238
239 sub AddTable
240 {
241     my ($class, $table, $useclass) = @_;
242
243     $tables{$table} = $useclass;
244 #    $useclass =~ s|::|/|oig;
245 #    require "$useclass.pm";
246 }
247
248
249 =head2 Font::TTF::Font->Init
250
251 For those people who like making fonts without reading them. This subroutine
252 will require all the table code for the various table types for you. Not
253 needed if using Font::TTF::Font::read before using a table.
254
255 =cut
256
257 sub Init
258 {
259     my ($class) = @_;
260     my ($t);
261
262     foreach $t (values %tables)
263     {
264         $t =~ s|::|/|oig;
265         require "$t.pm";
266     }
267 }
268
269 =head2 Font::TTF::Font->new(%props)
270
271 Creates a new font object and initialises with the given properties. This is
272 primarily for use when a TTF is embedded somewhere. Notice that the properties
273 are automatically preceded by a space when inserted into the object. This is in
274 order that fields do not clash with tables.
275
276 =cut
277
278 sub new
279 {
280     my ($class, %props) = @_;
281     my ($self) = {};
282
283     bless $self, $class;
284
285     foreach (keys %props)
286     { $self->{" $_"} = $props{$_}; }
287     $self;
288 }
289
290
291 =head2 Font::TTF::Font->open($fname)
292
293 Reads the header and directory for the given font file and creates appropriate
294 objects for each table in the font.
295
296 =cut
297
298 sub open
299 {
300     my ($class, $fname) = @_;
301     my ($fh);
302     my ($self) = {};
303     
304     unless (ref($fname))
305     {
306         $fh = IO::File->new($fname) or return undef;
307         binmode $fh;
308     } else
309     { $fh = $fname; }
310
311     $self->{' INFILE'} = $fh;
312     $self->{' fname'} = $fname;
313     $self->{' OFFSET'} = 0;
314     bless $self, $class;
315     
316     $self->read;
317 }
318
319 =head2 $f->read
320
321 Reads a Truetype font directory starting from the current location in the file.
322 This has been separated from the C<open> function to allow support for embedded
323 TTFs for example in TTCs. Also reads the C<head> and C<maxp> tables immediately.
324
325 =cut
326
327 sub read
328 {
329     my ($self) = @_;
330     my ($fh) = $self->{' INFILE'};
331     my ($dat, $i, $ver, $dir_num, $type, $name, $check, $off, $len, $t);
332
333     $fh->seek($self->{' OFFSET'}, 0);
334     $fh->read($dat, 12);
335     ($ver, $dir_num) = unpack("Nn", $dat);
336     $ver == 1 << 16 || $ver == unpack('N', 'OTTO') || $ver == 0x74727565 or return undef;  # support Mac sfnts
337     
338     for ($i = 0; $i < $dir_num; $i++)
339     {
340         $fh->read($dat, 16) || die "Reading table entry";
341         ($name, $check, $off, $len) = unpack("a4NNN", $dat);
342         $self->{$name} = $self->{' PARENT'}->find($self, $name, $check, $off, $len) && next
343                 if (defined $self->{' PARENT'});
344         $type = $tables{$name} || 'Font::TTF::Table';
345         $t = $type;
346         if ($^O eq "MacOS")
347         { $t =~ s/^|::/:/oig; }
348         else
349         { $t =~ s|::|/|oig; }
350         require "$t.pm";
351         $self->{$name} = $type->new(PARENT  => $self,
352                                     NAME    => $name,
353                                     INFILE  => $fh,
354                                     OFFSET  => $off,
355                                     LENGTH  => $len,
356                                     CSUM    => $check);
357     }
358     
359     foreach $t ('head', 'maxp')
360     { $self->{$t}->read if defined $self->{$t}; }
361
362     $self;
363 }
364
365
366 =head2 $f->out($fname [, @tablelist])
367
368 Writes a TTF file consisting of the tables in tablelist. The list is checked to
369 ensure that only tables that exist are output. (This means that you can't have
370 non table information stored in the font object with key length of exactly 4)
371
372 In many cases the user simply wants to output all the tables in alphabetical order.
373 This can be done by not including a @tablelist, in which case the subroutine will
374 output all the defined tables in the font in alphabetical order.
375
376 Returns $f on success and undef on failure, including warnings.
377
378 All output files must include the C<head> table.
379
380 =cut
381
382 sub out
383 {
384     my ($self, $fname, @tlist) = @_;
385     my ($fh);
386     my ($dat, $numTables, $sRange, $eSel);
387     my (%dir, $k, $mloc, $count);
388     my ($csum, $lsum, $msum, $loc, $oldloc, $len, $shift);
389
390     unless (ref($fname))
391     {
392         $fh = IO::File->new("+>$fname") || return warn("Unable to open $fname for writing"), undef;
393         binmode $fh;
394     } else
395     { $fh = $fname; }
396     
397     $self->{' oname'} = $fname;
398     $self->{' outfile'} = $fh;
399
400     if ($self->{' wantsig'})
401     {
402         $self->{' nocsum'} = 1;
403 #        $self->{'head'}{'checkSumAdjustment'} = 0;
404         $self->{' tempDSIG'} = $self->{'DSIG'};
405         $self->{' tempcsum'} = $self->{'head'}{' CSUM'};
406         delete $self->{'DSIG'};
407         @tlist = sort {$self->{$a}{' OFFSET'} <=> $self->{$b}{' OFFSET'}}
408             grep (length($_) == 4 && defined $self->{$_}, keys %$self) if ($#tlist < 0);
409     }
410     elsif ($#tlist < 0)
411     { @tlist = sort keys %$self; }
412     
413     @tlist = grep(length($_) == 4 && defined $self->{$_}, @tlist);
414     $numTables = $#tlist + 1;
415     $numTables++ if ($self->{' wantsig'});
416     
417     ($numTables, $sRange, $eSel, $shift) = Font::TTF::Utils::TTF_bininfo($numTables, 16);
418     $dat = pack("Nnnnn", 1 << 16, $numTables, $sRange, $eSel, $shift);
419     $fh->print($dat);
420     $msum = unpack("%32N*", $dat);
421
422 # reserve place holders for each directory entry
423     foreach $k (@tlist)
424     {
425         $dir{$k} = pack("A4NNN", $k, 0, 0, 0);
426         $fh->print($dir{$k});
427     }
428
429     $fh->print(pack('A4NNN', '', 0, 0, 0)) if ($self->{' wantsig'});
430
431     $loc = $fh->tell();
432     if ($loc & 3)
433     {
434         $fh->print(substr("\000" x 4, $loc & 3));
435         $loc += 4 - ($loc & 3);
436     }
437
438     foreach $k (@tlist)
439     {
440         $oldloc = $loc;
441         $self->{$k}->out($fh);
442         $loc = $fh->tell();
443         $len = $loc - $oldloc;
444         if ($loc & 3)
445         {
446             $fh->print(substr("\000" x 4, $loc & 3));
447             $loc += 4 - ($loc & 3);
448         }
449         $fh->seek($oldloc, 0);
450         $csum = 0; $mloc = $loc;
451         while ($mloc > $oldloc)
452         {
453             $count = ($mloc - $oldloc > 4096) ? 4096 : $mloc - $oldloc;
454             $fh->read($dat, $count);
455             $csum += unpack("%32N*", $dat);
456 # this line ensures $csum stays within 32 bit bounds, clipping as necessary
457             if ($csum > 0xffffffff) { $csum -= 0xffffffff; $csum--; }
458             $mloc -= $count;
459         }
460         $dir{$k} = pack("A4NNN", $k, $csum, $oldloc, $len);
461         $msum += $csum + unpack("%32N*", $dir{$k});
462         while ($msum > 0xffffffff) { $msum -= 0xffffffff; $msum--; }
463         $fh->seek($loc, 0);
464     }
465
466     unless ($self->{' nocsum'})             # assuming we want a file checksum
467     {
468 # Now we need to sort out the head table's checksum
469         if (!defined $dir{'head'})
470         {                                   # you have to have a head table
471             $fh->close();
472             return warn("No 'head' table to output in $fname"), undef;
473         }
474         ($csum, $loc, $len) = unpack("x4NNN", $dir{'head'});
475         $fh->seek($loc + 8, 0);
476         $fh->read($dat, 4);
477         $lsum = unpack("N", $dat);
478         if ($lsum != 0)
479         {
480             $csum -= $lsum;
481             if ($csum < 0) { $csum += 0xffffffff; $csum++; }
482             $msum -= $lsum * 2;                     # twice (in head and in csum)
483             while ($msum < 0) { $msum += 0xffffffff; $msum++; }
484         }
485         $lsum = 0xB1B0AFBA - $msum;
486         $fh->seek($loc + 8, 0);
487         $fh->print(pack("N", $lsum));
488         $dir{'head'} = pack("A4NNN", 'head', $csum, $loc, $len);
489     } elsif ($self->{' wantsig'})
490     {
491         if (!defined $dir{'head'})
492         {                                   # you have to have a head table
493             $fh->close();
494             return warn("No 'head' table to output in $fname"), undef;
495         }
496         ($csum, $loc, $len) = unpack("x4NNN", $dir{'head'});
497         $fh->seek($loc + 8, 0);
498         $fh->print(pack("N", 0));
499 #        $dir{'head'} = pack("A4NNN", 'head', $self->{' tempcsum'}, $loc, $len);
500     }
501
502 # Now we can output the directory again
503     if ($self->{' wantsig'})
504     { @tlist = sort @tlist; }
505     $fh->seek(12, 0);
506     foreach $k (@tlist)
507     { $fh->print($dir{$k}); }
508     $fh->print(pack('A4NNN', '', 0, 0, 0)) if ($self->{' wantsig'});
509     $fh->close();
510     $self;
511 }
512
513
514 =head2 $f->out_xml($filename [, @tables])
515
516 Outputs the font in XML format
517
518 =cut
519
520 sub out_xml
521 {
522     my ($self, $fname, @tlist) = @_;
523     my ($fh, $context, $numTables, $k);
524
525     $context->{'indent'} = ' ' x 4;
526
527     unless (ref($fname))
528     {
529         $fh = IO::File->new("+>$fname") || return warn("Unable to open $fname"), undef;
530         binmode $fh;
531     } else
532     { $fh = $fname; }
533
534     unless (scalar @tlist > 0)
535     {
536         @tlist = sort keys %$self;
537         @tlist = grep(length($_) == 4 && defined $self->{$_}, @tlist);
538     }
539     $numTables = $#tlist + 1;
540
541     $context->{'fh'} = $fh;
542     $fh->print("<?xml version='1.0' encoding='UTF-8'?>\n");
543     $fh->print("<font tables='$numTables'>\n\n");
544     
545     foreach $k (@tlist)
546     {
547         $fh->print("<table name='$k'>\n");
548         $self->{$k}->out_xml($context, $context->{'indent'});
549         $fh->print("</table>\n");
550     }
551
552     $fh->print("</font>\n");
553     $fh->close;
554     $self;
555 }
556
557
558 =head2 $f->XML_start($context, $tag, %attrs)
559
560 Handles start messages from the XML parser. Of particular interest to us are <font> and
561 <table>.
562
563 =cut
564
565 sub XML_start
566 {
567     my ($self, $context, $tag, %attrs) = @_;
568     my ($name, $type, $t);
569
570     if ($tag eq 'font')
571     { $context->{'tree'}[-1] = $self; }
572     elsif ($tag eq 'table')
573     {
574         $name = $attrs{'name'};
575         unless (defined $self->{$name})
576         {
577             $type = $tables{$name} || 'Font::TTF::Table';
578             $t = $type;
579             if ($^O eq "MacOS")
580             { $t =~ s/^|::/:/oig; }
581             else
582             { $t =~ s|::|/|oig; }
583             require "$t.pm";
584             $self->{$name} = $type->new('PARENT' => $self, 'NAME' => $name, 'read' => 1);
585         }
586         $context->{'receiver'} = ($context->{'tree'}[-1] = $self->{$name});
587     }
588     $context;
589 }
590
591
592 sub XML_end
593 {
594     my ($self) = @_;
595     my ($context, $tag, %attrs) = @_;
596     my ($i);
597
598     return undef unless ($tag eq 'table' && $attrs{'name'} eq 'loca');
599     if (defined $context->{'glyphs'} && $context->{'glyphs'} ne $self->{'loca'}{'glyphs'})
600     {
601         for ($i = 0; $i <= $#{$context->{'glyphs'}}; $i++)
602         { $self->{'loca'}{'glyphs'}[$i] = $context->{'glyphs'}[$i] if defined $context->{'glyphs'}[$i]; }
603         $context->{'glyphs'} = $self->{'loca'}{'glyphs'};
604     }
605     return undef;
606 }
607
608 =head2 $f->update
609
610 Sends update to all the tables in the font and then resets all the isDirty
611 flags on each table. The data structure in now consistent as a font (we hope).
612
613 =cut
614
615 sub update
616 {
617     my ($self) = @_;
618     
619     $self->tables_do(sub { $_[0]->update; });
620
621     $self;
622 }
623
624 =head2 $f->dirty
625
626 Dirties all the tables in the font
627
628 =cut
629
630 sub dirty
631 { $_[0]->tables_do(sub { $_[0]->dirty; }); $_[0]; }
632
633 =head2 $f->tables_do(&func [, tables])
634
635 Calls &func for each table in the font. Calls the table in alphabetical sort
636 order as per the order in the directory:
637
638     &func($table, $name);
639
640 May optionally take a list of table names in which case func is called
641 for each of them in the given order.
642 =cut
643
644 sub tables_do
645 {
646     my ($self, $func, @tables) = @_;
647     my ($t);
648
649     foreach $t (@tables ? @tables : sort grep {length($_) == 4} keys %$self)
650     { &$func($self->{$t}, $t); }
651     $self;
652 }
653
654
655 =head2 $f->release
656
657 Releases ALL of the memory used by the TTF font and all of its component
658 objects.  After calling this method, do B<NOT> expect to have anything left in
659 the C<Font::TTF::Font> object.
660
661 B<NOTE>, that it is important that you call this method on any
662 C<Font::TTF::Font> object when you wish to destruct it and free up its memory.
663 Internally, we track things in a structure that can result in circular
664 references, and without calling 'C<release()>' these will not properly get
665 cleaned up by Perl.  Once you've called this method, though, don't expect to be
666 able to do anything else with the C<Font::TTF::Font> object; it'll have B<no>
667 internal state whatsoever.
668
669 B<Developer note:> As part of the brute-force cleanup done here, this method
670 will throw a warning message whenever unexpected key values are found within
671 the C<Font::TTF::Font> object.  This is done to help ensure that any unexpected
672 and unfreed values are brought to your attention so that you can bug us to keep
673 the module updated properly; otherwise the potential for memory leaks due to
674 dangling circular references will exist.  
675
676 =cut
677
678 sub release
679 {
680     my ($self) = @_;
681
682 # delete stuff that we know we can, here
683
684     my @tofree = map { delete $self->{$_} } keys %{$self};
685
686     while (my $item = shift @tofree)
687     {
688         my $ref = ref($item);
689         if (UNIVERSAL::can($item, 'release'))
690         { $item->release(); }
691         elsif ($ref eq 'ARRAY')
692         { push( @tofree, @{$item} ); }
693         elsif (UNIVERSAL::isa($ref, 'HASH'))
694         { release($item); }
695     }
696
697 # check that everything has gone - it better had!
698     foreach my $key (keys %{$self})
699     { warn ref($self) . " still has '$key' key left after release.\n"; }
700 }
701
702 1;
703
704 =head1 BUGS
705
706 Bugs abound aplenty I am sure. There is a lot of code here and plenty of scope.
707 The parts of the code which haven't been implemented yet are:
708
709 =over 4
710
711 =item Post
712
713 Version 4 format types are not supported yet.
714
715 =item Cmap
716
717 Format type 2 (MBCS) has not been implemented yet and therefore may cause
718 somewhat spurious results for this table type.
719
720 =item Kern
721
722 Only type 0 & type 2 tables are supported (type 1 & type 3 yet to come).
723
724 =item TTC
725
726 The current Font::TTF::Font::out method does not support the writing of TrueType
727 Collections.
728
729 =back
730
731 In addition there are weaknesses or features of this module library
732
733 =over 4
734
735 =item *
736
737 There is very little (or no) error reporting. This means that if you have
738 garbled data or garbled data structures, then you are liable to generate duff
739 fonts.
740
741 =item *
742
743 The exposing of the internal data structures everywhere means that doing
744 radical re-structuring is almost impossible. But it stop the code from becoming
745 ridiculously large.
746
747 =back
748
749 Apart from these, I try to keep the code in a state of "no known bugs", which
750 given the amount of testing this code has had, is not a guarantee of high
751 quality, yet.
752
753 For more details see the appropriate class files.
754
755 =head1 AUTHOR
756
757 Martin Hosken Martin_Hosken@sil.org
758
759 Copyright Martin Hosken 1998.
760
761 No warranty or expression of effectiveness, least of all regarding anyone's
762 safety, is implied in this software or documentation.
763
764 =head2 Licensing
765
766 The Perl TTF module is licensed under the Perl Artistic License.
767