### Install TexSoup from Source

Source: https://texsoup.alvinwan.com/docs/_sources/quickstart.rst.txt

Install TexSoup by cloning the repository and running the setup script. This is useful for development or if you need the latest unreleased version.

```bash
git clone https://github.com/alvinwan/TexSoup.git
cd TexSoup
python setup.py install
```

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

### Install TexSoup

Source: https://texsoup.alvinwan.com/docs/quickstart.html

Installation instructions via pip or from the source repository.

```bash
pip install TexSoup
```

```bash
git clone https://github.com/alvinwan/TexSoup.git
cd TexSoup
python setup.py install
```

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

### Install TexSoup using pip

Source: https://texsoup.alvinwan.com/docs/_sources/quickstart.rst.txt

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

```bash
pip install TexSoup
```

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

### CharToLineOffset Usage Example

Source: https://texsoup.alvinwan.com/docs/_modules/TexSoup/utils.html

Demonstrates converting an absolute character position to a (line, column) tuple.

```python
clo = CharToLineOffset('''hello
world
I scream for ice cream!''')
clo(3)
clo(6)
clo(12)
```

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

### Check if Buffer Starts with a String

Source: https://texsoup.alvinwan.com/docs/utils.html

The `startswith` method checks if the buffer's content, starting from the current position, matches the provided string `s`.

```python
>>> b = Buffer('abcdef')
>>> b.startswith('abc')
True
```

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

### Buffer Start and End Checks

Source: https://texsoup.alvinwan.com/docs/_modules/TexSoup/utils.html

Checks if the buffer's current content starts or ends with a given string.

```python
b1.startswith('01')
```

```python
b1.endswith('1')
```

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

### Group characters in math switches

Source: https://texsoup.alvinwan.com/docs/tokenizer.html

Use `tokenize_math_sym_switch` to group characters within simple math switches like '$' or '$$'. It identifies the start of math environments.

```python
>>> tokenize_math_sym_switch(categorize(r'$\min_x$ \command'))
'$'
```

```python
>>> tokenize_math_sym_switch(categorize(r'$$\min_x$$ \command'))
'$$'
```

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

### Get All Content of a Node

Source: https://texsoup.alvinwan.com/docs/data.html

Use the `all` attribute to retrieve all content within a node, including whitespace and LaTeX source, useful for reconstructing the original string.

```python
>>> from TexSoup import TexSoup
>>> soup = TexSoup(r'''\
... \newcommand{reverseconcat}[3]{#3#2#1}
... ''')
>>> alls = soup.all
>>> alls[0]


>>> alls[1]
\newcommand{reverseconcat}[3]{#3#2#1}
```

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

### Tokenize Commands (Ignoring Line Breaks)

Source: https://texsoup.alvinwan.com/docs/_modules/TexSoup/reader.html

Processes general commands, specifically those starting with a double backslash, while ignoring line breaks within the command. It continues tokenizing until it encounters punctuation, whitespace, or math tokens.

```python
@token('command')
def tokenize_command(text):
    """Process command, but ignore line breaks. (double backslash)

    :param Buffer text: iterator over line, with current position
    """
    if text.peek() == '\':
        c = text.forward(1)
        tokens = set(string.punctuation + string.whitespace) - {'*'}
        while text.hasNext() and (c == '\' or text.peek() not in tokens) and c not in MATH_TOKENS:
            c += text.forward(1)
        return c
```

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

### Initialize TexEnv

Source: https://texsoup.alvinwan.com/docs/_modules/TexSoup/data.html

Initializes a Tex environment with name, contents, arguments, and whitespace preservation options.

```python
def __init__(self, name, contents=(), args=(), preserve_whitespace=False,
             nobegin=False, begin=False, end=False):
    """Initialization for Tex environment.

    :param str name: name of environment
    :param iterable contents: list of contents
    :param iterable args: list of Tex Arguments
    :param bool preserve_whitespace: If false, elements containing only
        whitespace will be removed from contents.
    :param bool nobegin: Disable \begin{...} notation.
    """
    super().__init__(name, contents, args, preserve_whitespace)

    self.nobegin = nobegin
    self.begin = begin if begin else (self.name if self.nobegin else "\begin{%s}" % self.name)
    self.end = end if end else (self.name if self.nobegin else "\end{%s}" % self.name)
```

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

### Create and Print TexNamedEnv

Source: https://texsoup.alvinwan.com/docs/data.html

Demonstrates creating a TexNamedEnv for a 'tabular' environment with content and arguments, and printing its string representation.

```python
>>> t = TexNamedEnv('tabular', ['\n0 & 0 & * \\\\n1 & 1 & * \\\\n'],
...     [BraceGroup('c | c c')])
>>> t
TexNamedEnv('tabular', ['\n0 & 0 & * \\\\n1 & 1 & * \\\\n'], [BraceGroup('c | c c')])
>>> print(t)
\begin{tabular}{c | c c}
0 & 0 & * \\
1 & 1 & * \\
\end{tabular}
>>> len(list(t.children))
0
```

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

### tokenize_line_comment

Source: https://texsoup.alvinwan.com/docs/_modules/TexSoup/reader.html

Processes a line comment starting with '%'.

```APIDOC
## Function: tokenize_line_comment(text)

### Description
Process a line comment.

### Parameters
#### Path Parameters
- **text** (Buffer) - Required - Iterator over line, with current position.

### Request Example
```
>>> tokenize_line_comment(Buffer('hello %world'))
>>> tokenize_line_comment(Buffer('%hello world'))
'%hello world'
>>> tokenize_line_comment(Buffer('%hello\n world'))
'%hello'
```
```

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

### Making a Soup

Source: https://texsoup.alvinwan.com/docs/soup.html

Demonstrates how to create a TexSoup object from a LaTeX file or string, including options for error tolerance.

```APIDOC
## Making a Soup

To parse a LaTeX document, pass an open filehandle or a string into the `TexSoup` constructor:

```python
>>> from TexSoup import TexSoup
>>> with open("main.tex") as f:
...     soup = TexSoup(f)
>>> soup2 = TexSoup(r'\begin{document}Hello world!\end{document}')
```

Alternatively, compute the data structure only:

```python
>>> from TexSoup import read
>>> soup3, _ = read(r'\begin{document}Hello world!\end{document}')
>>> soup3
[TexNamedEnv('document', ['Hello world!'], [])]
```

You can also ask TexSoup to tolerate LaTeX errors. In which case, TexSoup will make a best-effort guess:

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

To output the soup, you can call `str()` on a `TexSoup.data.TexNode` object, or any nested data structure:

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

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

### Initialize TexSoup Document

Source: https://texsoup.alvinwan.com/docs/searching.html

Load a LaTeX string into TexSoup for parsing. This is the initial step before performing any search operations.

```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)
```

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

### Get and set string content of TeX elements

Source: https://texsoup.alvinwan.com/docs/_modules/TexSoup/data.html

The `string` property allows you to get or set the textual content of a TeX command or environment, provided it meets specific criteria (single argument for commands, single text child for environments).

```python
>>> soup.textbf.string
'Hello'
>>> soup.textbf.string = 'Hello World'
>>> soup.textbf
\textbf{Hello World}
>>> soup = TexSoup(r'''\begin{equation}1+1\end{equation}''')
>>> soup.equation.string
'1+1'
```

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

### Initialize Buffer with String

Source: https://texsoup.alvinwan.com/docs/_modules/TexSoup/utils.html

Creates a Buffer instance from a string. Supports iteration and navigation.

```python
b1 = Buffer("012345")
next(b1)
```

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

### TexText Initialization

Source: https://texsoup.alvinwan.com/docs/_modules/TexSoup/data.html

Initializes a TexText object with the given text content.

```python
def __init__(self, text):
    super().__init__('text', [text])
    self._text = text
```

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

### Get Item (Access Arguments)

Source: https://texsoup.alvinwan.com/docs/_modules/TexSoup/data.html

Accesses arguments using standard list slicing or direct indexing.

```APIDOC
## __getitem__ (Access)

### Description
Standard list slicing. Returns TexArgs object for subset of list and returns an Arg object for single items.

### Method
__getitem__

### Parameters
#### Key for access
- **key** (int or slice) - Index or slice to access

### Request Example
```python
arguments[2]
arguments[:2]
```

### Response Example
```python
# Returns an Arg object for single item access
# Returns a TexArgs object for slice access
# Example assertions:
# arguments[2] == RArg('arg2')
# arguments[:2] == [RArg('arg0'), OArg('arg1')]
```
```

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

### TexSoup Name Property

Source: https://texsoup.alvinwan.com/docs/data.html

The `name` property gets or sets the name of the expression, used for search functions.

```APIDOC
## NAME PROPERTY

### Description
Name of the expression. Used for search functions.

### Method
`name` (getter/setter)

### Return Type
str

### Request Example
```python
from TexSoup import TexSoup
soup = TexSoup(r'''\textbf{Hello}''')
soup.textbf.name
soup.textbf.name = 'textit'
soup.textit
```

### Response Example
```
'textbf'
\textit{Hello}
```
```

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

### Create and Print a TexCmd Object

Source: https://texsoup.alvinwan.com/docs/_modules/TexSoup/data.html

Demonstrates the creation of a TexCmd object representing a LaTeX command with arguments and its string representation.

```python
textit = TexCmd('textit', args=[RArg('slant')])
t = TexCmd('textbf', args=[RArg('big ', textit, '.')])
print(t)
```

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

### Convert TexSoup object to string

Source: https://texsoup.alvinwan.com/docs/soup.html

Call str() on a TexSoup.data.TexNode object or any nested data structure to get its string representation.

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

```

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

### Create a TexSoup object from a file

Source: https://texsoup.alvinwan.com/docs/soup.html

Pass an open filehandle to the TexSoup constructor to parse a LaTeX document.

```python
>>> from TexSoup import TexSoup
>>> with open("main.tex") as f:
...     soup = TexSoup(f)
>>> soup2 = TexSoup(r'\begin{document}Hello world!\end{document}')

```

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

### Get All Contents of a Node

Source: https://texsoup.alvinwan.com/docs/data.html

The `contents` attribute returns all non-whitespace content within a node, including nested nodes, tokens, and strings.

```python
>>> from TexSoup import TexSoup
>>> soup = TexSoup(r'''\
... \begin{itemize}
...     Random text!
...     \item Hello
... \end{itemize}''')
>>> contents = soup.itemize.contents
>>> contents[0]
'\n    Random text!\n    '
>>> contents[1]
\item Hello
```

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

### Create and Print a TexEnv Object

Source: https://texsoup.alvinwan.com/docs/_modules/TexSoup/data.html

Demonstrates the creation of a TexEnv object representing a LaTeX environment and its string representation.

```python
t = TexEnv('tabular', ['\n0 & 0 & * \\\\
1 & 1 & * \\\\
'],
    [RArg('c | c c')])
print(t)
```

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

### Get and set environment name in TexSoup

Source: https://texsoup.alvinwan.com/docs/soup.html

The .name attribute of an environment can be accessed and modified. Changes are reflected when converting back to LaTeX.

```python
>>> env.name
'itemize'
>>> env.name = 'enumerate'
>>> env
\begin{enumerate}[label=\alph]\item Huehue\end{enumerate}
>>> soup
Haha \begin{enumerate}[label=\alph]\item Huehue\end{enumerate}

```

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

### Get Item from TexArgs

Source: https://texsoup.alvinwan.com/docs/_modules/TexSoup/data.html

Retrieves an item or a slice from the TexArgs list. Returns a TexArgs object for slices and an Arg object for single items.

```python
>>> arguments = TexArgs([RArg('arg0'), '[arg1]', '{arg2}'])
>>> arguments[2]
RArg('arg2')
>>> arguments[:2]
[RArg('arg0'), OArg('arg1')]
```

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

### Creating a TexEnv Instance

Source: https://texsoup.alvinwan.com/docs/data.html

TexEnv represents a LaTeX environment with a name, delimiters, and content. It is initialized with these components and can be printed to show its LaTeX representation.

```python
>>> t = TexEnv('displaymath', r'\[', r'\]',
...     ['\\mathcal{M} \\circ \\mathcal{A}'])
>>> t
TexEnv('displaymath', ['\\mathcal{M} \\circ \\mathcal{A}'], [])
>>> print(t)
\[\mathcal{M} \circ \mathcal{A}\]
>>> len(list(t.children))
0
```

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

### CharToLineOffset Initialization

Source: https://texsoup.alvinwan.com/docs/_modules/TexSoup/utils.html

Initializes CharToLineOffset with source code to map character positions to line and column numbers.

```python
def __init__(self, src):
    self.line_break_positions = [i for i, c in enumerate(src) if c == '\n']
```

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

### Buffer Initialization with Iterator

Source: https://texsoup.alvinwan.com/docs/_modules/TexSoup/utils.html

Initializes a Buffer with an iterator and an optional join function.

```python
def __init__(self, iterator, join=TokenWithPosition.join):
    """Initialization for Buffer

    :param iterator: iterator or iterable
    :param func join: function to join multiple buffer elements
    """
    assert hasattr(iterator, '__iter__'), 'Must be an iterable.'
    self.__iterator = iter(iterator)
    self.__queue = []
    self.__i = 0
    self.__join = join
```

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

### Tokenize LaTeX line comments

Source: https://texsoup.alvinwan.com/docs/tokenizer.html

Use `tokenize_line_comment` to process and extract LaTeX line comments. It handles comments starting with '%' and stops at newline characters.

```python
>>> tokenize_line_comment(categorize(r'%hello world\'))
'%hello world\'
```

```python
>>> tokenize_line_comment(categorize('hello %world'))
```

```python
>>> tokenize_line_comment(categorize('%}hello world'))
'%}hello world'
```

```python
>>> tokenize_line_comment(categorize('%}  '))
'%}  '
```

```python
>>> tokenize_line_comment(categorize('%hello\n world'))
'%hello'
```

```python
>>> b = categorize(r'\\%')
>>> _ = next(b), next(b)
>>> tokenize_line_comment(b)
'%'
```

```python
>>> tokenize_line_comment(categorize(r'\%'))
```

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

### Iterate over TexNode contents

Source: https://texsoup.alvinwan.com/docs/_modules/TexSoup/data.html

Demonstrates how to iterate over the contents of a TexNode.

```python
>>> node = TexNode(TexEnv('lstlisting', ('hai', 'there')))
>>> list(node)
['hai', 'there']
```

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

### Parse LaTeX arguments with read_args

Source: https://texsoup.alvinwan.com/docs/parser.html

Demonstrates parsing various bracket and brace-delimited arguments from a tokenized string.

```python
>>> from TexSoup.category import categorize
>>> from TexSoup.tokens import tokenize
>>> test = lambda s, *a, **k: read_args(tokenize(categorize(s)), *a, **k)
>>> test('[walla]{walla}{ba]ng}')  # 'regular' arg parse
[BracketGroup('walla'), BraceGroup('walla'), BraceGroup('ba', ']', 'ng')]
>>> test('\t[wa]\n{lla}\n\n{b[ing}')  # interspersed spacers + 2 newlines
[BracketGroup('wa'), BraceGroup('lla')]
>>> test('\t[\t{a]}bs', 2, 0)  # use char as arg, since no opt args
[BraceGroup('['), BraceGroup('a', ']')]
>>> test('\n[hue]\t[\t{a]}', 2, 1)  # check stop opt arg capture
[BracketGroup('hue'), BraceGroup('['), BraceGroup('a', ']')]
>>> test('\t\\item')
[]
>>> test('   \t    \n\t \n{bingbang}')
[]
>>> test('[tempt]{ing}[WITCH]{doctorrrr}', 0, 0)
[]
```

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

### Tokenize Line Comments

Source: https://texsoup.alvinwan.com/docs/_modules/TexSoup/reader.html

Identifies and tokenizes line comments, which start with a '%' character not preceded by a backslash. The tokenizer captures text until a newline character or the end of the input.

```python
@token('line_comment')
def tokenize_line_comment(text):
    r"""Process a line comment

    :param Buffer text: iterator over line, with current position

    >>> tokenize_line_comment(Buffer('hello %world'))
    >>> tokenize_line_comment(Buffer('%hello world'))
    '%hello world'
    >>> tokenize_line_comment(Buffer('%hello\n world'))
    '%hello'
    """
    result = TokenWithPosition('', text.position)
    if text.peek() == '%' and text.peek(-1) != '\':
        result += text.forward(1)
        while text.peek() != '\n' and text.hasNext():
            result += text.forward(1)
        return result
```

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

### Get and set command name in TexSoup

Source: https://texsoup.alvinwan.com/docs/soup.html

Access and modify the command's name using the .name attribute. Changes are reflected when converting back to LaTeX.

```python
>>> cmd.name
'textbf'
>>> cmd.name = 'textit'
>>> cmd
\textit{\large Large and bold}
>>> soup
I am \textit{\large Large and bold}

```

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

### Tokenize LaTeX line breaks

Source: https://texsoup.alvinwan.com/docs/tokenizer.html

Use `tokenize_line_break` to extract LaTeX line breaks, specifically sequences starting with '\\'. It distinguishes between line breaks and command names.

```python
>>> tokenize_line_break(categorize(r'\\aaa'))
'\\\\'
```

```python
>>> tokenize_line_break(categorize(r'\aaa'))
```

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

### TexEnv and TexCmd Classes

Source: https://texsoup.alvinwan.com/docs/data.html

Definitions for LaTeX environment and command abstractions.

```APIDOC
## TexEnv
Abstraction for a LaTeX command with starting and ending markers.
- **Attributes**: name, delimiters, contents.

## TexCmd
Abstraction for a LaTeX command.
- **Attributes**: command name, command arguments (optional or required).
```

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

### Modify the name of a LaTeX expression

Source: https://texsoup.alvinwan.com/docs/data.html

The `name` attribute allows you to get or set the name of a LaTeX expression. Changing the name can affect how the node is found in subsequent searches.

```python
>>> from TexSoup import TexSoup
>>> soup = TexSoup(r'''\textbf{Hello}''')
>>> soup.textbf.name
'textbf'
>>> soup.textbf.name = 'textit'
>>> soup.textbf
\textit{Hello}
```

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

### TexNode Class Overview

Source: https://texsoup.alvinwan.com/docs/_modules/TexSoup/data.html

Provides an overview of the TexNode class, its purpose, and initialization.

```APIDOC
## TexNode Class

### Description
A tree node representing an expression in the LaTeX document. Every node in the parse tree is a ``TexNode``, equipped with navigation, search, and modification utilities. To navigate the parse tree, use abstractions such as ``children`` and ``descendant``. To access content in the parse tree, use abstractions such as ``contents``, ``text``, ``string``, and ``args``.

Note that the LaTeX parse tree is largely shallow: only environments such as ``itemize`` or ``enumerate`` have children and thus descendants. Typical LaTeX expressions such as ``\section`` have *arguments* but not children.

### Initialization

#### Constructor
`__init__(self, expr, src=None)`

Creates a TexNode object.

- **expr** (TexExpr) - A LaTeX expression, either a singleton command or an environment containing other commands.
- **src** (str, optional) - LaTeX source string.
```

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

### Match LaTeX expressions

Source: https://texsoup.alvinwan.com/docs/_modules/TexSoup/data.html

Shows how to use the match functionality to count occurrences of specific LaTeX commands.

```python
>>> from TexSoup import TexSoup
>>> soup = TexSoup(r'\ref{hello}\ref{hello}\ref{hello}\ref{nono}')
>>> soup.count(r'\ref{hello}')
3
```

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

### Get the next LaTeX token from a buffer

Source: https://texsoup.alvinwan.com/docs/tokenizer.html

Use `next_token` to retrieve the next token from a LaTeX buffer and advance the iterator. This is useful for sequential parsing of LaTeX input.

```python
>>> b = categorize(r'\textbf{Do play\textit{nice}.}   $$\min_w \|w\|_2^2$$')
>>> print(next_token(b), next_token(b), next_token(b), next_token(b))
\ textbf { Do play
```

```python
>>> print(next_token(b), next_token(b), next_token(b), next_token(b))
\ textit { nice
```

```python
>>> print(next_token(b))
}
```

```python
>>> print(next_token(categorize('.}')))
.
```

```python
>>> next_token(b)
'.'
```

```python
>>> next_token(b)
'}'
```

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

### TexSoup String Property

Source: https://texsoup.alvinwan.com/docs/data.html

The `string` property gets or sets the string content of a Tex expression. This is valid if the expression is a TexCmd with one argument or a TexEnv with one TexText child.

```APIDOC
## STRING PROPERTY

### Description
This is valid if and only if
  1. the expression is a `TexCmd` AND has only one argument OR
  2. the expression is a `TexEnv` AND has only one TexText child

### Method
`string` (getter/setter)

### Return Type
Union[None, str]

### Request Example
```python
from TexSoup import TexSoup
soup = TexSoup(r'''\textbf{Hello}''')
soup.textbf.string
soup.textbf.string = 'Hello World'
soup.textbf.string
soup.textbf

soup = TexSoup(r'''\begin{equation}1+1\end{equation}''')
soup.equation.string
soup.equation.string = '2+2'
soup.equation.string
```

### Response Example
```
'Hello'
'Hello World'
\textbf{Hello World}
'1+1'
'2+2'
```
```

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

### Check Content Support for TexCmd

Source: https://texsoup.alvinwan.com/docs/_modules/TexSoup/data.html

Determines if the command supports children/contents, typically only for '\item'.

```python
def _supports_contents(self):
    return self.name == 'item'
```

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

### Extract All Text from LaTeX Document

Source: https://texsoup.alvinwan.com/docs/_sources/quickstart.rst.txt

Extract all plain text content from the parsed LaTeX document by iterating over `soup.text`. This can be useful for getting the textual content without LaTeX markup.

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

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

### rstrip() - Strip Trailing Whitespace

Source: https://texsoup.alvinwan.com/docs/_modules/TexSoup/utils.html

The `rstrip()` method removes trailing whitespace from the token's text and returns a new `TokenWithPosition` object with the stripped text and its original starting position.

```APIDOC
## rstrip()

### Description
Strips trailing whitespace from the token's text.

### Method
`rstrip(*args, **kwargs)`

### Parameters
- `*args`: Positional arguments to pass to the underlying `str.rstrip()` method.
- `**kwargs`: Keyword arguments to pass to the underlying `str.rstrip()` method.

### Returns
A new `TokenWithPosition` object with trailing whitespace removed and its position unchanged.

### Example
```python
from texsoup import TokenWithPosition

t = TokenWithPosition('  asdf  ', 2)
stripped_token = t.rstrip()
print(stripped_token.text) # Output: '  asdf'
print(stripped_token.position) # Output: 2
```
```

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

### read_args

Source: https://texsoup.alvinwan.com/docs/parser.html

Reads all arguments from a buffer, assuming the command name has already been parsed.

```APIDOC
## read_args

### Description
Reads all arguments from a buffer. By default, LaTeX allows up to 9 arguments of both types. If n_optional or n_required are not set, all valid bracket or brace groups are captured respectively.

### Parameters
- **src** (Buffer) - Required - A buffer of tokens
- **args** (TexArgs) - Optional - Existing arguments to extend
- **n_required** (int) - Optional - Number of required arguments. If < 0, all valid brace groups will be captured.
- **n_optional** (int) - Optional - Number of optional arguments. If < 0, all valid bracket groups will be captured.
- **tolerance** (int) - Optional - Error tolerance level (0 or 1)
- **mode** (str) - Optional - Math or not math mode

### Response
- **Returns** (TexArgs) - The parsed arguments
```

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

### Parse LaTeX String with TexSoup

Source: https://texsoup.alvinwan.com/docs/_sources/quickstart.rst.txt

Initialize TexSoup by passing a LaTeX document as a string to the TexSoup constructor. This creates a navigable soup object.

```python
from TexSoup import TexSoup
soup = TexSoup(tex_doc)
soup
```

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

### lstrip() - Strip Leading Whitespace

Source: https://texsoup.alvinwan.com/docs/_modules/TexSoup/utils.html

The `lstrip()` method removes leading whitespace from the token's text and returns a new `TokenWithPosition` object with the stripped text and its calculated starting position.

```APIDOC
## lstrip()

### Description
Strips leading whitespace from the token's text.

### Method
`lstrip(*args, **kwargs)`

### Parameters
- `*args`: Positional arguments to pass to the underlying `str.lstrip()` method.
- `**kwargs`: Keyword arguments to pass to the underlying `str.lstrip()` method.

### Returns
A new `TokenWithPosition` object with leading whitespace removed and its position adjusted.

### Example
```python
from texsoup import TokenWithPosition

t = TokenWithPosition('  asdf  ', 2)
stripped_token = t.lstrip()
print(stripped_token.text) # Output: 'asdf  '
print(stripped_token.position) # Output: 4
```
```

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

### Get and set TeX expression name

Source: https://texsoup.alvinwan.com/docs/_modules/TexSoup/data.html

The `name` property allows you to retrieve the name of a TeX expression (e.g., command or environment) and also to rename it. This is useful for searching or transforming elements.

```python
>>> soup.textbf.name
'textbf'
>>> soup.textbf.name = 'textit'
>>> soup.textit
\textit{Hello}
```

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

### Creating a TexCmd Instance

Source: https://texsoup.alvinwan.com/docs/data.html

TexCmd represents a LaTeX command with a name and arguments. Arguments can include nested structures like BraceGroups. The command can be printed to show its LaTeX representation.

```python
>>> textit = TexCmd('textit', args=[BraceGroup('slant')])
>>> t = TexCmd('textbf', args=[BraceGroup('big ', textit, '.')])
>>> t
TexCmd('textbf', [BraceGroup('big ', TexCmd('textit', [BraceGroup('slant')]), '.')])
>>> print(t)
\textbf{big \textit{slant}.}
>>> children = list(map(str, t.children))
>>> len(children)
1
>>> print(children[0])
\textit{slant}
```

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

### Get String Value of TexSoup Expression

Source: https://texsoup.alvinwan.com/docs/navigation.html

Extracts the string value from a TexSoup expression that has a single required argument or child. Useful for commands like \textit{} where the content is a simple string.

```python
>>> soup.textit.string
'world'
```

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

### TokenWithPosition Equality Comparison

Source: https://texsoup.alvinwan.com/docs/_modules/TexSoup/utils.html

Demonstrates how equality checks compare the underlying text content while ignoring the position attribute.

```python
>>> TokenWithPosition('asdf', 0) == TokenWithPosition('asdf', 2)
True
>>> TokenWithPosition('asdf', 0) == TokenWithPosition('asd', 0)
False
```

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

### Get and set the string content of a node

Source: https://texsoup.alvinwan.com/docs/data.html

The `string` attribute provides access to the text content of a `TexCmd` with a single argument or a `TexEnv` with a single `TexText` child. It can be used to both retrieve and modify the text.

```python
>>> from TexSoup import TexSoup
>>> soup = TexSoup(r'''\textbf{Hello}''')
>>> soup.textbf.string
'Hello'
>>> soup.textbf.string = 'Hello World'
>>> soup.textbf.string
'Hello World'
>>> soup.textbf
\textbf{Hello World}
>>> soup = TexSoup(r'''\begin{equation}1+1\end{equation}''')
>>> soup.equation.string
'1+1'
>>> soup.equation.string = '2+2'
>>> soup.equation.string
'2+2'
```

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

### read_env

Source: https://texsoup.alvinwan.com/docs/_modules/TexSoup/reader.html

Parses a standard LaTeX environment.

```APIDOC
## read_env

### Description
Reads the environment content from the buffer until the corresponding \end tag is reached.

### Parameters
- **src** (Buffer) - Required - A buffer of tokens.
- **expr** (TexExpr) - Required - The expression for the environment.
- **skip_envs** (tuple) - Optional - Environments to skip during parsing.

### Response
- **TexExpr** - The expression with parsed contents appended.
```

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

### strip() - Strip Leading and Trailing Whitespace

Source: https://texsoup.alvinwan.com/docs/_modules/TexSoup/utils.html

The `strip()` method removes both leading and trailing whitespace from the token's text and returns a new `TokenWithPosition` object with the stripped text and its calculated starting position.

```APIDOC
## strip()

### Description
Strips leading and trailing whitespace from the token's text.

### Method
`strip(*args, **kwargs)`

### Parameters
- `*args`: Positional arguments to pass to the underlying `str.strip()` method.
- `**kwargs`: Keyword arguments to pass to the underlying `str.strip()` method.

### Returns
A new `TokenWithPosition` object with leading and trailing whitespace removed and its position adjusted.

### Example
```python
from texsoup import TokenWithPosition

t = TokenWithPosition('  asdf  ', 2)
stripped_token = t.strip()
print(stripped_token.text) # Output: 'asdf'
print(stripped_token.position) # Output: 4
```
```

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

### Buffer __getitem__ Implementation

Source: https://texsoup.alvinwan.com/docs/_modules/TexSoup/utils.html

Supports indexing and slicing for the Buffer, retrieving elements or substrings.

```python
def __getitem__(self, i):
    """Supports indexing list

    >>> b = Buffer('asdf')
    >>> b[5]
    Traceback (most recent call last):
        ... 
    IndexError: list index out of range
    >>> b[0]
    'a'
    >>> b[1:3]
    'sd'
    >>> b[1:]
    'sdf'
    >>> b[:3]
    'asd'
    >>> b[:]
    'asdf'
    """
    if isinstance(i, int):
        old, j = self.__i, i
    else:
        old, j = self.__i, i.stop

    while j is None or self.__i <= j:
        try:
            next(self)
        except StopIteration:
            break
    self.__i = old
    if isinstance(i, int):
        return self.__queue[i]
    return self.__join(self.__queue[i])
```

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

### Repr for TexText

Source: https://texsoup.alvinwan.com/docs/_modules/TexSoup/data.html

Returns the developer-friendly representation of the TexText object.

```python
def __repr__(self):
    """
    >>> TexText('asdf')
    'asdf'
    """
    return repr(self._text)
```

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

### String Representation of TexCmd

Source: https://texsoup.alvinwan.com/docs/_modules/TexSoup/data.html

Returns the string representation of the TexCmd, including command name, arguments, and contents.

```python
def __str__(self):
    if self._contents:
        return '\\%s%s %s' % (self.name, self.args, ''.join(
            [str(e) for e in self.contents]))
    return '\\%s%s' % (self.name, self.args)
```

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

### Stringifying TexExpr Contents

Source: https://texsoup.alvinwan.com/docs/data.html

The `string` property provides a convenient way to get a string representation of a TexExpr's contents. It can also be used to set the contents, converting the input to a TexText object. Assignment must be of a compatible type.

```python
>>> expr = TexExpr('hello', ['naw'])
>>> expr.string
'naw'
>>> expr.string = 'huehue'
>>> expr.string
<class 'TexSoup.data.TexText'>
>>> str(expr)
"TexExpr('hello', ['huehue'])"
>>> expr.string = 35  
Traceback (most recent call last):
    ...
TypeError: ...
```

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

### Repr for TexCmd

Source: https://texsoup.alvinwan.com/docs/_modules/TexSoup/data.html

Returns the developer-friendly representation of the TexCmd object.

```python
def __repr__(self):
    if not self.args:
        return "TexCmd('%s')" % self.name
    return "TexCmd('%s', %s)" % (self.name, repr(self.args))
```

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

### Modify TexNamedEnv Name

Source: https://texsoup.alvinwan.com/docs/data.html

Shows how to create a TexNamedEnv for an 'equation' environment and then change its name, observing the effect on its string representation.

```python
>>> t = TexNamedEnv('equation', [r'5\sum_{i=0}^n i^2'])
>>> str(t)
'\\begin{equation}5\\sum_{i=0}^n i^2\\end{equation}'
>>> t.name = 'eqn'
>>> str(t)
'\\begin{eqn}5\\sum_{i=0}^n i^2\\end{eqn}'
```

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

### Environment Object

Source: https://texsoup.alvinwan.com/docs/soup.html

Details the different types of environment objects (TexEnv) and their properties like name, arguments, and contents.

```APIDOC
### Environment
Environments, or `TexEnv`, are split into three types:
  1. `TexNamedEnv`: The typical environments you think of, with a begin and an end, such as `\begin{itemize}...\end{itemize}`.
  2. `TexUnNamedEnv`: Special environments such as math `\(...\)`. All math environments fall in this category.
  3. `TexGroup`: Unnamed environments with single-character delimiters, like `{...}`.


You can access environments by name:

```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}
```

Every environment’s name can be accessed and modified using `.name`:

```python
>>> env.name
'itemize'
>>> env.name = 'enumerate'
>>> env
\begin{enumerate}[label=\alph]\item Huehue\end{enumerate}
>>> soup
Haha \begin{enumerate}[label=\alph]\item Huehue\end{enumerate}
```

As with commands, environments store arguments in a list `.args`:

```python
>>> str(env.args)
'[label=\\alph]'
```

Each environment will contain variable amounts of content, accessible via `.contents`:

```python
>>> list(env.contents)
[
  \item Huehue
]
```
```

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

### Access environment by name in TexSoup

Source: https://texsoup.alvinwan.com/docs/soup.html

Environments like \begin{itemize} can be accessed by their name attribute.

```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}

```

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

### TexExpr Initialization

Source: https://texsoup.alvinwan.com/docs/_modules/TexSoup/data.html

The TexExpr class is an abstract base class for TeX commands and environments. It is identified by a name, arguments, and its position in the parse tree. It is not directly instantiated.

```python
class TexExpr(object):
    """General abstraction for a TeX expression.

    An expression may be a command or an environment and is identified by
    a name, arguments, and place in the parse tree. This is an abstract and is
    not directly instantiated.
    """

    def __init__(self, name, contents=(), args=(), preserve_whitespace=False):
        self.name = name.strip()
        self.args = TexArgs(args)
        self.parent = None
        self._contents = list(contents) or []
        self.preserve_whitespace = preserve_whitespace

        for content in contents:
            if isinstance(content, (TexEnv, TexCmd)):
                content.parent = self
```

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

### TokenWithPosition Addition Operations

Source: https://texsoup.alvinwan.com/docs/_modules/TexSoup/utils.html

Shows how addition and concatenation preserve or calculate the position of the resulting TokenWithPosition object.

```python
>>> t1 = TokenWithPosition('as', 0) + TokenWithPosition('df', 1)
>>> str(t1)
'asdf'
>>> t1.position
0
>>> t2 = TokenWithPosition('as', 1) + 'df'
>>> str(t2)
'asdf'
>>> t3 = TokenWithPosition(t2)
>>> t3.position
1
```

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

### TokenWithPosition In-place Addition

Source: https://texsoup.alvinwan.com/docs/_modules/TexSoup/utils.html

Demonstrates the behavior of the += operator on a TokenWithPosition instance.

```python
>>> t1 = TokenWithPosition('as', 0)
>>> t1 += 'df'
>>> str(t1)
'asdf'
>>> t1.position
0
```

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

### Repr for TexEnv

Source: https://texsoup.alvinwan.com/docs/_modules/TexSoup/data.html

Returns the developer-friendly representation of the TexEnv object.

```python
def __repr__(self):
    if not self.args:
        return "TexEnv('%s')" % self.name
    return "TexEnv('%s', %s, %s)" % (self.name, repr(self._contents), repr(self.args))
```

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

### TokenWithPosition Iteration

Source: https://texsoup.alvinwan.com/docs/_modules/TexSoup/utils.html

Demonstrates iterating over a TokenWithPosition object to yield individual characters as new TokenWithPosition instances.

```python
>>> list(TokenWithPosition('asdf', 0))
['a', 's', 'd', 'f']
```

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

### TexNamedEnv

Source: https://texsoup.alvinwan.com/docs/data.html

Represents a LaTeX environment defined by \begin{env} and \end{env}. It stores the environment name, arguments, and content.

```APIDOC
## TexNamedEnv

### Description
Abstraction for a LaTeX command, denoted by `\begin{env}` and `\end{env}`. Contains three attributes: the environment name itself, the environment arguments (optional or required), and the environment’s contents.

**Warning**: Note that _setting_ TexNamedEnv.begin or TexNamedEnv.end has no effect. The begin and end tokens are always constructed from TexNamedEnv.name.

### Usage Examples
```python
>>> from TexSoup.data import TexNamedEnv, BraceGroup
>>> t = TexNamedEnv('tabular', ['\n0 & 0 & * \\\\n1 & 1 & * \\\\
'], [BraceGroup('c | c c')])
>>> t
TexNamedEnv('tabular', ['\n0 & 0 & * \\\\n1 & 1 & * \\\\
'], [BraceGroup('c | c c')])
>>> print(t)
\begin{tabular}{c | c c}
0 & 0 & * \\
1 & 1 & * \\
\end{tabular}
>>> len(list(t.children))
0
>>> t = TexNamedEnv('equation', [r'5\sum_{i=0}^n i^2'])
>>> str(t)
'\\begin{equation}5\\sum_{i=0}^n i^2\\end{equation}'
>>> t.name = 'eqn'
>>> str(t)
'\\begin{eqn}5\\sum_{i=0}^n i^2\\end{eqn}'
```
```

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

### Tokenize Singletone Symbols

Source: https://texsoup.alvinwan.com/docs/tokenizer.html

Processes singletone symbols as standalone tokens. Requires the 'tokenize' and 'categorize' functions.

```python
>>> next(tokenize(categorize(r'\begin turing')))
'\\'
>>> next(tokenize(categorize(r'\bf  {turing}')))
'\\'
>>> next(tokenize(categorize(r'{]}'))).category
<TokenCode.GroupBegin: 23>
```

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

### Other Environment Types

Source: https://texsoup.alvinwan.com/docs/data.html

Includes other environment types like TexUnNamedEnv, TexMathEnv, TexDisplayMathEnv, TexMathModeEnv, and TexDisplayMathModeEnv.

```APIDOC
## Other Environment Types

### Description
TexSoup provides abstractions for various LaTeX environment types:

- `TexUnNamedEnv`: Represents unnamed environments.
- `TexMathEnv`: Represents math environments.
- `TexDisplayMathEnv`: Represents display math environments.
- `TexMathModeEnv`: Represents math mode environments.
- `TexDisplayMathModeEnv`: Represents display math mode environments.

(Note: Specific usage examples for these are not provided in the source text.)
```

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

### TokenWithPosition Indexing

Source: https://texsoup.alvinwan.com/docs/_modules/TexSoup/utils.html

Shows how to access characters or slices while maintaining the correct position offset.

```python
>>> t1 = TokenWithPosition('asdf', 2)
>>> t1[0]
'a'
>>> t1[-1]
'f'
>>> t1[:]
'asdf'
```

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

### TexNode Methods

Source: https://texsoup.alvinwan.com/docs/data.html

Overview of common methods available on a TexNode object for tree manipulation and navigation.

```APIDOC
## append(nodes)

### Description
Add node(s) to this node’s list of children.

### Parameters
#### Request Body
- **nodes** (TexNode) - Required - List of nodes to add

## char_pos_to_line(char_pos)

### Description
Map position in the original string to parsed LaTeX position.

### Parameters
#### Query Parameters
- **char_pos** (int) - Required - Character position in the original string

### Response
#### Success Response (200)
- **result** (Tuple[int, int]) - (line number, index of character in line)

## count(name=None, **attrs)

### Description
Number of descendants matching criteria.

### Parameters
#### Query Parameters
- **name** (Union[None, str]) - Optional - Name of LaTeX expression
- **attrs** (dict) - Optional - LaTeX expression attributes

### Response
#### Success Response (200)
- **count** (int) - Number of matching expressions

## delete()

### Description
Delete this node from the parse tree. Where applicable, this will remove all descendants of this node from the parse tree.

## find(name=None, **attrs)

### Description
First descendant node matching criteria. Returns None if no descendant node found.

### Parameters
#### Query Parameters
- **name** (Union[None, str]) - Optional - Name of LaTeX expression
- **attrs** (dict) - Optional - LaTeX expression attributes

### Response
#### Success Response (200)
- **node** (TexNode) - Descendant node matching criteria
```

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

### Object Representation

Source: https://texsoup.alvinwan.com/docs/_modules/TexSoup/data.html

Provides a command-line friendly representation of the arguments list.

```APIDOC
## __repr__ (Representation)

### Description
Makes list of arguments command-line friendly.

### Method
__repr__

### Parameters
None

### Request Example
```python
TexArgs(['{a}', '[b]', '{c}'])
```

### Response Example
```python
# Returns a string representation suitable for debugging or command line.
# Example assertion:
# TexArgs(['{a}', '[b]', '{c}']) == '[RArg(\'a\'), OArg(\'b\'), RArg(\'c\')]'
```
```

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

### Command Object

Source: https://texsoup.alvinwan.com/docs/soup.html

Explains the structure and manipulation of command objects (TexCmd) within TexSoup.

```APIDOC
### Command
A `TexCmd` corresponds to a command in the original document:

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

You can access the underlying data structures using `.expr`:

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

Every command has a name:

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

You can change the command’s name too. This change will be reflected when you convert the TexSoup back to LaTeX:

```python
>>> cmd.name = 'textit'
>>> cmd
\textit{\large Large and bold}
>>> soup
I am \textit{\large Large and bold}
```

Commands may have any number of arguments, stored in `.args` as a list. Our command has just one argument:

```python
>>> len(cmd.args)
1
>>> str(cmd.args[0])
'{\\large Large and bold}'
```

You can add, remove, and modify arguments, treating `.args` as a list:

```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}'
```

All arguments are represented using TexSoup’s underlying data structures:

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

The above commands all apply to optional arguments as well. Note that all changes are reflected when we convert the soup back to LaTeX:

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

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

### TexEnv Class

Source: https://texsoup.alvinwan.com/docs/_modules/TexSoup/data.html

Represents a LaTeX environment like \begin{env} ... \end{env}.

```APIDOC
## TexEnv Class

### Description
Abstraction for a LaTeX command, denoted by `\begin{env}` and `\end{env}`. Contains three attributes: the environment name, its arguments, and its contents.

### Initialization
```python
def __init__(self, name, contents=(), args=(), preserve_whitespace=False, nobegin=False, begin=False, end=False):
    """Initialization for Tex environment.

    :param str name: name of environment
    :param iterable contents: list of contents
    :param iterable args: list of Tex Arguments
    :param bool preserve_whitespace: If false, elements containing only whitespace will be removed from contents.
    :param bool nobegin: Disable \begin{...} notation.
    """
```

### Methods
#### `__match__(self, name=None, attrs=())`
Check if given attributes match environment.

#### `__str__(self)`
Returns the string representation of the environment.

#### `__repr__(self)`
Returns the developer representation of the environment.
```