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