# HG changeset patch # User Franz Glasner # Date 1778488779 -7200 # Node ID 3c517c22df9c00db3be7c653220736632933d83f # Parent bff8b900713add1a75379448c9def49507313445 Much more details and refinements in the docs diff -r bff8b900713a -r 3c517c22df9c docs/lexer-algpseudocode.rst --- a/docs/lexer-algpseudocode.rst Mon May 11 01:31:12 2026 +0200 +++ b/docs/lexer-algpseudocode.rst Mon May 11 10:39:39 2026 +0200 @@ -36,6 +36,10 @@ \END PROGRAM {The Pseudoprogram} + +States +====== + The AlgPseudocode lexer and its language variants AlgPseudocodeDE and AlgPseudocodeFR basically work in three states: `default`, `expression` and `text`. @@ -80,60 +84,6 @@ - :ref:`explicit-token-types` -.. rubric:: Some Examples - -A synthetic example with many features: - -.. literalinclude:: examples/example-1.pseudocode - :language: algpseudocode - :lines: 2- - -With a customized `AlgPseudocodeLexer` and its `no_end` -option set to ``True``. - -.. literalinclude:: examples/example-1.pseudocode - :language: NoEndAlgPseudocode - :lines: 2- - -This is Wikipedia's description of *Dinic's Algorithm* -(see https://en.wikipedia.org/wiki/Dinic%27s_algorithm): - -.. literalinclude:: examples/algorithm-dinic.description - :language: algpseudocode - :lines: 2- - -This is Wikipedia's pseudocode of the *Ford–Fulkerson Algorithm* -(see https://en.wikipedia.org/wiki/Ford%E2%80%93Fulkerson_algorithm): - -.. literalinclude:: examples/algorithm-ford-fulkerson.pseudocode - :language: algpseudocode - :lines: 2- - -This is Wikipedia's pseudocode of the *Edmonds–Karp Algorithm* -(see https://en.wikipedia.org/wiki/Edmonds%E2%80%93Karp_algorithm) -with a custom lexer that skip all ``ENDxxx`` keywords: - -.. literalinclude:: examples/algorithm-edmonds-karp.pseudocode - :language: NoEndAlgPseudocode - :lines: 2- - -And now the *Edmonds–Karp Algorithm* with french keywords: - -.. literalinclude:: examples/algorithm-edmonds-karp.pseudocode - :language: algpseudocode-fr - :lines: 2- - -And again the *Edmonds–Karp Algorithm* with german keywords: - -.. literalinclude:: examples/algorithm-edmonds-karp.pseudocode - :language: algpseudocode-de - :lines: 2- - -More details you will find :ref:`here `. - - -.. _details-algpseudocode: - Lexer Options ============= @@ -156,7 +106,7 @@ **Default:** `False` If ``True`` all the ``\ENDxxx`` commands will be skipped and yield - nothing. + no output. .. describe:: gets @@ -284,31 +234,32 @@ They are not replaced by corresponding Unicode symbols. -Keywords +Commands ======== -Explicit Keywords ------------------ - - Start with a backslash character ``\`` - Case-insensitive +- Yield mostly to :py:class:`pygments.Token.Keyword` - Translated if a translation is found +- Depending on the command---may have required or optional parameters -Parameter handling is as follows: + Parameter handling is as follows: -- Parameters are enclosed in curly braces ``{`` and ``}`` -- Escaping within the braces is possible using the backslash ``\`` -- Parameters are separated from the keyword/command by a (possibly empty) run - of space or TAB characters. - This is true for required and optional parameters. + * Parameters are enclosed in curly braces ``{`` and ``}`` + * Escaping within the braces is possible using the backslash ``\`` as + escape character + * Parameters are separated from the keyword/command by a (possibly empty) run + of space or TAB characters. + This is true for required and optional parameters. -.. todo:: Escaping + .. todo:: Escaping - A single backslash is a Generic.Error token + A single backslash yields a Generic.Error token when in + `default` and `expression` states. -With Required Parameters -~~~~~~~~~~~~~~~~~~~~~~~~ +Commands With Required Parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: algpseudocode @@ -341,10 +292,10 @@ \TEXT{\NAME{an entity name\}} \NAME{an entity name} -With Optional Parameters -~~~~~~~~~~~~~~~~~~~~~~~~ +Commands With Optional Parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Some ``END``-keywords have optional parameters: +Some ``END``-commands have optional parameters: .. code-block:: algpseudocode @@ -360,13 +311,16 @@ \TEXT{\CLASS{Foo Bar Class\} ... \END CLASS {Foo Bar Class\}} \TEXT{yields} \CLASS{Foo Bar Class} ... \END CLASS {Foo Bar Class} -.. seealso:: Syntax variants: `END-Keywords`_ + \TEXT{\CLASS{Foo Bar Class\} ... \END CLASS} \TEXT{yields} \CLASS{Foo Bar Class} ... \END CLASS + +.. seealso:: For other syntax variants concerning `END` see also section + `END-Commands`_. -Without Parameters -~~~~~~~~~~~~~~~~~~ +Commands Without Parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -"Normal" Keywords +"Normal" Commands ''''''''''''''''' .. code-block:: algpseudocode @@ -404,11 +358,12 @@ they are interpreted to be part of the comment. -END-Keywords +END-Commands '''''''''''' -The separator character can be empty, a run of ASCII spaces, a run of TAB characters, -a single underscore ``_`` or a single hyphen ``-`` like: +The separator character can be empty, a run of ASCII spaces, a run of +TAB characters, a single underscore ``_`` or a single hyphen ``-`` +like: ``\ENDIF``, ``\END IF``, ``\END-IF``, ``\END_IF`` or ``\END IF`` @@ -427,7 +382,7 @@ \text{\END IF} \END IF \rem a single TAB character -The list of END-keywords (here always just with ``-`` as separator): +The list of END-commands (here always just with ``-`` as separator): .. code-block:: algpseudocode @@ -442,6 +397,9 @@ \text{\END-FORALL} \END-FORALL \text{\END-LOOP} \END-LOOP +.. note:: The output of END-commands can be suppressed by setting the + lexer option ``no_end`` to ``True``. + Names and Entities ================== @@ -467,6 +425,7 @@ \TEXT{Genève} Genève + .. _explicit-token-types: Explicit Token Types @@ -575,3 +534,54 @@ Sphinx and are not augmented with any default filters. For older Sphinx versions your mileage may vary. + + +Some Examples +============= + +A synthetic example with many features: + +.. literalinclude:: examples/example-1.pseudocode + :language: algpseudocode + :lines: 2- + +With a customized `AlgPseudocodeLexer` and its `no_end` +option set to ``True``. + +.. literalinclude:: examples/example-1.pseudocode + :language: NoEndAlgPseudocode + :lines: 2- + +This is Wikipedia's description of *Dinic's Algorithm* +(see https://en.wikipedia.org/wiki/Dinic%27s_algorithm): + +.. literalinclude:: examples/algorithm-dinic.description + :language: algpseudocode + :lines: 2- + +This is Wikipedia's pseudocode of the *Ford–Fulkerson Algorithm* +(see https://en.wikipedia.org/wiki/Ford%E2%80%93Fulkerson_algorithm): + +.. literalinclude:: examples/algorithm-ford-fulkerson.pseudocode + :language: algpseudocode + :lines: 2- + +This is Wikipedia's pseudocode of the *Edmonds–Karp Algorithm* +(see https://en.wikipedia.org/wiki/Edmonds%E2%80%93Karp_algorithm) +with a custom lexer that skip all ``ENDxxx`` keywords: + +.. literalinclude:: examples/algorithm-edmonds-karp.pseudocode + :language: NoEndAlgPseudocode + :lines: 2- + +And now the *Edmonds–Karp Algorithm* with french keywords: + +.. literalinclude:: examples/algorithm-edmonds-karp.pseudocode + :language: algpseudocode-fr + :lines: 2- + +And again the *Edmonds–Karp Algorithm* with german keywords: + +.. literalinclude:: examples/algorithm-edmonds-karp.pseudocode + :language: algpseudocode-de + :lines: 2-