Module latexpp.pragma_fix — fix class working with lpp-pragmas

class latexpp.pragma_fix.PragmaFix

A special kind of fix that processes latexpp pragma instructions.

A PragmaFix differs from other BaseFix-based classes in how they process LaTeX nodes. A PragmaFix subclass reimplements fix_pragma_scope() and/or fix_pragma_simple(), which are called upon encountering %%!lpp <instruction> [<args>] [{ ... %%!lpp }] constructs. The fix may then choose to process these pragma instructions, and their surrounding node lists, as it wishes.

Pragmas are fixes, and they reimplement BaseFix. Some built-in pragmas are always loaded and processed (e.g. the SkipPragma pragma). Others can be loaded into your list of fixes like normal fixes (e.g., latexpp.fixes.regional_fix.Apply).

fix_nodelist(nodelist)

Reimplemented from latexpp.fix.BaseFix. Subclasses should generally not reimplement this.

fix_pragma_scope(nodelist, jstart, jend, instruction, args)

Called when a scoped pragma is encountered. A scoped pragma is one with an opening brace at the end of the %%!lpp instruction, and is matched by a corresponding closing pragma instruction %%!lpp }.

This function may modify nodelist in place (including inserting/deleting elements). This function must return an index in nodelist where to continue processing of further pragmas after the current scope pragma, or an integer larger or equal to nodelist’s length to indicate the end of the list was reached.

Child nodes are already and automatically parsed for pragmas, so do NOT do this again when you reimplement fix_pragma_scope().

Scope pragmas are parsed and reported inner first, then the outer scopes. Nested scopes are allowed. A pragma scope must be opened and closed within the same LaTeX scope (you cannot open a scope and close it in a different LaTeX environment, for instance).

For instance, the SkipPragma fix removes the entire scope pragma and its contents with nodelist[jstart:jend] = [] and then returns jstart to continue processing after the removed block (which has new index jstart). It is OK for this function to return an index that is larger than or equal to len(nodelist); this is interpreted as there is no further content to process in nodelist.

Arguments:

  • nodelist is the full nodelist that is currently being processed.

  • jstart and jend are the indices in nodelist that point to the opening lpp pragma comment node and one past the closing lpp pragma comment node. This is like a Python range; for instance, you can remove the entire pragma block with nodelist[jstart:jend] = [].

  • instruction is the pragma instruction name (the word after %%!lpp).

  • args is a list of any remaining arguments after the instruction (excluding the opening brace).

The default implementation does not do anything and returns jend to continue after the current pragma scope.

fix_pragma_simple(nodelist, j, instruction, args)

Called when a simple pragma is encountered.

This function may modify nodelist[j] directly. It can also modify the nodelist in place, including inserting/deleting elements if required.

This function must return an index in nodelist where to continue processing of further pragmas after the current pragma. (It is OK for this function to return an index that is larger than or equal to len(nodelist); this is interpreted as there is no further content to process in nodelist.)

Arguments:

  • nodelist is the full nodelist that is currently being processed.

  • j is the index in nodelist that points to the encountered lpp pragma comment node that this function might want to handle.

  • instruction is the pragma instruction name (the word after %%!lpp).

  • args is a list of any remaining arguments after the instruction.

Simple pragmas are parsed & reported in linear order for each LaTeX scope (inner LaTeX scopes first).

The default implementation does not do anything and returns j+1 to continue processing after the current pragma.