NAME

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

DESCRIPTION

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

       It extends LaTeXML::Common::Object.

   Managing Input
       "$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 an object describing the current location in the input stream.

   Low-level methods
       "$tokens = $gullet->expandTokens($tokens);"
           Return  the  LaTeXML::Core::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.

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

       "$token = $gullet->readXToken($toplevel,$commentsok);"
           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.  If
           $commentsok, a comment read or pending will be returned.

       "$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($expanded);"
           Skip the next token from the input if it is a space.  If C($expanded> is true, expands ( like "  <one
           optional space" > ).

       "$tokens = $gullet->readBalanced;"
           Read  a  sequence of tokens from the input until the balancing '}' (assuming the '{' has already been
           read). Returns a LaTeXML::Core::Tokens, except in an array context, returns the collected tokens  and
           the closing token.

       "$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 matches the input, or undef if none do.  Each of the choices is
           an LaTeXML::Core::Tokens.

       "$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::Core::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::Common::Number according to TeX's rules of the various things that can be used  as  a
           numerical value.

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

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

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

       "$muglue = $gullet->readMuGlue;"
           Read a LaTeXML::Core::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.38.2                                       2024-02-27                         LaTeXML::Core::Gullet(3pm)