repository·master·Indexed 43 days ago
https://github.com/alvinwan/texsoupA fault-tolerant Python 3 package for searching, navigating, and modifying LaTeX documents by treating them as a searchable tree structure. Similar to BeautifulSoup, it parses LaTeX source code into a navigable hierarchy of TexNode objects, including TexCmd, TexEnv, and TexGroup, allowing for programmatic data extraction, format conversion, and document manipulation even with invalid LaTeX sources.
TexSoup provides several ways to view the contents of an environment or command. Use these attributes depending on whether you need to reconstruct the source exactly or just extract text.
| Attribute | Description |
|---|---|
.children | Nested Tex expressions. Does not include floating text. |
.contents | Nested Tex expressions and text. Does not contain whitespace-only text. |
.expr.all | All information needed to reconstruct the original source (includes all whitespace). |
.descendants | Tex expressions nested inside of other Tex expressions. |
.text | Returns text from all descendants, stripping all Tex expressions (useful for "detexing"). |
.string | If a command has exactly one required argument (or an environment has one child), this returns that argument as a string. |
Warning: Modifying the .contents list in-place will not affect the actual environment structure.
from TexSoup import TexSoup
tex_doc = """
\begin{document}
\section{Hello \textit{world}.}
\end{document}
"""
soup = TexSoup(tex_doc)
# Access the string argument of \textit
print(soup.textit.string) # Output: 'world'
# Access all text without LaTeX commands
print(soup.text) # Output: 'Hello world.'TexSoup powers several specialized conversion tools:
tex2py): Uses TexSoup to convert $\LaTeX$ into a document tree, organizing content based on a default or custom hierarchy.TexSoup.data. The core building blocks are TexNode objects, which can represent various LaTeX elements such as commands, environments, groups, and raw text. This tree structure allows for programmatic traversal and manipulation of LaTeX source code.TexSoup can be used for a variety of $\LaTeX$ processing tasks, ranging from simple reference counting to complex document conversions. Key practical applications include:
Detailed implementation scripts for these use cases are available in the examples/ directory of the repository.
To install from the source repository, clone the repository and use pip install . from within the directory.
$ git clone https://github.com/alvinwan/TexSoup.git
$ cd TexSoup
$ pip install .You can install the TexSoup package directly from PyPi using pip.
$ pip install texsoupEnvironments can be modified using text-based or list-based operations:
verbatim or math environments like \text{...}), use the .string attribute to replace the content.itemize), you can treat the environment's contents as a list. Use methods like .append(), .remove(), .insert(), and .extend() to add or remove elements (e.g., removing an \item and then re-inserting it elsewhere).>>> soup = TexSoup(r'\begin{verbatim}Huehue\end{verbatim}')
>>> soup.verbatim.string = 'HUEHUE'
>>> soup
\begin{verbatim}HUEHUE\end{verbatim}
>>> soup = TexSoup(r'$$\text{math}$$')
>>> soup.text.string = ''
>>> from TexSoup import TexSoup
>>> soup = TexSoup(r'''
... \begin{itemize}
... \item Hello
... \item Bye
... \end{itemize}''')
>>> tmp = soup.item
>>> soup.itemize.remove(soup.item)
>>> soup.itemize
\begin{itemize}
\item Bye
\end{itemize}
>>> soup.insert(1, tmp)
>>> soup
\begin{itemize}
\item Hello
\item Bye
\end{itemize}To find the expression that contains the current one, use the .parent attribute.
from TexSoup import TexSoup
tex_doc = """
\begin{document}
\section{Hello \textit{world}.}
\end{document}
"""
soup = TexSoup(tex_doc)
# Find the parent of the \textit command
print(soup.textit.parent) # Output: \section{Hello \textit{world}.}TexSoup provides utilities for searching specific patterns and extracting content:
.count(pattern) to find how many times a specific command or pattern appears..find_all(pattern) to locate commands. For example, to find references, search for the \ref{label} pattern.soup.char_pos_to_line(cmd.position) to convert a command's character position into a (line, column) tuple..text attribute to get a list of all text segments within the document, effectively stripping LaTeX commands.# Count and find references
count = soup.count(r'\ref{table:synonyms}')
for cmd in soup.find_all(r'\ref{table:synonyms}'):
print(soup.char_pos_to_line(cmd.position))
# Extract all text
all_text = list(soup.text)To parse a LaTeX document, pass the LaTeX string to the TexSoup constructor. This converts the string into a nested data structure that can be navigated and queried.
from TexSoup import TexSoup
tex_doc = """
\begin{document}
\section{Hello \textit{world}.}
\end{document}
"""
soup = TexSoup(tex_doc)To parse a $\LaTeX$ document, you can pass an open filehandle or a raw string into the TexSoup constructor. If you only want to compute the data structure without the full soup object, use the read function.
To handle $\LaTeX$ documents with syntax errors, use the tolerance parameter in the TexSoup constructor. Setting tolerance=1 allows TexSoup to make a best-effort guess to parse the content despite errors.
from TexSoup import TexSoup, read
# From a filehandle
with open("main.tex") as f:
soup = TexSoup(f)
# From a string
soup2 = TexSoup(r'\begin{document}Hello world!\end{document}')
# Compute data structure only
soup3, _ = read(r'\begin{document}Hello world!\end{document}')
# With error tolerance
soup4 = TexSoup(r'\begin{itemize}\item hullo\end{enumerate}', tolerance=1)