6.4.1 TeX Objects

class TeX([ownerDocument, file])

The TeX class is the central TeX engine that does all of the parsing, invoking of macros, and other document building tasks. You can pass in an owner document if you have a customized document node, or if it contains a customized configuration; otherwise, the default TeXDocument class is instantiated. The file  argument is the name of a LaTeX file. This file will be searched for using the standard LaTeX technique and will be read using the default input encoding in the document’s configuration.

disableLogging()

disables logging. This is useful if you are using the TeX object within another library and do not want all of the status information to be printed to the screen.

Note: This is a class method.

filename

the current filename being processed

jobname

the name of the basename at the top of the input stack

lineNumber

the line number of the current file being processed

expandTokens(tokens, normalize=False )

expand a list of unexpanded tokens. This method can be used to expand tokens without having them sent to the output stream. The returned value is a TeXFragment populated with the expanded tokens.

input(source )

add a new input source to the input stack. source  should be a Python file object. This can be used to add additional input sources to the stream after the TeX object has been instantiated.

__iter__()

return a generator that iterates through the tokens in the source. This method allows you to treat the TeX stream as an iterable and use it in looping constructs. While the looping is generally handled in the parse() method, you can manually expand the tokens in the source by looping over the TeX object as well.

for tok in TeX(open('myfile.tex')):
    print tok

itertokens()

return an iterator that iterates over the unexpanded tokens in the input document.

kpsewhich(name )

locate the given file in a kpsewhich-like manner. The full path to the file is returned if it is found; otherwise, None  is returned. Note: Currently, only the directories listed in the environment variable TEXINPUTS are searched.

normalize(tokens )

joins consecutive text tokens into a string. If the list of tokens contain tokens that are not text tokens, the original list of tokens is returned.

parse(output=None )

parse the sources currently in the input stack until they are empty. The output  argument is an optional Document node to put the resulting nodes into. If none is supplied, a TeXDocument instance will be created. The return value is the document from the output  argument or the instantiated TeXDocument object.

pushToken(token )

pushes a token back into the input stream to be re-read.

pushTokens(tokens )

pushes a list of tokens back into the input stream to be re-read.

readArgument(*args, **kwargs )

parse a macro argument without the LaTeX source that created it. This method is just a thin wrapper around readArgumentAndSource. See that method for more information.

readArgumentAndSource(spec=None, subtype=None, delim=’,’, expanded=False, default=None, parentNode=None, name=None )

parse a macro argument. Return the argument and the LaTeX source that created it. The arguments are described below.

Option

Description

spec 

string containing information about the type of argument to get. If it is ’None’, the next token is returned. If it is a two-character string, a grouping delimited by those two characters is returned (i.e. ’[]’). If it is a single-character string, the stream is checked to see if the next character is the one specified. In all cases, if the specified argument is not found, ’None’ is returned.

type 

data type to cast the argument to. New types can be added to the self.argtypes dictionary. The key should match this ’type’ argument and the value should be a callable object that takes a list of tokens as the first argument and a list of unspecified keyword arguments (i.e. **kwargs) for type specific information such as list delimiters.

subtype 

data type to use for elements of a list or dictionary

delim 

item delimiter for list and dictionary types

expanded 

boolean indicating whether the argument content should be expanded or just returned as an unexpanded text string

default 

value to return if the argument doesn’t exist

parentNode 

the node that the argument belongs to

name 

the name of the argument being parsed

The return value is always a two-element tuple. The second value is always a string. However, the first value can take the following values.

Value

Condition

None

the requested argument wasn’t found

object of requested type

if type  was specified

list of tokens

all other arguments

source(tokens )

return the LaTeX representation of the tokens in tokens 

textTokens(text )

convert a string of text into a series of tokens