NAME

       "LaTeXML::Gullet" - expands expandable tokens and parses common token sequences.

DESCRIPTION

       A "LaTeXML::Gullet" reads tokens (LaTeXML::Token) from a LaTeXML::Mouth.  It is responsible for expanding
       macros and expandable control sequences, if the current definition associated with the token in the
       LaTeXML::State is an LaTeXML::Expandable definition. The "LaTeXML::Gullet" also provides a variety of
       methods for reading  various types of input such as arguments, optional arguments, as well as for parsing
       LaTeXML::Number, LaTeXML::Dimension, etc, according to TeX's rules.

   Managing Input
       "$gullet->input($name,$types,%options);"
           Input the file named $name; Searches for matching files in the current "searchpath" with an extension
           being  one  of   $types  (an array of strings). If the found file has a perl extension (pm, ltxml, or
           latexml), it will be executed (loaded).  If the found file has a TeX extension  (tex,  sty,  cls)  it
           will be opened and latexml will prepare to read from it.

       "$gullet->openMouth($mouth, $noautoclose);"
           Is  this public? Prepares to read tokens from $mouth.  If $noautoclose is true, the Mouth will not be
           automatically closed when it is exhausted.

       "$gullet->closeMouth;"
           Is this public? Finishes reading from the current mouth, and reverts to the one in effect before  the
           last openMouth.

       "$gullet->flush;"
           Is this public? Clears all inputs.

       "$gullet->getLocator;"
           Returns a string describing the current location in the input stream.

   Low-level methods
       "$tokens = $gullet->expandTokens($tokens);"
           Return the LaTeXML::Tokens resulting from expanding all the tokens in $tokens.  This is actually only
           used  in  a  few  circumstances where the arguments to an expandable need explicit expansion; usually
           expansion happens at the right time.

       "@tokens = $gullet->neutralizeTokens(@tokens);"
           Another unusual method: Used for things like \edef and token registers, to inhibit further  expansion
           of control sequences and proper spawning of register tokens.

       "$token = $gullet->readToken;"
           Return the next token from the input source, or undef if there is no more input.

       "$token = $gullet->readXToken($toplevel);"
           Return the next unexpandable token from the input source, or undef if there is no more input.  If the
           next token is expandable, it is expanded, and its expansion is reinserted into the input.

       "$gullet->unread(@tokens);"
           Push the @tokens back into the input stream to be re-read.

   Mid-level methods
       "$token = $gullet->readNonSpace;"
           Read and return the next non-space token from the input after discarding any spaces.

       "$gullet->skipSpaces;"
           Skip the next spaces from the input.

       "$gullet->skip1Space;"
           Skip the next token from the input if it is a space.

       "$tokens = $gullet->readBalanced;"
           Read  a  sequence of tokens from the input until the balancing '}' (assuming the '{' has already been
           read). Returns a LaTeXML::Tokens.

       "$boole = $gullet->ifNext($token);"
           Returns true if the next token in the input matches $token; the possibly matching  token  remains  in
           the input.

       "$tokens = $gullet->readMatch(@choices);"
           Read  and return whichever of @choices (each are LaTeXML::Tokens) matches the input, or undef if none
           do.

       "$keyword = $gullet->readKeyword(@keywords);"
           Read and return whichever of @keywords (each a string) matches the input, or undef if none do.   This
           is similar to readMatch, but case and catcodes are ignored.  Also, leading spaces are skipped.

       "$tokens = $gullet->readUntil(@delims);"
           Read  and  return  a  (balanced)  sequence  of  LaTeXML::Tokens  until  matching one of the tokens in
           @delims.  In a list context, it also returns which of the delimiters ended the sequence.

   High-level methods
       "$tokens = $gullet->readArg;"
           Read and return a TeX argument; the next Token or Tokens (if surrounded by braces).

       "$tokens = $gullet->readOptional($default);"
           Read and return a LaTeX optional argument; returns  $default  if  there  is  no  '[',  otherwise  the
           contents of the [].

       "$thing = $gullet->readValue($type);"
           Reads an argument of a given type: one of 'Number', 'Dimension', 'Glue', 'MuGlue' or 'any'.

       "$value = $gullet->readRegisterValue($type);"
           Read  a  control  sequence  token (and possibly it's arguments) that names a register, and return the
           value.  Returns undef if the next token isn't such a register.

       "$number = $gullet->readNumber;"
           Read a LaTeXML::Number according to TeX's rules of the various things that can be used as a numerical
           value.

       "$dimension = $gullet->readDimension;"
           Read a LaTeXML::Dimension according to TeX's rules of the various  things  that  can  be  used  as  a
           dimension value.

       "$mudimension = $gullet->readMuDimension;"
           Read  a  LaTeXML::MuDimension  according  to  TeX's rules of the various things that can be used as a
           mudimension value.

       "$glue = $gullet->readGlue;"
           Read a  LaTeXML::Glue according to TeX's rules of the various things that  can  be  used  as  a  glue
           value.

       "$muglue = $gullet->readMuGlue;"
           Read  a  LaTeXML::MuGlue  according to TeX's rules of the various things that can be used as a muglue
           value.

AUTHOR

       Bruce Miller <bruce.miller@nist.gov>

COPYRIGHT

       Public domain software, produced as part of work done by the United States Government &  not  subject  to
       copyright in the US.

perl v5.10.1                                       2009-06-11                               LaTeXML::Gullet(3pm)