Defoma::Id(3pm)Defoma::Id(3pm)NAMEDefoma::Id - Defoma module to handle Id cache.
SYNOPSIS
use Defoma::Id;
$Id = defoma_id_open_cache( suffix, package_name );
defoma_id_close_cache( id_object );
defoma_id_register( id_object,
type => type,
font => font,
id => id,
priority => priority,
category => category,
origin => origin,
depend => depend,
hints => hints );
defoma_id_unregister( id_object,
type => type,
font => font,
id => id );
@index = defoma_id_grep_cache( id_object, search-type,
id => id,
font => font,
type => type,
category => category,
depid => depid,
depfont => depfont );
@hints = defoma_id_get_hints( id_object, index );
defoma_id_set( id_object, id, font, flag );
defoma_id_unset( id_object, id, font );
DESCRIPTIONDefoma::Id is a Defoma module to handle identifiers of fonts and
id-caches. It provides functions listed above which are supposed to be
called from Defoma-configuration scripts.
id-cache is sort of a database and its aim is to avoid name space con‐
flict. Applications often access fonts through their identifiers, so it
is desirable that one identifier point only one font. It is a difficult
requirement for automatic configuration because it can easily happen
that two or more fonts have the same identifier. Automatic configura‐
tion scripts can hardly detect which font is the best to be named the
identifier, or even such a situation occur. Defoma::Id is help for this
problem.
The rough flow of how Defoma::Id works is:
1. open an id-cache at init command of a Defoma-configuration script.
2. register identifier(s) of a font at register command of the script.
3. Defoma::Id looks up the id-cache to check if there's any other font
that has the same identifier, and calls back the script to make the
most appropriate font have the identifier, by do-install- command and
do-remove- command.
TYPE OF IDENTIFIER
It can handle three types of identifiers: RealName, Alias, and Substi‐
tuted.
RealName is a real name of a font and is usually taken from the Font‐
Name hint. If you want to register a font to an id-cache, at least one
RealName must be registered. You can pass the hints to options when you
register a RealName.
Alias is another name of a font and is usually taken from the Alias
hint. You have to specify the RealName of the font with origin when
you register an Alias.
Substituted is yet another name of a font, but unlike Alias, it is not
taken from the hints of the font, nor directly registered to an
id-cache by Defoma-configuration scripts. It is rather taken from a
subst-rule, which is handled by Defoma::Subst module, and is registered
by the module. If you want a certain font to substitute for another
id, you should register the font (and its RealName) to a subst-cache.
For more detail, please refer the Defoma::Subst manpage.
DETAIL OF HOW DEFOMA::ID WORKS
Registration and Unregistration of ids of a font are usually performed
on Defoma-configuration scripts at register and unregister commands re‐
spectively, and actual installation and removal for a certain id of a
font must not be performed at register and unregister commands, but at
do-install-(real,alias,subst) and do-remove-(real,alias,subst) commands
respectively. Following explains how an id of a font is registered/un‐
registered to/from an id-cache.
1.Registeration
Defoma::Id module records the id, font, type, priority and some
other informations in the id-cache.
1.2 the module seeks fonts which provides the id from the id-cache,
and gets the most prior font of them. RealName is always more
prior to Alias, and Alias is always more prior to Substituted.
1.3 If no font is actually installed for the id, the module calls
back the script with do-install-<type> command. If the script
succeeds installation of the font for the id, the module records
the id and the font as INSTALLED.
1.4 If another font is already INSTALLED for the id, the module
calls back the script with do-remove-<type> command to remove
the old most-prior font for the id, and removes the INSTALLED
entry. Then the module calls back again the script with do-in‐
stall-<type> command to install the new most-prior font for the
id. If the script succeeds installation of the font for the id,
the module records the id and the font as INSTALLED.
2.Unregistration
If the font is installed for the id, Defoma::Id module calls
back the script with do-remove-<type> command to remove the font
for the id, and removes the INSTALLED entry. Then the module
seeks fonts which provides the id from the id-cache. If the id
is provided by other fonts, the module seeks the most-prior font
from them, and installs it as mentioned above section 1.3.
2.2 The module removes the entry recording the id and the font.
These processes make only one, more appropriate font provide an certain
id, so the name-space conflict would be avoided.
FORMAT OF ID CACHE
id-cache holds eight items for each entry: id, font, type, priority,
category, depid, depfont and hints.
type represents the type of the entry in a combination of some letters.
id-cache handles font entry and mark entry. The latter is used to have
a certain less prior font installed for a certain id (i.e. marked as
USE), or to keep a certain font from being installed for a certain id
(i.e. marked as EXCLUDE), and is supposed to be set by users and not to
be referred from Defoma-configuration scripts, just for internal use.
On the other hand, font entry holds information of a certain id of a
font and may be referred from the scripts.
type consists of two or three letters. The first letter represents the
type of the entry and is either S or M (font entry or mark entry, re‐
spectively). If the first letter is S, which means it is font entry,
the second letter represents the type of the font and is either r, a, S
(real, alias or subst respectively). If the first letter is M, which
means it is mark entry, the second letter represents the type of the
mark and either of u or x (use or exclude respectively). If the entry
is font entry, which means the first letter is S, and the font and the
id of the entry is INSTALLED, there's a third letter and it is I.
depid and depfont represent dependency of the id of the font. The font
never gets installed unless the depfont is installed for the depid.
origin and depend arguments of defoma_id_register affect these items.
If the id of the font doesn't depend on any other id and/or font, these
items are set to '.'.
hints represents the hints of the id of the font. It is specified by
hints argument of defoma_id_register. You must use defoma_id_get_hints
to access the value of this item.
An item of each entry of an id-cache are accessible as an element of
id-object whose key is e_id, e_font, e_type, e_priority, e_category,
e_depid, e_depfont. For example, $Id->{e_font}->[3] accesses the font
of entry #3 of id-object $Id.
Here's an example of an id-cache.
# e_id e_font e_type e_priority e_category ...
0 Helvetica a.pfa SrI 20 type1 ...
1 Courier a.pfa Sa 20 type1 ...
2 Times-Roman b.ttf SrI 30 truetype ...
3 Courier b.ttf SaI 30 truetype ...
It show a.pfa has two identifiers: Helvetica for RealName and Courier
for Alias, and b.ttf has two identifiers: Times-Roman for RealName and
Courier For Alias.
Two fonts have the same identifier Courier, but this id-cache makes
Courier point to b.ttf (in other words, lets b.ttf provide Courier).
FUNCTIONS
defoma_id_open_cache is a function used to open an id-cache. id-caches
are independent between applications so usually a Defoma-configuration
script of a certain application cannot open an id-cache of another ap‐
plication. Each application can have more than one id-caches, and each
of them are distinguished by its suffix unique to the application. You
can omit the suffix argument if the application uses only one id-cache.
package_name should be omitted for most cases. It returns id_object
which is used as a descriptor for further handling of the id-cache.
defoma_id_close_cache is a function used to close an id-cache. Inter‐
nally it writes the content of an id-cache to the file which is identi‐
fied by id_object.
defoma_id_register is a function used to register a font and one of its
ids to an id-cache identified by id_object. You must at least pass
type, font, id and priority as its arguments. type is either of 're‐
al', 'alias' or 'subst', which corresponds to RealName, Alias or Sub‐
stituted mentioned above, respectively. 'subst' should be specified on‐
ly by Defoma::Subst module, so 'real' and 'alias' are possible choices.
If 'alias' is specified as the type of a font, you must specify the Re‐
alName of the font by origin. Specifying the origin is required for
non-RealName ids because they should not be installed unless the Real‐
Name of the font is installed. If 'real' is specified as the type, you
can specify the hints of the font by hints.
defoma_id_unregister is a function used to unregister one or all regis‐
tered id(s) of a certain font from and id-cache. If id is specified,
only the id of the specified font is unregistered from the id-cache
specified by id_object. Otherwise, all ids of the font are unregis‐
tered.
defoma_id_grep_cache is a function that searches the id-cache specified
by id_object for the specified id/font/category/depid/depfont, and re‐
turns a list of indexes. search-type is either of real, alias, subst,
font, installed or mark, which narrows down the subjects of searching.
id ,font ,type ,category ,depid and depfont decides the subjects of
searching more specifically. Not all of these, nor none of these are
required.
defoma_id_get_hints is a function that returns hints of the index of
the id-cache specified by id_object . If the index of Alias or Substi‐
tuted is specified, it returns the hints of its RealName that is speci‐
fied in the origin argument of defoma_id_register when the Alias/Sub‐
stituted identifier was registered.
defoma_id_set is a function used to make the specified font provide the
specified id, or to prevent the specified font from providing the
specifid id. install or exclude may be given to the flag. defo‐
ma_id_unset is a function used to unset the set flag of the specified
idandfont.
EXAMPLES
# Open an id-cache with 'test' as its suffix.
$Id = defoma_id_open_cache('test');
# register ids in register command.
my $font = shift;
my $h = parse_hints_start('Alias', @_);
my $fontname = $h->{FontName};
my @alias = split(/ /, $h->{Alias});
my $pri = $h->{Priority};
defoma_id_register($Id,
type => 'real',
font => $font,
id => $fontname,
priority => $pri,
hints => join(' ', @_));
foreach my $i (@alias) {
defoma_id_register($Id,
type => 'alias',
font => $font,
id => $i,
priority => $pri,
origin => $fontname);
}
# unregister ids.
defoma_id_unregister($Id, type => 'alias', font => $font);
defoma_id_unregister($Id, type => 'real', font => $font);
# close an id-cache
defoma_id_close_cache($Id);
# get a list of indexes of installed fonts that have
#'Helvetica' for the id.
my @list = defoma_id_grep_cache($Id, 'installed', id => 'Helvetica');
SEE ALSOdefoma(1). Defoma::Font(1). Defoma::Subst(1).
March 4, 2001 Defoma::Id(3pm)
