Debian Codegraph @

texmf-dist/source/latex/grading-scheme/grading-scheme.dtx

raw
1 % \iffalse meta-comment
2 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3 % This LaTeX docstrip file is free software and is licensed under the %
4 % Latex Project Public License v1.3c, or (at your choice) any later version %
5 % The latest version of the license can be found at %
6 % https://www.latex-project.org/lppl/lppl-1-3c.txt %
7 % You may use it freely for your purposes. %
8 % The packages home is https://ctan.org/pkg/grading-scheme %
9 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
10 %<*internal>
11 % \begingroup
12 % \input docstrip.tex
13 % \keepsilent
14 % \preamble
15 % ___________________________________________________________
16 % The grading-scheme package
17 % Copyright (C) 2022 Maximilian Kessler
18 % License information appended.
19 %
20 % \endpreamble
21 % \postamble
22 %
23 % Copyright 2022 Maximilian Kessler <[email protected]>
24 %
25 % Distributable under the LaTeX Project Public License,
26 % version 1.3c or higher (your choice). The latest version of
27 % this license is at: http://www.latex-project.org/lppl.txt
28 %
29 % This work is "author-maintained"
30 %
31 % This work consists of the files grading-scheme.dtx,
32 % grading-scheme.ins, a README file
33 % and the derived files grading-scheme.sty and grading-scheme.pdf.
34 %
35 % \endpostamble
36 % \askforoverwritefalse
37 %
38 % \generate{\file{grading-scheme.sty}{\from{grading-scheme.dtx}{package}}}
39 %
40 % \def\tmpa{plain}
41 % \ifx\tmpa\fmtname\endgroup\expandafter\bye\fi
42 % \endgroup
43 %</internal>
44 %
45 %<package>\ProvidesExplPackage {grading-scheme} {2022/02/24} {0.1.1}
46 %<package> {Typeset grading schemes in tabular format}
47 %
48 %<*driver>
49 \documentclass[full]{l3doc}
50 \usepackage{grading-scheme}
51 \begin{document}
52 \RecordChanges
53 \DocInput{grading-scheme.dtx}
54 \end{document}
55 %</driver>
56 % \fi
57 %
58 % \changes{0.1}{2022/02/22}{Initial release}
59 % \changes{0.1.1}{2022/02/24}{Bug fix (thanks to Denis Bitouzé), typos.}
60 %
61 %
62 %
63 %
64 % \title{The \pkg{grading-scheme} package}
65 %
66 % \author{Maximilian Keßler\thanks{[email protected]}}
67 % \date{Released 2022/02/24\\ \vskip 1.5em {\small version 0.1.1}}
68 %
69 % \maketitle
70 %
71 % \begin{abstract}
72 % This package aims at an easy-to-use interface to typeset
73 % grading schemes in tabular format, in particular grading-schemes
74 % of exercises of mathematical olympiads where multiple
75 % solutions have to be graded and might offer mutual
76 % exclusive ways of receiving points.
77 % \end{abstract}
78 %
79 % \setcounter{tocdepth}{2}
80 % \tableofcontents
81 %
82 % \begin{documentation}
83 %
84 % \section{General notions}
85 %
86 % Probably, an example is fitting best at this point.
87 % If you want to set up a grading scheme, with the \pkg{grading-scheme} package
88 % all you have to do to get the output of \autoref{tab:grading-scheme}
89 % is type the following:
90 %
91 % \iffalse
92 % Since the docstrip format already uses the pipe character
93 % to denote verbatim, we actually use \entry to typeset the table.
94 % In a user document, one could of course use the pipe syntax again.
95 % \fi
96 % \begin{table}[tp]
97 % \centering
98 % \begin{gradingscheme}{sum}
99 % \entry{At least one correct solution}{1}
100 % \entry{All correct solutions}{1}
101 % \begin{block}{max}
102 % \begin{block}[Uniqueness proofs]{max}
103 % \begin{block}[First solution]{sum}
104 % \entry{Show that either $4 \mid p - 2$ or $3 \mid p - 4$.}{3}
105 % \entry{Show that $m = 5$}{2}
106 % \entry{Show that $ n = 4 $}{1}
107 % \entry{Conclude solutions}{1}
108 % \end{block}
109 % \begin{block}[Second solution]{sum}
110 % \entry{Show that $p$ is even}{2}
111 % \entry{Reduce to at most 30 candidates}{3}
112 % \entry{Test all candidates}{2}
113 % \end{block}
114 % \end{block}
115 % \begin{block}{min(2)}
116 % \begin{block}[Plausible Arguments]{sum}
117 % \entry{plausible argument that there are finitely many solutions}{1}
118 % \entry{suggestion that divisibility by 4 is useful}{1}
119 % \entry{suggesting that not both of $m$, $n$ can be 'large'.}{1}
120 % \end{block}
121 % \end{block}
122 % \end{block}
123 % \end{gradingscheme}
124 % \caption{Example output of a grading scheme.}
125 % \label{tab:grading-scheme}
126 % \end{table}
127 %
128 % \begin{verbatim}
129 % \begin{gradingscheme}{sum}
130 % | At least one correct solution & 1
131 % | All correct solutions & 1
132 % \begin{block}{max}
133 % \begin{block}[Uniqueness proofs]{max}
134 % \begin{block}[First solution]{sum}
135 % | Show that either $4 \mid p - 2$ or $3 \mid p - 4$. & 3
136 % | Show that $m = 5$ & 2
137 % | Show that $ n = 4 $ & 1
138 % | Conclude solutions & 1
139 % \end{block}
140 % \begin{block}[Second solution]{sum}
141 % | Show that $p$ is even & 2
142 % | Reduce to at most 30 candidates & 3
143 % | Test all candidates & 2
144 % \end{block}
145 % \end{block}
146 % \begin{block}{min(2)}
147 % \begin{block}[Plausible Arguments]{sum}
148 % | plausible argument that there are finitely many solutions & 1
149 % | suggestion that divisibility by 4 is useful & 1
150 % | suggesting that not both of $m$, $n$ can be 'large'. & 1
151 % \end{block}
152 % \end{block}
153 % \end{block}
154 % \end{gradingscheme}
155 % \end{verbatim}
156 %
157 % Note in particular that the correct width of the rows and columns
158 % are automatically adjusted.
159 %
160 %
161 % For us, a grading scheme consists of several statements, each worth
162 % some specific number of points, that will be combined into a final
163 % number of points using a nested expression of operations, typically
164 % sums, maximums or minimus.
165 %
166 % An abstract grammar defining our notions is defined in
167 % \autoref{tab:grading-scheme-grammar}.
168 % The meanings of \meta{balanced text} and \meta{number} are
169 % as usual.
170 %
171 % \begin{table}[htpb]
172 % \centering
173 % \begin{tabular}{r@{\;:=\;}l}
174 % grading scheme & block \\
175 % block & [\meta{block description}], \meta{block operation}, \meta{element list} \\
176 % element list & \meta{element} $\mid$ \meta{element} : \meta{element list} \\
177 % element & \meta{block} $\mid$ \meta{entry} \\
178 % entry & \meta{entry description}, \meta{entry points} \\
179 % block description & \meta{balanced text} \\
180 % block operation & \meta{balanced text} \\
181 % entry description & \meta{balanced text} \\
182 % entry points & \meta{number} \\
183 % \end{tabular}
184 % \caption{Abstract grammer for a grading scheme}
185 % \label{tab:grading-scheme-grammar}
186 % \end{table}
187 %
188 % The package facilitates specifying a grading scheme according to this grammar
189 % and typesets these.
190 %
191 % \section{Usage}
192 %
193 % Load the package as usual by
194 % \begin{verbatim}
195 % \usepackage[pipe]{grading-scheme}
196 % \end{verbatim}
197 %
198 % The |pipe| option is of course optional and the only currently supported option.
199 % It activates the pipe syntax explained later.
200 %
201 % \begin{environment}{gradingscheme}
202 % \begin{syntax}
203 % \cs{begin}\{gradingscheme\}\oarg{description text}\Arg{operator}
204 % \cs{end}\{gradingscheme\}
205 % \end{syntax}
206 % The main environment provided by this package.
207 % Inside the grading scheme, any number of blocks and entries can
208 % be specified.
209 % The grading scheme environment will act like the outer-most block
210 % and typeset all its contents.
211 %
212 % Grading schemes cannot contain each other. As they are implemented
213 % as |tabular|s, you can (and maybe should) put a grading scheme
214 % into a |table| environment as if it were a regular |tabular|.
215 %
216 % \begin{texnote}
217 % Actually, the gradingscheme environment just sets up some hooks
218 % that further block environments and entries will fill
219 % and typesets these at the end of the environment.
220 %
221 % You could technically put any regular text inside the grading
222 % scheme and this will be typeset as if it had been specified
223 % before the grading scheme. However, this is definitely not
224 % recommended.
225 % \end{texnote}
226 % \end{environment}
227 %
228 % \begin{environment}{block}
229 % \begin{syntax}
230 % \cs{begin}\{block\}\oarg{description text}\Arg{operator}
231 % \cs{end}\{block\}
232 % \end{syntax}
233 %
234 % The \meta{description text} will be shown in a separate row
235 % on top of the block. If not specfied, no such row is inserted.
236 % The \meta{operator} is printed in small capitals (and rotated)
237 % in a column that spans the left side of the block,
238 % indicating that this operation is applied to the block.
239 %
240 % The block will be an element of the outer block or
241 % grading scheme it is contained in.
242 %
243 % Inside the block, any number of blocks or entries
244 % can be specified (in order) that will be typeset
245 % as members of this block.
246 %
247 % A block environment can only be used inside a gradingscheme.
248 % Block environments can contain each other in balanced form.
249 % \end{environment}
250 %
251 % \begin{function}{\entry}
252 % \begin{syntax}
253 % \cs{entry}\Arg{entry description}\Arg{points}
254 % \end{syntax}
255 %
256 % Specifies an entry with given description and points.
257 % The entry is typeset as part of the block/grading scheme
258 % containing it.
259 % \end{function}
260 %
261 % \begin{function}{|}
262 % \begin{syntax}
263 % $\mid$ \meta{entry description} \& \meta{points} \textbackslash{}n
264 % \end{syntax}
265 % This is an alternative form to specify an entry. The |\n|
266 % is to be interpreted as a newline in the source file, so $\mid$ reads
267 % until the end of the line.
268 %
269 % This is equivalent to calling \cs{entry}\Arg{entry description}\Arg{points}
270 %
271 % The package option |pipe| has to be specified to activate this
272 % syntax.
273 %
274 % \begin{texnote}
275 % The $\mid$ character (pipe) is made an active character for the scope
276 % of each gradingscheme environment.
277 % Thus, this syntax only works if the gradingscheme is read in
278 % expansion mode by \LaTeX{}, since otherwise the category code
279 % will be messed up.
280 % \end{texnote}
281 % \end{function}
282 %
283 %
284 % \section{\LaTeX3 interface}
285 %
286 % There is also a \LaTeX3 interface for dealing with this package
287 % that can deal with all of the mentioned notions separately,
288 % technically allowing you to combine them in other ways or formatting
289 % them into your custom tables.
290 %
291 % These functions are for now not documented separately, since the author
292 % thinks that such use cases would be rather rare.
293 %
294 % The \LaTeX3 interface is, however, \emph{not} considered to be stable
295 % yet, so if you really have to rely on this, feel free to contact
296 % the author.
297 %
298 % \PrintChanges
299 %
300 % \end{documentation}
301 %
302 %
303 % \begin{implementation}
304 %
305 % \section{\pkg{grading-scheme} implementation}
306 % \begin{macrocode}
307 %<*package>
308 % \end{macrocode}
309 %
310 % \begin{macrocode}
311 %<@@=grading_scheme>
312 % \end{macrocode}
313 %
314 % \subsection{Dependencies and options}
315 %
316 % Currently, there is only one option
317 %
318 % \begin{variable}{\g_@@_pipe_syntax_bool}
319 %
320 % This will toggle the pipe syntax option of the package.
321 %
322 % \begin{macrocode}
323 \bool_new:N \g_@@_pipe_syntax_bool
324 % \end{macrocode}
325 % \end{variable}
326 %
327 %
328 % \begin{macrocode}
329 \keys_define:nn { grading-scheme }
330 {
331 pipe .bool_gset:N = \g_@@_pipe_syntax_bool,
332 pipe .default:n = { true },
333 unknown .code:n =
334 {
335 \msg_error:nnn { grading-scheme } { unknown-option} { \l_keys_key_str }
336 }
337 }
338 \msg_new:nnn { grading-scheme } { unknown-option}
339 {
340 Unknown ~ option ~ '#1'.
341 }
342 \RequirePackage { l3keys2e }
343 \ProcessKeysOptions { grading-scheme }
344 \RequirePackage{multirow}
345 \RequirePackage{rotating}
346 % \end{macrocode}
347 %
348 % \subsection{A simple logging module}
349 %
350 % \begin{macrocode}
351 %<*log>
352 % \end{macrocode}
353 %
354 % We provide a simple log/debugging facility for this package.
355 %
356 % \begin{variable}{\g_@@_log_depth_int}
357 % Stores the log depth for indentation in the log file.
358 % \begin{macrocode}
359 \int_new:N \g_@@_log_depth_int
360 % \end{macrocode}
361 % \end{variable}
362 %
363 % \begin{macro}{\@@_log_incr:}
364 %
365 % Increments the log depth
366 %
367 % \begin{macrocode}
368 \cs_new:Npn \@@_log_incr:
369 {
370 \int_gincr:N \g_@@_log_depth_int
371 }
372 % \end{macrocode}
373 % \end{macro}
374 %
375 %
376 % \begin{macro}{\@@_log_decr:}
377 %
378 % Decrements the log depth
379 %
380 % \begin{macrocode}
381 \cs_new:Npn \@@_log_decr:
382 {
383 \int_gdecr:N \g_@@_log_depth_int
384 }
385 % \end{macrocode}
386 % \end{macro}
387 %
388 %
389 % \begin{macro}{\@@_log:n, \@@_log:x}
390 %
391 % Logs to the terminal and log file using the current depth.
392 %
393 % \begin{macrocode}
394 \cs_new:Npn \@@_log:n #1
395 {
396 \iow_term:x
397 {
398 [gs] \prg_replicate:nn \g_@@_log_depth_int { . . }
399 \exp_not:n { #1 }
400 }
401 \iow_log:x
402 {
403 [gs] \prg_replicate:nn \g_@@_log_depth_int { . . }
404 \exp_not:n { #1 }
405 }
406 }
407 \cs_generate_variant:Nn \@@_log:n { x }
408 % \end{macrocode}
409 % \end{macro}
410 %
411 %
412 % \begin{macrocode}
413 %</log>
414 % \end{macrocode}
415 %
416 % \subsection{Wrappers}
417 %
418 % We provide some \LaTeX3 wrappers for private usage.
419 %
420 % \begin{macro}{\@@_multicolumn:nnn}
421 %
422 % Just a wrapper around \cs{multicolumn} from \LaTeXe.
423 %
424 % \begin{macrocode}
425 \cs_set_eq:NN \@@_multicolumn:nnn \multicolumn
426 % \end{macrocode}
427 % \end{macro}
428 %
429 % \begin{macro}{\@@_multirow:nnn}
430 %
431 % Just a wrapper around \cs{multirow} from \LaTeXe.
432 %
433 % \begin{macrocode}
434 \cs_set_eq:NN \@@_multirow:nnn \multirow
435 % \end{macrocode}
436 % \end{macro}
437 %
438 % \begin{macro}{\@@_cline:n, \@@_cline:nn}
439 %
440 % A wrapper around \cs{cline}.
441 %
442 % The second form takes the beginning and ending
443 % column as separate arguments.
444 %
445 % \begin{macrocode}
446 \cs_set_eq:NN \@@_cline:n \cline
447 \cs_new:Npn \@@_cline:nn #1 #2
448 {
449 \@@_cline:n { #1 - #2 }
450 }
451 % \end{macrocode}
452 % \end{macro}
453 %
454 % \begin{macro}{\@@_hline:}
455 %
456 % Wrapper for a \cs{hline}
457 %
458 % \begin{macrocode}
459 \cs_set_eq:NN \@@_hline: \hline
460 % \end{macrocode}
461 % \end{macro}
462 %
463 %
464 % \begin{macro}{\@@_rotatebox:nnn}
465 %
466 % Wrapper around rotatebox
467 %
468 % \begin{macrocode}
469 \cs_new:Npn \@@_rotatebox:nnn #1 %implicit #2, #3
470 {
471 \rotatebox [ #1 ]
472 }
473 % \end{macrocode}
474 % \end{macro}
475 %
476 %
477 % \subsection{Customizable backends}
478 %
479 % We set up some functions that will be used internally,
480 % but could technically be customized at some point.
481 % For now, these are just constants.
482 %
483 % \begin{macro}{\@@_points:n}
484 %
485 % Prints the number of points.
486 % Used in the last column of the grading scheme.
487 %
488 % \begin{macrocode}
489 \cs_new:Npn \@@_points:n #1
490 {
491 \textbf{ #1 ~ P. }
492 }
493 % \end{macrocode}
494 % \end{macro}
495 %
496 % \begin{macro}{\@@_operation:n}
497 %
498 % Prints an operation.
499 % Used in the leftmost column of a block.
500 %
501 % \begin{macrocode}
502 \cs_new:Npn \@@_operation:n #1
503 {
504 { \sc #1 }
505 }
506 % \end{macrocode}
507 % \end{macro}
508 %
509 %
510 % \subsection{Resources}
511 %
512 % \subsubsection{Some general thoughts}
513 %
514 % This is some general reasoning about why we model data structures
515 % as we do in this package, comparing parts of \LaTeX3 to plain |C| code.
516 %
517 % We have to model elements, blocks and entries here.
518 % \LaTeX3 provides some data structures for this,
519 % and we will use property-lists to model our data structures for this package.
520 %
521 % When thinking about what a property list is,
522 % a call to \cs{prop_new:N} essentially allocates some memory for us
523 % and makes our given argument a \emph{pointer} to a data structure
524 % that we refer to as a \enquote{property list}.
525 %
526 % We want to think of these as pointers since modifying a property list
527 % at some place really also modifies this property list at another,
528 % so these behave like pointers.
529 %
530 % Considering the grouping mechanism of \TeX,
531 % this is of course not quite right for local variables
532 % (we assume that in the \LaTeX3 spirit,
533 % all variables are either local or global once and for all,
534 % to avoid confusion)
535 % since these rather correspond to one pointer at each
536 % grouping level, where upon entering such a grouping
537 % level, the (new) pointer is initialized with a copy of the outer instance of
538 % the pointer and destroyed again when leaving the current grouping level.
539 %
540 % In this spirit, we really want to think of grouping levels as \emph{scopes}
541 % like in \texttt{C}.
542 %
543 % Considering functions now, a typical \LaTeX3 function has no return value
544 % (these would be functions with the |_p| predicate or |_use:| functions
545 % that leave contents in the input stream),
546 % since this is in general not desired.
547 % Rather, we pass pointers as a function argument and receive the desired
548 % \enquote{return value} as written into our given pointer (overwriting
549 % any prior data), which is also a common behaviour in large parts of |C|.
550 %
551 % Now, as mentioned earlier, data structures such as property queues are
552 % just pointers that refer to some tokens with specific internal structure.
553 % All functions dealing with such pointers have to ensure that these
554 % invariants remain satisfied, and this is what functions like
555 % \cs{prop_get:NnN} or \cs{prop_put:Nn} do.
556 % The key point here is that we refer to these structures only
557 % with pointers and do not deal with them directly.
558 % This is what gives us some very nice abstrict model,
559 % hiding the class invariants of a property queue from the user and providing
560 % high-level semantic access to such data structures.
561 %
562 % Just for completeness, we mention that this is not the case for \emph{all}
563 % data structures.
564 % For example, a |clist| has some structure that is well-known and can be
565 % dealt with by the user directly.
566 % That is why there are also |clist| commands acceptiong |n|-type arguments
567 % for dealing with a |clist|, but no such commands for property-lists, as
568 % they only use |N| and thus essentially pointers.
569 %
570 % If we want to model data structures now, especially ours from this package,
571 % we even want data structures containing other data structures.
572 % Although technically, storing all data of a grading scheme in a single macro
573 % would be possible, due to its recursive structure, parsing would be quite
574 % a challenge and possibly also rather slow.
575 % Also, this would require \emph{direct} access to the representation of blocks
576 % contained in this block, which is undesired.
577 %
578 % Compare this to the question of putting a property-list inside a property-list.
579 % Since there is no (semantic/provided) possibility of actually putting a
580 % property-list anywhere, we cannot store property-lists in property-lists
581 % directly.
582 % We can, however, store the name of a property list inside of another one,
583 % this amounts to actually storing the \emph{pointer} to the first list
584 % inside the second one.
585 %
586 % Now, back to our package, we essentially want to model blocks and alike
587 % as |C|-style |struct|s that contain \emph{pointers} to their elements
588 % and similar.
589 % The classic question of ownership arises in this context,
590 % so we would have to consider shallow or deep copies and a user
591 % has to watch out when dealing with our data structures.
592 %
593 % Since only a limited set of operations is needed in our case,
594 % we take a simple approach by saying that each struct owns
595 % all its contents, that is, owns everythin its data member pointers
596 % point to, also recursively.
597 % This essentially forbids shallow-copying (violating our assumption)
598 % but we do not need this here, so this is okay.
599 %
600 % Still, this hase some undesired consequences:
601 % Since in \LaTeX3 each pointer has some name, we need to construct
602 % a lot of pointers on the fly where we are not able to actually
603 % specify their names directly, so we have to indirectly deal with pointers.
604 % That means that we actually need double-pointers, i.e. local variables
605 % \emph{containing} pointers to the data structures we are actually interested
606 % in. This is what a |void**| would correspond to in |C|.
607 % Also, note that once we store a pointer to some element in a property
608 % queue (e.g. the name of the list of members when dealing with a block),
609 % we actually also need a |void**| when retrieving this value again from
610 % the property queue, since we return by pointer.
611 %
612 % Consequently, this leads to quite a lot of expansion-control when dealing
613 % with such pointers, and if not taking precautions, also to easy confusion
614 % about what is a pointer and what not.
615 %
616 % Our approach to tackle these problems is described in \autoref{subsec:pointers}.
617 %
618 % \subsection{Pointers}
619 % \label{subsec:pointers}
620 %
621 % This module should/will be reworked into an own package in the future.
622 % Also, there is no proper documentation for it apart from the comments
623 % in the implementation, since this is not meant to be used in other
624 % code than this package currently, nor regarded stable.
625 %
626 % We introduce a new data type of |pointer| and a new argument
627 % type of |P|. The argument type |P| shall indicate a single expansion
628 % \emph{with the assumption that this expansion will yield a single token}.
629 % So, from an implementation point of view, this is the same as an |o|-type
630 % argument, just with further restricted assumptions.
631 %
632 % This also enables us to generate |P| variant arguments from |N| variant
633 % macros. Compare this to the usual deprecation warning that \LaTeX3
634 % gives when generating an |o| variant from an |N|-type argument:
635 %
636 % \begin{verbatim}
637 % ! LaTeX3 Error: Variant form 'o' deprecated for base form '\foo:N'. One
638 % (LaTeX3) should not change an argument from type 'N' to type 'o':
639 % (LaTeX3) base form only accepts a single token argument.
640 % \end{verbatim}
641 %
642 %
643 % Since basically anything in \LaTeX3 is in fact a pointer, we will
644 % introduce the |pointer| structure with the |ptr| type (suffix)
645 % and actually mean that this is a |void**|.
646 %
647 % Thus, we introduce the following conventions:
648 % \begin{enumerate}
649 % \item
650 % A \TeX-pointer is a \TeX control sequence that represents
651 % some data.
652 % \item
653 % A |pointer| is a control sequence that
654 % expands to a single \TeX{} control sequence that is a
655 % \TeX-pointer.
656 % \item
657 % The \emph{name} of a |pointer| is the name of the control sequence
658 % representing it.
659 % Thus, such a name always ends with |_ptr| by convetion.
660 % \item
661 % A |ptr| is said to be |NULL| if its expansion yields an undefined
662 % \TeX{} control sequence.
663 % We also refer to this as a |nullptr|.
664 % \item
665 % A \emph{typed pointer} is a pointer where the underlying type is specified.
666 % By this, we mean that expanding the token exactly once yields a token
667 % representing a data structure of the type we said this pointer to have
668 % or that the pointer is |NULL|.
669 % \item
670 % A \emph{void pointer} shall be a pointer whose actual type is unknown.
671 % \item
672 % When a |ptr| is of type |type|, we denote these by the suffix
673 % |_type_ptr|.
674 % \item
675 % \emph{Dereferencing} a pointer amounts to expanding it exactly once.
676 % \item
677 % A |P|-type argument accepts a single token that has to be of type |ptr|.
678 % The token is expanded exactly once and then treated as an |N|-type argument
679 % in the corresponding function.
680 % \end{enumerate}
681 %
682 %
683 % \begin{variable}{\g__ptr_counter_int}
684 %
685 % Counts the number of pointers given by \cs{ptr_new:N}.
686 % This ensures that each pointer can have a unique name
687 % regardless of grouping.
688 %
689 % \begin{macrocode}
690 \int_new:N \g__ptr_counter_int
691 % \end{macrocode}
692 % \end{variable}
693 %
694 % \begin{variable}{\l__ptr_var_prefix_str}
695 %
696 % Stores the prefix of new pointer variables.
697 %
698 % \begin{macrocode}
699 \str_new:N \l__ptr_var_prefix_str
700 % \end{macrocode}
701 % \end{variable}
702 %
703 %
704 %
705 % \begin{macro}{\ptr_new:N}
706 % \begin{syntax}
707 % \cs{ptr_new:N}\meta{pointer}
708 % \end{syntax}
709 %
710 % Gives a new unique pointer that is |NULL|.
711 % Gives an error when the \meta{pointer} already exists.
712 % The pointer variable is created globally.
713 %
714 % \begin{macrocode}
715 \cs_new:Npn \ptr_new:N #1
716 {
717 \__ptr_get_var_prefix:NN #1 \l__ptr_var_prefix_str
718 \ptr_new:NVn #1 \l__ptr_var_prefix_str { any }
719 }
720 \cs_new:Npn \ptr_new:Nn #1 #2
721 {
722 \ptr_new:Nnn { #1 } { #2 } { any }
723 }
724 % ptr var, prefix, type
725 \cs_new:Npn \ptr_new:Nnn #1 #2 %i #3
726 {
727 \str_case:nnT
728 { #2 }
729 {
730 { l } { }
731 { g } { }
732 }
733 {
734 \tl_new:N #1
735 }
736 \__ptr_init:Nnn #1 { #2 } %i { #3 }
737 }
738 \cs_generate_variant:Nn \ptr_new:Nnn { N V n }
739 % ptr var, prefix, type
740 % assumes that the pointer name exists already in case of l or g prefix
741 \cs_new:Npn \__ptr_init:Nnn #1 #2 % implicit #3
742 {
743 \__ptr_get_var_prefix:NN #1 \l__ptr_var_prefix_str
744 \str_case:VnF
745 \l__ptr_var_prefix_str
746 {
747 { l }
748 {
749 \cs_set_eq:NN \__ptr_poly_tl_set:Nx \tl_set:Nx
750 }
751 { g }
752 {
753 \cs_set_eq:NN \__ptr_poly_tl_set:Nx \tl_gset:Nx
754 }
755 { c }
756 {
757 \cs_set_eq:NN \__ptr_poly_tl_set:Nx \tl_const:Nx
758 }
759 }
760 {
761 \str_show:N \l__ptr_var_prefix_str % TODO: show error
762 }
763 \__ptr_init_aux:Nnn #1 { #2 }
764 }
765 \cs_generate_variant:Nn \__ptr_init:Nnn { N V n }
766 % ptr var, prefix, type. assumes poly_tl_set:Nx has been set
767 \cs_new:Npn \__ptr_init_aux:Nnn #1 #2 #3
768 {
769 \__ptr_poly_tl_set:Nx #1
770 {
771 \exp_not:c
772 {
773 #2
774 __ptr__unique__
775 \int_use:N \g__ptr_counter_int
776 _
777 #3
778 }
779 }
780 \int_gincr:N \g__ptr_counter_int
781 }
782 \cs_generate_variant:Nn \__ptr_init:Nnn { N V n }
783 % \end{macrocode}
784 % \end{macro}
785 %
786 %
787 % \begin{macro}{\__ptr_get_var_prefix:NN}
788 %
789 % Gets the first character of the name of the variable given as |#1|.
790 % The first character is assumed to be one of |c|, |l| or |g| by
791 % usual naming conventions.
792 %
793 % \begin{macrocode}
794 \cs_new:Npn \__ptr_get_var_prefix:NN #1 #2
795 {
796 \tl_if_head_eq_charcode:fNTF { \cs_to_str:N #1 } l
797 {
798 \str_set:Nn #2 { l }
799 }
800 {
801 \tl_if_head_eq_charcode:fNTF { \cs_to_str:N #1 } g
802 {
803 \str_set:Nn #2 { g }
804 }
805 {
806 \tl_if_head_eq_charcode:fNTF { \cs_to_str:N #1 } c
807 {
808 \str_set:Nn #2 { c }
809 }
810 {
811 \msg_error:nnx { ptr } { variable-name-illegal-prefix }
812 {
813 \token_to_str:N #1
814 }
815 }
816 }
817 }
818 }
819 % \end{macrocode}
820 % \begin{macrocode}
821 \msg_new:nnnn { ptr } { variable-name-illegal-prefix }
822 {
823 Requested ~ new ~ pointer ~ '#1' ~ has ~ illegal ~ prefix.
824 }
825 {
826 Prefix ~ should ~ be ~ one ~ of ~ 'l', ~ 'g' ~ or ~ 'c'.
827 }
828 % \end{macrocode}
829 % \end{macro}
830 %
831 %
832 %
833 % \begin{macro}{\ptr_clear:N}
834 %
835 % Clears this pointer.
836 % This makes the pointer equivalent to a new |nullptr|.
837 %
838 % \begin{macrocode}
839 \cs_new:Npn \ptr_clear:N #1
840 {
841 \__ptr_get_var_prefix:NN #1 \l__ptr_var_prefix_str
842 \__ptr_init:NVn #1 \l__ptr_var_prefix_str { any }
843 }
844 \cs_new:Npn \ptr_clear:Nn #1 #2
845 {
846 \__ptr_init:Nnn #1 { #2 } { any }
847 }
848 % \end{macrocode}
849 % \end{macro}
850 %
851 % \begin{macro}{\ptr_set:NN}
852 %
853 % Sets the pointer to represent the given argument.
854 %
855 % \begin{macrocode}
856 \cs_set_eq:NN \ptr_set:NN \tl_set:Nn
857 % \end{macrocode}
858 % \end{macro}
859 %
860 % \begin{macro}{\ptr_set_eq:NN}
861 %
862 % Accepts two pointers.
863 % The first is set to be equivalent to the second.
864 %
865 % \begin{macrocode}
866 \cs_set_eq:NN \ptr_set_eq:NN \tl_set_eq:NN
867 % \end{macrocode}
868 % \end{macro}
869 %
870 %
871 % \begin{macro}{\ptr_use:N}
872 %
873 % Uses the pointer, i.e.~expands to the stored \TeX{}-pointer.
874 %
875 % \begin{macrocode}
876 \cs_set_eq:NN \ptr_use:N \tl_use:N
877 % \end{macrocode}
878 % \end{macro}
879 %
880 % \begin{macro}{\__ptr_check:N}
881 %
882 % Checks that the given argument is a pointer.
883 %
884 % \begin{macrocode}
885 \cs_new:Npn \__ptr_check:N #1
886 {
887 \tl_if_single:NF #1
888 {
889 \msg_error:nnx { ptr } { is-not-a-pointer }
890 {
891 \token_to_str:N #1
892 }
893 }
894 }
895 % \end{macrocode}
896 % \begin{macrocode}
897 \msg_new:nnn { ptr } { is-not-a-pointer }
898 {
899 The ~ control ~ sequence ~ '#1' ~ is ~ not ~ a ~ valid ~ pointer.
900 }
901 % \end{macrocode}
902 % \end{macro}
903 %
904 % \begin{macro}{\__ptr_check:NN}
905 %
906 % Checks that the second argument is a pointer.
907 %
908 % \begin{macrocode}
909 \cs_new:Npn \__ptr_check:NN #1 #2
910 {
911 \__ptr_check:N #2
912 #1 #2
913 }
914 % \end{macrocode}
915 % \end{macro}
916 %
917 % \begin{macro}{\__ptr_check:nN}
918 %
919 % Checks that the second argument is a pointer.
920 %
921 % \begin{macrocode}
922 \cs_new:Npn \__ptr_check:nN #1 #2
923 {
924 \__ptr_check:N #2
925 { #1 } #2
926 }
927 % \end{macrocode}
928 % \end{macro}
929 %
930 %
931 %
932 % \begin{variable}{\l__ptr_content_tl}
933 %
934 % Stores the (internal) \TeX-pointer
935 % of a |pointer|.
936 %
937 % \begin{macrocode}
938 \tl_new:N \l__ptr_content_tl
939 % \end{macrocode}
940 % \end{variable}
941 %
942 % \begin{macro}{\exp_args:NP, \exp_args:NNP, \exp_args:NNNP, \exp_args:NNNNP, \exp_args:NPP}
943 %
944 % Expands a pointer.
945 % This leaves the first tokens as a single token in the input
946 % stream, followed by the value of the pointer
947 % as a single token.
948 %
949 % If the last argument does not expand to
950 % a single token,
951 % an error is given.
952 %
953 % \begin{macrocode}
954 \cs_new:Npn \exp_args:NP #1 #2
955 {
956 \__ptr_check:N #2
957 \exp_last_unbraced:No #1 #2
958 }
959 \cs_new:Npn \exp_args:NNP #1 #2 #3
960 {
961 \__ptr_check:N #3
962 \exp_last_unbraced:NNo #1 #2 #3
963 }
964 \cs_new:Npn \exp_args:NNNP #1 #2 #3 #4
965 {
966 \__ptr_check:N #4
967 \exp_last_unbraced:NNNo #1 #2 #3 #4
968 }
969 \cs_new:Npn \exp_args:NNNNP #1 #2 #3 #4 #5
970 {
971 \__ptr_check:N #5
972 \exp_last_unbraced:NNNNo #1 #2 #3 #4 #5
973 }
974 \cs_new:Npn \exp_args:NPP #1 #2 #3
975 {
976 \__ptr_check:N #2
977 \__ptr_check:N #3
978 \exp_last_two_unbraced:Noo #1 #2 #3
979 }
980 % \end{macrocode}
981 % \end{macro}
982 %
983 %
984 % \begin{macro}[TF]{\ptr_if_null:N}
985 %
986 % Checkes if the pointer is |NULL|.
987 %
988 % \begin{macrocode}
989 \cs_new:Npn \ptr_if_null:NT
990 {
991 \exp_args:NP \cs_if_exist:NF
992 }
993 \cs_new:Npn \ptr_if_null:NF
994 {
995 \exp_args:NP \cs_if_exist:NT
996 }
997 \cs_new:Npn \ptr_if_null:NTF #1 #2 #3
998 {
999 \exp_args:NP \cs_if_exist:NTF #1 { #3 } { #2 }
1000 }
1001 % \end{macrocode}
1002 % \end{macro}
1003 %
1004 % \begin{macro}{\tl_set_eq:NP, \tl_set_eq:PN, \tl_set_eq:PP, \tl_use:P}
1005 % \begin{macro}{\exp_not:P}
1006 % \begin{macro}{\clist_new:P, \clist_put_right:Pn, \clist_gput_right:Pn, \clist_map_function:PN, \prop_show:P, \clist_show:P}
1007 %
1008 %
1009 % Just variants of \cs{tl_set_eq:NN} with indicated signature.
1010 %
1011 % \begin{macrocode}
1012 \cs_new:Npn \tl_set_eq:NP
1013 {
1014 \exp_args:NNP \tl_set_eq:NN
1015 }
1016 \cs_new:Npn \tl_set_eq:PN
1017 {
1018 \exp_args:NP \tl_set_eq:NN
1019 }
1020 \cs_new:Npn \tl_set_eq:PP
1021 {
1022 \exp_args:NPP \tl_set_eq:NN
1023 }
1024 \cs_new:Npn \tl_use:P
1025 {
1026 \exp_args:NP \tl_use:N
1027 }
1028 \cs_new:Npn \exp_not:P
1029 {
1030 \exp_args:NP\exp_not:N
1031 }
1032 \cs_new:Npn \clist_new:P
1033 {
1034 \exp_args:NP \clist_new:N
1035 }
1036 \cs_new:Npn \clist_show:P
1037 {
1038 \exp_args:NP \clist_show:N
1039 }
1040 \cs_new:Npn \clist_put_right:Pn
1041 {
1042 \exp_args:NP \clist_put_right:Nn
1043 }
1044 \cs_new:Npn \clist_gput_right:Pn
1045 {
1046 \exp_args:NP \clist_gput_right:Nn
1047 }
1048 \cs_new:Npn \clist_map_function:PN
1049 {
1050 \exp_args:NP \clist_map_function:NN
1051 }
1052 \cs_new:Npn \prop_show:P
1053 {
1054 \exp_args:NP \prop_show:N
1055 }
1056 % \end{macrocode}
1057 % \end{macro}
1058 % \end{macro}
1059 % \end{macro}
1060 %
1061 %
1062 %
1063 %
1064 % \begin{macro}{\ptr_show:N}
1065 %
1066 % Shows information about this pointer,
1067 % namely:
1068 %
1069 % If it is |NULL|, then it indicates this.
1070 % If it is not |NULL|, then the \TeX-pointer
1071 % and the contained contents of the \TeX-pointer
1072 % (in unexpanded form) are shown.
1073 %
1074 % \begin{macrocode}
1075 \cs_new:Npn \ptr_show:N #1
1076 {
1077 \__ptr_check:N #1
1078 \ptr_if_null:NTF #1
1079 {
1080 \tl_show:x
1081 {
1082 \token_to_str:N #1 -> \exp_not:P #1 = NULL
1083 }
1084 }
1085 {
1086 \tl_show:x
1087 {
1088 \token_to_str:N #1 -> \exp_not:P #1 -> \exp_args:NP \exp_not:V #1
1089 }
1090 }
1091 }
1092 % \end{macrocode}
1093 % \end{macro}
1094 %
1095 %
1096 % \subsection{Structs}
1097 %
1098 % We will model |C|-style |struct|s as property-lists in this package.
1099 % Each struct member is put into the property list, using its
1100 % 'name' as a key, and we store the corresponding contents there.
1101 %
1102 % We will also have a local variable named correspondingly for each
1103 % |struct| member. In case we deal with a struct and want to acces
1104 % its data, we load the values from the property-list into these
1105 % local variables.
1106 % Thus, the full information about a |struct| is contained in the
1107 % property-list, and we can work with them quite conveniently
1108 % when implementing functions.
1109 %
1110 %
1111 % \subsection{Entries}
1112 %
1113 % An entry is for us the following:
1114 %
1115 % \begin{verbatim}
1116 % struct Entry {
1117 % tl description;
1118 % int points;
1119 % }
1120 % \end{verbatim}
1121 %
1122 % \begin{macro}{\grading_scheme_entry_new:N, \grading_scheme_entry_clear:N, \grading_scheme_entry_set_eq:NN, \grading_scheme_entry_gclear:N, \grading_scheme_entry_gset_eq:NN}
1123 %
1124 % Do what their signature suggests.
1125 % We just forward them to the property lists.
1126 %
1127 % \begin{macrocode}
1128 \cs_set_eq:NN \grading_scheme_entry_new:N \prop_new:N
1129 \cs_set_eq:NN \grading_scheme_entry_clear:N \prop_clear:N
1130 \cs_set_eq:NN \grading_scheme_entry_set_eq:NN \prop_set_eq:NN
1131 \cs_set_eq:NN \grading_scheme_entry_gclear:N \prop_gclear:N
1132 \cs_set_eq:NN \grading_scheme_entry_gset_eq:NN \prop_gset_eq:NN
1133 % \end{macrocode}
1134 % \end{macro}
1135 %
1136 % \begin{variable}{\l_@@_entry_points_int, \l_@@_entry_description_tl}
1137 %
1138 % The mentioned local variables where we retrieve values.
1139 %
1140 % \begin{macrocode}
1141 \int_new:N \l_@@_entry_points_int
1142 \tl_new:N \l_@@_entry_description_tl
1143 % \end{macrocode}
1144 % \end{variable}
1145 %
1146 %
1147 % \begin{macro}{\grading_scheme_entry_set_description:Nn, \grading_scheme_entry_gset_description:Nn}
1148 %
1149 % Sets the description.
1150 %
1151 % \begin{macrocode}
1152 \cs_new:Npn \grading_scheme_entry_set_description:Nn #1 % implicit description
1153 {
1154 \prop_put:Nnn #1 { description }
1155 }
1156 \cs_new:Npn \grading_scheme_entry_gset_description:Nn #1 % implicit description
1157 {
1158 \prop_gput:Nnn #1 { description }
1159 }
1160 % \end{macrocode}
1161 % \end{macro}
1162 %
1163 %
1164 % \begin{macro}{\grading_scheme_entry_set_points:Nn, \grading_scheme_entry_gset_points:Nn}
1165 %
1166 % Sets the points.
1167 %
1168 % \begin{macrocode}
1169 \cs_new:Npn \grading_scheme_entry_set_points:Nn #1 #2
1170 {
1171 \prop_put:Nnx #1 { points } { \int_eval:n { #2 } }
1172 }
1173 \cs_new:Npn \grading_scheme_entry_gset_points:Nn #1 #2
1174 {
1175 \prop_gput:Nnn #1 { points } { \int_eval:n { #2 } }
1176 }
1177 % \end{macrocode}
1178 % \end{macro}
1179 %
1180 % \begin{macro}{\grading_scheme_entry_get_description:NN}
1181 %
1182 % Gets the description of the entry and stores it in |#2|.
1183 % The assignment is local.
1184 %
1185 % \begin{macrocode}
1186 \cs_new:Npn \grading_scheme_entry_get_description:NN #1 %implicit #2
1187 {
1188 \prop_get:NnN #1 { description }
1189 }
1190 % \end{macrocode}
1191 % \end{macro}
1192 %
1193 % \begin{macro}{\grading_scheme_entry_get_points:NN}
1194 %
1195 % Gets the points of the entry and stores it in |#2|.
1196 % The assignment is local.
1197 %
1198 % \begin{macrocode}
1199 \cs_new:Npn \grading_scheme_entry_get_points:NN #1 %implicit #2
1200 {
1201 \prop_get:NnN #1 { points }
1202 }
1203 % \end{macrocode}
1204 % \end{macro}
1205 %
1206 %
1207 % \begin{macro}{\@@_entry_load_points:N}
1208 %
1209 % Loads the points into the local variable
1210 %
1211 % \begin{macrocode}
1212 \cs_new:Npn \@@_entry_load_points:N #1
1213 {
1214 \grading_scheme_entry_get_points:NN #1 \l_@@_entry_points_int
1215 }
1216 % \end{macrocode}
1217 % \end{macro}
1218 %
1219 % \begin{macro}{\@@_entry_load_description:N}
1220 %
1221 % Loads the description of an entry
1222 %
1223 % \begin{macrocode}
1224 \cs_new:Npn \@@_entry_load_description:N #1
1225 {
1226 \grading_scheme_entry_get_description:NN #1 \l@@_entry_description_tl
1227 }
1228 % \end{macrocode}
1229 % \end{macro}
1230 %
1231 %
1232 % \begin{macro}{\grading_scheme_entry_format:NnnN, \grading_scheme_entry_gformat:NnnN,\grading_scheme_entry_format:PnnN, \grading_scheme_entry_gformat:PnnN}
1233 % \begin{syntax}
1234 % \cs{grading_scheme_entry_put:NnnN}\Arg{entry}\Arg{indent}\Arg{width}\Arg{tl var}
1235 % \end{syntax}
1236 %
1237 % Puts the formatted contents of the entry into the \meta{tl var}.
1238 % The \meta{indent} specify how many tabs will be inserted
1239 % before adding the contents.
1240 % The \meta{width} specifies how many columns this entry will occupy.
1241 % This \meta{width} has to be at least 2.
1242 %
1243 % An |\\| is inserted at the end of the entry.
1244 %
1245 % \begin{macrocode}
1246 \cs_new:Npn \grading_scheme_entry_format:NnnN
1247 {
1248 \cs_set_eq:NN \@@_tl_put_right:Nx \tl_put_right:Nx
1249 \@@_entry_format:NnnN
1250 }
1251 \cs_new:Npn \grading_scheme_entry_gformat:NnnN
1252 {
1253 \cs_set_eq:NN \@@_tl_put_right:Nx \tl_gput_right:Nx
1254 \@@_entry_format:NnnN
1255 }
1256 \cs_new:Npn \grading_scheme_entry_format:PnnN
1257 {
1258 \exp_args:NP \grading_scheme_entry_format:NnnN
1259 }
1260 \cs_new:Npn \grading_scheme_entry_gformat:PnnN
1261 {
1262 \exp_args:NP \grading_scheme_entry_gformat:NnnN
1263 }
1264 % \end{macrocode}
1265 % \end{macro}
1266 %
1267 % \begin{macro}{\@@_entry_format:NnnN, \@@_entry_format:PnnN}
1268 %
1269 % Aux function that assumes that \cs{@@_tl_put_right:Nx}
1270 % has been so to globally or locally putting into the token list.
1271 %
1272 % \begin{macrocode}
1273 \cs_new:Npn \@@_entry_format:NnnN #1 #2 #3 #4
1274 {
1275 %<*log>
1276 \@@_log:x
1277 { Formatting ~ entry ~ '\token_to_str:N #1' ~ into ~ '\token_to_str:N #4' with }
1278 \@@_log:n { indent = '#2' ~ and ~ width ~ '#3' }
1279 \prop_log:N #1
1280 \@@_log_incr:
1281 %</log>
1282 \@@_entry_assert_description:N #1 % implicitly loads value
1283 \@@_entry_assert_points:N #1 % implicitly loads value
1284 \@@_tl_put_right:Nx #4
1285 {
1286 \prg_replicate:nn { #2 } { & }
1287 \exp_not:N \@@_multicolumn:nnn
1288 {
1289 \int_eval:n { #3 -1 }
1290 }
1291 { l }
1292 {
1293 \exp_not:V \l_@@_entry_description_tl
1294 }
1295 &
1296 \exp_not:N \@@_points:n
1297 {
1298 \tl_use:N \l_@@_entry_points_int
1299 }
1300 \\
1301 }
1302 %<*log>
1303 \@@_log_decr:
1304 \@@_log:x { / Formatting ~ entry ~ '\token_to_str:N #1' }
1305 %</log>
1306 }
1307 \cs_new:Npn \@@_entry_forrmat:PnnN % implicit #1-4
1308 {
1309 \exp_args:NP \@@_entry_format:NnnN
1310 }
1311 % \end{macrocode}
1312 % \end{macro}
1313 %
1314 %
1315 %
1316 % \begin{macro}{\@@_entry_assert_description:N, \@@_entry_assert_points:N}
1317 %
1318 % These functions check the presence of values of an entry.
1319 % If an entry is absent, an error message is omitted.
1320 %
1321 % \begin{macrocode}
1322 \cs_new:Npn \@@_entry_assert_description:N #1
1323 {
1324 \@@_entry_load_description:N #1
1325 \quark_if_no_value:NT \l_@@_entry_description_tl
1326 {
1327 \msg_error:nnxxx { grading-scheme } { missing-value }
1328 { entry } { \token_to_str:N #1 } { description }
1329 }
1330 }
1331 \cs_new:Npn \@@_entry_assert_points:N #1
1332 {
1333 \@@_entry_load_points:N #1
1334 \quark_if_no_value:NT \l_@@_entry_points_int
1335 {
1336 \msg_error:nnxxx { grading-scheme } { missing-value }
1337 { entry } { \token_to_str:N #1 } { points }
1338 }
1339 }
1340 \msg_new:nnn { grading-scheme } { missing-value }
1341 {
1342 #1 ~ '#2' ~ has ~ no ~ #3.
1343 }
1344 % \end{macrocode}
1345 % \end{macro}
1346 %
1347 %
1348 % \subsection{Blocks}
1349 %
1350 % \subsubsection{Struct setting / reading}
1351 %
1352 % A \meta{block} is for us the following:
1353 %
1354 % \begin{verbatim}
1355 % struct Block {
1356 % clist* elements;
1357 % tl text;
1358 % tl operation;
1359 % }
1360 % \end{verbatim}
1361 %
1362 % \begin{macro}{\grading_scheme_block_new:N, \grading_scheme_block_clear:N, \grading_scheme_block_set_eq:NN, \grading_scheme_block_gclear:N, \grading_scheme_block_gset_eq:NN}
1363 %
1364 % Do what thear names suggest. We just forward these to the property lists.
1365 %
1366 % \begin{macrocode}
1367 \cs_set_eq:NN \grading_scheme_block_new:N \prop_new:N
1368 \cs_set_eq:NN \grading_scheme_block_clear:N \prop_clear:N
1369 \cs_set_eq:NN \grading_scheme_block_set_eq:NN \prop_gset_eq:NN
1370 \cs_set_eq:NN \grading_scheme_block_gclear:N \prop_gclear:N
1371 \cs_set_eq:NN \grading_scheme_block_gset_eq:NN \prop_gset_eq:NN
1372 % \end{macrocode}
1373 % \end{macro}
1374 %
1375 % \begin{variable}{\l_@@_block_elements_clist_ptr, \l_@@_block_description_tl, \l_@@_block_operation_tl}
1376 %
1377 % The mentioned local variables where we retrieve values.
1378 %
1379 % \begin{macrocode}
1380 \ptr_new:N \l_@@_block_elements_clist_ptr
1381 \tl_new:N \l_@@_block_description_tl
1382 \tl_new:N \l_@@_block_operation_tl
1383 % \end{macrocode}
1384 % \end{variable}
1385 %
1386 % \begin{macro}
1387 % {
1388 % \grading_scheme_block_set_description:Nn, \grading_scheme_block_gset_description:Nn,
1389 % \grading_scheme_block_set_operation_tl:Nn, \grading_scheme_block_gset_operation_tl:Nn,
1390 % \grading_scheme_block_set_elements:NN, \grading_scheme_block_gset_elements:NN,
1391 % \grading_scheme_block_set_elements:NP, \grading_scheme_block_gset_elements:NP,
1392 % }
1393 %
1394 % Set the description / operation or elements of the block.
1395 %
1396 % When setting elements, a \meta{clist var} is expected.
1397 %
1398 % \begin{macrocode}
1399 \cs_new:Npn \grading_scheme_block_set_description:Nn #1 % implicit description
1400 {
1401 \prop_put:Nnn #1 { description }
1402 }
1403 \cs_new:Npn \grading_scheme_block_gset_description:Nn #1 % implicit description
1404 {
1405 \prop_gput:Nnn #1 { description }
1406 }
1407 \cs_new:Npn \grading_scheme_block_set_operation:Nn #1 % implicit operation
1408 {
1409 \prop_put:Nnn #1 { operation }
1410 }
1411 \cs_new:Npn \grading_scheme_block_gset_operation:Nn #1 % implicit operation
1412 {
1413 \prop_gput:Nnn #1 { operation }
1414 }
1415 \cs_new:Npn \grading_scheme_block_set_elements:NN #1 % implicit elements clist
1416 {
1417 \prop_put:Nnn #1 { elements }
1418 }
1419 \cs_new:Npn \grading_scheme_block_gset_elements:NN #1 % implicit elements clist
1420 {
1421 \prop_gput:Nnn #1 { elements }
1422 }
1423 \cs_new:Npn \grading_scheme_block_set_elements:NP
1424 {
1425 \exp_args:NNP \grading_scheme_block_set_elements:NN
1426 }
1427 \cs_new:Npn \grading_scheme_block_gset_elements:NP
1428 {
1429 \exp_args:NNP \grading_scheme_block_gset_elements:NN
1430 }
1431 % \end{macrocode}
1432 % \end{macro}
1433 %
1434 % \begin{macro}{\grading_scheme_block_get_description:NN, \grading_scheme_block_get_operation:NN, \grading_scheme_block_get_elements:NN}
1435 %
1436 % \begin{syntax}
1437 % \cs{grading_scheme_block_get_description:NN}\meta{block var}\meta{tl var}
1438 % \cs{grading_scheme_block_get_operation:NN}\meta{block var}\meta{tl var}
1439 % \cs{grading_scheme_block_get_elements:NN}\meta{block var}\meta{clist ptr}
1440 % \end{syntax}
1441 %
1442 % Get access to the members of the block.
1443 % The assignment is local.
1444 % The returned values might be \cs{q_no_value}
1445 % if no value is present.
1446 %
1447 % \begin{macrocode}
1448 \cs_new:Npn \grading_scheme_block_get_description:NN #1 % implicit #2
1449 {
1450 \prop_get:NnN #1 { description }
1451 }
1452 \cs_new:Npn \grading_scheme_block_get_operation:NN #1 % implicit #2
1453 {
1454 \prop_get:NnN #1 { operation }
1455 }
1456 \cs_new:Npn \grading_scheme_block_get_elements:NN #1 % implicit #2
1457 {
1458 \prop_get:NnN #1 { elements }
1459 }
1460 % \end{macrocode}
1461 % \end{macro}
1462 %
1463 % \begin{macro}{\@@_block_load_description:N, \@@_block_load_operation:N, \@@_block_load_elements:NN}
1464 %
1465 % Loads the members into the corresponding local variables.
1466 %
1467 % \begin{macrocode}
1468 \cs_new:Npn \@@_block_load_description:N #1
1469 {
1470 \grading_scheme_block_get_description:NN #1 \l_@@_block_description_tl
1471 }
1472 \cs_new:Npn \@@_block_load_operation:N #1
1473 {
1474 \grading_scheme_block_get_operation:NN #1 \l_@@_block_operation_tl
1475 }
1476 \cs_new:Npn \@@_block_load_elements:N #1
1477 {
1478 \grading_scheme_block_get_elements:NN #1 \l_@@_block_elements_clist_ptr
1479 }
1480 % \end{macrocode}
1481 % \end{macro}
1482 %
1483 %
1484 %
1485 % \begin{macro}{\@@_block_ensure_elements:N}
1486 %
1487 % Ensures that this block has an elements attribute that is a valid
1488 % clist pointer.
1489 %
1490 % If no value is present, or the pointer is |NULL|,
1491 % a pointer and/or the clist variable
1492 % are created.
1493 %
1494 % \begin{macrocode}
1495 \cs_new:Npn \@@_block_ensure_elements:N % implicit #1
1496 {
1497 \cs_set_eq:NN
1498 \@@_block_set_elements_optg:NP
1499 \grading_scheme_block_set_elements:NP
1500 \@@_block_ensure_elements_aux:nN { l }
1501 }
1502 \cs_new:Npn \@@_block_gensure_elements:N % implicit #1
1503 {
1504 \cs_set_eq:NN
1505 \@@_block_set_elements_optg:NP
1506 \grading_scheme_block_gset_elements:NP
1507 \@@_block_ensure_elements_aux:nN { g } %i #1
1508 }
1509 % prefix, block
1510 % assumes that \@@_block_set_elements_optg:NP has been
1511 \cs_new:Npn \@@_block_ensure_elements_aux:nN #1 #2
1512 {
1513 \@@_block_load_elements:N #2
1514 \quark_if_no_value:NT \l_@@_block_elements_clist_ptr
1515 {
1516 \ptr_clear:Nn \l_@@_block_elements_clist_ptr { #1 }
1517 \@@_block_set_elements_optg:NP
1518 #2
1519 \l_@@_block_elements_clist_ptr
1520 }
1521 \ptr_if_null:NT \l_@@_block_elements_clist_ptr
1522 {
1523 \clist_new:P \l_@@_block_elements_clist_ptr
1524 }
1525 }
1526 % \end{macrocode}
1527 % \end{macro}
1528 %
1529 %
1530 % \begin{macro}{\grading_scheme_block_add_element:NN, \grading_scheme_block_gadd_element:NN, \grading_scheme_block_add_element:PP, \grading_scheme_block_gadd_element:PP, \grading_scheme_block_add_element:PN, \grading_scheme_block_gadd_element:PN}
1531 % \begin{syntax}
1532 % \cs{grading_scheme_block_add_element:NN}\meta{block var}\meta{element var}
1533 % \end{syntax}
1534 %
1535 % Add an element to the block.
1536 %
1537 % \begin{macrocode}
1538 \cs_new:Npn \grading_scheme_block_add_element:NN #1 % implicit element
1539 {
1540 \@@_block_ensure_elements:N #1 % also loads local variable
1541 \clist_put_right:Pn \l_@@_block_elements_clist_ptr
1542 }
1543 \cs_new:Npn \grading_scheme_block_gadd_element:NN #1 % implicit element
1544 {
1545 \@@_block_gensure_elements:N #1 % also loads local variable
1546 \clist_gput_right:Pn \l_@@_block_elements_clist_ptr
1547 }
1548 \cs_new:Npn \grading_scheme_block_add_element:PP
1549 {
1550 \exp_args:NPP \grading_scheme_block_add_element:NN
1551 }
1552 \cs_new:Npn \grading_scheme_block_gadd_element:PP
1553 {
1554 \exp_args:NPP \grading_scheme_block_gadd_element:NN
1555 }
1556 \cs_new:Npn \grading_scheme_block_add_element:PN
1557 {
1558 \exp_args:NP \grading_scheme_block_add_element:NN
1559 }
1560 \cs_new:Npn \grading_scheme_block_gadd_element:PN
1561 {
1562 \exp_args:NP \grading_scheme_block_gadd_element:NN
1563 }
1564 % \end{macrocode}
1565 % \end{macro}
1566 %
1567 % \subsubsection{Formatting blocks}
1568 %
1569 %
1570 % \begin{macro}{\grading_scheme_block_format:NnnnN, \grading_scheme_block_gformat:NnnnN, \grading_scheme_block_format:PnnnN, \grading_scheme_block_gformat:PnnnN}
1571 %
1572 % \begin{syntax}
1573 % \cs{grading_scheme_block_format:NnnnN}\meta{block var}\Arg{indent}\Arg{width}\Arg{indent first row}\meta{tl var}
1574 % \end{syntax}
1575 %
1576 % Formats this block and puts the control sequence into \meta{tl var}.
1577 %
1578 % The \meta{indent} and \meta{width} work as in \cs{grading_scheme_entry_format:NnnN}.
1579 %
1580 % \meta{indent first row} can be any \meta{boolean expression} and indicates
1581 % if the first row is also indented.
1582 % Set this to false to start the block in a row of the tabular that already
1583 % has contents.
1584 %
1585 % \begin{macrocode}
1586 \cs_new:Npn \grading_scheme_block_format:NnnnN %implicit #1-5
1587 {
1588 \cs_set_eq:NN \@@_tl_put_right:Nx \tl_put_right:Nx
1589 \cs_set_eq:NN \@@_element_format_optg:NnnnN \grading_scheme_element_format:NnnnN
1590 \cs_set_eq:NN \@@_tl_set:Nn \tl_set:Nn
1591 \@@_block_format:NnnnN
1592 }
1593 \cs_new:Npn \grading_scheme_block_gformat:NnnnN %implicit #1-5
1594 {
1595 \cs_set_eq:NN \@@_tl_put_right:Nx \tl_gput_right:Nx
1596 \cs_set_eq:NN \@@_element_format_optg:NnnnN \grading_scheme_element_gformat:NnnnN
1597 \cs_set_eq:NN \@@_tl_set:Nn \tl_gset:Nn
1598 \@@_block_format:NnnnN
1599 }
1600 \cs_new:Npn \grading_scheme_block_format:PnnnN % implicit #1-5
1601 {
1602 \exp_args:NP
1603 \grading_scheme_block_format:NnnnN
1604 }
1605 \cs_new:Npn \grading_scheme_block_gformat:PnnnN % implicit #1-5
1606 {
1607 \exp_args:NP
1608 \grading_scheme_block_gformat:NnnnN
1609 }
1610 % \end{macrocode}
1611 % \end{macro}
1612 %
1613 %
1614 % For formatting the block, we need some local variables:
1615 %
1616 %
1617 % \begin{variable}{\l_@@_block_indent_bool}
1618 %
1619 % Controls whether the \cs{@@_block_indent:nN} macro
1620 % will actually perform an indent.
1621 %
1622 % \begin{macrocode}
1623 \bool_new:N \l_@@_block_indent_bool
1624 % \end{macrocode}
1625 % \end{variable}
1626 %
1627 % \begin{variable}{\@@_block_height_int}
1628 %
1629 % Locally stores the height of the block to be typeset.
1630 %
1631 % \begin{macrocode}
1632 \int_new:N \l_@@_block_height_int
1633 % \end{macrocode}
1634 % \end{variable}
1635 %
1636 %
1637 %
1638 % \begin{macro}{\@@_block_format:NnnnN, \@@_block_format:PnnnN}
1639 %
1640 % Aux function.
1641 % Assumes that \cs{@@__tl_put_right:Nx}
1642 % has been set properly.
1643 %
1644 % \begin{macrocode}
1645 \cs_new:Npn \@@_block_format:NnnnN #1 #2 #3 #4 #5
1646 {
1647 %<*log>
1648 \@@_log:x
1649 {
1650 Formatting ~ block ~ '\token_to_str:N #1' ~ into ~ '\token_to_str:N #5'
1651 ~ with ~ indent ='#2', ~ width ~ '#3' ~ and ~ first ~
1652 row = '\bool_to_str:n { #4 }'
1653 }
1654 \prop_log:N #1
1655 \@@_block_load_elements:N #1
1656 \exp_args:NP \clist_log:N \l_@@_block_elements_clist_ptr
1657 \@@_log_incr:
1658 %</log>
1659 % \end{macrocode}
1660 % We need grouping here so that our indentation boolean
1661 % is not messed up by recursive calls:
1662 % \begin{macrocode}
1663 \bool_set:Nn \l_@@_block_indent_bool { #4 && \c_true_bool }
1664 \group_begin:
1665 \@@_block_load_description:N #1
1666 \grading_scheme_block_get_height:NN #1 \l_@@_block_height_int
1667 % \end{macrocode}
1668 % We now format the description of the block if a value is present.
1669 % \begin{macrocode}
1670 \quark_if_no_value:NF \l_@@_block_description_tl
1671 {
1672 \@@_block_indent:nN { #2 } #5
1673 \@@_tl_put_right:Nx #5
1674 {
1675 \exp_not:N \@@_multicolumn:nnn
1676 {
1677 \int_eval:n { #3 }
1678 }
1679 { l| }
1680 {
1681 \exp_not:V \l_@@_block_description_tl
1682 }
1683 \\
1684 \exp_not:N \@@_cline:nn
1685 {
1686 \int_eval:n { #2 + 2 }
1687 }
1688 {
1689 \int_eval:n { #2 + #3 }
1690 }
1691 }
1692 }
1693 % \end{macrocode}
1694 % Now, we have to format the operation of this block.
1695 % This is a multirow with rotated description
1696 % \begin{macrocode}
1697 \@@_block_indent:nN { #2 } #5
1698 \@@_block_assert_operation:N #1
1699 \@@_tl_put_right:Nx #5
1700 {
1701 \exp_not:N \@@_multirow:nnn
1702 {
1703 \int_eval:n { \int_use:N \l_@@_block_height_int - 1 }
1704 }
1705 { * }
1706 {
1707 \exp_not:N \@@_rotatebox:nnn
1708 { origin = c }
1709 { 90 }
1710 {
1711 \exp_not:N \@@_operation:n
1712 {
1713 \exp_not:V \l_@@_block_operation_tl
1714 }
1715 }
1716 }
1717 &
1718 }
1719 % \end{macrocode}
1720 % The first element of our block must not be indented:
1721 % \begin{macrocode}
1722 \bool_set_false:N \l_@@_block_indent_bool
1723 % \end{macrocode}
1724 % Now, we want to recursively typeset all elements of this block.
1725 % We need a customized function for this to map over the elements.
1726 % \begin{macrocode}
1727 \cs_set:Npn \@@_block_format_element:N ##1
1728 {
1729 \@@_element_format_optg:NnnnN
1730 ##1
1731 { #2 + 1 } % indent is one more that the current block
1732 { #3 - 1 } % width is one less than current block
1733 { \l_@@_block_indent_bool }
1734 #5
1735 % \end{macrocode}
1736 % This ensures that the second and all further elements will get indented:
1737 % \begin{macrocode}
1738 \bool_set_true:N \l_@@_block_indent_bool
1739 }
1740 \@@_block_ensure_elements:N #1 % load + sanitize elements
1741 \clist_map_function:PN
1742 \l_@@_block_elements_clist_ptr
1743 \@@_block_format_element:N
1744 % \end{macrocode}
1745 % Now, we need to 'smuggle out' the output token list of the current group.
1746 % \begin{macrocode}
1747 \exp_args:NNNV
1748 \group_end:
1749 \@@_tl_set:Nn
1750 #5
1751 #5
1752 %<*log>
1753 \@@_log_decr:
1754 \@@_log:x { / Formatting ~ block ~ '\token_to_str:N #1' }
1755 %</log>
1756 }
1757 \cs_new:Npn \@@_block_format:PnnnN
1758 {
1759 \exp_args:NP \@@_block_format:NnnnN
1760 }
1761 % \end{macrocode}
1762 % \end{macro}
1763 %
1764 %
1765 % \begin{macro}{\@@_block_assert_operation:N}
1766 %
1767 % Asserts that the block has an operation
1768 % and loads it.
1769 % If no operation is set,
1770 % an error is emitted.
1771 %
1772 % \begin{macrocode}
1773 \cs_new:Npn \@@_block_assert_operation:N #1
1774 {
1775 \@@_block_load_operation:N #1
1776 \quark_if_no_value:NT \l_@@_block_operation_tl
1777 {
1778 \msg_error:nnxxx { grading-scheme } { missing-value}
1779 { block }
1780 { \token_to_str:N #1 }
1781 { operation }
1782 }
1783 }
1784 % \end{macrocode}
1785 % \end{macro}
1786 %
1787 %
1788 %
1789 % \begin{macro}{\@@_block_indent:nN}
1790 % \begin{syntax}
1791 % \cs{@@_block_indent:nN}\Arg{indent}\meta{tl var}
1792 % \end{syntax}
1793 %
1794 % Performs the indent into \meta{tl var}
1795 % iff \cs{l_@@_block_indent_bool} is true.
1796 %
1797 % Sets \cs{l_@@_block_indent_bool} to true afterwards.
1798 %
1799 % \begin{macrocode}
1800 \cs_new:Npn \@@_block_indent:nN #1 #2
1801 {
1802 \bool_if:NT \l_@@_block_indent_bool
1803 {
1804 \@@_tl_put_right:Nx #2
1805 {
1806 \prg_replicate:nn { #1 } { & }
1807 }
1808 }
1809 \bool_set_true:N \l_@@_block_indent_bool
1810 }
1811 % \end{macrocode}
1812 % \end{macro}
1813 %
1814 %
1815 % \subsubsection{Width and height of a block}
1816 %
1817 % \begin{variable}{\l_@@_height_sum_int, \l_@@_height_acc_int}
1818 %
1819 % Some temporary int values
1820 %
1821 % \begin{macrocode}
1822 \int_new:N \l_@@_height_sum_int
1823 \int_new:N \l_@@_height_acc_int
1824 % \end{macrocode}
1825 % \end{variable}
1826 %
1827 %
1828 % \begin{macro}{\grading_scheme_block_get_height:NN, \grading_scheme_block_get_height:PN}
1829 % \begin{syntax}
1830 % \cs{grading_scheme_block_get_height:NN}\meta{block var}\meta{int var}
1831 % \end{syntax}
1832 %
1833 % Gets the height of a block and stores
1834 % it into the \meta{int var}.
1835 %
1836 % \begin{macrocode}
1837 \cs_new:Npn \grading_scheme_block_get_height:NN #1 #2
1838 {
1839 %<*log>
1840 \@@_log:x { Getting ~ height ~ of ~ block ~ '\token_to_str:N #1' }
1841 \@@_log_incr:
1842 %</log>
1843 % \end{macrocode}
1844 % Grouping is needed to not mess up local variables in the recursion:
1845 % \begin{macrocode}
1846 \group_begin:
1847 \@@_block_load_elements:N #1
1848 \int_zero:N \l_@@_height_sum_int
1849 \clist_map_function:PN
1850 \l_@@_block_elements_clist_ptr
1851 \@@_block_height_accumulator:N
1852 \grading_scheme_block_if_description:NT #1
1853 {
1854 \int_incr:N \l_@@_height_sum_int
1855 }
1856 % \end{macrocode}
1857 % Smuggle out this length at return it to the caller:
1858 % \begin{macrocode}
1859 \exp_args:NNNV
1860 \group_end:
1861 \int_set:Nn #2 \l_@@_height_sum_int
1862 %<*log>
1863 \@@_log_decr:
1864 \@@_log:x
1865 {
1866 / Getting ~ height ~ of ~ block ~ '\token_to_str:N #1':
1867 '\int_use:N #2'
1868 }
1869 %</log>
1870 }
1871 \cs_new:Npn \grading_scheme_block_get_height:PN
1872 {
1873 \exp_args:NP \grading_scheme_block_get_height:NN
1874 }
1875 % \end{macrocode}
1876 % \end{macro}
1877 %
1878 %
1879 % \begin{macro}{\@@_block_height_accumulator:N}
1880 %
1881 % This is mapped on the elements of a block
1882 % and accumulates the heights.
1883 %
1884 % \begin{macrocode}
1885 \cs_new:Npn \@@_block_height_accumulator:N #1
1886 {
1887 \grading_scheme_element_get_height:NN #1 \l_@@_height_acc_int
1888 \int_add:Nn \l_@@_height_sum_int
1889 { \int_use:N \l_@@_height_acc_int }
1890 }
1891 % \end{macrocode}
1892 % \end{macro}
1893 %
1894 % \begin{macro}[TF]{\grading_scheme_block_if_description:N}
1895 %
1896 % Tests if the given \meta{block var} has a description
1897 % set or not.
1898 % Also loads this description
1899 %
1900 % \begin{macrocode}
1901 \cs_new:Npn \grading_scheme_block_if_description:NT #1 % implicit #2
1902 {
1903 \@@_block_load_description:N #1
1904 \quark_if_no_value:NF \l_@@_block_description_tl
1905 }
1906 \cs_new:Npn \grading_scheme_block_if_description:NF #1 % implicit #2
1907 {
1908 \@@_block_load_description:N #1
1909 \quark_if_no_value:NT \l_@@_block_description_tl
1910 }
1911 \cs_new:Npn \grading_scheme_block_if_description:NTF #1 #2 #3
1912 {
1913 \@@_block_load_description:N #1
1914 \quark_if_no_value:NTF \l_@@_block_description_tl
1915 { #3 }
1916 { #2 }
1917 }
1918 % \end{macrocode}
1919 % \end{macro}
1920 %
1921 %
1922 % \begin{variable}{\l_@@_max_width_int}
1923 %
1924 % \begin{macrocode}
1925 % \end{macrocode}
1926 % \end{variable}
1927 %
1928 % \begin{variable}{\l_@@_width_acc_int,\l_@@_max_width_int}
1929 %
1930 % Some temporary int values
1931 %
1932 % \begin{macrocode}
1933 \int_new:N \l_@@_max_width_int
1934 \int_new:N \l_@@_width_acc_int
1935 % \end{macrocode}
1936 % \end{variable}
1937 %
1938 %
1939 %
1940 %
1941 % \begin{macro}{\grading_scheme_block_get_natural_width:NN,\grading_scheme_block_get_natural_width:PN}
1942 %
1943 % Gets the \enquote{natural} width of a block,
1944 % that is: The minimal width of this block so
1945 % that it can be typeset properly.
1946 %
1947 % \begin{macrocode}
1948 \cs_new:Npn \grading_scheme_block_get_natural_width:NN #1 #2
1949 {
1950 %<*log>
1951 \@@_log:x
1952 { Getting ~ natural ~ width ~ of ~ block ~ '\token_to_str:N #1'. }
1953 \@@_log_incr:
1954 %</log>
1955 \group_begin:
1956 \@@_block_load_elements:N #1
1957 \int_zero:N \l_@@_max_width_int
1958 \clist_map_function:PN
1959 \l_@@_block_elements_clist_ptr
1960 \@@_block_width_accumulator:N
1961 \int_incr:N \l_@@_max_width_int
1962 \exp_args:NNNV
1963 \group_end:
1964 \int_set:Nn #2 \l_@@_max_width_int
1965 %<*log>
1966 \@@_log_decr:
1967 \@@_log:x
1968 { / Getting ~ natural ~ width ~ of ~ block ~ '\token_to_str:N #1'. }
1969 %</log>
1970 }
1971 \cs_new:Npn \grading_scheme_block_get_natural_width:PN
1972 {
1973 \exp_args:NP \grading_scheme_block_get_natural_width:NN
1974 }
1975 % \end{macrocode}
1976 % \end{macro}
1977 %
1978 % \begin{macro}{\@@_block_width_accumulator:N}
1979 %
1980 % Gets the natural width of subelements
1981 % and accumulates the maximum of them.
1982 %
1983 % \begin{macrocode}
1984 \cs_new:Npn \@@_block_width_accumulator:N #1
1985 {
1986 %<*log>
1987 \@@_log:x { Accumulating ~ width ~ of ~ '\token_to_str:N #1' }
1988 \@@_log_incr:
1989 %</log>
1990 \grading_scheme_element_get_natural_width:NN #1 \l_@@_width_acc_int
1991 \int_set:Nn \l_@@_max_width_int
1992 {
1993 \int_max:nn
1994 \l_@@_width_acc_int
1995 \l_@@_max_width_int
1996 }
1997 %<*log>
1998 \@@_log_decr:
1999 \@@_log:x { / Accumulationg ~ width ~ of ~ '\token_to_str:N #1' }
2000 %</log>
2001 }
2002 % \end{macrocode}
2003 % \end{macro}
2004 %
2005 %
2006 % \subsection{Elements}
2007 %
2008 % As discussed earlier, an \meta{element} is either a \meta{block}
2009 % or an \meta{entry}.
2010 % Thus, our natural representation is as follows:
2011 %
2012 % \begin{verbatim}
2013 % struct Element {
2014 % void* content;
2015 % tl type;
2016 % }
2017 % \end{verbatim}
2018 %
2019 % which essentially just implements a |union| that knows of its current
2020 % member.
2021 %
2022 %
2023 % \begin{macro}{\@@_element_new:N, \@@_element_clear:N, \@@_element_set_eq:NN, \@@_element_gclear:N, \@@_element_gset_eq:NN}
2024 %
2025 % Do what these say. Forward to the underlying property lists.
2026 %
2027 % \begin{macrocode}
2028 \cs_set_eq:NN \grading_scheme_element_new:N \prop_new:N
2029 \cs_set_eq:NN \grading_scheme_element_clear:N \prop_clear:N
2030 \cs_set_eq:NN \grading_scheme_element_set_eq:NN \prop_set_eq:NN
2031 \cs_set_eq:NN \grading_scheme_element_gclear:N \prop_gclear:N
2032 \cs_set_eq:NN \grading_scheme_element_gset_eq:NN \prop_gset_eq:NN
2033 % \end{macrocode}
2034 % \end{macro}
2035 %
2036 % \begin{variable}{\l_@@_element_content_void_ptr, \l_@@_element_type_str}
2037 %
2038 % Mentioned local variables.
2039 %
2040 % \begin{macrocode}
2041 \ptr_new:N \l_@@_element_content_void_ptr
2042 \str_new:N \l_@@_element_type_str
2043 % \end{macrocode}
2044 % \end{variable}
2045 %
2046 %
2047 % \begin{macro}{\grading_scheme_element_set_block:NN, \grading_scheme_element_gset_block:NN, \grading_scheme_element_set_entry:NN, \grading_scheme_element_gset_entry:NN}
2048 % \begin{syntax}
2049 % \cs{grading_scheme_element_set_block:NN} \meta{element var}\meta{block var}
2050 % \end{syntax}
2051 %
2052 % \begin{macrocode}
2053 \cs_new:Npn \grading_scheme_element_set_block:NN #1 % implicit #2
2054 {
2055 \prop_put:Nnn #1 { type } { block }
2056 \prop_put:Nnn #1 { content }
2057 }
2058 \cs_new:Npn \grading_scheme_element_gset_block:NN #1 % implicit #2
2059 {
2060 \prop_gput:Nnn #1 { type } { block }
2061 \prop_gput:Nnn #1 { content }
2062 }
2063 \cs_new:Npn \grading_scheme_element_set_entry:NN #1 % implicit #2
2064 {
2065 \prop_put:Nnn #1 { type } { entry }
2066 \prop_put:Nnn #1 { content }
2067 }
2068 \cs_new:Npn \grading_scheme_element_gset_entry:NN #1 % implicit #2
2069 {
2070 \prop_gput:Nnn #1 { type } { entry }
2071 \prop_gput:Nnn #1 { content }
2072 }
2073 % \end{macrocode}
2074 % \end{macro}
2075 %
2076 % \begin{macro}{\grading_scheme_element_get_content:NN, \grading_scheme_element_get_type:NN}
2077 % \begin{syntax}
2078 % \cs{grading_scheme_element_get_content:NN} \meta{element var}\meta{void ptr}
2079 % \cs{grading_scheme_element_get_type:NN} \meta{element var}\meta{str var}
2080 % \end{syntax}
2081 %
2082 % Get the contents. The assignment is local.
2083 %
2084 % \begin{macrocode}
2085 \cs_new:Npn \grading_scheme_element_get_content:NN #1 % implicit #2
2086 {
2087 \prop_get:NnN #1 { content }
2088 }
2089 \cs_new:Npn \grading_scheme_element_get_type:NN #1 % implicit #2
2090 {
2091 \prop_get:NnN #1 { type }
2092 }
2093 % \end{macrocode}
2094 % \end{macro}
2095 %
2096 % \begin{macro}{\@@_element_load_content:N, \@@_element_load_type:NN}
2097 %
2098 % Loads the element into the local variables.
2099 %
2100 % \begin{macrocode}
2101 \cs_new:Npn \@@_element_load_content:N #1
2102 {
2103 \grading_scheme_element_get_content:NN #1 \l_@@_element_content_void_ptr
2104 }
2105 \cs_new:Npn \@@_element_load_type:N #1
2106 {
2107 \grading_scheme_element_get_type:NN #1 \l_@@_element_type_str
2108 }
2109 % \end{macrocode}
2110 % \end{macro}
2111 %
2112 % \begin{macro}[noTF]{\grading_scheme_element_cases:Nnn}
2113 % \begin{syntax}
2114 % \cs{grading_scheme_element_cases}\meta{element var}\Arg{entry code}\Arg{block code}
2115 % \end{syntax}
2116 %
2117 % Distinguishes between the
2118 % cases of the element type.
2119 %
2120 % Also loads the element type.
2121 %
2122 % \begin{macrocode}
2123 \cs_new:Npn \grading_scheme_element_cases:Nnn % implicit #1-3
2124 {
2125 \cs_set_eq:NN \@@_str_case:Vnw \str_case:Vn
2126 \@@_element_cases:Nnnw
2127 }
2128 \cs_new:Npn \grading_scheme_element_cases:NnnT % implicit #1-4
2129 {
2130 \cs_set_eq:NN \@@_str_case:Vnw \str_case:VnT
2131 \@@_element_cases:Nnnw
2132 }
2133 \cs_new:Npn \grading_scheme_element_cases:NnnF % implicit #1-4
2134 {
2135 \cs_set_eq:NN \@@_str_case:Vnw \str_case:VnF
2136 \@@_element_cases:Nnnw
2137 }
2138 \cs_new:Npn \grading_scheme_element_cases:NnnTF % implicit #1-5
2139 {
2140 \cs_set_eq:NN \@@_str_case:Vnw \str_case:VnTF
2141 \@@_element_cases:Nnnw
2142 }
2143 % \end{macrocode}
2144 % \end{macro}
2145 %
2146 % \begin{macro}{\@@_element_cases:Nnnw}
2147 %
2148 % This assumes that \cs{@@_str_case:Vnw}
2149 % has been set to a \cs{str_case:VnTF}
2150 % variant and uses this variant for
2151 % switching the type cases.
2152 %
2153 % \begin{macrocode}
2154 \cs_new:Npn \@@_element_cases:Nnnw #1 #2 #3 % implicit branches
2155 {
2156 \@@_element_load_type:N #1
2157 \@@_str_case:Vnw \l_@@_element_type_str
2158 {
2159 { entry } { #2 }
2160 { block } { #3 }
2161 }
2162 % implicit branches
2163 }
2164 % \end{macrocode}
2165 % \end{macro}
2166 %
2167 % \begin{macro}{\grading_scheme_element_format:NnnnN, \grading_scheme_element_gformat:NnnnN, \grading_scheme_element_format:PnnnN, \grading_scheme_element_gformat:PnnnN}
2168 %
2169 % Same syntax as \cs{grading_scheme_block_format:NnnnN}.
2170 %
2171 % \begin{macrocode}
2172 \cs_new:Npn \grading_scheme_element_format:NnnnN % implicit #1-5
2173 {
2174 \cs_set_eq:NN \@@_entry_format_aux:PnnN \grading_scheme_entry_format:PnnN
2175 \cs_set_eq:NN \@@_block_format_aux:PnnnN \grading_scheme_block_format:PnnnN
2176 \cs_set_eq:NN \@@_tl_put_right:Nx \tl_put_right:Nx
2177 \@@_element_format:NnnnN
2178 }
2179 \cs_new:Npn \grading_scheme_element_gformat:NnnnN % implicit #1-5
2180 {
2181 \cs_set_eq:NN \@@_entry_format_aux:PnnN \grading_scheme_entry_gformat:PnnN
2182 \cs_set_eq:NN \@@_block_format_aux:PnnnN \grading_scheme_block_gformat:PnnnN
2183 \cs_set_eq:NN \@@_tl_put_right:Nx \tl_put_gright:Nx
2184 \@@_element_format:NnnnN
2185 }
2186 \cs_new:Npn \grading_scheme_element_format:PnnnN % implicit #1-5
2187 {
2188 \exp_args:NP \grading_scheme_element_format:NnnnN
2189 }
2190 \cs_new:Npn \grading_scheme_element_gformat:PnnnN % implicit #1-5
2191 {
2192 \exp_args:NP \grading_scheme_element_gformat:NnnnN
2193 }
2194 % \end{macrocode}
2195 % \end{macro}
2196 %
2197 %
2198 % \begin{macro}{\@@_element_format:NnnnN, \@@_element_format:PnnnN}
2199 %
2200 % Aux function.
2201 %
2202 % \begin{macrocode}
2203 \cs_new:Npn \@@_element_format:NnnnN #1 #2 #3 #4 #5
2204 {
2205 %<*log>
2206 \@@_log:x
2207 {
2208 Formatting ~ element ~ '\token_to_str:N #1' ~ into ~ '\token_to_str:N #5'.
2209 }
2210 \@@_log_incr:
2211 \prop_log:N #1
2212 %</log>
2213 \@@_element_load_content:N #1
2214 \grading_scheme_element_cases:NnnF #1
2215 {
2216 \bool_if:nTF { #4 }
2217 {
2218 \@@_entry_format_aux:PnnN
2219 \l_@@_element_content_void_ptr
2220 { #2 }
2221 { #3 }
2222 #5
2223 }
2224 {
2225 \@@_entry_format_aux:PnnN
2226 \l_@@_element_content_void_ptr
2227 { 0 }
2228 { #3 }
2229 #5
2230 }
2231 }
2232 {
2233 \@@_block_format_aux:PnnnN
2234 \l_@@_element_content_void_ptr
2235 { #2 }
2236 { #3 }
2237 { #4 }
2238 #5
2239 }
2240 {
2241 \msg_error:nnxxx { grading-scheme } { missing-value }
2242 { element }
2243 { \token_to_str:N #1 }
2244 { type / content }
2245 }
2246 \@@_tl_put_right:Nx #5
2247 {
2248 \exp_not:N \@@_cline:nn
2249 {
2250 \int_eval:n { #2 +1 }
2251 }
2252 {
2253 \int_eval:n { #2 + #3 }
2254 }
2255 }
2256 %<*log>
2257 \@@_log_decr:
2258 \@@_log:x { Done typesetting ~ element ~ '\token_to_str:N #1' }
2259 %</log>
2260 }
2261 \cs_new:Npn \@@_element_format:PnnnN % implicit #1-5
2262 {
2263 \exp_args:NP \@@_element_format:NnnnN
2264 }
2265 % \end{macrocode}
2266 % \end{macro}
2267 %
2268 %
2269 % \begin{macro}{\grading_scheme_element_get_height:NN, \grading_scheme_element_get_height:PN}
2270 %
2271 % Get the the height of an element.
2272 %
2273 % \begin{macrocode}
2274 \cs_new:Npn \grading_scheme_element_get_height:NN #1 #2
2275 {
2276 \grading_scheme_element_cases:NnnF #1
2277 {
2278 \int_set:Nn #2 { 1 }
2279 }
2280 {
2281 \@@_element_load_content:N #1
2282 \grading_scheme_block_get_height:PN
2283 \l_@@_element_content_void_ptr
2284 #2
2285 }
2286 {
2287 \msg_error:nnxxx { grading-scheme } { missing-value }
2288 { element }
2289 { \token_to_str:N #1 }
2290 { type / content }
2291 }
2292 }
2293 \cs_new:Npn \grading_scheme_element_get_height:PN
2294 {
2295 \exp_args:NP \grading_scheme_element_get_height:NN
2296 }
2297 % \end{macrocode}
2298 % \end{macro}
2299 %
2300 % \begin{macro}{\grading_scheme_element_get_natural_width:NN, \grading_scheme_element_get_natural_width:PN}
2301 %
2302 % Get the natural width of an element
2303 %
2304 % \begin{macrocode}
2305 \cs_new:Npn \grading_scheme_element_get_natural_width:NN #1 #2
2306 {
2307 \grading_scheme_element_cases:NnnF #1
2308 {
2309 \int_set:Nn { #2 } { 2 }
2310 }
2311 {
2312 \@@_element_load_content:N #1
2313 \grading_scheme_block_get_natural_width:PN
2314 \l_@@_element_content_void_ptr
2315 #2
2316 }
2317 {
2318 \msg_error:nnxxx { grading-scheme } { missing-value }
2319 { element }
2320 { \token_to_str:N #1 }
2321 { type / content }
2322 }
2323 }
2324 \cs_new:Npn \grading_scheme_element_get_natural_width:PN
2325 {
2326 \exp_args:NP \grading_scheme_element_get_natural_width:NN
2327 }
2328 % \end{macrocode}
2329 % \end{macro}
2330 %
2331 %
2332 % \begin{variable}{\l_@@_width_int}
2333 %
2334 % Local int vars for typesetting.
2335 %
2336 % \begin{macrocode}
2337 \int_new:N \l_@@_width_int
2338 % \end{macrocode}
2339 % \end{variable}
2340 %
2341 % \begin{variable}{\g_@@_table_tl}
2342 %
2343 % Token list where we will build the table.
2344 %
2345 % \begin{macrocode}
2346 \tl_new:N \g_@@_table_tl
2347 % \end{macrocode}
2348 % \end{variable}
2349 %
2350 %
2351 %
2352 %
2353 % \begin{macro}{\grading_scheme_element_typeset:N, \grading_scheme_element_typeset:P}
2354 %
2355 % Typesets this element as a tabular and inserts this into the output stream.
2356 %
2357 % \begin{macrocode}
2358 \cs_new:Npn \grading_scheme_element_typeset:N #1
2359 {
2360 \grading_scheme_element_get_natural_width:NN #1 \l_@@_width_int
2361 \tl_gclear:N \g_@@_table_tl
2362 \tl_gput_right:Nn \g_@@_table_tl
2363 {
2364 \begin{tabular}
2365 }
2366 \tl_gput_right:Nx \g_@@_table_tl
2367 {
2368 {
2369 \prg_replicate:nn { \l_@@_width_int -1 } { |l }
2370 | l |
2371 }
2372 \exp_not:N \@@_hline:
2373 }
2374 \grading_scheme_element_gformat:NnnnN
2375 #1
2376 { 0 }
2377 { \l_@@_width_int }
2378 { \c_false_bool }
2379 \g_@@_table_tl
2380 \tl_gput_right:Nn \g_@@_table_tl
2381 {
2382 \end{tabular}
2383 }
2384 \group_begin:
2385 \tl_set:Nn \arraystretch { 1.5 }
2386 \tl_use:N \g_@@_table_tl
2387 \group_end:
2388 }
2389 \cs_new:Npn \grading_scheme_element_typeset:P
2390 {
2391 \exp_args:NP \grading_scheme_element_typeset:N
2392 }
2393 % \end{macrocode}
2394 % \end{macro}
2395 %
2396 %
2397 % \subsection{Facilities for populating data structures}
2398 %
2399 % TODO: what about global / local assignments here?
2400 %
2401 %
2402 % \begin{macro}{\grading_scheme_entry_new:Nnn, \grading_scheme_entry_new:Pnn}
2403 % \begin{syntax}
2404 % \cs{grading_scheme_entry_new:Nnn}\meta{entry var}\Arg{description}\Arg{points}
2405 % \end{syntax}
2406 %
2407 % \begin{macrocode}
2408 \cs_new:Npn \grading_scheme_entry_new:Nnn #1 #2 % implcit #3
2409 {
2410 \grading_scheme_entry_new:N #1
2411 \grading_scheme_entry_gset_description:Nn #1 { #2 }
2412 \grading_scheme_entry_gset_points:Nn #1
2413 }
2414 \cs_new:Npn \grading_scheme_entry_new:Pnn
2415 {
2416 \exp_args:NP \grading_scheme_entry_new:Nnn
2417 }
2418 % \end{macrocode}
2419 % \end{macro}
2420 %
2421 % \begin{macro}{\grading_scheme_block_new:Nnn, \grading_scheme_block_new:Pnn}
2422 % \begin{syntax}
2423 % \cs{grading_scheme_block_new:Nnn}\meta{block var}\Arg{description}\Arg{operation}
2424 % \end{syntax}
2425 %
2426 % \begin{macrocode}
2427 \cs_new:Npn \grading_scheme_block_new:Nnn #1 #2 % implicit #3
2428 {
2429 \grading_scheme_block_new:N #1
2430 \grading_scheme_block_gset_description:Nn #1 { #2 }
2431 \grading_scheme_block_gset_operation:Nn #1
2432 }
2433 \cs_new:Npn \grading_scheme_block_new:Pnn
2434 {
2435 \exp_args:NP \grading_scheme_block_new:Nnn
2436 }
2437 % \end{macrocode}
2438 % \end{macro}
2439 %
2440 % \begin{macro}{\grading_scheme_block_new:Nn, \grading_scheme_block_new:Pn}
2441 % \begin{syntax}
2442 % \cs{grading_scheme_block_new:Nn}\meta{block var}\Arg{operation}
2443 % \end{syntax}
2444 %
2445 % Same as above, but no description provided.
2446 %
2447 % \begin{macrocode}
2448 \cs_new:Npn \grading_scheme_block_new:Nn #1 % implicit #2
2449 {
2450 \grading_scheme_block_new:N #1
2451 \grading_scheme_block_gset_operation:Nn #1
2452 }
2453 \cs_new:Npn \grading_scheme_block_new:Pn
2454 {
2455 \exp_args:NP \grading_scheme_block_new:Nn
2456 }
2457 % \end{macrocode}
2458 % \end{macro}
2459 %
2460 % \begin{macro}{\grading_scheme_element_from_entry_new:NN, \grading_scheme_element_from_entry_new:NP, \grading_scheme_element_from_entry_new:PP,
2461 % \grading_scheme_element_gfrom_entry_new:NN, \grading_scheme_element_gfrom_entry_new:NP, \grading_scheme_element_gfrom_entry_new:PP}
2462 % \begin{syntax}
2463 % \cs{grading_scheme_element_from_entry_new:NN}\meta{element var}\meta{entry var}
2464 % \end{syntax}
2465 %
2466 % wraps the entry into a new element.
2467 %
2468 % \begin{macrocode}
2469 \cs_new:Npn \grading_scheme_element_from_entry_new:NN #1 #2
2470 {
2471 \grading_scheme_element_new:N #1
2472 \grading_scheme_element_set_entry:NN #1 #2
2473 }
2474 \cs_new:Npn \grading_scheme_element_from_entry_new:NP
2475 {
2476 \exp_args:NP \grading_scheme_element_from_entry_new:NN
2477 }
2478 \cs_new:Npn \grading_scheme_element_from_entry_new:PP
2479 {
2480 \exp_args:NPP \grading_scheme_element_from_entry_new:NN
2481 }
2482 \cs_new:Npn \grading_scheme_element_gfrom_entry_new:NN #1 #2
2483 {
2484 \grading_scheme_element_new:N #1
2485 \grading_scheme_element_gset_entry:NN #1 #2
2486 }
2487 \cs_new:Npn \grading_scheme_element_gfrom_entry_new:NP
2488 {
2489 \exp_args:NP \grading_scheme_element_gfrom_entry_new:NN
2490 }
2491 \cs_new:Npn \grading_scheme_element_gfrom_entry_new:PP
2492 {
2493 \exp_args:NPP \grading_scheme_element_gfrom_entry_new:NN
2494 }
2495 % \end{macrocode}
2496 % \end{macro}
2497 %
2498 % \begin{macro}{\grading_scheme_element_from_block_new:NN, \grading_scheme_element_from_block_new:NP, \grading_scheme_element_from_block_new:NP,
2499 % \grading_scheme_element_gfrom_block_new:NN, \grading_scheme_element_from_gblock_new:NP, \grading_scheme_element_gfrom_block_new:NP}
2500 % \begin{syntax}
2501 % \cs{grading_scheme_element_from_block_new:NN}\meta{element var}\meta{block var}
2502 % \end{syntax}
2503 %
2504 % wraps the block into a new element.
2505 %
2506 % \begin{macrocode}
2507 \cs_new:Npn \grading_scheme_element_from_block_new:NN #1 #2
2508 {
2509 \grading_scheme_element_new:N #1
2510 \grading_scheme_element_set_block:NN #1 #2
2511 }
2512 \cs_new:Npn \grading_scheme_element_from_block_new:NP
2513 {
2514 \exp_args:NP \grading_scheme_element_from_block_new:NN
2515 }
2516 \cs_new:Npn \grading_scheme_element_from_block_new:PP
2517 {
2518 \exp_args:NPP \grading_scheme_element_from_block_new:NN
2519 }
2520 \cs_new:Npn \grading_scheme_element_gfrom_block_new:NN #1 #2
2521 {
2522 \grading_scheme_element_new:N #1
2523 \grading_scheme_element_gset_block:NN #1 #2
2524 }
2525 \cs_new:Npn \grading_scheme_element_gfrom_block_new:NP
2526 {
2527 \exp_args:NP \grading_scheme_element_gfrom_block_new:NN
2528 }
2529 \cs_new:Npn \grading_scheme_element_gfrom_block_new:PP
2530 {
2531 \exp_args:NPP \grading_scheme_element_gfrom_block_new:NN
2532 }
2533 % \end{macrocode}
2534 % \end{macro}
2535 %
2536 % \subsection{Grading scheme environment}
2537 %
2538 % When building a grading scheme,
2539 % we introduce a \cs{g_@@_curr_block_ptr}
2540 % that is a pointer to the current block
2541 % that is being populated.
2542 %
2543 % Block environments and entries will create
2544 % new blocks/entries and add themselves to
2545 % the block pointed out by \cs{g_@@_curr_block_ptr}
2546 %
2547 %
2548 % \begin{variable}{\l_@@_entry_ptr, \l_@@_element_ptr, \l_@@_curr_block_ptr}
2549 %
2550 % \begin{macrocode}
2551 \ptr_new:Nn \l_@@_entry_ptr { g }
2552 \ptr_new:Nn \l_@@_element_ptr { g }
2553 \ptr_new:Nn \l_@@_curr_block_ptr { g }
2554 % \end{macrocode}
2555 % \end{variable}
2556 %
2557 %
2558 %
2559 % \begin{macro}{\@@_entry:nn}
2560 %
2561 % Creates an entry in the current block.
2562 %
2563 % \begin{macrocode}
2564 \cs_new:Npn \@@_entry:nn #1 #2
2565 {
2566 \ptr_clear:Nn \l_@@_entry_ptr { g }
2567 \ptr_clear:Nn \l_@@_element_ptr { g }
2568 \grading_scheme_entry_new:Pnn
2569 \l_@@_entry_ptr
2570 { #1 }
2571 { #2 }
2572 \grading_scheme_element_gfrom_entry_new:PP
2573 \l_@@_element_ptr
2574 \l_@@_entry_ptr
2575 \grading_scheme_block_gadd_element:PP
2576 \l_@@_curr_block_ptr
2577 \l_@@_element_ptr
2578 }
2579 % \end{macrocode}
2580 % \end{macro}
2581 %
2582 % \begin{macro}{\@@_block_begin:nn, \@@_block_begin:n, \@@_block_end:}
2583 %
2584 %
2585 %
2586 % \begin{macrocode}
2587 \cs_new:Npn \@@_block_begin:nn % implicit #1, #2
2588 {
2589 \ptr_clear:Nn \l_@@_curr_block_ptr { g }
2590 \grading_scheme_block_new:Pnn \l_@@_curr_block_ptr
2591 }
2592 \cs_new:Npn \@@_block_begin:n % implicit #1
2593 {
2594 \ptr_clear:Nn \l_@@_curr_block_ptr { g }
2595 \grading_scheme_block_new:Pn \l_@@_curr_block_ptr
2596 }
2597 \cs_new:Npn \@@_block_end:
2598 {
2599 \ptr_clear:Nn \l_@@_element_ptr { g }
2600 \grading_scheme_element_gfrom_block_new:PP
2601 \l_@@_element_ptr
2602 \l_@@_curr_block_ptr
2603 \cs_gset:Npx \@@_after_group:
2604 {
2605 \exp_not:N \grading_scheme_block_gadd_element:PN
2606 \exp_not:N \l_@@_curr_block_ptr
2607 \exp_not:P \l_@@_element_ptr
2608 }
2609 \group_insert_after:N \@@_after_group:
2610 }
2611 % \end{macrocode}
2612 % \end{macro}
2613 %
2614 %
2615 % \begin{macro}{\entry}
2616 %
2617 %
2618 %
2619 % \begin{macrocode}
2620 \NewDocumentCommand \entry { m m }
2621 {
2622 \@@_entry:nn { #1 } { #2 }
2623 }
2624 % \end{macrocode}
2625 % \end{macro}
2626 %
2627 %
2628 % \begin{macro}{block}
2629 %
2630 % \begin{macrocode}
2631 \NewDocumentEnvironment { block } { o m }
2632 {
2633 \IfValueTF { #1 }
2634 {
2635 \@@_block_begin:nn { #1 } { #2 }
2636 }
2637 {
2638 \@@_block_begin:n { #2 }
2639 }
2640 }
2641 {
2642 \@@_block_end:
2643 }
2644 % \end{macrocode}
2645 % \end{macro}
2646 %
2647 % \begin{macro}{gradingscheme}
2648 %
2649 %
2650 %
2651 % \begin{macrocode}
2652 \NewDocumentEnvironment {gradingscheme} { o m }
2653 {
2654 \bool_if:NT \g_@@_pipe_syntax_bool
2655 {
2656 \char_set_active_eq:NN | \@@_entry_oneline:w
2657 \char_set_catcode_active:N |
2658 }
2659 \IfValueTF { #1 }
2660 {
2661 \@@_block_begin:nn { #1 } { #2 }
2662 }
2663 {
2664 \@@_block_begin:n { #2 }
2665 }
2666 }
2667 {
2668 \ptr_clear:Nn \l_@@_element_ptr { g }
2669 \grading_scheme_element_gfrom_block_new:PP
2670 \l_@@_element_ptr
2671 \l_@@_curr_block_ptr
2672 \grading_scheme_element_typeset:P \l_@@_element_ptr
2673 }
2674 % \end{macrocode}
2675 % \end{macro}
2676 %
2677 % \subsection{Implementing the pipe syntax}
2678 %
2679 % Everything left is conditional on the pipe option having been specified:
2680 % \begin{macrocode}
2681 \bool_if:NF \g_@@_pipe_syntax_bool
2682 {
2683 \endinput
2684 }
2685 % \end{macrocode}
2686 %
2687 %
2688 % In order to offer syntax based on $\mid$, we make $\mid$ an active character
2689 % that will read until the end of the line, split at the |@| character,
2690 % and pass this on to a \cs{@@_entry:nn}
2691 %
2692 % \begin{macro}{\s_@@_endline}
2693 %
2694 % A scan mark that will denote the end of the line
2695 % for us.
2696 %
2697 % \begin{macrocode}
2698 \scan_new:N \s_@@_endline
2699 % \end{macrocode}
2700 % \end{macro}
2701 %
2702 % \begin{macro}{\@@_parse_entry:w}
2703 % \begin{syntax}
2704 % \cs{@@_parse_entry:w} \meta{description} \& \meta{points} \cs{s_endline}
2705 % \end{syntax}
2706 %
2707 % Creates a new entry based on our scan mark.
2708 %
2709 % \begin{macrocode}
2710 \cs_new:Npn \@@_parse_entry:w #1 & #2 \s_endline
2711 {
2712 \@@_entry:nn { #1 } { #2 }
2713 }
2714 % \end{macrocode}
2715 % \end{macro}
2716 %
2717 % \begin{macro}{\@@_replace_newline:w, \@@_replace_newline_aux:w}
2718 %
2719 % Calling \cs{@@_replace_newline:w}
2720 % replaces the next occurence of a newline character with
2721 % \cs{s_@@_endline}.
2722 %
2723 % This is done by briefly switching category codes.
2724 %
2725 % \begin{macrocode}
2726 \cs_new:Npn \@@_replace_newline:w
2727 {
2728 \group_begin:
2729 \char_set_catcode_active:N\^^M
2730 \@@_replace_newline_aux:w
2731 }
2732 % \end{macrocode}
2733 %
2734 % We need to briefly make the newline character an active character
2735 % in this source file so that pattern matching works correctly.
2736 % \begin{macrocode}
2737 \char_set_catcode_active:N\^^M
2738 \cs_new:Npn \@@_replace_newline_aux:w #1 ^^M
2739 {
2740 \group_end:
2741 #1 \s_endline
2742 }
2743 \char_set_catcode_end_line:N\^^M
2744 % \end{macrocode}
2745 % \end{macro}
2746 %
2747 %
2748 % \begin{macro}{\@@_entry_oneline:w}
2749 %
2750 % Parses a one-line entry.
2751 %
2752 % \begin{macrocode}
2753 \cs_new:Npn \@@_entry_oneline:w
2754 {
2755 \@@_replace_newline:w
2756 \@@_parse_entry:w
2757 }
2758 % \end{macrocode}
2759 % \end{macro}
2760 %
2761 %
2762 % \begin{macrocode}
2763 %</package>
2764 % \end{macrocode}
2765 %
2766 % \end{implementation}
2767 %
2768 % \PrintIndex
2769 %