macrospec — Specifying definitions for the parser¶

Provides classes and helper functions to describe a LaTeX context of known macros and environments, specifying how they should be parsed by pylatexenc.latexwalker.

New in version 2.0: The entire module pylatexenc.macrospec was introduced in pylatexenc 2.0.

Macro and environment definitions ¶

class pylatexenc.macrospec.MacroSpec(macroname, arguments_spec_list=None, **kwargs)¶

Stores the specification of a macro.

This stores the macro name and instructions on how to parse the macro arguments.

macroname¶: The name of the macro, without the leading backslash.

args_parser¶

The parser instance that can understand this macro’s arguments. For standard LaTeX macros this is usually a MacroStandardArgsParser instance.

If you specify a string, then for convenience this is interpreted as an argspec argument for MacroStandardArgsParser and such an instance is automatically created.

Deprecated since version 3.0: The args_parser attribute is deprecated since pylatexenc 3.0. Macro, environment, and specials specification classes now return more general parsers meant to handle the entire macro/environment/specials invocation, not only their arguments, via the get_node_parser() method.

finalize_node(node)¶

Doc …………….

MUST RETURN the new node instance.

This is called from the LatexMacroCallParser instance, i.e., this function won’t be called by default if you override get_node_parser() and return a different parser instance.

get_node_parser(token)¶

Return a parser instance that is capable of parsing this node construct.

This base class instantiates and returns an object of the type spec_node_parser_type that was specified to the constructor. (This type is set to LatexMacroCallParser, LatexEnvironmentCallParser, or LatexSpecialsCallParser by the corresponding subclasses MacroSpec, EnvironmentSpec, or SpecialsSpec.) The given type’s constructor is assumed to accept to positional arguments to which the token object token and the present spec instance (self) are passed.

make_after_parsing_state_delta(parsed_node, latex_walker)¶

If applicable, create a ParsingStateDelta class to convey any changes in the parsing state after completing this callable node.

The default implementation returns None. You may, but do not have to, override this method to customize its behavior. You can specify a custom callable to make_after_parsing_state_delta=… in the constructor which will be invoked in this method.

This method is called from the LatexMacroCallParser instance, i.e., this function won’t be called by default if you override get_node_parser() and return a different parser instance.

make_arguments_parsing_state_delta(token, latex_walker)¶: Doc …………….

make_body_parser(token, nodeargd, arg_parsing_state_delta)¶

Doc. …………….

For environment specs only. ……..

make_body_parsing_state_delta(token, nodeargd, arg_parsing_state_delta, latex_walker)¶

Doc …………….

This method only makes sense for LaTeX environments. It’s defined in the base class CallableSpec for consistency with the other make_**_parsing_state_delta() methods. This base class implementation, if no custom body parsing state delta function is set in the constructor, relies on self.body_parsing_state_delta being available!

Note: arg_parsing_state_delta is always None (unless you actually went ahead and replaced the the arguments_parser attribute, which is a LatexArgumentsParser or LatexNoArgumentsParser instance, by a custom parser).

needs_arguments()¶: Doc …………….

parse_args(w, pos, parsing_state=None)¶: Deprecated since version 3.0: This method is not recommented starting from pylatexenc 3. You can use parser stored as the arguments_parser attribute instead.

class pylatexenc.macrospec.EnvironmentSpec(environmentname, arguments_spec_list=None, **kwargs)¶

Stores the specification of a LaTeX environment.

This stores the environment name and instructions on how to parse any arguments provided after \begin{environment}<args>.

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*}.

environmentname¶: The name of the environment, i.e., the argument of \begin{...} and \end{...}.

body_parsing_state_delta¶: The parsing state changes that are set in order to parse the body contents of the environment.

args_parser¶

The parser instance that can understand this environment’s arguments. For standard LaTeX environment this is usually a MacroStandardArgsParser instance.

If you specify a string, then for convenience this is interpreted as an argspec argument for MacroStandardArgsParser and such an instance is automatically created.

Deprecated since version 3.0: The args_parser attribute is deprecated since pylatexenc 3.0. Macro, environment, and specials specification classes now return more general parsers meant to handle the entire macro/environment/specials invocation, not only their arguments, via the get_node_parser() method.

is_math_mode¶: Indicates if the contents is to be interpreted in Math Mode. This would be True for environments like \begin{equation}, \begin{align}, etc., but is left to None for \begin{figure}, etc.

Deprecated since version 3.0: The field is_math_mode was deprecated in pylatexenc 3 in favor of the field body_parsing_state_delta. Instead of is_math_mode=True, use body_parsing_state_delta=ParsingStateDeltaEnterMathMode().

finalize_node(node)¶

Doc …………….

MUST RETURN the new node instance.

This is called from the LatexMacroCallParser instance, i.e., this function won’t be called by default if you override get_node_parser() and return a different parser instance.

get_node_parser(token)¶

Return a parser instance that is capable of parsing this node construct.

This base class instantiates and returns an object of the type spec_node_parser_type that was specified to the constructor. (This type is set to LatexMacroCallParser, LatexEnvironmentCallParser, or LatexSpecialsCallParser by the corresponding subclasses MacroSpec, EnvironmentSpec, or SpecialsSpec.) The given type’s constructor is assumed to accept to positional arguments to which the token object token and the present spec instance (self) are passed.

make_after_parsing_state_delta(parsed_node, latex_walker)¶

If applicable, create a ParsingStateDelta class to convey any changes in the parsing state after completing this callable node.

The default implementation returns None. You may, but do not have to, override this method to customize its behavior. You can specify a custom callable to make_after_parsing_state_delta=… in the constructor which will be invoked in this method.

This method is called from the LatexMacroCallParser instance, i.e., this function won’t be called by default if you override get_node_parser() and return a different parser instance.

make_arguments_parsing_state_delta(token, latex_walker)¶: Doc …………….

make_body_parser(token, nodeargd, arg_parsing_state_delta)¶

Doc. …………….

For environment specs only. ……..

make_body_parsing_state_delta(token, nodeargd, arg_parsing_state_delta, latex_walker)¶

Doc …………….

This method only makes sense for LaTeX environments. It’s defined in the base class CallableSpec for consistency with the other make_**_parsing_state_delta() methods. This base class implementation, if no custom body parsing state delta function is set in the constructor, relies on self.body_parsing_state_delta being available!

Note: arg_parsing_state_delta is always None (unless you actually went ahead and replaced the the arguments_parser attribute, which is a LatexArgumentsParser or LatexNoArgumentsParser instance, by a custom parser).

needs_arguments()¶: Doc …………….

parse_args(w, pos, parsing_state=None)¶: Deprecated since version 3.0: This method is not recommented starting from pylatexenc 3. You can use parser stored as the arguments_parser attribute instead.

class pylatexenc.macrospec.SpecialsSpec(specials_chars, arguments_spec_list=None, **kwargs)¶

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

specials_chars¶: The string (one or several characters) that has a special meaning. E.g., ‘&’, ‘~’, ‘``’, etc.

args_parser¶: A parser (e.g. 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. ‘~’).

Deprecated since version 3.0: The args_parser attribute is deprecated since pylatexenc 3.0. Macro, environment, and specials specification classes now return more general parsers meant to handle the entire macro/environment/specials invocation, not only their arguments, via the get_node_parser() method.

finalize_node(node)¶

Doc …………….

MUST RETURN the new node instance.

This is called from the LatexMacroCallParser instance, i.e., this function won’t be called by default if you override get_node_parser() and return a different parser instance.

get_node_parser(token)¶

Return a parser instance that is capable of parsing this node construct.

This base class instantiates and returns an object of the type spec_node_parser_type that was specified to the constructor. (This type is set to LatexMacroCallParser, LatexEnvironmentCallParser, or LatexSpecialsCallParser by the corresponding subclasses MacroSpec, EnvironmentSpec, or SpecialsSpec.) The given type’s constructor is assumed to accept to positional arguments to which the token object token and the present spec instance (self) are passed.

make_after_parsing_state_delta(parsed_node, latex_walker)¶

If applicable, create a ParsingStateDelta class to convey any changes in the parsing state after completing this callable node.

The default implementation returns None. You may, but do not have to, override this method to customize its behavior. You can specify a custom callable to make_after_parsing_state_delta=… in the constructor which will be invoked in this method.

This method is called from the LatexMacroCallParser instance, i.e., this function won’t be called by default if you override get_node_parser() and return a different parser instance.

make_arguments_parsing_state_delta(token, latex_walker)¶: Doc …………….

make_body_parser(token, nodeargd, arg_parsing_state_delta)¶

Doc. …………….

For environment specs only. ……..

make_body_parsing_state_delta(token, nodeargd, arg_parsing_state_delta, latex_walker)¶

Doc …………….

This method only makes sense for LaTeX environments. It’s defined in the base class CallableSpec for consistency with the other make_**_parsing_state_delta() methods. This base class implementation, if no custom body parsing state delta function is set in the constructor, relies on self.body_parsing_state_delta being available!

Note: arg_parsing_state_delta is always None (unless you actually went ahead and replaced the the arguments_parser attribute, which is a LatexArgumentsParser or LatexNoArgumentsParser instance, by a custom parser).

needs_arguments()¶: Doc …………….

parse_args(w, pos, parsing_state=None)¶: Deprecated since version 3.0: This method is not recommented starting from pylatexenc 3. You can use parser stored as the arguments_parser attribute instead.

pylatexenc.macrospec.std_macro(macname, *args, **kwargs)¶

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 (EnvironmentSpec) instead of a macro specification, use the function std_environment() instead.

The helper function 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.

pylatexenc.macrospec.std_environment(envname, *args, **kwargs)¶

Return an environment specification for the given environment. Syntax:

spec = std_environment(envname, argspec, is_math_mode=True|False|None)
#  or
spec = std_environment(envname, optarg, numargs, is_math_mode=True|False|None)
#  or
spec = std_environment( (envname, argspec), is_math_mode=True|False|None)
#  or
spec = std_environment( (envname, optarg, numargs), is_math_mode=True|False|None)
#  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 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.

pylatexenc.macrospec.std_specials(specials_chars)¶

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 SpecialsSpec directly.

Latex Context “Database”¶

class pylatexenc.macrospec.LatexContextDb(**kwargs)¶

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 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 MacroSpec, EnvironmentSpec, and SpecialsSpec instances, respectively. When used with pylatexenc.latex2text.LatexNodes2Text, the specifications for macros, environments, and other specials are stored as pylatexenc.latex2text.MacroTextSpec , pylatexenc.latex2text.EnvironmentTextSpec, and 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 add_context_category(), one should refrain from modifying it directly after providing it to, e.g., a 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 filtered_context().

To (partially) ensure that the database isn’t modified while it is being used, it can be “frozen” with the method freeze(). This method simply sets a flag and will cause methods like add_context_category() to raise an error. You can always construct new context category instances based on the present one by calling filtered_context() or extended_with().

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

The constructor doesn’t accept any meaningful arguments.

freeze()¶

Disable future changes to the information contained in this object.

LatexWalker objects expect that context category databases are immutable, they don’t change. Building a context database object, however, might require several calls to add_context_category, etc.

So what the latexwalker does is that it freeze()s the context db object to prevent future changes.

add_context_category(category, macros=[], environments=[], specials=[], prepend=False, insert_before=None, insert_after=None)¶

Register a category of macro and environment specifications in the context database.

The category name category must not already exist in the database. If category is None, then a unique automatically-generated and internal category name is used.

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=’…’.

set_unknown_macro_spec(macrospec)¶: Set the macro spec to use when encountering a macro that is not in the database.

set_unknown_environment_spec(environmentspec)¶: Set the environment spec to use when encountering a LaTeX environment that is not in the database.

set_unknown_specials_spec(specialsspec)¶

Set the latex specials spec to use when encountering a LaTeX environment that is not in the database.

### FIXME: When is an “unknown specials” encountered ??

categories()¶: Return a list of valid category names that are registered in the current database context.

get_macro_spec(macroname, raise_if_not_found=False)¶

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 set_unknown_macro_spec() or None if no such spec was set.

get_environment_spec(environmentname, raise_if_not_found=False)¶

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 set_unknown_environment_spec() or None if no such spec was set.

get_specials_spec(specials_chars, raise_if_not_found=False)¶

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 test_for_specials() instead. Unlike test_for_specials(), 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 set_unknown_specials_spec() or None if no such spec was set.

test_for_specials(s, pos, parsing_state=None)¶

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.

iter_macro_specs(categories=None)¶

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.

iter_environment_specs(categories=None)¶

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.

iter_specials_specs(categories=None)¶

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.

filter_context(*args, **kwargs)¶: Deprecated since version 3.0: The filter_context() method was renamed filtered_context(). The method signature is unchanged.

filtered_context(keep_categories=[], exclude_categories=[], keep_which=[], create_class=None)¶

Return a new 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. 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.

New in version 3.0: The filter_context() method was renamed filtered_context() in pylatexenc 3.0.

extended_with(category=None, macros=None, environments=None, specials=None, create_class=None, **kwargs)¶

Creates a new context category by adding a new category before all others. (Behaves as you’d imagine immediately after issuing a \newcommand\newmacro{...}).

If category is None, then an internal category name is used.

(Note: If category is None, it might happen that a new category isn’t actually created; if the current object’s first category is already an internally-created one, that one is used.)

class pylatexenc.macrospec.ParsingStateDeltaExtendLatexContextDb(extend_latex_context, **kwargs)¶

Bases: ParsingStateDelta

In addition to setting attributes, this parsing state delta object can also extend the latex context.

extend_latex_context¶

A dictionary with keys ‘macros’, ‘environments’, ‘specials’, as accepted by LatexContextDb.add_context_category().

Can be used along with set_parsing_state; in which case definitions are added on top of the parsing state change.

Lower-level parsers for macro, environments, and specials ¶

You shouldn’t have to use these directly.

class pylatexenc.macrospec.LatexNoArgumentsParser¶

Bases: LatexParserBase

Convenience class for whenever there are no arguments to parse at all.

parse(latex_walker, token_reader, parsing_state, **kwargs)¶: Returns an empty pylatexenc.latexnodes.ParsedArguments object instance, and no parsing state delta.

class pylatexenc.macrospec.LatexArgumentsParser(arguments_spec_list, **kwargs)¶

Bases: LatexParserBase

A parser class that handles the arguments of a callable (a macro, an environment, or specials).

Doc ……………………

The parser’s main function (parse()) produces a ParsedArguments instance.

Any parser carry-over information generated by individual argument parsers is ignored (with a warning).

arguments_spec_list¶

A list of pylatexenc.latexnodes.LatexArgumentSpec instances describing a sequence of arguments (along with suitable parsers) that a given callable accepts.

The constructor expects an iterable of elements that are either already LatexArgumentSpec instances, or that are a string representing a standard argument type, in which case the string is used to construct a LatexArgumentSpec (see doc for that class).

parse(latex_walker, token_reader, parsing_state, **kwargs)¶: See class doc.

class pylatexenc.macrospec.LatexEnvironmentBodyContentsParserInfo(delimited_expression_parser, opening_delimiter_tokens, group_parsing_state, parsing_state, delimiters, latex_walker)¶: Bases: LatexDelimitedExpressionParserInfo

class pylatexenc.macrospec.LatexEnvironmentBodyContentsParser(environmentname, contents_parsing_state_delta=None, child_parsing_state_delta=None, discard_parsing_state_delta=True, **kwargs)¶

Bases: LatexDelimitedExpressionParser

Parse an environment body, up to a final \end{environmentname}.

Use can use the contents_parsing_state_delta to influence the parsing state used to parse the environment body contents.

You can also use child_parsing_state_delta to influence the parsing state used for children encountered in the main body contents. The child parsing state delta is always applied onto the main original parsing state, not onto the contents parsing state.

Either of contents_parsing_state_delta and child_parsing_state_delta is None, then the corresponding parsing state is taken to be the main parent parsing state.

You can achieve an effect of locally applying a different parsing state for the immediate children of the body contents but not further/deeper children by setting contents_parsing_state_delta while keeping child_parsing_state_delta=None. The rationale to do this is to locally enable commands that are meant to provide information about or otherwise directly relate to that environment, say, \label or \item, without those commands being active in any further children. For instance, you can achieve the following behavior:

class pylatexenc.macrospec.LatexMacroCallParser(token_call, macrospec)¶: Bases: _LatexCallableParserBase

class pylatexenc.macrospec.LatexEnvironmentCallParser(token_call, environmentspec)¶: Bases: _LatexCallableParserBase

class pylatexenc.macrospec.LatexSpecialsCallParser(token_call, specialsspec)¶: Bases: _LatexCallableParserBase

Legacy (2.x) Macro arguments parsers ¶

class pylatexenc.macrospec.MacroStandardArgsParser(argspec=None, optional_arg_no_space=False, args_math_mode=None, **kwargs)¶

Parses the arguments to a LaTeX macro.

Deprecated since version 3.0: This class is part of pylatexenc 2.x’s macro argument parsing API. Starting with pylatexenc 3.0, each macro/environment/specials argument is parsed with an individual macro parser. See pylatexenc.latexnodes.LatexArgumentSpec, pylatexenc.latexnodes.parsers.LatexStandardArgumentParser. (You can also check out the lower-level pylatexenc.macrospec.LatexMacroCallParser, pylatexenc.macrospec.LatexEnvironmentCallParser, and pylatexenc.macrospec.LatexSpecialsCallParser.)

This class parses a simple macro argument specification with a specified arrangement of optional and mandatory arguments.

This class also serves as base class for more advanced argument parsers (e.g. for a \verb+...+ macro argument parser). In such cases, subclasses should attempt to provide the most suitable argspec (and argnlist for the corresponding ParsedMacroArgs) for their use, if appropriate, or set them to None.

Arguments:

argspec: must be a string in which each character corresponds to an argument. The character ‘{’ represents a mandatory argument (single token or LaTeX group) and the character ‘[’ denotes an optional argument delimited by braces. The character ‘*’ denotes a possible star char at that position in the argument list, a corresponding latexwalker.LatexCharsNode('*') (or None if no star) will be inserted in the argument node list. For instance, the string ‘*{[[{’ would be suitable to specify the signature of the ‘\newcommand’ macro.

Currently, the argspec string may only contain the characters ‘*’, ‘{’ and ‘[‘.

The argspec may also be None, which is the same as specifying an empty string.

optional_arg_no_space: If set to True, then an optional argument cannot have any whitespace between the preceeding tokens and the ‘[’ character. Set this to True in cases such as for \\ in AMS-math environments, where AMS apparently introduced a patch to prevent a bracket on a new line after \\ from being interpreted as the optional argument to \\.

args_math_mode: Either None, or a list of the same length as argspec. If a list is given, then each item must be True, False, or None. The corresponding argument (cf. argspec) is then respectively parsed in math mode (True), in text mode (False), or with the mode unchanged (None). If args_math_mode is None, then all arguments are parsed in the same mode as the current mode.

additional unrecognized keyword arguments are passed on to superclasses in case of multiple inheritance

Attributes:

argspec¶: Argument type specification provided to the constructor.

optional_arg_no_space¶: See the corresponding constructor argument.

args_math_mode¶: See the corresponding constructor argument.

parse_args(w, pos, parsing_state=None)¶

Parse the arguments encountered at position pos in the LatexWalker instance w.

You may override this function to provide custom parsing of complicated macro arguments (say, \verb+...+). The method will be called by keyword arguments, so the argument names should not be altered.

The argument w is the pylatexenc.latexwalker.LatexWalker object that is currently parsing LaTeX code. You can call methods like w.get_goken(), w.get_latex_expression() etc., to parse and read arguments.

The argument parsing_state is the current parsing state in the LatexWalker (e.g., are we currently in math mode?). See doc for ParsingState.

This function should return a tuple (argd, pos, len) where:

argd is a ParsedMacroArgs instance, or an instance of a subclass of ParsedMacroArgs. The base parse_args() provided here returns a ParsedMacroArgs instance.
pos is the position of the first parsed content. It should be the same as the pos argument, except if there is whitespace at that position in which case the returned pos would have to be the position where the argument contents start.
len is the length of the parsed expression. You will probably want to continue parsing stuff at the index pos+len in the string.

pylatexenc.macrospec.ParsedMacroArgs¶: alias of ParsedArguments

class pylatexenc.macrospec.VerbatimArgsParser(verbatim_arg_type, verbatim_environment_name='verbatim', verbatim_argspec='', verbatim_parsed_args_class=<class 'pylatexenc.macrospec._pyltxenc2_argparsers._verbatimargsparser.ParsedVerbatimArgs'>, specials_delimiters=('|', '|'), **kwargs)¶

Bases: MacroStandardArgsParser

Parses the arguments to various LaTeX verbatim constructs such as \begin{verbatim}...\end{verbatim} environment or \verb+...+.

Deprecated since version 3.0: This class is part of pylatexenc 2.x’s macro argument parsing API. Starting with pylatexenc 3.0, each macro/environment/specials argument is parsed with an individual macro parser. (See pylatexenc.latexnodes.LatexArgumentSpec, pylatexenc.macrospec.LatexStandardArgumentParser.) To parse verbatim contents for macro arguments and body contents, see pylatexenc.latexnodes.parsers.LatexDelimitedVerbatimParser and pylatexenc.latexnodes.parsers.LatexVerbatimEnvironmentContentsParser.

This class also serves to illustrate how to write custom parsers for complicated macro arguments. See also MacroStandardArgsParser.

Arguments:

verbatim_arg_type¶: One of ‘verbatim-environment’, ‘verb-macro’, or ‘specials-delimiters’.

verbatim_environment_name¶: Name of the environment which acts as verbatim environment. This is used to find the end of the environment in the document (we simply search for \end{environment-name}).

verbatim_environment_argspec¶: Specify any standard macro argument(s) the verbatim environment (or analog environment such as the lstlisting environment) accepts before their verbatim content.

verbatim_parsed_args_class¶: The class to use to construct the parsed-arguments object after we parsed the verbatim construct. By default this is ParsedVerbatimArgs. You can use another class that derives from ParsedVerbatimArgs and that accepts the same keyword arguments.

specials_delimiters¶: When parsing a “specials” form of a verbatim construct (e.g. |\begin| and |\end| are special \LaTeX\ commands), specify the opening and closing delimiter here. When parsing the verbatim construct, the closing delimiter is searched and its first occurence is used (there is no brace/parenthesis matching or anything of the kind).

class pylatexenc.macrospec.ParsedVerbatimArgs(verbatim_chars_node, verbatim_delimiters=None, verbatim_argspec='', verbatim_argnlist=[], **kwargs)¶

Bases: ParsedArguments

Parsed representation of arguments to LaTeX verbatim constructs, such as \begin{verbatim}...\end{verbatim} or \verb|...|.

Instances of ParsedVerbatimArgs are returned by the args parser VerbatimArgsParser.

Arguments:

verbatim_chars_node — a properly initialized pylatexenc.latexwalker.LatexCharsNode that stores the verbatim text provided. It is used to initialize the base class ParsedMacroArgs to expose a single mandatory argument with the given verbatim text. The verbatim_text attribute is initialized from this node, too.

verbatim_delimiters — a 2-item tuple of characters used to delimit the verbatim arguemnt (in case of a \verb+...+ macro) or None.

verbatim_argspec, verbatim_argnlist — the argspec and node list representing any regular (optional or mandatory) argument(s) that the construct might have accepted, before the verbatim content. (E.g. \begin{lstlisting}[language=Python])

Attributes:

verbatim_text¶: The verbatim text that was provided

verbatim_delimiters¶: If the verbatim text was specified as an argument to \verb$...$, then this is set to a 2-item tuple that specifies the begin and end delimiters. Otherwise, the attribute is None.

Deprecated since version 3.0: This class was deprecated in pylatexenc 3. Starting from pylatexenc 3, the preferred way to parse verbatim arguments is to use a verbatim parser (pylatexenc.latexnodes.parsers.LatexDelimitedVerbatimParser) as an argument in a pylatexenc.macrospec.LatexArgumentsParser instance.

to_json_object()¶

Called when we export the node structure to JSON when running latexwalker in command-line.

Return a representation of the current parsed arguments in an object, typically a dictionary, that can easily be exported to JSON. The object may contain latex nodes and other parsed-argument objects, as we use a custom JSON encoder that understands these types.

Subclasses may

pylatexenc

Navigation

Related Topics

macrospec — Specifying definitions for the parser¶

Macro and environment definitions ¶

Latex Context “Database”¶

Lower-level parsers for macro, environments, and specials ¶

Legacy (2.x) Macro arguments parsers ¶

macrospec — Specifying definitions for the parser¶

Macro and environment definitions¶

Latex Context “Database”¶

Lower-level parsers for macro, environments, and specials¶

Legacy (2.x) Macro arguments parsers¶

Macro and environment definitions ¶

Lower-level parsers for macro, environments, and specials ¶

Legacy (2.x) Macro arguments parsers ¶