6.4.1 TeX Objects

class TeX([ownerDocument, file])

The TeX class is the central T_eX 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 L^aT_eX file. This file will be searched for using the standard L^aT_eX 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 L^aT_eX 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 L^aT_eX 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 L^aT_eX representation of the tokens in tokens

textTokens(text)

convert a string of text into a series of tokens