NAME

TeX::XDV::Parse - Perl extension for parsing TeX XDV files

SYNOPSIS

package My_XDV_Parser;
use TeX::XDV::Parse;
@ISA = qw( TeX::XDV::Parse );

sub dir {...}
sub pic_file {...}
sub glyph_array {...}
sub glyph_string {...}
sub native_font_def {...}

DESCRIPTION

TeX::XDV::Parse is an extension of TeX::DVI::Parse, much as XDV is an extension of DVI. This module simply overlays the additional XDV functionality on top of TeX::DVI::Parse and inherits its interface.

To use, you should subclass this module and define functions to handle each of the XDV/DVI commands. Each command will be passed the appropriate arguments. For example:

sub dir {
  my ($self, $opcode, $direction) = @_;
  ...
}

The additional XDV commands are dir, glyph_string, glyph_array, pic_file, and native_font_def. Optionally, the XDV flag constants are also available for import.

An example module, TeX::XDV::Print, is available in the source distribution package under the inc directory.

See the TeX::DVI::Parse documentation for details on the DVI commands.

METHODS

dir( direction )

Sets either left to right or top to bottom direction.

0 = horizontal
1 = vertical

pic_file( $type, $a, $b, $c, $d, $tx, $ty, $page, $len, $file )

Sets an image.

type : file type
   a : affine transform element
   b : affine transform element
   c : affine transform element
   d : affine transform element
  tx : affine transform element
  ty : affine transform element
 len : length of filename
page : page number
file : filename

The affine transform takes the form

[ a   b   0 ]
[ c   d   0 ]
[ tx  ty  1 ]

In general though, to transform a point (x,y):

x' = ax + cy + tx
y' = bx + dy + ty

glyph_string( $width, $count, $x_loc, ..., $glyph, ... )

Set a string of glyphs.

width : TeX width
count : glyph count
x_loc : TeX horizontal location (x count)
glyph : glyph id (x count)

The glyph string will generally be broken at word boundaries with whitespace excluded. The exception is at line endings where a word is hypenated. The word will naturally be broken into two seperate glyph strings.

x_loc and glyph are repeated count times.

glyph is the glyph id of the character to set in the current font, which isn't necessarily the same as the characters ordinal value.

glyph_array( $width, $count, $x_loc, $y_loc, ..., $glyph, ... )

Set an array of glyphs.

width : TeX width
count : glyph count
x_loc : TeX horizontal location (x count)
y_loc : TeX vertical location (x count)
glyph : glyph id (x count)

A glyph array is similar to a glyph string, but also include vertical location information.

x_loc and y_loc are sent in pairs. The pairs are repeated count times. glyph is also repeated count times, but after all the x_loc and y_loc pairs.

glyph is the glyph id of the character to set in the current font, which isn't necessarily the same as the characters ordinal value.

native_font_def($k,$ps,$fl,$p_len,$f_len,$s_len,$n,$f,$s,@more)

Defines a font.

     k : font id
    ps : point size in TeX units
    fl : flags
 p_len : ps name len
 f_len : family name len
 s_len : style name len
     n : font_name
     f : fam_name
     s : sty_name
     c : rgba_color
  nvar : nvars
   var : variations * nvars
extend : extend
 slant : slant
  bold : embolden

The @more element may or may not contain further information depending on the fl flags. If the appropriate flag is set, the corresponding element will be present. If not, the element will be missing. Be sure these checks are done in order or confusion will ensue.

XDV_FLAG_COLORED    => rgba_color
XDV_FLAG_VARIATIONS => nvar, var
XDV_FLAG_EXTEND     => extend
XDV_FLAG_SLANT      => slant
XDV_FLAG_EMBOLDEN   => bold

The nvar element naturally enumerates the var variations, if present. Each variation is itself two elements: axis and value.

EXPORT

None, by default.

On request, the following flags are available either individually or together through the ":constants" tag:

XDV_FLAG_FONTTYPE_ATSUI
XDV_FLAG_FONTTYPE_ICU
XDV_FLAG_VERTICAL
XDV_FLAG_COLORED
XDV_FLAG_FEATURES
XDV_FLAG_VARIATIONS
XDV_FLAG_EXTEND
XDV_FLAG_SLANT
XDV_FLAG_EMBOLDEN

SEE ALSO

TeX::DVI::Parse

AUTHOR

Rick Myers, <jrm at cpan dot org>

COPYRIGHT AND LICENSE

Copyright (C) 2013-2015 by Rick Myers

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.16.3 or, at your option, any later version of Perl 5 you may have available.

cpanm TeX::XDV::Parse

perl -MCPAN -e shell
install TeX::XDV::Parse