NAME

Text::TeX -- Perl module for parsing of TeX.

SYNOPSIS

  use Text::TeX;

  sub report {
    my($eaten,$txt) = (shift,shift);
    print "Comment: `", $eaten->[1], "'\n" if defined $eaten->[1];
    print "@{$txt->{waitfors}} ", ref $eaten, ": `", $eaten->[0], "'";
    if (defined $eaten->[3]) {
      my @arr = @{ $eaten->[3] };
      foreach (@arr) {
	print " ", $_->print;
      }
    }
    print "\n";
  }

  my $file = new Text::TeX::OpenFile 'test.tex',
    'defaultact' => \&report;
  $file->process;

DESCRIPTION

A new TeX parser is created by

$file = new Text::TeX::OpenFile $filename, attr1 => $val1, ...;

$filename may be undef, in this case the text to parse may be specified in the attribute string.

Recognized attributes are:

string

contains the text to parse before parsing $filename.

defaultact

denotes a procedure to submit output tokens to.

tokens

gives a hash of descriptors for input token. A sane default is provided.

A call to the method process launches the parser.

Tokenizer

When the parser is running, it processes input stream by splitting it into input tokens using some heuristics similar to the actual rules of TeX tokenizer. However, since it does not use the exact rules, the resulting tokens may be wrong if some advanced TeX command are used, say, the character classes are changed.

This should not be of any concern if the stream in question is a "user" file, but is important for "packages".

Digester

The processed input tokens are handled to the digester, which handles them according to the provided tokens attribute. A sequence of input tokens is converted into output tokens. To each input token there corresponds 0 or more output tokens. The output tokens are delivered one-by-one to the action handler of the processor.

Output token is a reference to an object (which is usually an array reference). Some elements of the array have a special meaning to the Digester. The first one is the substring of the input which generated this token. The second contains comment which preceeded this substring, or undef.

tokens attribute

This is a hash reference which describes how the input tokens should be handled. A key to this hash is a literal like ^ or \fraction. A value should be another hash reference, with the following keys recognized:

class

Into which class to bless the token. Several predefined classes are provided. The default is Text::TeX::Token.

PostProcess

What kind of special processing to do with the input after the class methods are called. Recognized PostProcesss are:

delimit_args

When the token of this PostProcess is encountered, it is converted into Text::Tex::BegArgsToken. Then the arguments are processed as usual, and an output token of type Text::Tex::ArgToken is inserted between them. Finally, after all the arguments are processed, an output token Text::Tex::EndArgsToken is inserted.

The first element of these simulated output tokens is an array reference with the first element being the initial output token which generated this sequence. The second element of the internal array is the number of arguments required by the input token. The Text::Tex::ArgToken token has a third element, which is the ordinal of the argument which ends immediately before this token.

If lookahead attribute is present, a token Text::Tex::LookAhead will be returned instead of Text::Tex::EndArgsToken. The additional elements of $token-[0]> are: the reference to the corresponding lookahead attribute, the relevant key (text of following token) and the corresponding value.

In such a case the input token which was looked-ahead would generate an output token of type Text::Tex::BegArgsTokenLookedAhead (if it usually generates Text::Tex::BegArgsToken).

local

Used if this macro introduces a local change, which should be undone at the end of enclosing block. At the end of the block an output token Text::TeX::EndLocal is delivered, with $token-[0]> being the output token which started the local event.

Useful for font switching.

Some additional keys may be recognized by the code for the particular class.

count

number of arguments to the macro.

waitfor

gives the matching token for a starting delimiter token.

eatargs

number of tokens to swallow literally and put into the relevant slot of the output token. The surrounding braces are stripped.

selfmatch

is used with eatargs==1. Denotes that the matching token is also eatargs==1, and the swallowed tokens should coinside (like with \begin{blah} ... \end{blah}).

lookahead

is a hash with keys being texts of tokens which need to be treated specially after the end of arguments for the current token. If the corresponding text follows the token indeed, a token Text::Tex::LookAhead is returned instead of Text::Tex::EndArgsToken.

Symbol font table

The hash %Text::TeX::xfont contains the translation table from TeX tokens into the corresponding font elements. The values are array references of the form [fontname, char], Currently the only font supported is symbol.

AUTHOR

Ilya Zakharevich, ilya@math.ohio-state.edu

SEE ALSO

perl(1).