--- name: "Defoma::Id" section: "3pm" platform: "linux" package: "defoma" version: "0.11.11" release: "Debian 6.0 (Squeeze)" platforms: ["linux"] url: "https://new.carta.tech/Defoma::Id" --- # Defoma::Id(3pm) Defoma module to handle Id cache. ## NAME Defoma::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* ); ## DESCRIPTION Defoma::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 conflict. 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 configuration 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 Substituted. *RealName* is a real name of a font and is usually taken from the FontName 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 respectively, 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/unregistered 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-\ 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-\ 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-install-\ 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-\ 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, respectively). 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 application. 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. Internally it writes the content of an id-cache to the file which is identified 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 'real', 'alias' or 'subst', which corresponds to RealName, Alias or Substituted mentioned above, respectively. 'subst' should be specified only 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 RealName of the font by *origin*. Specifying the *origin* is required for non-RealName ids because they should not be installed unless the RealName 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 registered 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 unregistered. **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 returns 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 Substituted is specified, it returns the hints of its RealName that is specified in the *origin* argument of **defoma\_id\_register** when the Alias/Substituted 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*. **defoma\_id\_unset** is a function used to unset the set flag of the specified *id*and*font*. ## 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 ALSO [**defoma**(1)](/defoma/1.md). **Defoma::Font**(1). **Defoma::Subst**(1).