## 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