### Install TexSoup from Source

Source: https://github.com/alvinwan/texsoup/blob/master/README.md

Clone the TexSoup repository and install it locally using pip. This method is useful for development or when needing the latest unreleased changes.

```bash
$ git clone https://github.com/alvinwan/TexSoup.git
$ cd TexSoup
$ pip install .
```

--------------------------------

### Install TexSoup using Pip

Source: https://github.com/alvinwan/texsoup/blob/master/README.md

Install the TexSoup package from PyPi using pip. This is the recommended method for most users.

```bash
$ pip install texsoup
```

--------------------------------

### Count Label References in LaTeX

Source: https://context7.com/alvinwan/texsoup/llms.txt

Use TexSoup to find all labels and count their occurrences via \ref and \pageref commands. Requires the TexSoup library to be installed.

```python
from TexSoup import TexSoup

def count_references(tex):
    """Count references to each label in a LaTeX document."""
    soup = TexSoup(tex)

    # Extract all unique labels
    labels = set(label.string for label in soup.find_all('label'))

    # Count references for each label
    label_refs = {}
    for label in labels:
        refs = soup.find_all(r'\ref{%s}' % label)
        pagerefs = soup.find_all(r'\pageref{%s}' % label)
        label_refs[label] = len(list(refs)) + len(list(pagerefs))

    return label_refs

tex_doc = r"""
\begin{document}
\section{Introduction}\label{sec:intro}
See Section \ref{sec:methods} for methods.
\section{Methods}\label{sec:methods}
As mentioned in Section \ref{sec:intro}...
See Figure \ref{fig:results} and Table \ref{tab:data}.
\ref{sec:intro} again.
\end{document}
"""

counts = count_references(tex_doc)
print(counts)
# Output: {'sec:intro': 2, 'sec:methods': 1}
```

--------------------------------

### Access Command Arguments Count

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/soup.rst

Get the number of arguments for a command by checking the length of the '.args' list.

```python
>>> len(cmd.args)
1
```

--------------------------------

### Get Character Positions and Convert to Line/Column

Source: https://context7.com/alvinwan/texsoup/llms.txt

Access the `position` property to get the character offset of a node in the source. Use `char_pos_to_line` to convert these offsets into human-readable line and column numbers.

```python
from TexSoup import TexSoup

soup = TexSoup(r"""
\section{Hey}
\textbf{Silly}
\textit{Willy}
""")

# Get character position
print(soup.section.position)
# Output: 1

print(soup.textbf.position)
# Output: 15

# Convert to line and column numbers
print(soup.char_pos_to_line(10))
# Output: (1, 9)

print(soup.char_pos_to_line(20))
# Output: (2, 5)

# Use with find_all for reporting
for cmd in soup.find_all('textit'):
    line, col = soup.char_pos_to_line(cmd.position)
    print(f"Found \textit at line {line}, column {col}")
# Output: Found \textit at line 3, column 0
```

--------------------------------

### Access Command Object

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/soup.rst

Access a command within the soup object by its name. For example, 'soup.textbf' retrieves the \textbf command.

```python
>>> soup = TexSoup(r'I am \textbf{\large Large and bold}')
>>> cmd = soup.textbf
>>> cmd
\textbf{\large Large and bold}
```

--------------------------------

### Working with Math Environments in LaTeX

Source: https://context7.com/alvinwan/texsoup/llms.txt

TexSoup can parse and manipulate various LaTeX math environments, including inline math ($...$), display math ($$...$$), and named environments like `equation`. The `string` attribute can be used to get or set the content.

```python
from TexSoup import TexSoup

# Inline math
soup = TexSoup(r'The equation $E = mc^2$ is famous.')
print(soup.find('$'))
# Output: $E = mc^2$

# Display math
soup2 = TexSoup(r'$$\sum_{i=0}^n i^2$$')
print(soup2.find('$$'))
# Output: $$\sum_{i=0}^n i^2$$

# Named math environments
soup3 = TexSoup(r'\begin{equation}a^2 + b^2 = c^2\end{equation}')
print(soup3.equation.string)
# Output: 'a^2 + b^2 = c^2'

# Modify math content
soup3.equation.string = 'x + y = z'
print(soup3)
# Output: \begin{equation}x + y = z\end{equation}

# Math mode with text
soup4 = TexSoup(r'$$\textrm{math}\sum$$')
soup4.textrm.string = 'not math'
print(soup4)
```

--------------------------------

### Modifying String Content

Source: https://context7.com/alvinwan/texsoup/llms.txt

The `string` property enables getting and setting the text content of single-argument commands or text-only environments.

```APIDOC
## Modifying String Content

The `string` property allows getting and setting the text content of single-argument commands or text-only environments.

```python
from TexSoup import TexSoup

# Modify command content
soup = TexSoup(r'\textbf{Hello}')
print(soup.textbf.string)
# Output: 'Hello'

soup.textbf.string = 'Hello World'
print(soup.textbf)
# Output: \textbf{Hello World}

# Modify environment content
soup2 = TexSoup(r'\begin{equation}1+1\end{equation}')
print(soup2.equation.string)
# Output: '1+1'

soup2.equation.string = '2+2=4'
print(soup2)
# Output: \begin{equation}2+2=4\end{equation}

# Modify verbatim environment
soup3 = TexSoup(r'\begin{verbatim}code here\end{verbatim}')
soup3.verbatim.string = 'new code'
print(soup3)
# Output: \begin{verbatim}new code\end{verbatim}
```
```

--------------------------------

### Modifying String Content in TexSoup

Source: https://context7.com/alvinwan/texsoup/llms.txt

Get or set the text content of single-argument commands or text-only environments using the `string` property. This applies to commands like `\textbf` and environments like `equation` or `verbatim`.

```python
from TexSoup import TexSoup

# Modify command content
soup = TexSoup(r'\textbf{Hello}')
print(soup.textbf.string)
# Output: 'Hello'

soup.textbf.string = 'Hello World'
print(soup.textbf)
# Output: \textbf{Hello World}

# Modify environment content
soup2 = TexSoup(r'\begin{equation}1+1\end{equation}')
print(soup2.equation.string)
# Output: '1+1'

soup2.equation.string = '2+2=4'
print(soup2)
# Output: \begin{equation}2+2=4\end{equation}

# Modify verbatim environment
soup3 = TexSoup(r'\begin{verbatim}code here\end{verbatim}')
soup3.verbatim.string = 'new code'
print(soup3)
# Output: \begin{verbatim}new code\end{verbatim}
```

--------------------------------

### Benchmark Default Backends

Source: https://github.com/alvinwan/texsoup/blob/master/benchmarks/README.md

Run benchmarks on the default set of backends for specified arXiv source packages. Includes options for repeats and warmups.

```bash
python3 benchmarks/arxiv.py 2004.05565 1706.03762 1512.03385 --repeats 3 --warmups 1
```

--------------------------------

### Extract All Text Content from LaTeX

Source: https://context7.com/alvinwan/texsoup/llms.txt

The `text` property of a TexSoup object recursively extracts all text content, effectively removing LaTeX commands. Use `list(soup.text)` to get individual text elements or `''.join(str(t) for t in soup.text)` to get the full text.

```python
from TexSoup import TexSoup

soup = TexSoup(r"""
\begin{document}
\section{Hello \textit{world}.}
\subsection{Watermelon}
(n.) A sacred fruit.
Also known as:
\begin{itemize}
  \item red lemon
  \item life
\end{itemize}
\end{document}
")

# Get all text content
text_content = list(soup.text)
print(text_content)
# Output: ['Hello ', 'world', '.', 'Watermelon', '\n(n.) A sacred fruit...', ...]

# Join all text
full_text = ''.join(str(t) for t in soup.text)
print(full_text)
# Output: Combined text without LaTeX commands
```

--------------------------------

### Initialize TexSoup Document

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/searching.rst

Load a LaTeX document string into a TexSoup object for searching. Ensure TexSoup is imported.

```python
tex_doc = """
\begin{document}
\section{Hello \textit{world}.}
\subsection{Watermelon}
(n.) A sacred fruit. Also known as:
\begin{itemize}
  \item red lemon
  \item life
\end{itemize}
Here is the prevalence of each synonym, in Table \ref{table:synonyms}.
\begin{tabular}{c c}\label{table:synonyms}
  red lemon & uncommon \\ \n
  life & common
\end{tabular}
\end{document}
"""
from TexSoup import TexSoup
soup = TexSoup(tex_doc)
```

--------------------------------

### Initialize Document Ready Functions

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/_templates/layout.html

Binds various UI components and utility functions when the DOM is ready. Adds a 'has-code' class to links containing code blocks for styling.

```javascript
$(document).ready(function() {
  mobileMenu.bind();
  mobileTOC.bind();
  pytorchAnchors.bind();
  sideMenus.bind();
  scrollToAnchor.bind();
  highlightNavigation.bind();
  // Add class to links that have code blocks, since we cannot create links in code blocks
  $("article.pytorch-article a span.pre").each(function(e) {
    $(this).closest("a").addClass("has-code");
  });
})
```

--------------------------------

### TexDisplayMathModeEnv

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/data.rst

Represents a LaTeX display math mode environment.

```APIDOC
## TexDisplayMathModeEnv()

### Description
Represents a LaTeX display math mode environment.

### Members
This class has various members that are documented in the source but not detailed here.
```

--------------------------------

### TexMathEnv

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/data.rst

Represents a LaTeX math environment, such as \begin{math} ... \end{math}.

```APIDOC
## TexMathEnv()

### Description
Represents a LaTeX math environment, such as \begin{math} ... \end{math}.

### Members
This class has various members that are documented in the source but not detailed here.
```

--------------------------------

### Count and Locate LaTeX References

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/quickstart.rst

Demonstrates counting specific LaTeX commands like \ref and finding their line numbers. Useful for analyzing cross-references and their positions.

```python
soup.count(r'\ref{table:synonyms}')
for cmd in soup.find_all(r'\ref{table:synonyms}'):
  soup.char_pos_to_line(cmd.position)
```

--------------------------------

### Searching Elements with find and find_all in TexSoup

Source: https://context7.com/alvinwan/texsoup/llms.txt

Locate elements by command or environment names. `find` returns the first match, `find_all` returns all matches. Both can accept strings or lists of names, and `find_all` can search for exact command strings or use regular expressions.

```python
from TexSoup import TexSoup

soup = TexSoup(r"""
\section{Ooo}
\textit{eee}
\textit{ooo}
\textbf{bold}
\ref{fig:1}
\ref{fig:2}
\ref{table:1}
""")

# Find first matching element
print(soup.find('textit'))
# Output: \textit{eee}

# Find returns None if not found
print(soup.find('textbf'))
# Output: \textbf{bold}
print(soup.find('nonexistent'))
# Output: None

# Find all matching elements
results = soup.find_all('textit')
print(results)
# Output: [\textit{eee}, \textit{ooo}]

# Find multiple command types
results = soup.find_all(['textit', 'textbf'])
print(results)
# Output: [\textit{eee}, \textit{ooo}, \textbf{bold}]

# Find by exact command with arguments
refs = soup.find_all(r'\ref{fig:1}')
print(list(refs))
# Output: [\ref{fig:1}]

# Find all refs
all_refs = soup.find_all('ref')
print(list(all_refs))
# Output: [\ref{fig:1}, \ref{fig:2}, \ref{table:1}]
```

--------------------------------

### Benchmark Specific Backends

Source: https://github.com/alvinwan/texsoup/blob/master/benchmarks/README.md

Benchmark a restricted subset of backends for given arXiv source packages. Useful for comparing specific tools.

```bash
python3 benchmarks/arxiv.py 2004.05565 --backends texsoup latexwalker plastex
```

--------------------------------

### TexMathModeEnv

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/data.rst

Represents a LaTeX math mode environment.

```APIDOC
## TexMathModeEnv()

### Description
Represents a LaTeX math mode environment.

### Members
This class has various members that are documented in the source but not detailed here.
```

--------------------------------

### TexDisplayMathEnv

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/data.rst

Represents a LaTeX display math environment, such as \begin{displaymath} ... \end{displaymath} or \[ ... \].

```APIDOC
## TexDisplayMathEnv()

### Description
Represents a LaTeX display math environment, such as \begin{displaymath} ... \end{displaymath} or \[ ... \].

### Members
This class has various members that are documented in the source but not detailed here.
```

--------------------------------

### Parse LaTeX Document with TexSoup

Source: https://github.com/alvinwan/texsoup/blob/master/README.md

Instantiate TexSoup by passing a LaTeX document as a string or file handle. This creates a navigable soup object for further processing.

```python
from TexSoup import TexSoup
soup = TexSoup("""
\begin{document}

\section{Hello \textit{world}.}

\subsection{Watermelon}

(n.) A sacred fruit. Also known as:

\begin{itemize}
\item red lemon
\item life
\end{itemize}

Here is the prevalence of each synonym.

\begin{tabular}{c c}
red lemon & uncommon \\
life & common
\end{tabular}

\end{document}
")
```

--------------------------------

### Create TexSoup Object from File

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/soup.rst

Parse a LaTeX document from an open file handle into a TexSoup object.

```python
>>> from TexSoup import TexSoup
>>> with open("main.tex") as f:
...     soup = TexSoup(f)
```

--------------------------------

### Access Environment Name

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/soup.rst

Retrieve the name of an environment using the '.name' attribute.

```python
>>> env.name
'itemize'
```

--------------------------------

### Google Analytics Initialization

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/_templates/layout.html

Initializes Google Analytics tracking for the website. This snippet should be included to track page views and user interactions.

```javascript
(function(i, s, o, g, r, a, m) {
  i['GoogleAnalyticsObject'] = r;
  i[r] = i[r] || function() {
    (i[r].q = i[r].q || []).push(arguments)
  }, i[r].l = 1 * new Date();
  a = s.createElement(o),
  m = s.getElementsByTagName(o)[0];
  a.async = 1;
  a.src = g;
  m.parentNode.insertBefore(a, m)
})(window, document, 'script', '//www.google-analytics.com/analytics.js', 'ga');
ga('create', 'UA-32800241-3', 'alvinwan.com');
ga('send', 'pageview');
```

--------------------------------

### TexEnv

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/data.rst

Represents a LaTeX environment, typically enclosed in \begin{env} ... \end{env}.

```APIDOC
## TexEnv()

### Description
Represents a LaTeX environment, typically enclosed in \begin{env} ... \end{env}.

### Members
This class has various members that are documented in the source but not detailed here.
```

--------------------------------

### Navigate TexSoup Data Structure

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/quickstart.rst

Demonstrates accessing elements within the parsed LaTeX document using attribute access and parent navigation. Useful for inspecting document structure.

```python
soup.section
soup.section.name
soup.section.string
soup.section.parent.name
soup.tabular
soup.tabular.args[0]
soup.item
```

--------------------------------

### Append, Remove, and Extend Command Arguments

Source: https://context7.com/alvinwan/texsoup/llms.txt

Demonstrates modifying a command's arguments by appending, removing, or extending them. Use these methods to dynamically alter command parameters.

```python
from TexSoup import TexSoup

cmd = TexSoup(r'\textit{hello}')

# Append new argument
cmd.args.append('{moar}')
print(cmd)
# Output: \textit{hello}{moar}

# Remove argument
cmd.args.remove('{moar}')
print(cmd)
# Output: \textit{hello}

# Extend with multiple arguments
cmd.args.extend(['[optional]', '{required}'])
print(cmd)
# Output: \textit{hello}[optional]{required}

# Slice to keep only some arguments
cmd.args = cmd.args[:2]
print(cmd)
# Output: \textit{hello}[optional]

# Modify argument content using .string
cmd.args[0].string = 'world'
print(cmd)
# Output: \textit{world}[optional]
```

--------------------------------

### Modify Verbatim Environment String Content

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/modification.rst

Change the text content of environments like \begin{verbatim} using the .string attribute.

```python
soup = TexSoup(r'\begin{verbatim}Huehue\end{verbatim}')
soup.verbatim.string = 'HUEHUE'
print(soup)
```

--------------------------------

### Access Commands and Environments by Name in TexSoup

Source: https://context7.com/alvinwan/texsoup/llms.txt

Access LaTeX commands and environments directly as attributes of a parsed node. This returns the first matching element.

```python
from TexSoup import TexSoup

soup = TexSoup(r"""
\begin{document}
\section{Hello \textit{world}.}
\subsection{Watermelon}
\begin{itemize}
\item red lemon
\item life
\end{itemize}
\begin{tabular}{c c}
red lemon & uncommon \\
life & common
\end{tabular}
\end{document}
")

# Access first section
print(soup.section)
# Output: \section{Hello \textit{world}.}

# Access command name
print(soup.section.name)
# Output: 'section'

# Access the string content of a single-argument command
print(soup.section.string)
# Output: 'Hello \textit{world}.'

# Access environments
print(soup.itemize)
# Output: \begin{itemize}\item red lemon\item life\end{itemize}

print(soup.tabular)
# Output: \begin{tabular}{c c}red lemon & uncommon \\life & common\end{tabular}

# Access nested commands
print(soup.section.textit)
# Output: \textit{world}

# Access items within environments
print(soup.itemize.item)
# Output: \item red lemon
```

--------------------------------

### Append and Insert Nodes into Environments

Source: https://context7.com/alvinwan/texsoup/llms.txt

Use `append` to add nodes to the end of an environment's content, or `insert` to add them at a specific index. This is useful for dynamically building lists or other environments.

```python
from TexSoup import TexSoup

soup = TexSoup(r"""
\begin{itemize}
    \item Hello
\end{itemize}
""")

# Copy an existing item
item_copy = soup.item.copy()

# Append to environment
soup.itemize.append('    ', item_copy)
print(soup.itemize)
# Output: \begin{itemize}    \item Hello    \item Hello\end{itemize}

# Insert at specific position
soup2 = TexSoup(r"""
\begin{itemize}
    \item First
    \item Last
\end{itemize}
""")
middle_item = soup2.item.copy()
soup2.item.delete()
soup2.itemize.insert(1, middle_item)
print(soup2.itemize)
# Shows item inserted at position 1
```

--------------------------------

### to_buffer Function

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/utils.rst

Converts input to a Buffer object.

```APIDOC
## to_buffer Function

### Description
Converts various input types (e.g., strings, file paths) into a `Buffer` object for consistent text processing.

### Parameters
(Parameters are documented via `:members:` directive in the source, specific details not provided in this snippet.)
```

--------------------------------

### Benchmark External Converters Without Timeout

Source: https://github.com/alvinwan/texsoup/blob/master/benchmarks/README.md

Run external converters like LaTeXML without a command timeout. Useful for long-running processes or debugging timeouts.

```bash
python3 benchmarks/arxiv.py 2004.05565 --backends latexml --command-timeout-seconds 0
```

--------------------------------

### Access Environment Arguments

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/soup.rst

Environments store arguments in a list accessible via the '.args' attribute, similar to commands.

```python
>>> soup = TexSoup(r'Haha \begin{itemize}[label=\alph]\item Huehue\end{itemize}')
>>> env = soup.itemize
>>> env
\begin{itemize}[label=\alph]\item Huehue\end{itemize}
```

--------------------------------

### Insert Item into Environment

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/modification.rst

Add an item to an environment's content at a specific position using .insert().

```python
soup.insert(1, tmp)
print(soup)
```

--------------------------------

### Command Tokenizer Functions

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/tokenizer.rst

Functions for tokenizing command names.

```APIDOC
## tokenize_command_name

### Description
Tokenizes command names.

### Method
`tokenize_command_name(tex_string)`
```

--------------------------------

### Find All Elements by String Filter

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/searching.rst

Use .find_all with a string to find all occurrences of a specific LaTeX command or environment.

```python
soup.find_all('item')
```

--------------------------------

### TexSoup Function

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/main.rst

The main TexSoup function serves as the entry point for parsing LaTeX code.

```APIDOC
## TexSoup

### Description
Parses LaTeX code into a navigable structure.

### Signature
TexSoup(tex_string: str, **kwargs)

### Parameters
* **tex_string** (str) - The LaTeX code to parse.
* **kwargs** - Additional keyword arguments for customization.
```

--------------------------------

### Access Command Name

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/soup.rst

Retrieve the name of a command using the '.name' attribute.

```python
>>> cmd.name
'textbf'
```

--------------------------------

### TexUnNamedEnv

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/data.rst

Represents an unnamed LaTeX environment.

```APIDOC
## TexUnNamedEnv()

### Description
Represents an unnamed LaTeX environment.

### Members
This class has various members that are documented in the source but not detailed here.
```

--------------------------------

### TexCmd

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/data.rst

Represents a LaTeX command, such as \command[args]{arg}.

```APIDOC
## TexCmd()

### Description
Represents a LaTeX command, such as \command[args]{arg}.

### Members
This class has various members that are documented in the source but not detailed here.
```

--------------------------------

### Find All LaTeX Items with TexSoup

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/quickstart.rst

Shows how to find all occurrences of a specific LaTeX command, such as \item, within the parsed document. Useful for collecting all instances of a particular element.

```python
list(soup.find_all('item'))
```

--------------------------------

### Searching with find and find_all

Source: https://context7.com/alvinwan/texsoup/llms.txt

Methods for locating specific elements within the parsed LaTeX structure. `find` returns the first match, and `find_all` returns all matches.

```APIDOC
## Searching with find and find_all

The `find` method returns the first matching element, while `find_all` returns all matching elements. Both accept command/environment names as strings or lists.

```python
from TexSoup import TexSoup

soup = TexSoup(r"""
\section{Ooo}
\textit{eee}
\textit{ooo}
\textbf{bold}
\ref{fig:1}
\ref{fig:2}
\ref{table:1}
""")

# Find first matching element
print(soup.find('textit'))
# Output: \textit{eee}

# Find returns None if not found
print(soup.find('textbf'))
# Output: \textbf{bold}
print(soup.find('nonexistent'))
# Output: None

# Find all matching elements
results = soup.find_all('textit')
print(results)
# Output: [\textit{eee}, \textit{ooo}]

# Find multiple command types
results = soup.find_all(['textit', 'textbf'])
print(results)
# Output: [\textit{eee}, \textit{ooo}, \textbf{bold}]

# Find by exact command with arguments
refs = soup.find_all(r'\ref{fig:1}')
print(list(refs))
# Output: [\ref{fig:1}]

# Find all refs
all_refs = soup.find_all('ref')
print(list(all_refs))
# Output: [\ref{fig:1}, \ref{fig:2}, \ref{table:1}]
```
```

--------------------------------

### Token Class

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/utils.rst

Base class for tokens.

```APIDOC
## Token Class

### Description
Base class for all tokens in TexSoup. Provides fundamental token properties.

### Members
(Members are documented via `:members:` directive in the source, specific details not provided in this snippet.)
```

--------------------------------

### TexNamedEnv

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/data.rst

Represents a named LaTeX environment, such as \begin{figure} ... \end{figure}.

```APIDOC
## TexNamedEnv()

### Description
Represents a named LaTeX environment, such as \begin{figure} ... \end{figure}.

### Members
This class has various members that are documented in the source but not detailed here.
```

--------------------------------

### Math Tokenizer Functions

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/tokenizer.rst

Functions for tokenizing mathematical symbols and switches.

```APIDOC
## tokenize_math_sym_switch

### Description
Tokenizes math symbol switches.

### Method
`tokenize_math_sym_switch(tex_string)`

## tokenize_math_asym_switch

### Description
Tokenizes asynchronous math switches.

### Method
`tokenize_math_asym_switch(tex_string)`

## tokenize_punctuation_command_name

### Description
Tokenizes punctuation within command names.

### Method
`tokenize_punctuation_command_name(tex_string)`
```

--------------------------------

### Tokenizer Functions

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/tokenizer.rst

Core functions for tokenizing TeX input.

```APIDOC
## tokenize

### Description
Tokenizes the given TeX string.

### Method
`tokenize(tex_string)`

## next_token

### Description
Retrieves the next token from a tokenized stream.

### Method
`next_token(tokens)`
```

--------------------------------

### TexArgs

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/data.rst

Represents the arguments of a LaTeX command or environment.

```APIDOC
## TexArgs()

### Description
Represents the arguments of a LaTeX command or environment.

### Members
This class has various members that are documented in the source but not detailed here.
```

--------------------------------

### Access First Item Globally with TexSoup

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/navigation.rst

Retrieves the first \item expression found anywhere in the document. This demonstrates that direct name access searches the entire parsed structure.

```python
soup.item
```

--------------------------------

### Find All Elements by List Filter

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/searching.rst

Pass a list of strings to .find_all to find elements matching any of the specified filters. This is useful for searching multiple types of elements simultaneously.

```python
soup.find_all(['item', 'textit'])
```

--------------------------------

### Navigate and Search Parsed LaTeX with TexSoup

Source: https://github.com/alvinwan/texsoup/blob/master/README.md

Access elements by tag name, traverse the document tree using parent/child relationships, and find all occurrences of a specific tag. The `args` attribute can be used to access arguments of environments or commands.

```python
>>> soup.section  # grabs the first `section`
\section{Hello \textit{world}.}
>>> soup.section.name
'section'
>>> soup.section.string
'Hello \\textit{world}.'
>>> soup.section.parent.name
'document'
>>> soup.tabular
\begin{tabular}{c c}
red lemon & uncommon \\
life & common
\end{tabular}
>>> soup.tabular.args[0]
'c c'
>>> soup.item
\item red lemon
>>> list(soup.find_all('item'))
[\item red lemon, \item life]
```

--------------------------------

### Extend Command Arguments

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/modification.rst

Add multiple arguments to a command's argument list using .extend().

```python
cmd.args.extend(['[moar]', '{crazy}'])
print(cmd)
```

--------------------------------

### Tolerate LaTeX Errors

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/soup.rst

Instantiate TexSoup with 'tolerance=1' to enable best-effort parsing of documents containing LaTeX errors.

```python
>>> soup4 = TexSoup(r'\begin{itemize}\item hullo\end{enumerate}', tolerance=1)
>>> soup4
\begin{itemize}\item hullo\end{itemize}\end{enumerate}
```

--------------------------------

### Create TexSoup Object from String

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/soup.rst

Parse a LaTeX document directly from a string into a TexSoup object.

```python
>>> soup2 = TexSoup(r'\begin{document}Hello world!\end{document}')
```

--------------------------------

### Counting Elements in TexSoup

Source: https://context7.com/alvinwan/texsoup/llms.txt

Use the `count` method to determine the number of descendants that match specific criteria, such as command names or exact command strings.

```python
from TexSoup import TexSoup

soup = TexSoup(r"""
\section{Hey}
\textit{Silly}
\textit{Willy}
\ref{hello}
\ref{hello}
\ref{hello}
\ref{nono}
""")

# Count by command name
print(soup.count('section'))
# Output: 1

print(soup.count('textit'))
# Output: 2

# Count specific command with arguments
print(soup.count(r'\ref{hello}'))
# Output: 3

print(soup.count(r'\ref{nono}'))
# Output: 1
```

--------------------------------

### Access Command Arguments as List

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/soup.rst

View all arguments of a command as a list using the '.args' attribute.

```python
>>> str(cmd.args)
'{\large Large and bold}'
```

```python
>>> cmd.args
[BraceGroup('floating')]
```

--------------------------------

### Environment Parser Functions

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/parser.rst

Functions for parsing different types of TeX environments.

```APIDOC
## read_item

### Description
Parses an item within an environment.

### Method
`read_item()`

## unclosed_env_handler

### Description
Handles unclosed environments.

### Method
`unclosed_env_handler()`

## read_math_env

### Description
Parses a math environment.

### Method
`read_math_env()`

## read_skip_env

### Description
Parses a skippable environment.

### Method
`read_skip_env()`

## read_env

### Description
Parses a general TeX environment.

### Method
`read_env()`
```

--------------------------------

### Access First Item in List with TexSoup

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/navigation.rst

Retrieves the first \item expression found within an \itemize environment. Note that direct name access only returns the first match.

```python
soup.itemize.item
```

--------------------------------

### Buffer Class

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/utils.rst

Represents a text buffer for processing.

```APIDOC
## Buffer Class

### Description
Represents a text buffer, providing methods for reading and manipulating text content. It is used internally for parsing and processing.

### Members
(Members are documented via `:members:` directive in the source, specific details not provided in this snippet.)
```

--------------------------------

### Set Command String Content

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/modification.rst

Update the content of a single-argument command using its .string attribute. This is applicable to commands like \section or \textit.

```python
cmd.string = 'corgis are the best'
print(cmd)
```

--------------------------------

### Replace Nodes with Other Nodes or Strings

Source: https://context7.com/alvinwan/texsoup/llms.txt

The `replace_with` method allows you to substitute a node with one or more other nodes, or even a plain string. This is powerful for transforming document content.

```python
from TexSoup import TexSoup

soup = TexSoup(r"""
\begin{itemize}
    \item Hello
    \item Bye
\end{itemize}
""")

# Get items
items = list(soup.find_all('item'))
bye_item = items[1]

# Replace first item with the bye item
soup.item.replace_with(bye_item)
print(soup.itemize)
# Output: \begin{itemize}    \item Bye\item Bye\end{itemize}

# Replace with string
soup2 = TexSoup(r'\textbf{old}\textit{Y}O\textit{U}')
soup2.textbf.delete()
soup2.textit.replace_with('S')
print(soup2)
# Output: SO\textit{U}
```

--------------------------------

### Navigating Children and Contents

Source: https://context7.com/alvinwan/texsoup/llms.txt

Accessing nested elements within a TexSoup object using properties like `children`, `contents`, `text`, and `descendants`.

```APIDOC
## Navigating Children and Contents

TexSoup provides several properties for accessing an element's nested content: `children` (TeX expressions only), `contents` (expressions and text), `text` (text only), and `descendants` (all nested expressions recursively).

```python
from TexSoup import TexSoup

soup = TexSoup(r"""
\begin{itemize}
    Random text!
    \item Hello
    \item Bye
\end{itemize}
""")

# Get children (TeX expressions only, excludes text)
print(soup.itemize.children)
# Output: [\item Hello, \item Bye]

# Get contents (includes text and expressions)
contents = soup.itemize.contents
print(contents[0])
# Output: '\n    Random text!\n    '
print(contents[1])
# Output: \item Hello

# Get all text from descendants
soup2 = TexSoup(r"""
\begin{itemize}
    \begin{itemize}
        \item Nested
    \end{itemize}
\end{itemize}
""")
print(list(soup2.text))
# Output: [' Nested\n    ']

# Get all descendants recursively
descendants = list(soup2.itemize.descendants)
print(descendants[1])
# Output: \item Nested
```
```

--------------------------------

### General Parser Functions

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/parser.rst

Functions for general TeX parsing and peeking.

```APIDOC
## read_tex

### Description
Parses TeX content.

### Method
`read_tex()`

## read_expr

### Description
Parses a TeX expression.

### Method
`read_expr()`

## read_spacer

### Description
Parses whitespace in TeX content.

### Method
`read_spacer()`

## make_read_peek

### Description
Creates a function to peek at TeX content.

### Method
`make_read_peek()`
```

--------------------------------

### TexText

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/data.rst

Represents plain text within the LaTeX document.

```APIDOC
## TexText()

### Description
Represents plain text within the LaTeX document.

### Members
This class has various members that are documented in the source but not detailed here.
```

--------------------------------

### Resolve LaTeX Imports Recursively

Source: https://context7.com/alvinwan/texsoup/llms.txt

This function recursively resolves \input and \include commands in a LaTeX document. It handles FileNotFoundError by keeping the original command. Ensure base_path is correctly set for relative paths.

```python
from TexSoup import TexSoup

def resolve_imports(tex, base_path=''):
    """Recursively resolve all imports in a LaTeX document."""
    soup = TexSoup(tex)

    # Resolve \input commands
    for _input in soup.find_all('input'):
        try:
            path = base_path + _input.args[0].string
            with open(path) as f:
                nested = resolve_imports(f.read(), base_path)
            _input.replace_with(*nested.contents)
        except FileNotFoundError:
            pass  # Keep original if file not found

    # Resolve \include commands
    for include in soup.find_all('include'):
        try:
            path = base_path + include.args[0].string
            with open(path) as f:
                nested = resolve_imports(f.read(), base_path)
            include.replace_with(*nested.contents)
        except FileNotFoundError:
            pass

    return soup

# Usage
tex_doc = r"""
\begin{document}
\input{chapter1}
\include{chapter2}
\end{document}
"""
# expanded = resolve_imports(tex_doc)
# print(expanded)
```

--------------------------------

### Access Command Expression

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/soup.rst

Access the underlying expression of a command using '.expr' to see its detailed structure, including arguments and nested commands.

```python
>>> cmd.expr
TexCmd('textbf', [BraceGroup(TexCmd('large'), ' Large and bold')])
```

--------------------------------

### TexExpr

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/data.rst

Represents a LaTeX expression, which can be a command, environment, or text.

```APIDOC
## TexExpr()

### Description
Represents a LaTeX expression, which can be a command, environment, or text.

### Members
This class has various members that are documented in the source but not detailed here.
```

--------------------------------

### Command Parser Functions

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/parser.rst

Functions for parsing TeX commands.

```APIDOC
## read_command

### Description
Parses a TeX command.

### Method
`read_command()`
```

--------------------------------

### Searching with Regular Expressions

Source: https://context7.com/alvinwan/texsoup/llms.txt

Utilize `search_regex` to find patterns within the text content of the LaTeX document, returning `Token` objects with position information.

```APIDOC
## Searching with Regular Expressions

The `search_regex` method searches text content using regular expressions, returning matching `Token` objects with position information.

```python
from TexSoup import TexSoup

soup = TexSoup(r"""
\begin{document}
Hello world! This is a test.
Email: test@example.com
Phone: 123-456-7890
\end{document}
""")

# Search for patterns in text content
for match in soup.search_regex(r'\d{3}-\d{3}-\d{4}'):
    print(f"Found: {match}")
# Output: Found: 123-456-7890

# Search for email pattern
for match in soup.search_regex(r'\S+@\S+'):
    print(f"Email: {match}")
# Output: Email: test@example.com

# Access position of matches
for match in soup.search_regex(r'world'):
    print(f"Found '{match}' at position {match.position}")
# Output: Found 'world' at position 24
```
```

--------------------------------

### Parse LaTeX Documents with TexSoup

Source: https://context7.com/alvinwan/texsoup/llms.txt

Use the TexSoup function to parse LaTeX from strings or file handles. Options include skipping environments, setting tolerance for malformed LaTeX, and specifying encoding.

```python
from TexSoup import TexSoup

# Parse a LaTeX document from a string
tex_source = r"""
\begin{document}

\section{Hello \textit{world}.}

\subsection{Watermelon}

(n.) A sacred fruit. Also known as:

\begin{itemize}
\item red lemon
\item life
\end{itemize}

Here is the prevalence of each synonym.

\begin{tabular}{c c}
red lemon & uncommon \\
life & common
\end{tabular}

\end{document}
"""

soup = TexSoup(tex_source)
print(soup)
# Output: Full document structure

# Parse from a file
with open('document.tex') as f:
    soup = TexSoup(f)

# Parse with skip_envs to exclude certain environments from parsing
soup = TexSoup(tex_source, skip_envs=('verbatim', 'lstlisting'))

# Parse with tolerance for malformed LaTeX (0=strict, 1=tolerant)
soup = TexSoup(tex_source, tolerance=1)
```

--------------------------------

### BracketGroup

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/data.rst

Represents a group delimited by square brackets, e.g., [options].

```APIDOC
## BracketGroup()

### Description
Represents a group delimited by square brackets, e.g., [options].

### Members
This class has various members that are documented in the source but not detailed here.
```

--------------------------------

### Modify Math Environment String Content

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/modification.rst

Update the content of math environments (e.g., $$...$$) using the .string attribute.

```python
soup = TexSoup(r'$$\text{math}$$')
soup.text.string = ''
```

--------------------------------

### Navigating Element Children and Contents in TexSoup

Source: https://context7.com/alvinwan/texsoup/llms.txt

Access nested elements and text within a LaTeX structure. Use `children` for TeX expressions only, `contents` for both expressions and text, `text` for text only, and `descendants` for all nested expressions recursively.

```python
from TexSoup import TexSoup

soup = TexSoup(r"""
\begin{itemize}
    Random text!
    \item Hello
    \item Bye
\end{itemize}
""")

# Get children (TeX expressions only, excludes text)
print(soup.itemize.children)
# Output: [\item Hello, \item Bye]

# Get contents (includes text and expressions)
contents = soup.itemize.contents
print(contents[0])
# Output: '\n    Random text!\n    '
print(contents[1])
# Output: \item Hello

# Get all text from descendants
soup2 = TexSoup(r"""
\begin{itemize}
    \begin{itemize}
        \item Nested
    \end{itemize}
\end{itemize}
""")
print(list(soup2.text))
# Output: [' Nested\n    ']

# Get all descendants recursively
descendants = list(soup2.itemize.descendants)
print(descendants[1])
# Output: \item Nested
```

--------------------------------

### Extract All Text from LaTeX Document

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/quickstart.rst

Illustrates how to extract all plain text content from a parsed LaTeX document. Useful for text analysis or content summarization.

```python
list(soup.text)
```

--------------------------------

### Access Parent Expression with TexSoup

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/navigation.rst

Navigates from a child expression (e.g., \textit) up to its immediate parent expression (e.g., \section).

```python
soup.textit.parent
```

--------------------------------

### Text Tokenizer Functions

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/tokenizer.rst

Functions for tokenizing text elements like symbols and strings.

```APIDOC
## tokenize_symbols

### Description
Tokenizes symbols in text.

### Method
`tokenize_symbols(tex_string)`

## tokenize_string

### Description
Tokenizes strings in text.

### Method
`tokenize_string(tex_string)`
```

--------------------------------

### Navigate Parent Relationships in TexSoup

Source: https://context7.com/alvinwan/texsoup/llms.txt

Use the `parent` property to traverse up the document tree to access containing elements. This allows for navigating the hierarchy of LaTeX elements.

```python
from TexSoup import TexSoup

soup = TexSoup(r"""
\begin{document}
\section{Hello \textit{world}.}
\begin{itemize}
\item red lemon
\end{itemize}
\end{document}
")

# Access parent of a section
print(soup.section.parent.name)
# Output: 'document'

# Access parent chain
item = soup.item
print(item.parent.name)
# Output: 'itemize'

print(item.parent.parent.name)
# Output: 'document'

# Access parent of nested command	extit = soup.textit
print(textit.parent.name)
# Output: 'section'
```

--------------------------------

### Access Command Arguments

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/soup.rst

Access and manipulate command arguments using the '.args' attribute, which behaves like a list. Changes are reflected in the soup's string representation.

```python
>>> cmd.args.append('{moar}')  # add arguments
>>> str(cmd.args)
'{\large Large and bold}{moar}'
>>> cmd.args.remove('{\large Large and bold}')  # remove arguments
>>> str(cmd.args)
'{moar}'
>>> cmd.args[0].string = 'floating'  # modify arguments
>>> str(cmd.args)
'{floating}'
```

```python
>>> cmd.args.append('[optional]')  # add optional arg
>>> str(cmd.args)
'{floating}[optional]'
>>> cmd.args.remove('[optional]')  # remove optional arg
>>> str(cmd.args)
'{floating}'
```

--------------------------------

### Convert Soup to String

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/soup.rst

Convert a TexSoup object or its nested data structures back into a LaTeX string representation using str().

```python
>>> str(soup4)
'\\begin{itemize}\\item hullo\\end{itemize}\\end{enumerate}'
```

--------------------------------

### CharToLineOffset Class

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/utils.rst

Maps character offsets to line and column numbers.

```APIDOC
## CharToLineOffset Class

### Description
Utility class for mapping character offsets within a string to their corresponding line and column numbers. Useful for error reporting and navigation.

### Members
(Members are documented via `:members:` directive in the source, specific details not provided in this snippet.)
```

--------------------------------

### Escape Tokenizer Functions

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/tokenizer.rst

Functions for tokenizing escaped symbols and related constructs.

```APIDOC
## tokenize_escaped_symbols

### Description
Tokenizes escaped symbols.

### Method
`tokenize_escaped_symbols(tex_string)`

## tokenize_line_comment

### Description
Tokenizes line comments.

### Method
`tokenize_line_comment(tex_string)`

## tokenize_line_break

### Description
Tokenizes line breaks.

### Method
`tokenize_line_break(tex_string)`

## tokenize_ignore

### Description
Tokenizes content to be ignored.

### Method
`tokenize_ignore(tex_string)`
```

--------------------------------

### TexNode

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/data.rst

Represents a generic node in the TexSoup abstract syntax tree. It serves as the base class for all other node types.

```APIDOC
## TexNode()

### Description
Represents a generic node in the TexSoup abstract syntax tree. It serves as the base class for all other node types.

### Members
This class has various members that are documented in the source but not detailed here.
```

--------------------------------

### Access Italicized Text with TexSoup

Source: https://github.com/alvinwan/texsoup/blob/master/docs/source/navigation.rst

Navigates directly to the first \textit{} expression within the parsed document. Use this for quick access to specific tagged content.

```python
soup.textit
```

--------------------------------

### Access Command Arguments in TexSoup

Source: https://context7.com/alvinwan/texsoup/llms.txt

Use the `args` property to access command arguments as a `TexArgs` object. Arguments are represented as `BraceGroup` or `BracketGroup`. Supports indexing, slicing, and length checks.

```python
from TexSoup import TexSoup

soup = TexSoup(r"\newcommand{reverseconcat}[3]{#3#2#1}")

# Access all arguments
print(soup.newcommand.args)
# Output: [BraceGroup('reverseconcat'), BracketGroup('3'), BraceGroup('#3#2#1')]

# Access individual arguments by index
print(soup.newcommand.args[0])
# Output: BraceGroup('reverseconcat')

# Get the string content of an argument
print(soup.newcommand.args[0].string)
# Output: 'reverseconcat'

# Slice arguments
print(soup.newcommand.args[:2])
# Output: [BraceGroup('reverseconcat'), BracketGroup('3')]

# Check argument count
print(len(soup.newcommand.args))
# Output: 3

# Access tabular arguments
soup2 = TexSoup(r"\begin{tabular}{c c}data\end{tabular}")
print(soup2.tabular.args[0])
# Output: BraceGroup('c c')
print(soup2.tabular.args[0].string)
# Output: 'c c'
```

--------------------------------

### Copy Nodes Independently

Source: https://context7.com/alvinwan/texsoup/llms.txt

The `copy` method creates a deep copy of a node, detached from its parent. This allows you to reuse nodes or modify them without affecting the original structure.

```python
from TexSoup import TexSoup

soup = TexSoup(r"""
\section{Hey}
\textit{Silly}
\textit{Willy}
""")

# Copy a node
section_copy = soup.section.copy()

# Verify copy has no parent
print(section_copy.parent is None)
# Output: True

# Original still has parent
print(soup.section.parent is not None)
# Output: True

# Copy can be modified independently
section_copy.string = 'Copied'
print(section_copy)
# Output: \section{Copied}
print(soup.section)
# Output: \section{Hey}
```