---
name: "LaTeXML::Core::State"
section: "3pm"
platform: "linux"
package: "latexml"
version: "0.8.8-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/LaTeXML::Core::State"
---

# LaTeXML::Core::State(3pm)

stores the current state of processing.

## NAME

"LaTeXML::Core::State" - stores the current state of processing.

## DESCRIPTION

A `"LaTeXML::Core::State"` object stores the current state of processing. It recording catcodes, variables values, definitions and so forth, as well as mimicking TeX's scoping rules.

### Access to State and Processing

- "$STATE-\>getStomach;"

  Returns the current Stomach used for digestion.

- "$STATE-\>getModel;"

  Returns the current Model representing the document model.

### Scoping

The assignment methods, described below, generally take a `$scope` argument, which determines how the assignment is made.  The allowed values and their implications are:

```
 global   : global assignment.
 local    : local assignment, within the current grouping.
 undef    : global if \global preceded, else local (default)
 <name>   : stores the assignment in a `scope' which
            can be loaded later.
```

If no scoping is specified, then the assignment will be global if a preceding `"\global"` has set the global flag, otherwise the value will be assigned within the current grouping.

- "$STATE-\>pushFrame;"

  Starts a new level of grouping. Note that this is lower level than `"\bgroup"`; See LaTeXML::Core::Stomach.

- "$STATE-\>popFrame;"

  Ends the current level of grouping. Note that this is lower level than `"\egroup"`; See LaTeXML::Core::Stomach.

- "$STATE-\>setPrefix($prefix);"

  Sets a prefix (eg. `"global"` for `"\global"`, etc) for the next operation, if applicable.

- "$STATE-\>clearPrefixes;"

  Clears any prefixes.

### Values

- "$value = $STATE-\>lookupValue($name);"

  Lookup the current value associated with the the string `$name`.

- "$STATE-\>assignValue($name,$value,$scope);"

  Assign `$value` to be associated with the the string `$name`, according to the given scoping rule.

  Values are also used to specify most configuration parameters (which can therefore also be scoped).  The recognized configuration parameters are:

  ```
   STRICT            : whether errors (eg. undefined macros)
                       are fatal.
   INCLUDE_COMMENTS  : whether to preserve comments in the
                       source, and to add occasional line
                       number comments. (Default true).
   PRESERVE_NEWLINES : whether newlines in the source should
                       be preserved (not 100% TeX-like).
                       By default this is true.
   SEARCHPATHS       : a list of directories to search for
                       sources, implementations, etc.
  ```

- "$STATE-\>pushValue($name,$value);"

  This is like `"->assign"`, but pushes a value onto the end of the stored value, which should be a LIST reference. Scoping is not handled here (yet?), it simply pushes the value onto the last binding of `$name`.

- "$boole = $STATE-\>isValuebound($type,$name,$frame);"

  Returns whether the value `$name` is bound. If  `$frame` is given, check whether it is bound in the `$frame`-th frame, with 0 being the top frame.

### Category Codes

- "$value = $STATE-\>lookupCatcode($char);"

  Lookup the current catcode associated with the the character `$char`.

- "$STATE-\>assignCatcode($char,$catcode,$scope);"

  Set `$char` to have the given `$catcode`, with the assignment made according to the given scoping rule.

  This method is also used to specify whether a given character is active in math mode, by using `"math:$char"` for the character, and using a value of 1 to specify that it is active.

### Definitions

- "$defn = $STATE-\>lookupMeaning($token);"

  Get the "meaning" currently associated with `$token`, either the definition (if it is a control sequence or active character)\
    or the token itself if it shouldn't be executable. (See LaTeXML::Core::Definition)

- "$STATE-\>assignMeaning($token,$defn,$scope);"

  Set the definition associated with `$token` to `$defn`. If `$globally` is true, it makes this the global definition rather than bound within the current group. (See LaTeXML::Core::Definition, and LaTeXML::Package)

- "$STATE-\>installDefinition($definition, $scope);"

  Install the definition into the current stack frame under its normal control sequence.

### Named Scopes

Named scopes can be used to set variables or redefine control sequences within a scope other than the standard TeX grouping. For example, the LaTeX implementation will automatically activate any definitions that were defined with a named scope of, say "section:4", during the portion of the document that has the section counter equal to 4.  Similarly, a scope named "label:foo" will be activated in portions of the document where `"\label{foo}"` is in effect.

- "$STATE-\>activateScope($scope);"

  Installs any definitions that were associated with the named `$scope`. Note that these are placed in the current grouping frame and will disappear when that grouping ends.

- "$STATE-\>deactivateScope($scope);"

  Removes any definitions that were associated with the named `$scope`. Normally not needed, since a scopes definitions are locally bound anyway.

- "$sp = $STATE-\>convertUnit($unit);"

  Converts a TeX unit of the form `'10em'` (or whatever TeX unit) into scaled points.  (Defined here since in principle it could track the size of ems and so forth (but currently doesn't))

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