---
name: "Defoma::Subst"
section: "3pm"
platform: "linux"
package: "defoma"
version: "0.11.11"
release: "Debian 6.0 (Squeeze)"
platforms: ["linux"]
url: "https://new.carta.tech/Defoma::Subst"
---

# Defoma::Subst(3pm)

Defoma module to handle Subst cache/rule.

## NAME

Defoma::Subst - Defoma module to handle Subst cache/rule.

## SYNOPSIS

use Defoma::Subst;

$Sb = defoma\_subst\_open(\
   rulename =\> *rulename*,\
   threshold =\> *threshold*,\
   idobject =\> *id\_object*,\
   private =\> *private\_flag* );

defoma\_subst\_close( *subst\_object* );

defoma\_subst\_register( *subst\_object*, *font*, *realname* );

defoma\_subst\_unregister( *subst\_object*, *font* *realname* );

defoma\_subst\_add\_rule( *subst\_object*, *required\_id*, *rule...* );

defoma\_subst\_remove\_rule( *subst\_object*, *required\_id*, *rule...* );

## DESCRIPTION

Defoma::Subst is a Defoma module to handle subst-cache and subst-rule. When a certain id is required but not provided as RealName or Alias by any font, fonts which have similar appearance and the same characters should substitute for such a font. Required ids and their information about appearance and charset things (called \*rule\*) are described in a  subst-rule.  Defoma::Subst compares such a rule of a certain required id with hints of a  substitutive font and calculates the degree of similarity in percentage, and registers the required id and the font with the value as its priority as 'Substituted' type to an id-cache through Defoma::Id module.

subst-rule is mainly edittable by users, which means users edit  subst-rule file to add/remove/modify the required ids and their information, but sometimes unedittable by them and modified by a Defoma-configuration script.  The former is called **public** subst-rule and the latter is called **private** subst-rule.

subst-cache holds fonts which are candidacies for substituting for  required ids. As mentioned above, a rule of a required id and hints of such a font are compared. Hints are not recorded in a subst-cache  so retrieved from an id-cache. In addition a required id and its rule are recorded in an subst-rule, so subst-cache, subst-rule and id-cache  are strongly linked up. Especially subst-cache and subst-rule are not separatable and Defoma::Subst handles these two through a single united object.

**defoma\_subst\_open** is a function used to open a subst-cache and subst-rule specified by *rulename* and *private\_flag* and returns the *subst\_object* used for further operation. If the subst-rule is private one, set *private\_flag* to non-zero. Otherwise it can be omitted. The subst-rule becomes public. *id\_object* must be specified because subst-cache and subst-rule are strongly linked up to id-cache as mentioned above. Hints of a substitutive font are retrieved from the id-cache specified by the *id\_object*, and required ids described in the subst-rule are registered to the id-cache. *threshold* prevents fonts that have less degree of similarity from being registered. If a required id is already registered in the id-cache, substitutive fonts whose degree of similarity are less than this  *threshold* are not registered to an id-cache.

**defoma\_subst\_close** is a function used to close a subst-cache and subst-rule specified by  *subst\_object*. Internally it writes the content of cache and rule stored in a memory to files.

**defoma\_subst\_register** is a function used to register a font which is candidate for substituting for required ids to the subst-cache specified by *subst\_object*. RealName of the font must be specified.

**defoma\_subst\_unregister** is a function used to unregister a font from the subst-cache specified by *subst\_object*. RealName can be omitted.

**defoma\_subst\_add\_rule** is a function used to add a required id and its rule to the subst-rule specified by *subst\_object*.

**defoma\_subst\_remove\_rule** is a function used to remove a required id and its rule from the subst-rule specified by *sbst\_object*. If *rule* is omitted, all the rules describing the  *required\_id* are removed from the subst-rule. Otherwise only one rule specified by *rule* and *required\_id*  is removed.

## EXAMPLES

1\. Open private subst-rule and subst-rule.

```
$Id = defoma_id_open();
$Sb = defoma_subst_open(rulename => 'subst1',
                        idobject => $Id);
```

2\. Register a substitutive font.

```
defoma_id_register($Id, type => 'real',
                   font => $font,
                   id => $realname,
                   priority => $priority,
                   hints => join(' ', @_));
defoma_subst_register($Sb, $font, $realname);
```

3\. Unregister.

```
defoma_subst_unregister($Id, $font);
defoma_id_unregister($Id, 'real', $font);
```

4\. Add a rule.

```
defoma_subst_add_rule($Sb, 'Helvetica', @hints);
```

5\. Remove all rules for Helvetica.

```
defoma_subst_remove_rule($Sb, 'Helvetica');
```

## SEE ALSO

[**defoma**(1)](/defoma/1.md). **Defoma::Id**(1).