Mercurial > hgrepos > Python > libs > pygments-lexer-pseudocode2
changeset 126:e91c9dcbeb77
Rename details.rst to details-algpseudocode.rst
| author | Franz Glasner <fzglas.hg@dom66.de> |
|---|---|
| date | Wed, 06 May 2026 17:02:04 +0200 |
| parents | 3629bf09b30d |
| children | 4d55475d61a3 |
| files | docs/details-algpseudocode.rst docs/details.rst docs/index.rst |
| diffstat | 3 files changed, 294 insertions(+), 294 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/details-algpseudocode.rst Wed May 06 17:02:04 2026 +0200 @@ -0,0 +1,293 @@ +.. -*- coding: utf-8; indent-tabs-mode: nil; -*- + + +********* + Details +********* + +.. role:: algpseudocode(code) + :language: algpseudocode + + +Lexer Options +============= + +`no_end` + + Default: ``False`` + + If ``True`` all the ``ENDxxx`` commands will be skipped and yield nothing. + +`gets` + + Default: ``←`` + + The operator symbol to be printed by the command ``\GETS``. + + Often used alternative: ``:=``. + +`remark` + + Default: ``▷`` + + The symbol to be printed as when starting comments with ``\REMARK`` or ``\REM`` + + +Comments +======== + +- with the ``\REMARK`` or ``\REM`` keywords +- multi-line comments with ``/* ... */``; they can be **nested** +- multi-line comments with ``(* ... *)``; they can be **nested** +- single-line comments with ``//`` or ``#`` (until the end of the line) + + +Literals +======== + +Strings and numbers as in `Python <https://www.python.org>`_. + +To yield non-string-delimiting single- and double-quotes you have to escape them +using ``\'`` or ``\"``. This must be used to typeset something as +:algpseudocode:`f\\'(x) = 0`. + + +Keywords +======== + +Explicit Keywords +----------------- + +- Start with a backslash character ``\`` +- Case-insensitive +- Translated if a translation is found + +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. + + +With Required Parameters +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: algpseudocode + + \TEXT{\PROGRAM {A Program\} or \PROG {A Program\}} \PROGRAM {A Program} + \TEXT{\ALGORITHM{An Algorithm\} or \ALGO{An Algorithm\}} \ALGORITHM{An Algorithm} + \TEXT{\PROCEDURE{A Procedure\} or \PROC{A Procedure\}} \PROCEDURE{A Procedure} + \TEXT{\FUNCTION{A Function\} or \FUNC{A Function\} or \FN{A Function\}} \FUNCTION{A Function} + \TEXT{\CLASS{A Class\}} \CLASS{A Class} + + \TEXT{\STATEMENT{the expression\} \STATE{the expression\} \BLOCK{the expression\}} \STATEMENT{the expression} + + \TEXT{expr1: \\EXPRESSION{expression a in b\} expr2: \\EXPR{expression b in a\}} \TEXT{expr1: \EXPRESSION{expression a in b} expr2: \EXPR{expression b in a}} + + \TEXT{\TEXTSTATEMENT{the text\} \TEXTSTATE{the text\} \TSTATEMENT{the text\} \TSTATE{the text\} \TEXTBLOCK{the text\} \TBLOCK{the text\}} \TEXTSTATEMENT{the text} + + \TEXT{\INPUT{Input 1\}} \INPUT{Input 1} + \TEXT{\INPUTS{Input 2\}} \INPUTS{Input 2} + + \TEXT{\OUTPUT{Output 1\}} \OUTPUT{Output 1} + \TEXT{\OUTPUTS{Output 2\}} \OUTPUTS{Output 2} + + \TEXT{\ENSURE{Whatever should be ensured!\}} \ENSURE{Whatever should be ensured!} + + \TEXT{\REQUIRE{Whatever should be required.\}} \REQUIRE{Whatever should be required.} + + \TEXT{\RETURNS{Return 2\}} \RETURNS{Return 2} + + \TEXT{\CALL{a function\}(p1, p2)} \CALL{a function}(p1, p2) + + +With Optional Parameters +~~~~~~~~~~~~~~~~~~~~~~~~ + +Some ``END``-keywords have optional parameters: + +.. code-block:: algpseudocode + + \TEXT{\ENDPROGRAM \ENDPROG} \ENDPROGRAM + \TEXT{\ENDALGORITHM \ENDALGO} \ENDALGORITHM + \TEXT{\ENDPROCEDURE \ENDPROC} \ENDPROCEDURE + \TEXT{\ENDFUNCTION \ENDFUNC \ENDFN} \ENDFUNCTION + \TEXT{\ENDCLASS} \ENDCLASS + +They are used like this: + +.. code-block:: algpseudocode + + \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`_ + + +Without Parameters +~~~~~~~~~~~~~~~~~~ + +"Normal" Keywords +''''''''''''''''' + +.. code-block:: algpseudocode + + \TEXT{\IF} \IF + \TEXT{\THEN} \THEN + \TEXT{\ELSE} \ELSE + \TEXT{\ELSEIF or \ELSIF or \ELIF} \ELSEIF \text{or} \ELSIF \text{or} \ELIF + \TEXT{\DO} \DO + \TEXT{\WHILE} \WHILE + \TEXT{\FORALL} \FORALL + \TEXT{\FOR} \FOR + \TEXT{\FROM} \FROM + \TEXT{\TO} \TO + \TEXT{\STEP} \STEP + \TEXT{\IN} \IN + \TEXT{\LOOP} \LOOP + \TEXT{\REPEAT} \REPEAT + \TEXT{\UNTIL} \UNTIL + + \TEXT{\RETURN} \RETURN + + \TEXT{\BEGIN} \BEGIN + \TEXT{\END} \END + + \TEXT{\IS} \IS + \TEXT{\WITH} \WITH + + \TEXT{\\REMARK or \\REM} \REMARK A comment with a sigil + +``\REMARK`` or ``\REM`` is special: all characters to the end of the +line are taken as comment; curly braces are not needed -- in fact: +they are interpreted as part of the comment. + + +END-Keywords +'''''''''''' + +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`` + + +.. code-block:: algpseudocode + + \text{\ENDIF} \ENDIF \rem empty + + \text{\END IF} \END IF \rem a single space + + \text{\END IF} \END IF \rem two spaces + + \text{\END-IF} \END-IF \rem a single hyphen + + \text{\END_IF} \END_IF \rem a single underscore + + \text{\END IF} \END IF \rem a single TAB character + +The list of END-keywords (here always just with ``-`` as separator): + +.. code-block:: algpseudocode + + \text{\END-PROGRAM \END-PROG} \END-PROGRAM + \text{\END-ALGORITHM \END-ALGO} \END-ALGORITHM + \text{\END-PROCEDURE \END-PROC} \END-PROCEDURE + \text{\END-FUNCTION \END-FUNC \END-FN} \END-FUNCTION + \text{\END-CLASS} \END-CLASS + \text{\END-IF} \END-IF + \text{\END-WHILE} \END-WHILE + \text{\END-FOR} \END-FOR + \text{\END-FORALL} \END-FORALL + \text{\END-LOOP} \END-LOOP + + +Explicit Token Types +==================== + +Handle keywords and operators that are not handled by default or change +the default handling of some expressions. + +`XX` represents a value in the :mod:`pygments.token.STANDARD_TYPES` dict. +Its corresponding token type (the associated `key` in this `dict`) is used as +token type. + +``\\tt-XX/SINGLE-CHAR`` + + no escaping needed + + `SINGLE-CHAR` is a single character and can be *every* character + (including a carriage-return or line-feed) + +``\\ttx-XX{CHARACTERS}`` + +``\\ttx-XX(CHARACTERS)`` + +``\\ttx-XX[CHARACTERS]`` + +``\\ttx-XX<CHARACTERS>`` + +``\\ttx-XX<SEP>CHARACTERS<SEP>`` + + No escaping possible! There are enough alternatives available! + + `SEP` is one of ``/:|=*+!\$~``. + + +Examples: + +.. code-block:: algpseudocode + + \text{• \\tt-kc/C} \tt-kc/C \rem C as Keyword.Constant + \text{• \\tt-ow/∈} \tt-ow/∈ \rem ∈ as Operator.Word + \text{• \\ttx-kc{A New Constant Keyword\}} \ttx-kc{A New Constant Keyword} \rem As a new Keyword.Constant + \text{• \\ttx-nv{A New Variable Name\}} \ttx-nv{A New Variable Name} \rem An explicit Name.Variable + \text{• \\ttx-k(∈ ∌)} \ttx-k(∈ ∌) \rem ∈ and ∌ as (ordinary) Keywords + \text{• \\ttx-o<∈ ∌>} \ttx-o<∈ ∌> \rem ∈ and ∌ as (ordinary) Operators + /* + * The line below has ∈_∌ as (peculiar) function name. + * Their params are automatic. + */ + \text{• \\ttx-nf<∈_∌>(p1, p2)} \ttx-nf<∈_∌>(p1, p2) + /* + * The line below has ∈_∌ as (peculiar) decorator name (as used in Python). + * Their params are automatic. + */ + \text{• \\ttx-nd[∈_∌](p1, p2)} \ttx-nd[∈_∌](p1, p2) + /* + * This is a non-existing token type: you get some generic error marking + * with a Generic.Error token and no expansion. + */ + \text{• \\ttx-NON-EXISTING[∈_∌](p1, p2)} \ttx-NON_EXISTING[∈_∌](p1, p2) + +.. note:: Explicit token types are **case-sensitive**. + + +Customized Lexers in Sphinx +=========================== + +Defining lexers with non-default options in Sphinx can be done in its +configuration file :file:`conf.py`: + +.. code-block:: python + + from functools import partial + from pygments_lexer_pseudocode2.algpseudocode import AlgPseudocodeLexer + + def setup(app): + + # + # Add a custom lexer: AlgPseudocodeLexer with custom init + # option "no_end". + # + # In modern Sphinx versions given lexer must be callable and may + # not be a lexer instance. So use an indirection with "partial" + # here. + # + app.add_lexer("noend-algpseudocode", + partial(AlgPseudocodeLexer, no_end=True)) + +Similarily it works for custom styles and filters. + +For older Sphinx versions your mileage may vary.
--- a/docs/details.rst Wed May 06 16:59:44 2026 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,293 +0,0 @@ -.. -*- coding: utf-8; indent-tabs-mode: nil; -*- - - -********* - Details -********* - -.. role:: algpseudocode(code) - :language: algpseudocode - - -Lexer Options -============= - -`no_end` - - Default: ``False`` - - If ``True`` all the ``ENDxxx`` commands will be skipped and yield nothing. - -`gets` - - Default: ``←`` - - The operator symbol to be printed by the command ``\GETS``. - - Often used alternative: ``:=``. - -`remark` - - Default: ``▷`` - - The symbol to be printed as when starting comments with ``\REMARK`` or ``\REM`` - - -Comments -======== - -- with the ``\REMARK`` or ``\REM`` keywords -- multi-line comments with ``/* ... */``; they can be **nested** -- multi-line comments with ``(* ... *)``; they can be **nested** -- single-line comments with ``//`` or ``#`` (until the end of the line) - - -Literals -======== - -Strings and numbers as in `Python <https://www.python.org>`_. - -To yield non-string-delimiting single- and double-quotes you have to escape them -using ``\'`` or ``\"``. This must be used to typeset something as -:algpseudocode:`f\\'(x) = 0`. - - -Keywords -======== - -Explicit Keywords ------------------ - -- Start with a backslash character ``\`` -- Case-insensitive -- Translated if a translation is found - -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. - - -With Required Parameters -~~~~~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: algpseudocode - - \TEXT{\PROGRAM {A Program\} or \PROG {A Program\}} \PROGRAM {A Program} - \TEXT{\ALGORITHM{An Algorithm\} or \ALGO{An Algorithm\}} \ALGORITHM{An Algorithm} - \TEXT{\PROCEDURE{A Procedure\} or \PROC{A Procedure\}} \PROCEDURE{A Procedure} - \TEXT{\FUNCTION{A Function\} or \FUNC{A Function\} or \FN{A Function\}} \FUNCTION{A Function} - \TEXT{\CLASS{A Class\}} \CLASS{A Class} - - \TEXT{\STATEMENT{the expression\} \STATE{the expression\} \BLOCK{the expression\}} \STATEMENT{the expression} - - \TEXT{expr1: \\EXPRESSION{expression a in b\} expr2: \\EXPR{expression b in a\}} \TEXT{expr1: \EXPRESSION{expression a in b} expr2: \EXPR{expression b in a}} - - \TEXT{\TEXTSTATEMENT{the text\} \TEXTSTATE{the text\} \TSTATEMENT{the text\} \TSTATE{the text\} \TEXTBLOCK{the text\} \TBLOCK{the text\}} \TEXTSTATEMENT{the text} - - \TEXT{\INPUT{Input 1\}} \INPUT{Input 1} - \TEXT{\INPUTS{Input 2\}} \INPUTS{Input 2} - - \TEXT{\OUTPUT{Output 1\}} \OUTPUT{Output 1} - \TEXT{\OUTPUTS{Output 2\}} \OUTPUTS{Output 2} - - \TEXT{\ENSURE{Whatever should be ensured!\}} \ENSURE{Whatever should be ensured!} - - \TEXT{\REQUIRE{Whatever should be required.\}} \REQUIRE{Whatever should be required.} - - \TEXT{\RETURNS{Return 2\}} \RETURNS{Return 2} - - \TEXT{\CALL{a function\}(p1, p2)} \CALL{a function}(p1, p2) - - -With Optional Parameters -~~~~~~~~~~~~~~~~~~~~~~~~ - -Some ``END``-keywords have optional parameters: - -.. code-block:: algpseudocode - - \TEXT{\ENDPROGRAM \ENDPROG} \ENDPROGRAM - \TEXT{\ENDALGORITHM \ENDALGO} \ENDALGORITHM - \TEXT{\ENDPROCEDURE \ENDPROC} \ENDPROCEDURE - \TEXT{\ENDFUNCTION \ENDFUNC \ENDFN} \ENDFUNCTION - \TEXT{\ENDCLASS} \ENDCLASS - -They are used like this: - -.. code-block:: algpseudocode - - \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`_ - - -Without Parameters -~~~~~~~~~~~~~~~~~~ - -"Normal" Keywords -''''''''''''''''' - -.. code-block:: algpseudocode - - \TEXT{\IF} \IF - \TEXT{\THEN} \THEN - \TEXT{\ELSE} \ELSE - \TEXT{\ELSEIF or \ELSIF or \ELIF} \ELSEIF \text{or} \ELSIF \text{or} \ELIF - \TEXT{\DO} \DO - \TEXT{\WHILE} \WHILE - \TEXT{\FORALL} \FORALL - \TEXT{\FOR} \FOR - \TEXT{\FROM} \FROM - \TEXT{\TO} \TO - \TEXT{\STEP} \STEP - \TEXT{\IN} \IN - \TEXT{\LOOP} \LOOP - \TEXT{\REPEAT} \REPEAT - \TEXT{\UNTIL} \UNTIL - - \TEXT{\RETURN} \RETURN - - \TEXT{\BEGIN} \BEGIN - \TEXT{\END} \END - - \TEXT{\IS} \IS - \TEXT{\WITH} \WITH - - \TEXT{\\REMARK or \\REM} \REMARK A comment with a sigil - -``\REMARK`` or ``\REM`` is special: all characters to the end of the -line are taken as comment; curly braces are not needed -- in fact: -they are interpreted as part of the comment. - - -END-Keywords -'''''''''''' - -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`` - - -.. code-block:: algpseudocode - - \text{\ENDIF} \ENDIF \rem empty - - \text{\END IF} \END IF \rem a single space - - \text{\END IF} \END IF \rem two spaces - - \text{\END-IF} \END-IF \rem a single hyphen - - \text{\END_IF} \END_IF \rem a single underscore - - \text{\END IF} \END IF \rem a single TAB character - -The list of END-keywords (here always just with ``-`` as separator): - -.. code-block:: algpseudocode - - \text{\END-PROGRAM \END-PROG} \END-PROGRAM - \text{\END-ALGORITHM \END-ALGO} \END-ALGORITHM - \text{\END-PROCEDURE \END-PROC} \END-PROCEDURE - \text{\END-FUNCTION \END-FUNC \END-FN} \END-FUNCTION - \text{\END-CLASS} \END-CLASS - \text{\END-IF} \END-IF - \text{\END-WHILE} \END-WHILE - \text{\END-FOR} \END-FOR - \text{\END-FORALL} \END-FORALL - \text{\END-LOOP} \END-LOOP - - -Explicit Token Types -==================== - -Handle keywords and operators that are not handled by default or change -the default handling of some expressions. - -`XX` represents a value in the :mod:`pygments.token.STANDARD_TYPES` dict. -Its corresponding token type (the associated `key` in this `dict`) is used as -token type. - -``\\tt-XX/SINGLE-CHAR`` - - no escaping needed - - `SINGLE-CHAR` is a single character and can be *every* character - (including a carriage-return or line-feed) - -``\\ttx-XX{CHARACTERS}`` - -``\\ttx-XX(CHARACTERS)`` - -``\\ttx-XX[CHARACTERS]`` - -``\\ttx-XX<CHARACTERS>`` - -``\\ttx-XX<SEP>CHARACTERS<SEP>`` - - No escaping possible! There are enough alternatives available! - - `SEP` is one of ``/:|=*+!\$~``. - - -Examples: - -.. code-block:: algpseudocode - - \text{• \\tt-kc/C} \tt-kc/C \rem C as Keyword.Constant - \text{• \\tt-ow/∈} \tt-ow/∈ \rem ∈ as Operator.Word - \text{• \\ttx-kc{A New Constant Keyword\}} \ttx-kc{A New Constant Keyword} \rem As a new Keyword.Constant - \text{• \\ttx-nv{A New Variable Name\}} \ttx-nv{A New Variable Name} \rem An explicit Name.Variable - \text{• \\ttx-k(∈ ∌)} \ttx-k(∈ ∌) \rem ∈ and ∌ as (ordinary) Keywords - \text{• \\ttx-o<∈ ∌>} \ttx-o<∈ ∌> \rem ∈ and ∌ as (ordinary) Operators - /* - * The line below has ∈_∌ as (peculiar) function name. - * Their params are automatic. - */ - \text{• \\ttx-nf<∈_∌>(p1, p2)} \ttx-nf<∈_∌>(p1, p2) - /* - * The line below has ∈_∌ as (peculiar) decorator name (as used in Python). - * Their params are automatic. - */ - \text{• \\ttx-nd[∈_∌](p1, p2)} \ttx-nd[∈_∌](p1, p2) - /* - * This is a non-existing token type: you get some generic error marking - * with a Generic.Error token and no expansion. - */ - \text{• \\ttx-NON-EXISTING[∈_∌](p1, p2)} \ttx-NON_EXISTING[∈_∌](p1, p2) - -.. note:: Explicit token types are **case-sensitive**. - - -Customized Lexers in Sphinx -=========================== - -Defining lexers with non-default options in Sphinx can be done in its -configuration file :file:`conf.py`: - -.. code-block:: python - - from functools import partial - from pygments_lexer_pseudocode2.algpseudocode import AlgPseudocodeLexer - - def setup(app): - - # - # Add a custom lexer: AlgPseudocodeLexer with custom init - # option "no_end". - # - # In modern Sphinx versions given lexer must be callable and may - # not be a lexer instance. So use an indirection with "partial" - # here. - # - app.add_lexer("noend-algpseudocode", - partial(AlgPseudocodeLexer, no_end=True)) - -Similarily it works for custom styles and filters. - -For older Sphinx versions your mileage may vary.