Ki#ydZddlZejjdkr dZeZdZdZne ZdZdZd d l m Z m Z m Z mZGd d eZGd deZGddeZdZdZdZGddeZdS)a" Provides classes and helper functions to describe a LaTeX context of known macros and environments, specifying how they should be parsed by :py:mod:`pylatexenc.latexwalker`. .. versionadded:: 2.0 The entire module :py:mod:`pylatexenc.macrospec` was introduced in `pylatexenc 2.0`. Nc|SN)ss u/var/www/development/aibuddy-work/election-extract/venv/lib/python3.11/site-packages/pylatexenc/macrospec/__init__.pyunicoder +s1Hc|Srrxs rr-!r c|Srrr s rrr.rr cFt|dSNzutf-8)r encoder s rrr2s'!**"3"3G"<"<r c,|dSr)decoder s rrr3s!((7"3"3r )ParsedMacroArgsMacroStandardArgsParserParsedVerbatimArgsVerbatimArgsParsercBeZdZdZeffd ZdZdZxZS) MacroSpeca Stores the specification of a macro. This stores the macro name and instructions on how to parse the macro arguments. .. py:attribute:: macroname The name of the macro, without the leading backslash. .. py:attribute:: args_parser The parser instance that can understand this macro's arguments. For standard LaTeX macros this is usually a :py:class:`MacroStandardArgsParser` instance. If you specify a string, then for convenience this is interpreted as an argspec argument for :py:class:`MacroStandardArgsParser` and such an instance is automatically created. c tt|jdi|||_t |t rt ||_dS||_dSNr)superr__init__ macroname isinstance _basestringr args_parser)selfr!r$kwargs __class__s rr zMacroSpec.__init__Rsc'i'11&111" k; / / +6{CCD   *D   r c&|jj|i|Sz Shorthand for calling the :py:attr:`args_parser`\ 's `parse_args()` method. See :py:class:`MacroStandardArgsParser`. r$ parse_argsr%argsr&s rr+zMacroSpec.parse_argsZ +t*D;F;;;r c(d|jd|jdS)NzMacroSpec(macroname=, args_parser=))r!r$r%s r__repr__zMacroSpec.__repr__as:>...$JZJZJZ[[r __name__ __module__ __qualname____doc__rr r+r3 __classcell__r's@rrr=s{(/F.E.G.G++++++<<<\\\\\\\r rcDeZdZdZedffd ZdZdZxZS)EnvironmentSpecaP Stores the specification of a LaTeX environment. This stores the environment name and instructions on how to parse any arguments provided after ``\begin{environment}``. .. py:attribute:: environmentname The name of the environment, i.e., the argument of ``\begin{...}`` and ``\end{...}``. .. py:attribute:: args_parser The parser instance that can understand this environment's arguments. For standard LaTeX environment this is usually a :py:class:`MacroStandardArgsParser` instance. If you specify a string, then for convenience this is interpreted as an argspec argument for :py:class:`MacroStandardArgsParser` and such an instance is automatically created. .. py:attribute:: is_math_mode A boolean that indicates whether or not the contents is to be interpreted in Math Mode. This would be True for environments like ``\begin{equation}``, ``\begin{align}``, etc., but False for ``\begin{figure}``, etc. .. note:: Starred variants of environments (as in ``\begin{equation*}``) must not be specified using an argspec as for macros (e.g., `argspec='*'`). Rather, we need to define a separate environment spec for the starred variant with the star in the name itself (``EnvironmentSpec('equation*', None)``) because the star really is part of the environment name. If you happened to use ``EnvironmentSpec('equation', '*')``, then the parser would recognize the expression ``\begin{equation}*`` but not ``\begin{equation*}``. Fc tt|jdi|||_t |t rt ||_n||_||_dSr) rr<r environmentnamer"r#rr$ is_math_mode)r%r>r$r?r&r's rr zEnvironmentSpec.__init__si-ot$$-77777. k; / / +6{CCD  *D (r c&|jj|i|Sr)r*r,s rr+zEnvironmentSpec.parse_argsr.r c8d|jd|jd|jdS)Nz EnvironmentSpec(environmentname=r0z, is_math_mode=r1)r>r$r?r2s rr3zEnvironmentSpec.__repr__s0  $"2"2"2D4E4E4E  r r4r:s@rr<r<fsx&&N5L4K4M4M#))))))<<<       r r<c2eZdZdZ dfd ZdZdZxZS) SpecialsSpecas Specification of a LaTeX "special char sequence": an active char, a ligature, or some other non-macro char sequence that has a special meaning. For instance, '&', '~', and '``' are considered as "specials". .. py:attribute:: specials_chars The string (one or several characters) that has a special meaning. E.g., '&', '~', '``', etc. .. py:attribute:: args_parser A parser (e.g. :py:class:`MacroStandardArgsParser`) that is invoked when the specials is encountered. Can/should be set to `None` if the specials should not parse any arguments (e.g. '~'). Nc dtt|jdi|||_||_dSr)rrCr specials_charsr$)r%rEr$r&r's rr zSpecialsSpec.__init__s> +lD!!*44V444,&r c8|jdS|jj|i|S)a Basically a shorthand for calling the :py:attr:`args_parser`\ 's `parse_args()` method. See :py:class:`MacroStandardArgsParser`. If however the py:attr:`args_parser` attribute is `None`, then this method returns `None`. Nr*r,s rr+zSpecialsSpec.parse_argss-   #4*t*D;F;;;r c(d|jd|jdS)NzSpecialsSpec(specials_chars=r0r1)rEr$r2s rr3zSpecialsSpec.__repr__s%    !1!1!1  r r)r5r6r7r8r r+r3r9r:s@rrCrCsj$"'''''' < < <       r rCct|trAt|dkrtdt|dd}|d}t|tr$t|dkrtd|St|t r$t|dkrtd|St|dkr |d}n|t|dkr#td|||ds$t|dtr |d}nd }|drd }|d |dzz }|d d r3t |t||dd St |t|S)a Return a macro specification for the given macro. Syntax:: spec = std_macro(macname, argspec) # or spec = std_macro(macname, optarg, numargs) # or spec = std_macro( (macname, argspec), ) # or spec = std_macro( (macname, optarg, numargs), ) # or spec = std_macro( spec ) # spec is already a `MacroSpec` -- no-op - `macname` is the name of the macro, without the leading backslash. - `argspec` is a string either characters "\*", "{" or "[", in which star indicates an optional asterisk character (e.g. starred macro variants), each curly brace specifies a mandatory argument and each square bracket specifies an optional argument in square brackets. For example, "{{\*[{" expects two mandatory arguments, then an optional star, an optional argument in square brackets, and then another mandatory argument. `argspec` may also be `None`, which is the same as ``argspec=''``. - `optarg` may be one of `True`, `False`, or `None`, corresponding to these possibilities: + if `True`, the macro expects as first argument an optional argument in square brackets. Then, `numargs` specifies the number of additional mandatory arguments to the command, given in usual curly braces (or simply as one TeX token like a single macro) + if `False`, the macro only expects a number of mandatory arguments given by `numargs`. The mandatory arguments are given in usual curly braces (or simply as one TeX token like a single macro) + if `None`, then `numargs` is a string like `argspec` above. I.e., ``std_macro(macname, None, argspec)`` is the same as ``std_macro(macname, argspec)``. - `numargs`: depends on `optarg`, see above. To make environment specifications (:py:class:`EnvironmentSpec`) instead of a macro specification, use the function :py:func:`std_environment()` instead. The helper function :py:func:`std_environment()` is a shorthand for calling this function with additional keyword arguments. An optional keyword argument `make_environment_spec=True` to the present function may be specified to return an `EnvironmentSpec` instead of a `MacroSpec`. In this case, you can further specify the `environment_is_math_mode=True|False` to specify whether of not the environment represents a math mode. rz=No positional arguments expected if first argument is a tuplerNzANo positional arguments expected if first argument is a MacroSpeczGNo positional arguments expected if first argument is a EnvironmentSpecrz@Wrong number of arguments for std_macro, macname={!r}, args={!r}[{make_environment_specFenvironment_is_math_mode)r$r?r$) r"tuplelen TypeErrorrr<formatr#getr)macnamer-r&argspecs r std_macrorVsn'5!! t99>>[\\ \WQRR[!!!*'9%% t99>>_`` `'?++ t99>>eff f 4yyA~~q' Ta N U U   !WDG[99q' 7 G3tAw; zz)511[w4KG4T4T,2JJ7QSX,Y,Y[[[ [ W*A'*J*J K K KKr c|dd}t|}|d|t|g|Ri|S)a Return an environment specification for the given environment. Syntax:: spec = std_environment(envname, argspec, is_math_mode=True|False) # or spec = std_environment(envname, optarg, numargs, is_math_mode=True|False) # or spec = std_environment( (envname, argspec), is_math_mode=True|False) # or spec = std_environment( (envname, optarg, numargs), is_math_mode=True|False) # or spec = std_environment( spec ) # spec is already a `EnvironmentSpec` -- no-op - `envname` is the name of the environment, i.e., the argument to ``\begin{...}``. - `argspec` is a string either characters "\*", "{" or "[", in which star indicates an optional asterisk character (e.g. starred environment variants), each curly brace specifies a mandatory argument and each square bracket specifies an optional argument in square brackets. For example, "{{\*[{" expects two mandatory arguments, then an optional star, an optional argument in square brackets, and then another mandatory argument. `argspec` may also be `None`, which is the same as ``argspec=''``. .. note:: See :py:class:`EnvironmentSpec` for an important remark about starred variants for environments. TL;DR: a starred verison of an environment is defined as a separate `EnvironmentSpec` with the star in the name and *not* using an ``argspec='*'``. - `optarg` may be one of `True`, `False`, or `None`, corresponding to these possibilities: + if `True`, the environment expects as first argument an optional argument in square brackets. Then, `numargs` specifies the number of additional mandatory arguments to the command, given in usual curly braces (or simply as one TeX token like a single environment) + if `False`, the environment only expects a number of mandatory arguments given by `numargs`. The mandatory arguments are given in usual curly braces (or simply as one TeX token like a single environment) + if `None`, then `numargs` is a string like `argspec` above. I.e., ``std_environment(envname, None, argspec)`` is the same as ``std_environment(envname, argspec)``. - `numargs`: depends on `optarg`, see above. - `is_math_mode`: if set to True, then the environment represents a math mode environment (e.g., 'equation', 'align', 'gather', etc.), i.e., whose contents should be parsed in an appropriate math mode. Note that `is_math_mode` *must* be given as a keyword argument, in contrast to all other arguments which must be positional (non-keyword) arguments. r?FT)rLrM)popdictupdaterV)envnamer-r&r?kwargs2s rstd_environmentr]2sar::ne44L6llG NN,8::: W /t / / /w / //r c$t|dS)a Return a latex specials specification for the given character sequence. Syntax:: spec = std_specials(specials_chars) where `specials_chars` is the sequence of characters that has a special LaTeX meaning, e.g. ``&`` or ``''``. This helper function only allows to create specs for simple specials without any argument parsing. For more complicated specials, you can instantiate a :py:class:`SpecialsSpec` directly. NrN)rCrEs r std_specialsr`rs D 9 9 99r ceZdZdZfdZgggdddfdZdZdZdZd Z d Z d Z d Z dd Z ddZddZddZgggfdZxZS)LatexContextDba Store a database of specifications of known macros, environments, and other latex specials. This might be, e.g., how many arguments a macro accepts, or how to determine the text representation of a macro or environment. When used with :py:class:`pylatexenc.latexwalker.LatexWalker`, the specifications describe mostly rules for parsing arguments of macros and environments, and which sequences of characters to consider as "latex specials". Specifications for macros, environments, and other specials are stored as :py:class:`MacroSpec`, :py:class:`EnvironmentSpec`, and :py:class:`SpecialsSpec` instances, respectively. When used with :py:class:`pylatexenc.latex2text.LatexNodes2Text`, the specifications for macros, environments, and other specials are stored as :py:class:`pylatexenc.latex2text.MacroTextSpec` , :py:class:`pylatexenc.latex2text.EnvironmentTextSpec`, and :py:class:`pylatexenc.latex2text.SpecialsTextSpec` instances, respectively. In fact, the objects stored in this database may be of any type, except that macro specifications must have an attribute `macroname`, environment specifications must have an attribute `environmentname`, and specials specification must have an attribute `specials_chars`. The `LatexContextDb` instance is meant to be (pseudo-)immutable. Once constructed and all the definitions added with :py:meth:`add_context_category()`, one should refrain from modifying it directly after providing it to, e.g., a :py:class:`~pylatexenc.latexwalker.LatexWalker` object. The reason is that the latex walker keeps track of what the latex context was when parsing nodes, and modifying the context will modify that stored information, too. Instead of being tempted to modify the object, create a new one with :py:meth:`filter_context()`. See :py:func:`pylatexenc.latexwalker.get_default_latex_context_db()` for the default latex context for `latexwalker` with a default collection of known latex macros and environments. See :py:func:`pylatexenc.latex2text.get_default_latex_context_db()` for the default latex context for `latex2text` with a set of text replacements for a collection of known macros and environments. c tt|jdi|g|_i|_d|_d|_d|_dSr)rrbr category_listdunknown_macro_specunknown_environment_specunknown_specials_spec)r%r&r's rr zLatexContextDb.__init__sS,nd##,66v666"&(,%%)"""r FNc ||jvr"td|td|||fDdkrt d|r|jd|n|rB||jvr|j|}nd}|j||ns|rW||jvr|j|dz}nt|j}|j||n|j|td|Dtd|Dtd|Dd |j |<d S) a Register a category of macro and environment specifications in the context database. The category name `category` must not already exist in the database. The argument `macros` is an iterable (e.g., a list) of macro specification objects. The argument `environments` is an iterable (e.g., a list) of environment spec objects. Similarly, the `specials` argument is an iterable of latex specials spec instances. If you specify `prepend=True`, then macro and environment lookups will prioritize this category over other categories. Categories are normally searched for in the order they are registered to the database; if you specify `prepend=True`, then the new category is prepended to the existing list so that it is searched first. If `insert_before` is not `None`, then it must be a string; the definitions are inserted in the category list immediately before the given category name, or at the beginning of the list if the given category doesn't exist. If `insert_after` is not `None`, then it must be a string; the definitions are inserted in the category list immediately after the given category name, or at the end of the list if the given category doesn't exist. You may only specify one of `prepend=True`, `insert_before='...'` or `insert_after='...'`. z9Category {} is already registered in the context databasecg|]}||Srr).0r s r z7LatexContextDb.add_context_category..sIIIqaIIIIr rzgadd_context_category(): You may only specify one of prepend=True, insert_before=... or insert_after=...rc3(K|] }|j|fVdSr)r!)rkms r z6LatexContextDb.add_context_category..s)>>Q[!,>>>>>>r c3(K|] }|j|fVdSr)r>)rkes rroz6LatexContextDb.add_context_category..s* P PQ1#4a"8 P P P P P Pr c3(K|] }|j|fVdSrr_)rkrs rroz6LatexContextDb.add_context_category..s*GGq/3GGGGGGr macros environmentsspecialsN) rd ValueErrorrRrPrQinsertindexappendrYre) r%categoryrtrurvprepend insert_before insert_afteris radd_context_categoryz#LatexContextDb.add_context_categorys> t) ) )X$fX..00 0 IIWm\BIII J JQ N NRSS S  0   % %a 2 2 2 2  0 222&,,];;   % %a 2 2 2 2  0t111&,,\::Q>*++   % %a 2 2 2 2   % %h / / />>f>>>>> P P, P P PPPGGXGGGGG  xr c||_dS)zj Set the macro spec to use when encountering a macro that is not in the database. N)rf)r% macrospecs rset_unknown_macro_specz%LatexContextDb.set_unknown_macro_specs #,r c||_dS)z| Set the environment spec to use when encountering a LaTeX environment that is not in the database. N)rg)r%environmentspecs rset_unknown_environment_specz+LatexContextDb.set_unknown_environment_specs )8%%%r c||_dS)z Set the latex specials spec to use when encountering a LaTeX environment that is not in the database. N)rh)r% specialsspecs rset_unknown_specials_specz(LatexContextDb.set_unknown_specials_spec s &2"""r c*t|jS)zt Return a list of valid category names that are registered in the current database context. )listrdr2s r categorieszLatexContextDb.categoriess D&'''r c|jD]2}||j|dvr|j|d|cS3|jS)a Look up a macro specification by macro name. The macro name is searched for in all categories one by one and the first match is returned. Returns a macro spec instance that matches the given `macroname`. If the macro name was not found, we return the default macro specification set by :py:meth:`set_unknown_macro_spec()` or `None` if no such spec was set. rt)rdrerf)r%r!cats rget_macro_speczLatexContextDb.get_macro_specsV% 8 8CDF3K111vc{8,Y77772&&r c|jD]2}||j|dvr|j|d|cS3|jS)a Look up an environment specification by environment name. The environment name is searched for in all categories one by one and the first match is returned. Returns the environment spec. If the environment name was not found, we return the default environment specification set by :py:meth:`set_unknown_environment_spec()` or `None` if no such spec was set. ru)rdrerg)r%r>rs rget_environment_specz#LatexContextDb.get_environment_spec'sX% D DC$&+n"===vc{>2?CCCC>,,r c|jD]2}||j|dvr|j|d|cS3|jS)a Look up a "latex specials" specification by character sequence. The sequence name is searched for in all categories one by one and the first match is returned. If you are parsing a chunk of LaTeX code, you should use :py:meth:`test_for_specials()` instead. Unlike :py:meth:`test_for_specials()`, :py:meth:`get_specials_spec()` returns the first match regardless of matched length. [Rationale: we only need to worry about matching the longest specials sequence when parsing LaTeX code. Calling `get_specials_spec()` means one has already parsed the sequence and one is looking up additional specs on it.] Returns the specials spec. If the latex specials was not found, we return the default latex specials specification set by :py:meth:`set_unknown_specials_spec()` or `None` if no such spec was set. rv)rdrerh)r%rErs rget_specials_specz LatexContextDb.get_specials_spec8sV&% ? ?CZ!888vc{:.~>>>>9))r cd}d}|jD]{}|j|dD]S}t||kr>|||r(|j|d|}t|}T||S)a Test the given position in the string for any LaTeX specials. The lookup proceeds by searching for in all categories one by one and the first match is returned, except that the longest match accross all categories is returned. For instance, a match of '``' in a later category will take precedence over a match of '`' in a earlier-searched category. Returns a specials spec instance, or `None` if no specials are detected at the position `pos`. rNrv)rdrekeysrP startswith)r%rpos parsing_statebest_match_len best_match_srrEs rtest_for_specialsz LatexContextDb.test_for_specialsQs % 9 9C"&&+j"9">">"@"@ 9 9~&&77ALLY\<]<]7#'6#;z#:>#JL%(%8%8N 9 r c#K||j}|D]_}||jvr(td||j|j|dD]}|V`dS)a Yield the macro specs corresponding to all macros in the given categories. If `categories` is `None`, then the known macro specs from all categories are provided in one long iterable sequence. Otherwise, `categories` should be a list or iterable of category names (e.g., 'latex-base') of macro specs to return. The macro specs from the different categories specified are concatenated into one long sequence which is yielded spec by spec. NzAInvalid latex macro spec db category: {!r} (Expected one of {!r})rtrdrwrRrevaluesr%rcspecs riter_macro_specszLatexContextDb.iter_macro_specsgs  +J  A*** !d"(&D,>"?"?AAAq (+2244       r c#K||j}|D]_}||jvr(td||j|j|dD]}|V`dS)a  Yield the environment specs corresponding to all environments in the given categories. If `categories` is `None`, then the known environment specs from all categories are provided in one long iterable sequence. Otherwise, `categories` should be a list or iterable of category names (e.g., 'latex-base') of environment specs to return. The environment specs from the different categories specified are concatenated into one long sequence which is yielded spec by spec. NGInvalid latex environment spec db category: {!r} (Expected one of {!r})rurrs riter_environment_specsz%LatexContextDb.iter_environment_specs~s  +J  A*** ]VAt122q .188::       r c#K||j}|D]_}||jvr(td||j|j|dD]}|V`dS)a Yield the specials specs corresponding to all environments in the given categories. If `categories` is `None`, then the known specials specs from all categories are provided in one long iterable sequence. Otherwise, `categories` should be a list or iterable of category names (e.g., 'latex-base') of specials specs to return. The specials specs from the different categories specified are concatenated into one long sequence which is yielded spec by spec. Nrrvrrs riter_specials_specsz"LatexContextDb.iter_specials_specss  +J  A*** !j"(&D,>"?"?AAAq *-4466       r ct}|j|_|j|_|j|_| pd|v}| pd|v}| pd|v}|jD]}|r||vr |r||vr|||r%|j|dng|r%|j|dng|r%|j|dng|S)a Return a new :py:class:`LatexContextDb` instance where we only keep certain categories of macro and environment specifications. If `keep_categories` is set to a nonempty list, then the returned context will not contain any definitions that do not correspond to the specified categories. If `exclude_categories` is set to a nonempty list, then the returned context will not contain any definitions that correspond to the specified categories. It is explicitly fine to have category names in `keep_categories` and `exclude_categories` that don't exist in the present object (cf. :py:meth:`categories()`). The argument `keep_which`, if non-empty, specifies which definitions to keep. It should be a subset of the list ['macros', 'environments', 'specials']. The returned context will make a copy of the dictionaries that store the macro and environment specifications, but the specification classes (and corresponding argument parsers) might correspond to the same instances. I.e., the returned context is not a full deep copy. rtrurvrs)rbrfrgrhrdrrer) r%keep_categoriesexclude_categories keep_which new_context keep_macroskeep_environments keep_specialsrs rfilter_contextzLatexContextDb.filter_contexts>8%&& )-)@ &/3/L ,,0,F )$n>J(> *NJn .J&B* *B %  C 3o#=#=! c-?&?&?  , ,9DLtvc{8,33555"EV^TVC[8??AAA\^=JRZ077999PR -    r r)r5r6r7r8r rrrrrrrrrrrrrr9r:s@rrbrbs@&&N*****57RRT%*$T= = = = ~,,,888222(((''' ---"***2,.42.0B"$44444444r rb)r8sys version_infomajorr strr#_str_from_unicode_unicode_from_str basestring _argparsersrrrrobjectrr<rCrVr]r`rbrr rrs4   AK# # K<<33 ++++++++++++ %\%\%\%\%\%\%\%\R< < < < < f< < < @( ( ( ( ( 6( ( ( \[L[L[L|=0=0=0@ : : :.\\\\\V\\\\\r