.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.48)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "Font::TTF::Scripts::Volt 3"
.TH Font::TTF::Scripts::Volt 3 2026-10-03 "perl v5.44.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Font::TTF::Scripts::Volt \- Memory representation of a Volt based font
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 10
\& use Font::TTF::Scripts::Volt;
\& $fv = Font::TTF::Scripts::Volt\->read_font($ttf_file, $ap_file, %opts);
\& $dat = $fv\->parse_volt;
\& @map = $fv\->align_glyphs($dat);
\& $fv\->merge_volt($dat, \e@map);
\& $fv\->make_classes;
\& $fv\->make_anchors;
\& $fv\->make_groups;
\& $fv\->make_lookups;
\& $res = $fv\->out_volt;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Font::TTF::Scripts::Volt\*(C'\fR is based on and inherits from \f(CW\*(C`Font::TTF::Scripts::AP\*(C'\fR
and as such supports all the information and methods in such an object. The read method does
little beyond calling the corresponding AP method.
.PP
The real power in this module is in the \f(CW\*(C`parse_volt\*(C'\fR that can parse Volt source code.
It does it rather slowly, but it does do it and reads it into an internal data structure.
This data structure can then be merged into an existing font using \f(CW\*(C`align_glyphs\*(C'\fR and \f(CW\*(C`merge_volt\*(C'\fR.
From there it can be output as Volt source. The data structure representing the Volt source
is a hash containing the following elements:
.IP glyphs 4
.IX Item "glyphs"
Similar to the glyphs array from AP but adds a few Volt specific sub values
.RS 4
.IP uni 4
.IX Item "uni"
A possibly empty array of Unicode scalar values (as decimal integers).
.IP type 4
.IX Item "type"
MARK, BASE (in VOLT UI this is the SIMPLE type), LIGATURE or COMPONENT. 
This element will not be defined if the VOLT type is UNASSIGNED.
.IP component_num 4
.IX Item "component_num"
Number of components in a ligature
.IP name 4
.IX Item "name"
Volt name in the source
.IP anchors 4
.IX Item "anchors"
An optional hash by anchor name that contains an array of anchor definitions, one anchor for each ligature component 
(non\-ligature glyphs have a single element in the array). Each anchor definition is a hash including:
.RS 4
.IP pos 4
.IX Item "pos"
A \f(CW\*(C`pos\*(C'\fR type containing the actual position of the anchor point
.IP locked 4
.IX Item "locked"
Contains LOCKED if the anchor point is locked
.RE
.RS 4
.RE
.RE
.RS 4
.RE
.IP scripts 4
.IX Item "scripts"
A hash of script structures keyed off the script tag as used in Volt, containing:
.RS 4
.IP name 4
.IX Item "name"
Optional script name as in Volt
.IP tag 4
.IX Item "tag"
Four letter script tag that ends up in the font
.IP langs 4
.IX Item "langs"
An array of language structures consisting of (nearly there)
.RS 4
.IP name 4
.IX Item "name"
Optional language name as in Volt
.IP tag 4
.IX Item "tag"
Four letter language tag that ends up in the font
.IP features 4
.IX Item "features"
Hash of feature structures keyed by feature tag, each containing (last one)
.RS 4
.IP name 4
.IX Item "name"
Optional name of the feature
.IP tag 4
.IX Item "tag"
Four letter feature tag that ends up in the font
.IP lookups 4
.IX Item "lookups"
Array of names of lookups associated with this feature
.RE
.RS 4
.RE
.RE
.RS 4
.RE
.RE
.RS 4
.RE
.IP groups 4
.IX Item "groups"
A hash of group definitions by name. The contents is an array of \f(CW\*(C`context_item\*(C'\fRs corresponding
to each element in the defining enum for the group.
.IP lookups 4
.IX Item "lookups"
An array of lookups in the order they appear in the Volt source. Each lookup consists of
.RS 4
.IP id 4
.IX Item "id"
Lookup name
.IP base 4
.IX Item "base"
Contains PROCESS_BASE if that is in the lookup
.IP marks 4
.IX Item "marks"
Contains one of SKIP_MARKS, PROCESS_MARKS, or MARK_GLYPH_SET
.IP all 4
.IX Item "all"
Contains a group name or ALL according to what is to be processed
.IP dir 4
.IX Item "dir"
Contains LTR or RTL
.IP comment 4
.IX Item "comment"
Comment, if any, associated with the lookup; string value but can be multi\-line.
.IP contexts 4
.IX Item "contexts"
Contains an array of contexts as per IN_CONTEXT. Each element of the array is itself
an array corresponding to the elements in a context. The first element this
array is a string IN_CONTEXT or EXCEPT_CONTEXT depending on the type of context. Subsequent
elements are arrays that consist of two elements: A string LEFT or RIGHT and a \f(CW\*(C`context_item\*(C'\fR.
.IP lookup 4
.IX Item "lookup"
A two\-element array, the first element giving the lookup type: \f(CW\*(C`sub\*(C'\fR or \f(CW\*(C`pos\*(C'\fR and the second
element being the content of the lookup.
.Sp
For a \f(CW\*(C`sub\*(C'\fR lookup the second element is an array each element of which is a substitution
pair held in an array. The first element of this substitution pair is an array of
\&\f(CW\*(C`context_item\*(C'\fRs to be substituted and the second element is an array of \f(CW\*(C`context_item\*(C'\fRs that
the subsitutition is substituted with.
.Sp
For a \f(CW\*(C`pos\*(C'\fR lookup, the second element is an array hashes, one per sublookup. The
elements in the hash are dependent on the type of positioning but have consistent
meaning:
.RS 4
.IP type 4
.IX Item "type"
The type of positioning. May be ATTACH, ATTACH_CURSIVE, ADJUST_SINGLE, ADJUST_PAIR.
.IP context 4
.IX Item "context"
Gives the context glyph for ATTACH and ADJUST_SINGLE lookups and consists of an array
of \f(CW\*(C`context_item\*(C'\fRs
.IP first 4
.IX Item "first"
The first context glyph for an ADJUST_PAIR. It consists of an array of \f(CW\*(C`context_item\*(C'\fRs
which are referenced by number according to their index (starting at 1) in the
positioning.
.IP second 4
.IX Item "second"
The second context glyph for an ADJUST_PAIR. It consists of an array of \f(CW\*(C`contexts_item\*(C'\fRs
which correspond to the second number in a position.
.IP exits 4
.IX Item "exits"
An array of \f(CW\*(C`context_item\*(C'\fRs one for each glyph with an \f(CW\*(C`exit\*(C'\fR anchor. Used only in
ATTACH_CURSIVE
.IP enters 4
.IX Item "enters"
An array of \f(CW\*(C`context_item\*(C'\fRs one for each glyph with an \f(CW\*(C`entry\*(C'\fR anchor. Used only in
ATTACH_CURSIVE
.IP to 4
.IX Item "to"
Used in an ATTACH to specify what glyphs are being attached and
with which anchor point. Each element of this array is an array with two elements:
a \f(CW\*(C`context_item\*(C'\fR to specify the moving glyph(s) (the non\-moving glyph is specified by the
\&\f(CW\*(C`context\*(C'\fR hash entry) and the name of the anchor point used to link the two. The
base glyph has an anchor with the anchor name and the second glyph has an anchor
with the anchor named prefixed by MARK_
.IP adj 4
.IX Item "adj"
An adjustment is used in a ADJUST_SINGLE as an array of positioning elements of type
\&\f(CW\*(C`pos\*(C'\fR each one corresponding to a \f(CW\*(C`context_item\*(C'\fR in the context array.
.Sp
For an ADJUST_PAIR the adj is an array of arrays. Each sub array has 3 elements:
first index into the \f(CW\*(C`first\*(C'\fR array (starting at 1), second index into the \f(CW\*(C`second\*(C'\fR
array (starting at 1) and a \f(CW\*(C`pos\*(C'\fR to specify the actual adjustment of those two
glyphs.
.RE
.RS 4
.RE
.RE
.RS 4
.RE
.IP info 4
.IX Item "info"
The info hash contains some global information for the whole font with the following
hash elements:
.RS 4
.IP ppos 4
.IX Item "ppos"
Specifies the pixesl per em for positioning purpsoes
.IP grid 4
.IX Item "grid"
Specifies the pixels per em for the grid
.IP pres 4
.IX Item "pres"
Specifies the presentation pixels per em
.IP ppfmt2 4
.IX Item "ppfmt2"
Optional. If TRUE, then the project options request use of pair position format 2 (rather than the default of format 1).
.IP cmap 4
.IX Item "cmap"
An array of cmap entries, each of which is an array of 3 numbers.
.RE
.RS 4
.Sp
In addition to extra entries in the main object there are two types that are used
in various places:
.RE
.SS context_item
.IX Subsection "context_item"
A \f(CW\*(C`context_item\*(C'\fR consists of an array with two or three elements. The first, a string, gives the type
of the context item and the subsequent elements give the value. The context types are:
.IP GLYPH 4
.IX Item "GLYPH"
The second array element contains a glyph id. Note it does not contain a glyph name.
The name is resolved to an id in the parser and converted back to a name during output.
.IP GROUP 4
.IX Item "GROUP"
The second array element is a string holding the name of the group being referenced
.IP RANGE 4
.IX Item "RANGE"
The second and third array elements are the first and last glyph id for the range. Ranges
are particularly difficult to work with when merging different glyph arrays so should
be avoided
.IP ENUM 4
.IX Item "ENUM"
An enum is a way of embedding a list of contexts within a context. The second
array element is an array of \f(CW\*(C`context_item\*(C'\fRs
.SS Pos
.IX Subsection "Pos"
A positioning element is a glorious animal. You would think that it could just be
an \f(CW\*(C`x\*(C'\fR and \f(CW\*(C`y\*(C'\fR co\-ordinate. You would be so wrong! A \f(CW\*(C`pos\*(C'\fR is a hash with
three elements: \f(CW\*(C`x\*(C'\fR, \f(CW\*(C`y\*(C'\fR and \f(CW\*(C`adv\*(C'\fR. \f(CW\*(C`adv\*(C'\fR specifies changes to the advance
width of a glyph in ADJUST_PAIR.
.PP
Each of these hash entries is an array. The first element of the array is the
actual co\-ordinate value. The second is an optionally empty array of adjustments
to that co\-ordinate. Each element of that array is a two element array of the
adjust value and the ppem value at which the adjustment occurs.
.ie n .SS "$fv = Font::TTF::Scripts::Volt\->read_font ($ttf_file, $ap_file, %opts)"
.el .SS "\f(CW$fv\fP = Font::TTF::Scripts::Volt\->read_font ($ttf_file, \f(CW$ap_file\fP, \f(CW%opts\fP)"
.IX Subsection "$fv = Font::TTF::Scripts::Volt->read_font ($ttf_file, $ap_file, %opts)"
Additional options available to this function include
.IP \-point2anchor 4
.IX Item "-point2anchor"
Reference to a function that parses an Attachment Point name and returns a list considting of
a Volt anchor name and component number. The components should be numbered starting
from 1. Special conditions that may be returned:
.Sp
If the return value is undef, or if the anchor name is undef, then this attachment point is ignored.
.Sp
If the returned component number is undef, 1 will be assumed.
.Sp
If \f(CW\*(C`\-point2anchor\*(C'\fR is not provided, a default function (see below) is used.
.ie n .SS $fv\->out_volt(%opts)
.el .SS \f(CW$fv\fP\->out_volt(%opts)
.IX Subsection "$fv->out_volt(%opts)"
Assembles the VOLT project source and returns it as a multi\-line string.
.PP
Options include
.PP
.Vb 1
\&  \-default_glyphtype  Glyphs whose C<type> is unknown get set to this type
.Ve
.ie n .SS $fv\->parse_volt([$vtext])
.el .SS \f(CW$fv\fP\->parse_volt([$vtext])
.IX Subsection "$fv->parse_volt([$vtext])"
Parses volt source. If no \f(CW$vtext\fR then take it from the \f(CW\*(C`TSIV\*(C'\fR table in the font.
.ie n .SS "$fv\->normal_rules($ndrawn, \e%opts)"
.el .SS "\f(CW$fv\fP\->normal_rules($ndrawn, \e%opts)"
.IX Subsection "$fv->normal_rules($ndrawn, %opts)"
Generate ligature lookup \f(CW\*(C`normal_rules\*(C'\fR based on Unicode composition rules. 
If \f(CW$ndrawn\fR is true, then add rules for all Unicode composites, otherwise
only those composites whose glyph is an actual TrueType contour glyph.
.PP
Options:
  \-force   force new lookup even if it already exists.
.ie n .SS "$fv\->make_lookups($ligtype, \e%opts)"
.el .SS "\f(CW$fv\fP\->make_lookups($ligtype, \e%opts)"
.IX Subsection "$fv->make_lookups($ligtype, %opts)"
Construct substitution lookups for all \f(CW\*(C`classes\*(C'\fR and \f(CW\*(C`ligclasses\*(C'\fR, and 
position lookups for all \f(CW\*(C`lists\*(C'\fR. Options include
.PP
.Vb 2
\&  \-force   force new lookup even if it already exists.
\&  \-notmark list of anchors that do not imply a MARK glyph (e.g. "_R")
.Ve
.ie n .SS $fv\->make_groups
.el .SS \f(CW$fv\fP\->make_groups
.IX Subsection "$fv->make_groups"
Convert all \f(CW\*(C`lists\*(C'\fR, \f(CW\*(C`classes\*(C'\fR and \f(CW\*(C`ligclasses\*(C'\fR into Volt \f(CW\*(C`groups\*(C'\fR.
.ie n .SS $fv\->make_anchors
.el .SS \f(CW$fv\fP\->make_anchors
.IX Subsection "$fv->make_anchors"
Convert all attachment points in \f(CW$fv\fR into Volt \f(CW\*(C`anchors\*(C'\fR
.SS point2anchor
.IX Subsection "point2anchor"
This function, used if \f(CW\*(C`\-point2anchor\*(C'\fR option isn\*(Aqt provided, peels off any digits at the 
end of the supplied Attachment Point name and uses them for the component. Anchor names
starting with "_" are altered to start with "MARK_" instead.
.PP
NB: This function is not an object method, and it can be overridden by setting the \f(CW\*(C`\-point2anchor\*(C'\fR
option of \f(CW\*(C`read_font\*(C'\fR.
.SH "See also"
.IX Header "See also"
Font::TTF::Scripts::AP
.SH AUTHOR
.IX Header "AUTHOR"
Martin Hosken <http://scripts.sil.org/FontUtils>.
.SH LICENSING
.IX Header "LICENSING"
Copyright (c) 1998\-2016, SIL International (http://www.sil.org)
.PP
This module is released under the terms of the Artistic License 2.0.
For details, see the full text of the license in the file LICENSE.