Mercurial > hgrepos > Python > libs > pygments-lexer-pseudocode2

comparison docs/details-algpseudocode.rst @ 126:e91c9dcbeb77

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Rename details.rst to details-algpseudocode.rst
author Franz Glasner <fzglas.hg@dom66.de>
date Wed, 06 May 2026 17:02:04 +0200
parents docs/details.rst@3629bf09b30d
children 4d55475d61a3
comparison
equal deleted inserted replaced
125:3629bf09b30d 126:e91c9dcbeb77
1 .. -*- coding: utf-8; indent-tabs-mode: nil; -*-
2
3
4 *********
5 Details
6 *********
7
8 .. role:: algpseudocode(code)
9 :language: algpseudocode
10
11
12 Lexer Options
13 =============
14
15 `no_end`
16
17 Default: ``False``
18
19 If ``True`` all the ``ENDxxx`` commands will be skipped and yield nothing.
20
21 `gets`
22
23 Default: ``←``
24
25 The operator symbol to be printed by the command ``\GETS``.
26
27 Often used alternative: ``:=``.
28
29 `remark`
30
31 Default: ``▷``
32
33 The symbol to be printed as when starting comments with ``\REMARK`` or ``\REM``
34
35
36 Comments
37 ========
38
39 - with the ``\REMARK`` or ``\REM`` keywords
40 - multi-line comments with ``/* ... */``; they can be **nested**
41 - multi-line comments with ``(* ... *)``; they can be **nested**
42 - single-line comments with ``//`` or ``#`` (until the end of the line)
43
44
45 Literals
46 ========
47
48 Strings and numbers as in `Python <https://www.python.org>`_.
49
50 To yield non-string-delimiting single- and double-quotes you have to escape them
51 using ``\'`` or ``\"``. This must be used to typeset something as
52 :algpseudocode:`f\\'(x) = 0`.
53
54
55 Keywords
56 ========
57
58 Explicit Keywords
59 -----------------
60
61 - Start with a backslash character ``\``
62 - Case-insensitive
63 - Translated if a translation is found
64
65 Parameter handling is as follows:
66
67 - Parameters are enclosed in curly braces ``{`` and ``}``
68 - Escaping within the braces is possible using the backslash ``\``
69 - Parameters are separated from the keyword/command by a (possibly empty) run
70 of space or TAB characters.
71 This is true for required and optional parameters.
72
73
74 With Required Parameters
75 ~~~~~~~~~~~~~~~~~~~~~~~~
76
77 .. code-block:: algpseudocode
78
79 \TEXT{\PROGRAM {A Program\} or \PROG {A Program\}} \PROGRAM {A Program}
80 \TEXT{\ALGORITHM{An Algorithm\} or \ALGO{An Algorithm\}} \ALGORITHM{An Algorithm}
81 \TEXT{\PROCEDURE{A Procedure\} or \PROC{A Procedure\}} \PROCEDURE{A Procedure}
82 \TEXT{\FUNCTION{A Function\} or \FUNC{A Function\} or \FN{A Function\}} \FUNCTION{A Function}
83 \TEXT{\CLASS{A Class\}} \CLASS{A Class}
84
85 \TEXT{\STATEMENT{the expression\} \STATE{the expression\} \BLOCK{the expression\}} \STATEMENT{the expression}
86
87 \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}}
88
89 \TEXT{\TEXTSTATEMENT{the text\} \TEXTSTATE{the text\} \TSTATEMENT{the text\} \TSTATE{the text\} \TEXTBLOCK{the text\} \TBLOCK{the text\}} \TEXTSTATEMENT{the text}
90
91 \TEXT{\INPUT{Input 1\}} \INPUT{Input 1}
92 \TEXT{\INPUTS{Input 2\}} \INPUTS{Input 2}
93
94 \TEXT{\OUTPUT{Output 1\}} \OUTPUT{Output 1}
95 \TEXT{\OUTPUTS{Output 2\}} \OUTPUTS{Output 2}
96
97 \TEXT{\ENSURE{Whatever should be ensured!\}} \ENSURE{Whatever should be ensured!}
98
99 \TEXT{\REQUIRE{Whatever should be required.\}} \REQUIRE{Whatever should be required.}
100
101 \TEXT{\RETURNS{Return 2\}} \RETURNS{Return 2}
102
103 \TEXT{\CALL{a function\}(p1, p2)} \CALL{a function}(p1, p2)
104
105
106 With Optional Parameters
107 ~~~~~~~~~~~~~~~~~~~~~~~~
108
109 Some ``END``-keywords have optional parameters:
110
111 .. code-block:: algpseudocode
112
113 \TEXT{\ENDPROGRAM \ENDPROG} \ENDPROGRAM
114 \TEXT{\ENDALGORITHM \ENDALGO} \ENDALGORITHM
115 \TEXT{\ENDPROCEDURE \ENDPROC} \ENDPROCEDURE
116 \TEXT{\ENDFUNCTION \ENDFUNC \ENDFN} \ENDFUNCTION
117 \TEXT{\ENDCLASS} \ENDCLASS
118
119 They are used like this:
120
121 .. code-block:: algpseudocode
122
123 \TEXT{\CLASS{Foo Bar Class\} ... \END CLASS {Foo Bar Class\}} \TEXT{yields} \CLASS{Foo Bar Class} ... \END CLASS {Foo Bar Class}
124
125 .. seealso:: Syntax variants: `END-Keywords`_
126
127
128 Without Parameters
129 ~~~~~~~~~~~~~~~~~~
130
131 "Normal" Keywords
132 '''''''''''''''''
133
134 .. code-block:: algpseudocode
135
136 \TEXT{\IF} \IF
137 \TEXT{\THEN} \THEN
138 \TEXT{\ELSE} \ELSE
139 \TEXT{\ELSEIF or \ELSIF or \ELIF} \ELSEIF \text{or} \ELSIF \text{or} \ELIF
140 \TEXT{\DO} \DO
141 \TEXT{\WHILE} \WHILE
142 \TEXT{\FORALL} \FORALL
143 \TEXT{\FOR} \FOR
144 \TEXT{\FROM} \FROM
145 \TEXT{\TO} \TO
146 \TEXT{\STEP} \STEP
147 \TEXT{\IN} \IN
148 \TEXT{\LOOP} \LOOP
149 \TEXT{\REPEAT} \REPEAT
150 \TEXT{\UNTIL} \UNTIL
151
152 \TEXT{\RETURN} \RETURN
153
154 \TEXT{\BEGIN} \BEGIN
155 \TEXT{\END} \END
156
157 \TEXT{\IS} \IS
158 \TEXT{\WITH} \WITH
159
160 \TEXT{\\REMARK or \\REM} \REMARK A comment with a sigil
161
162 ``\REMARK`` or ``\REM`` is special: all characters to the end of the
163 line are taken as comment; curly braces are not needed -- in fact:
164 they are interpreted as part of the comment.
165
166
167 END-Keywords
168 ''''''''''''
169
170 The separator character can be empty, a run of ASCII spaces, a run of TAB characters,
171 a single underscore ``_`` or a single hyphen ``-`` like:
172
173 ``\ENDIF``, ``\END IF``, ``\END-IF``, ``\END_IF`` or ``\END IF``
174
175
176 .. code-block:: algpseudocode
177
178 \text{\ENDIF} \ENDIF \rem empty
179
180 \text{\END IF} \END IF \rem a single space
181
182 \text{\END IF} \END IF \rem two spaces
183
184 \text{\END-IF} \END-IF \rem a single hyphen
185
186 \text{\END_IF} \END_IF \rem a single underscore
187
188 \text{\END IF} \END IF \rem a single TAB character
189
190 The list of END-keywords (here always just with ``-`` as separator):
191
192 .. code-block:: algpseudocode
193
194 \text{\END-PROGRAM \END-PROG} \END-PROGRAM
195 \text{\END-ALGORITHM \END-ALGO} \END-ALGORITHM
196 \text{\END-PROCEDURE \END-PROC} \END-PROCEDURE
197 \text{\END-FUNCTION \END-FUNC \END-FN} \END-FUNCTION
198 \text{\END-CLASS} \END-CLASS
199 \text{\END-IF} \END-IF
200 \text{\END-WHILE} \END-WHILE
201 \text{\END-FOR} \END-FOR
202 \text{\END-FORALL} \END-FORALL
203 \text{\END-LOOP} \END-LOOP
204
205
206 Explicit Token Types
207 ====================
208
209 Handle keywords and operators that are not handled by default or change
210 the default handling of some expressions.
211
212 `XX` represents a value in the :mod:`pygments.token.STANDARD_TYPES` dict.
213 Its corresponding token type (the associated `key` in this `dict`) is used as
214 token type.
215
216 ``\\tt-XX/SINGLE-CHAR``
217
218 no escaping needed
219
220 `SINGLE-CHAR` is a single character and can be *every* character
221 (including a carriage-return or line-feed)
222
223 ``\\ttx-XX{CHARACTERS}``
224
225 ``\\ttx-XX(CHARACTERS)``
226
227 ``\\ttx-XX[CHARACTERS]``
228
229 ``\\ttx-XX<CHARACTERS>``
230
231 ``\\ttx-XX<SEP>CHARACTERS<SEP>``
232
233 No escaping possible! There are enough alternatives available!
234
235 `SEP` is one of ``/:|=*+!\$~``.
236
237
238 Examples:
239
240 .. code-block:: algpseudocode
241
242 \text{• \\tt-kc/C} \tt-kc/C \rem C as Keyword.Constant
243 \text{• \\tt-ow/∈} \tt-ow/∈ \rem ∈ as Operator.Word
244 \text{• \\ttx-kc{A New Constant Keyword\}} \ttx-kc{A New Constant Keyword} \rem As a new Keyword.Constant
245 \text{• \\ttx-nv{A New Variable Name\}} \ttx-nv{A New Variable Name} \rem An explicit Name.Variable
246 \text{• \\ttx-k(∈ ∌)} \ttx-k(∈ ∌) \rem ∈ and ∌ as (ordinary) Keywords
247 \text{• \\ttx-o<∈ ∌>} \ttx-o<∈ ∌> \rem ∈ and ∌ as (ordinary) Operators
248 /*
249 * The line below has ∈_∌ as (peculiar) function name.
250 * Their params are automatic.
251 */
252 \text{• \\ttx-nf<∈_∌>(p1, p2)} \ttx-nf<∈_∌>(p1, p2)
253 /*
254 * The line below has ∈_∌ as (peculiar) decorator name (as used in Python).
255 * Their params are automatic.
256 */
257 \text{• \\ttx-nd[∈_∌](p1, p2)} \ttx-nd[∈_∌](p1, p2)
258 /*
259 * This is a non-existing token type: you get some generic error marking
260 * with a Generic.Error token and no expansion.
261 */
262 \text{• \\ttx-NON-EXISTING[∈_∌](p1, p2)} \ttx-NON_EXISTING[∈_∌](p1, p2)
263
264 .. note:: Explicit token types are **case-sensitive**.
265
266
267 Customized Lexers in Sphinx
268 ===========================
269
270 Defining lexers with non-default options in Sphinx can be done in its
271 configuration file :file:`conf.py`:
272
273 .. code-block:: python
274
275 from functools import partial
276 from pygments_lexer_pseudocode2.algpseudocode import AlgPseudocodeLexer
277
278 def setup(app):
279
280 #
281 # Add a custom lexer: AlgPseudocodeLexer with custom init
282 # option "no_end".
283 #
284 # In modern Sphinx versions given lexer must be callable and may
285 # not be a lexer instance. So use an indirection with "partial"
286 # here.
287 #
288 app.add_lexer("noend-algpseudocode",
289 partial(AlgPseudocodeLexer, no_end=True))
290
291 Similarily it works for custom styles and filters.
292
293 For older Sphinx versions your mileage may vary.