% \iffalse meta-comment
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% This LaTeX docstrip file is free software and is licensed under the %
% Latex Project Public License v1.3c, or (at your choice) any later version %
% The latest version of the license can be found at %
% https://www.latex-project.org/lppl/lppl-1-3c.txt %
% You may use it freely for your purposes. %
% The packages home is https://ctan.org/pkg/grading-scheme %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%<*internal>
% \begingroup
% \input docstrip.tex
% \keepsilent
% \preamble
% ___________________________________________________________
% The grading-scheme package
% Copyright (C) 2022 Maximilian Kessler
% License information appended.
%
% \endpreamble
% \postamble
%
% Copyright 2022 Maximilian Kessler <ctan@maximilian-kessler.de>
%
% Distributable under the LaTeX Project Public License,
% version 1.3c or higher (your choice). The latest version of
% this license is at: http://www.latex-project.org/lppl.txt
%
% This work is "author-maintained"
%
% This work consists of the files grading-scheme.dtx,
% grading-scheme.ins, a README file
% and the derived files grading-scheme.sty and grading-scheme.pdf.
%
% \endpostamble
% \askforoverwritefalse
%
% \generate{\file{grading-scheme.sty}{\from{grading-scheme.dtx}{package}}}
%
% \def\tmpa{plain}
% \ifx\tmpa\fmtname\endgroup\expandafter\bye\fi
% \endgroup
%</internal>
%
%<package>\ProvidesExplPackage {grading-scheme} {2022/02/24} {0.1.1}
%<package> {Typeset grading schemes in tabular format}
%
%<*driver>
\documentclass[full]{l3doc}
\usepackage{grading-scheme}
\begin{document}
\RecordChanges
\DocInput{grading-scheme.dtx}
\end{document}
%</driver>
% \fi
%
% \changes{0.1}{2022/02/22}{Initial release}
% \changes{0.1.1}{2022/02/24}{Bug fix (thanks to Denis Bitouzé), typos.}
%
%
%
%
% \title{The \pkg{grading-scheme} package}
%
% \author{Maximilian Keßler\thanks{ctan@maximilian-kessler.de}}
% \date{Released 2022/02/24\\ \vskip 1.5em {\small version 0.1.1}}
%
% \maketitle
%
% \begin{abstract}
% This package aims at an easy-to-use interface to typeset
% grading schemes in tabular format, in particular grading-schemes
% of exercises of mathematical olympiads where multiple
% solutions have to be graded and might offer mutual
% exclusive ways of receiving points.
% \end{abstract}
%
% \setcounter{tocdepth}{2}
% \tableofcontents
%
% \begin{documentation}
%
% \section{General notions}
%
% Probably, an example is fitting best at this point.
% If you want to set up a grading scheme, with the \pkg{grading-scheme} package
% all you have to do to get the output of \autoref{tab:grading-scheme}
% is type the following:
%
% \iffalse
% Since the docstrip format already uses the pipe character
% to denote verbatim, we actually use \entry to typeset the table.
% In a user document, one could of course use the pipe syntax again.
% \fi
% \begin{table}[tp]
% \centering
% \begin{gradingscheme}{sum}
% \entry{At least one correct solution}{1}
% \entry{All correct solutions}{1}
% \begin{block}{max}
% \begin{block}[Uniqueness proofs]{max}
% \begin{block}[First solution]{sum}
% \entry{Show that either $4 \mid p - 2$ or $3 \mid p - 4$.}{3}
% \entry{Show that $m = 5$}{2}
% \entry{Show that $ n = 4 $}{1}
% \entry{Conclude solutions}{1}
% \end{block}
% \begin{block}[Second solution]{sum}
% \entry{Show that $p$ is even}{2}
% \entry{Reduce to at most 30 candidates}{3}
% \entry{Test all candidates}{2}
% \end{block}
% \end{block}
% \begin{block}{min(2)}
% \begin{block}[Plausible Arguments]{sum}
% \entry{plausible argument that there are finitely many solutions}{1}
% \entry{suggestion that divisibility by 4 is useful}{1}
% \entry{suggesting that not both of $m$, $n$ can be 'large'.}{1}
% \end{block}
% \end{block}
% \end{block}
% \end{gradingscheme}
% \caption{Example output of a grading scheme.}
% \label{tab:grading-scheme}
% \end{table}
%
% \begin{verbatim}
% \begin{gradingscheme}{sum}
% | At least one correct solution & 1
% | All correct solutions & 1
% \begin{block}{max}
% \begin{block}[Uniqueness proofs]{max}
% \begin{block}[First solution]{sum}
% | Show that either $4 \mid p - 2$ or $3 \mid p - 4$. & 3
% | Show that $m = 5$ & 2
% | Show that $ n = 4 $ & 1
% | Conclude solutions & 1
% \end{block}
% \begin{block}[Second solution]{sum}
% | Show that $p$ is even & 2
% | Reduce to at most 30 candidates & 3
% | Test all candidates & 2
% \end{block}
% \end{block}
% \begin{block}{min(2)}
% \begin{block}[Plausible Arguments]{sum}
% | plausible argument that there are finitely many solutions & 1
% | suggestion that divisibility by 4 is useful & 1
% | suggesting that not both of $m$, $n$ can be 'large'. & 1
% \end{block}
% \end{block}
% \end{block}
% \end{gradingscheme}
% \end{verbatim}
%
% Note in particular that the correct width of the rows and columns
% are automatically adjusted.
%
%
% For us, a grading scheme consists of several statements, each worth
% some specific number of points, that will be combined into a final
% number of points using a nested expression of operations, typically
% sums, maximums or minimus.
%
% An abstract grammar defining our notions is defined in
% \autoref{tab:grading-scheme-grammar}.
% The meanings of \meta{balanced text} and \meta{number} are
% as usual.
%
% \begin{table}[htpb]
% \centering
% \begin{tabular}{r@{\;:=\;}l}
% grading scheme & block \\
% block & [\meta{block description}], \meta{block operation}, \meta{element list} \\
% element list & \meta{element} $\mid$ \meta{element} : \meta{element list} \\
% element & \meta{block} $\mid$ \meta{entry} \\
% entry & \meta{entry description}, \meta{entry points} \\
% block description & \meta{balanced text} \\
% block operation & \meta{balanced text} \\
% entry description & \meta{balanced text} \\
% entry points & \meta{number} \\
% \end{tabular}
% \caption{Abstract grammer for a grading scheme}
% \label{tab:grading-scheme-grammar}
% \end{table}
%
% The package facilitates specifying a grading scheme according to this grammar
% and typesets these.
%
% \section{Usage}
%
% Load the package as usual by
% \begin{verbatim}
% \usepackage[pipe]{grading-scheme}
% \end{verbatim}
%
% The |pipe| option is of course optional and the only currently supported option.
% It activates the pipe syntax explained later.
%
% \begin{environment}{gradingscheme}
% \begin{syntax}
% \cs{begin}\{gradingscheme\}\oarg{description text}\Arg{operator}
% \cs{end}\{gradingscheme\}
% \end{syntax}
% The main environment provided by this package.
% Inside the grading scheme, any number of blocks and entries can
% be specified.
% The grading scheme environment will act like the outer-most block
% and typeset all its contents.
%
% Grading schemes cannot contain each other. As they are implemented
% as |tabular|s, you can (and maybe should) put a grading scheme
% into a |table| environment as if it were a regular |tabular|.
%
% \begin{texnote}
% Actually, the gradingscheme environment just sets up some hooks
% that further block environments and entries will fill
% and typesets these at the end of the environment.
%
% You could technically put any regular text inside the grading
% scheme and this will be typeset as if it had been specified
% before the grading scheme. However, this is definitely not
% recommended.
% \end{texnote}
% \end{environment}
%
% \begin{environment}{block}
% \begin{syntax}
% \cs{begin}\{block\}\oarg{description text}\Arg{operator}
% \cs{end}\{block\}
% \end{syntax}
%
% The \meta{description text} will be shown in a separate row
% on top of the block. If not specfied, no such row is inserted.
% The \meta{operator} is printed in small capitals (and rotated)
% in a column that spans the left side of the block,
% indicating that this operation is applied to the block.
%
% The block will be an element of the outer block or
% grading scheme it is contained in.
%
% Inside the block, any number of blocks or entries
% can be specified (in order) that will be typeset
% as members of this block.
%
% A block environment can only be used inside a gradingscheme.
% Block environments can contain each other in balanced form.
% \end{environment}
%
% \begin{function}{\entry}
% \begin{syntax}
% \cs{entry}\Arg{entry description}\Arg{points}
% \end{syntax}
%
% Specifies an entry with given description and points.
% The entry is typeset as part of the block/grading scheme
% containing it.
% \end{function}
%
% \begin{function}{|}
% \begin{syntax}
% $\mid$ \meta{entry description} \& \meta{points} \textbackslash{}n
% \end{syntax}
% This is an alternative form to specify an entry. The |\n|
% is to be interpreted as a newline in the source file, so $\mid$ reads
% until the end of the line.
%
% This is equivalent to calling \cs{entry}\Arg{entry description}\Arg{points}
%
% The package option |pipe| has to be specified to activate this
% syntax.
%
% \begin{texnote}
% The $\mid$ character (pipe) is made an active character for the scope
% of each gradingscheme environment.
% Thus, this syntax only works if the gradingscheme is read in
% expansion mode by \LaTeX{}, since otherwise the category code
% will be messed up.
% \end{texnote}
% \end{function}
%
%
% \section{\LaTeX3 interface}
%
% There is also a \LaTeX3 interface for dealing with this package
% that can deal with all of the mentioned notions separately,
% technically allowing you to combine them in other ways or formatting
% them into your custom tables.
%
% These functions are for now not documented separately, since the author
% thinks that such use cases would be rather rare.
%
% The \LaTeX3 interface is, however, \emph{not} considered to be stable
% yet, so if you really have to rely on this, feel free to contact
% the author.
%
% \PrintChanges
%
% \end{documentation}
%
%
% \begin{implementation}
%
% \section{\pkg{grading-scheme} implementation}
% \begin{macrocode}
%<*package>
% \end{macrocode}
%
% \begin{macrocode}
%<@@=grading_scheme>
% \end{macrocode}
%
% \subsection{Dependencies and options}
%
% Currently, there is only one option
%
% \begin{variable}{\g_@@_pipe_syntax_bool}
%
% This will toggle the pipe syntax option of the package.
%
% \begin{macrocode}
\bool_new:N \g_@@_pipe_syntax_bool
% \end{macrocode}
% \end{variable}
%
%
% \begin{macrocode}
\keys_define:nn { grading-scheme }
{
pipe .bool_gset:N = \g_@@_pipe_syntax_bool,
pipe .default:n = { true },
unknown .code:n =
{
\msg_error:nnn { grading-scheme } { unknown-option} { \l_keys_key_str }
}
}
\msg_new:nnn { grading-scheme } { unknown-option}
{
Unknown ~ option ~ '#1'.
}
\RequirePackage { l3keys2e }
\ProcessKeysOptions { grading-scheme }
\RequirePackage{multirow}
\RequirePackage{rotating}
% \end{macrocode}
%
% \subsection{A simple logging module}
%
% \begin{macrocode}
%<*log>
% \end{macrocode}
%
% We provide a simple log/debugging facility for this package.
%
% \begin{variable}{\g_@@_log_depth_int}
% Stores the log depth for indentation in the log file.
% \begin{macrocode}
\int_new:N \g_@@_log_depth_int
% \end{macrocode}
% \end{variable}
%
% \begin{macro}{\@@_log_incr:}
%
% Increments the log depth
%
% \begin{macrocode}
\cs_new:Npn \@@_log_incr:
{
\int_gincr:N \g_@@_log_depth_int
}
% \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\@@_log_decr:}
%
% Decrements the log depth
%
% \begin{macrocode}
\cs_new:Npn \@@_log_decr:
{
\int_gdecr:N \g_@@_log_depth_int
}
% \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\@@_log:n, \@@_log:x}
%
% Logs to the terminal and log file using the current depth.
%
% \begin{macrocode}
\cs_new:Npn \@@_log:n #1
{
\iow_term:x
{
[gs] \prg_replicate:nn \g_@@_log_depth_int { . . }
\exp_not:n { #1 }
}
\iow_log:x
{
[gs] \prg_replicate:nn \g_@@_log_depth_int { . . }
\exp_not:n { #1 }
}
}
\cs_generate_variant:Nn \@@_log:n { x }
% \end{macrocode}
% \end{macro}
%
%
% \begin{macrocode}
%</log>
% \end{macrocode}
%
% \subsection{Wrappers}
%
% We provide some \LaTeX3 wrappers for private usage.
%
% \begin{macro}{\@@_multicolumn:nnn}
%
% Just a wrapper around \cs{multicolumn} from \LaTeXe.
%
% \begin{macrocode}
\cs_set_eq:NN \@@_multicolumn:nnn \multicolumn
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_multirow:nnn}
%
% Just a wrapper around \cs{multirow} from \LaTeXe.
%
% \begin{macrocode}
\cs_set_eq:NN \@@_multirow:nnn \multirow
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_cline:n, \@@_cline:nn}
%
% A wrapper around \cs{cline}.
%
% The second form takes the beginning and ending
% column as separate arguments.
%
% \begin{macrocode}
\cs_set_eq:NN \@@_cline:n \cline
\cs_new:Npn \@@_cline:nn #1 #2
{
\@@_cline:n { #1 - #2 }
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_hline:}
%
% Wrapper for a \cs{hline}
%
% \begin{macrocode}
\cs_set_eq:NN \@@_hline: \hline
% \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\@@_rotatebox:nnn}
%
% Wrapper around rotatebox
%
% \begin{macrocode}
\cs_new:Npn \@@_rotatebox:nnn #1 %implicit #2, #3
{
\rotatebox [ #1 ]
}
% \end{macrocode}
% \end{macro}
%
%
% \subsection{Customizable backends}
%
% We set up some functions that will be used internally,
% but could technically be customized at some point.
% For now, these are just constants.
%
% \begin{macro}{\@@_points:n}
%
% Prints the number of points.
% Used in the last column of the grading scheme.
%
% \begin{macrocode}
\cs_new:Npn \@@_points:n #1
{
\textbf{ #1 ~ P. }
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_operation:n}
%
% Prints an operation.
% Used in the leftmost column of a block.
%
% \begin{macrocode}
\cs_new:Npn \@@_operation:n #1
{
{ \sc #1 }
}
% \end{macrocode}
% \end{macro}
%
%
% \subsection{Resources}
%
% \subsubsection{Some general thoughts}
%
% This is some general reasoning about why we model data structures
% as we do in this package, comparing parts of \LaTeX3 to plain |C| code.
%
% We have to model elements, blocks and entries here.
% \LaTeX3 provides some data structures for this,
% and we will use property-lists to model our data structures for this package.
%
% When thinking about what a property list is,
% a call to \cs{prop_new:N} essentially allocates some memory for us
% and makes our given argument a \emph{pointer} to a data structure
% that we refer to as a \enquote{property list}.
%
% We want to think of these as pointers since modifying a property list
% at some place really also modifies this property list at another,
% so these behave like pointers.
%
% Considering the grouping mechanism of \TeX,
% this is of course not quite right for local variables
% (we assume that in the \LaTeX3 spirit,
% all variables are either local or global once and for all,
% to avoid confusion)
% since these rather correspond to one pointer at each
% grouping level, where upon entering such a grouping
% level, the (new) pointer is initialized with a copy of the outer instance of
% the pointer and destroyed again when leaving the current grouping level.
%
% In this spirit, we really want to think of grouping levels as \emph{scopes}
% like in \texttt{C}.
%
% Considering functions now, a typical \LaTeX3 function has no return value
% (these would be functions with the |_p| predicate or |_use:| functions
% that leave contents in the input stream),
% since this is in general not desired.
% Rather, we pass pointers as a function argument and receive the desired
% \enquote{return value} as written into our given pointer (overwriting
% any prior data), which is also a common behaviour in large parts of |C|.
%
% Now, as mentioned earlier, data structures such as property queues are
% just pointers that refer to some tokens with specific internal structure.
% All functions dealing with such pointers have to ensure that these
% invariants remain satisfied, and this is what functions like
% \cs{prop_get:NnN} or \cs{prop_put:Nn} do.
% The key point here is that we refer to these structures only
% with pointers and do not deal with them directly.
% This is what gives us some very nice abstrict model,
% hiding the class invariants of a property queue from the user and providing
% high-level semantic access to such data structures.
%
% Just for completeness, we mention that this is not the case for \emph{all}
% data structures.
% For example, a |clist| has some structure that is well-known and can be
% dealt with by the user directly.
% That is why there are also |clist| commands acceptiong |n|-type arguments
% for dealing with a |clist|, but no such commands for property-lists, as
% they only use |N| and thus essentially pointers.
%
% If we want to model data structures now, especially ours from this package,
% we even want data structures containing other data structures.
% Although technically, storing all data of a grading scheme in a single macro
% would be possible, due to its recursive structure, parsing would be quite
% a challenge and possibly also rather slow.
% Also, this would require \emph{direct} access to the representation of blocks
% contained in this block, which is undesired.
%
% Compare this to the question of putting a property-list inside a property-list.
% Since there is no (semantic/provided) possibility of actually putting a
% property-list anywhere, we cannot store property-lists in property-lists
% directly.
% We can, however, store the name of a property list inside of another one,
% this amounts to actually storing the \emph{pointer} to the first list
% inside the second one.
%
% Now, back to our package, we essentially want to model blocks and alike
% as |C|-style |struct|s that contain \emph{pointers} to their elements
% and similar.
% The classic question of ownership arises in this context,
% so we would have to consider shallow or deep copies and a user
% has to watch out when dealing with our data structures.
%
% Since only a limited set of operations is needed in our case,
% we take a simple approach by saying that each struct owns
% all its contents, that is, owns everythin its data member pointers
% point to, also recursively.
% This essentially forbids shallow-copying (violating our assumption)
% but we do not need this here, so this is okay.
%
% Still, this hase some undesired consequences:
% Since in \LaTeX3 each pointer has some name, we need to construct
% a lot of pointers on the fly where we are not able to actually
% specify their names directly, so we have to indirectly deal with pointers.
% That means that we actually need double-pointers, i.e. local variables
% \emph{containing} pointers to the data structures we are actually interested
% in. This is what a |void**| would correspond to in |C|.
% Also, note that once we store a pointer to some element in a property
% queue (e.g. the name of the list of members when dealing with a block),
% we actually also need a |void**| when retrieving this value again from
% the property queue, since we return by pointer.
%
% Consequently, this leads to quite a lot of expansion-control when dealing
% with such pointers, and if not taking precautions, also to easy confusion
% about what is a pointer and what not.
%
% Our approach to tackle these problems is described in \autoref{subsec:pointers}.
%
% \subsection{Pointers}
% \label{subsec:pointers}
%
% This module should/will be reworked into an own package in the future.
% Also, there is no proper documentation for it apart from the comments
% in the implementation, since this is not meant to be used in other
% code than this package currently, nor regarded stable.
%
% We introduce a new data type of |pointer| and a new argument
% type of |P|. The argument type |P| shall indicate a single expansion
% \emph{with the assumption that this expansion will yield a single token}.
% So, from an implementation point of view, this is the same as an |o|-type
% argument, just with further restricted assumptions.
%
% This also enables us to generate |P| variant arguments from |N| variant
% macros. Compare this to the usual deprecation warning that \LaTeX3
% gives when generating an |o| variant from an |N|-type argument:
%
% \begin{verbatim}
% ! LaTeX3 Error: Variant form 'o' deprecated for base form '\foo:N'. One
% (LaTeX3) should not change an argument from type 'N' to type 'o':
% (LaTeX3) base form only accepts a single token argument.
% \end{verbatim}
%
%
% Since basically anything in \LaTeX3 is in fact a pointer, we will
% introduce the |pointer| structure with the |ptr| type (suffix)
% and actually mean that this is a |void**|.
%
% Thus, we introduce the following conventions:
% \begin{enumerate}
% \item
% A \TeX-pointer is a \TeX control sequence that represents
% some data.
% \item
% A |pointer| is a control sequence that
% expands to a single \TeX{} control sequence that is a
% \TeX-pointer.
% \item
% The \emph{name} of a |pointer| is the name of the control sequence
% representing it.
% Thus, such a name always ends with |_ptr| by convetion.
% \item
% A |ptr| is said to be |NULL| if its expansion yields an undefined
% \TeX{} control sequence.
% We also refer to this as a |nullptr|.
% \item
% A \emph{typed pointer} is a pointer where the underlying type is specified.
% By this, we mean that expanding the token exactly once yields a token
% representing a data structure of the type we said this pointer to have
% or that the pointer is |NULL|.
% \item
% A \emph{void pointer} shall be a pointer whose actual type is unknown.
% \item
% When a |ptr| is of type |type|, we denote these by the suffix
% |_type_ptr|.
% \item
% \emph{Dereferencing} a pointer amounts to expanding it exactly once.
% \item
% A |P|-type argument accepts a single token that has to be of type |ptr|.
% The token is expanded exactly once and then treated as an |N|-type argument
% in the corresponding function.
% \end{enumerate}
%
%
% \begin{variable}{\g__ptr_counter_int}
%
% Counts the number of pointers given by \cs{ptr_new:N}.
% This ensures that each pointer can have a unique name
% regardless of grouping.
%
% \begin{macrocode}
\int_new:N \g__ptr_counter_int
% \end{macrocode}
% \end{variable}
%
% \begin{variable}{\l__ptr_var_prefix_str}
%
% Stores the prefix of new pointer variables.
%
% \begin{macrocode}
\str_new:N \l__ptr_var_prefix_str
% \end{macrocode}
% \end{variable}
%
%
%
% \begin{macro}{\ptr_new:N}
% \begin{syntax}
% \cs{ptr_new:N}\meta{pointer}
% \end{syntax}
%
% Gives a new unique pointer that is |NULL|.
% Gives an error when the \meta{pointer} already exists.
% The pointer variable is created globally.
%
% \begin{macrocode}
\cs_new:Npn \ptr_new:N #1
{
\__ptr_get_var_prefix:NN #1 \l__ptr_var_prefix_str
\ptr_new:NVn #1 \l__ptr_var_prefix_str { any }
}
\cs_new:Npn \ptr_new:Nn #1 #2
{
\ptr_new:Nnn { #1 } { #2 } { any }
}
% ptr var, prefix, type
\cs_new:Npn \ptr_new:Nnn #1 #2 %i #3
{
\str_case:nnT
{ #2 }
{
{ l } { }
{ g } { }
}
{
\tl_new:N #1
}
\__ptr_init:Nnn #1 { #2 } %i { #3 }
}
\cs_generate_variant:Nn \ptr_new:Nnn { N V n }
% ptr var, prefix, type
% assumes that the pointer name exists already in case of l or g prefix
\cs_new:Npn \__ptr_init:Nnn #1 #2 % implicit #3
{
\__ptr_get_var_prefix:NN #1 \l__ptr_var_prefix_str
\str_case:VnF
\l__ptr_var_prefix_str
{
{ l }
{
\cs_set_eq:NN \__ptr_poly_tl_set:Nx \tl_set:Nx
}
{ g }
{
\cs_set_eq:NN \__ptr_poly_tl_set:Nx \tl_gset:Nx
}
{ c }
{
\cs_set_eq:NN \__ptr_poly_tl_set:Nx \tl_const:Nx
}
}
{
\str_show:N \l__ptr_var_prefix_str % TODO: show error
}
\__ptr_init_aux:Nnn #1 { #2 }
}
\cs_generate_variant:Nn \__ptr_init:Nnn { N V n }
% ptr var, prefix, type. assumes poly_tl_set:Nx has been set
\cs_new:Npn \__ptr_init_aux:Nnn #1 #2 #3
{
\__ptr_poly_tl_set:Nx #1
{
\exp_not:c
{
#2
__ptr__unique__
\int_use:N \g__ptr_counter_int
_
#3
}
}
\int_gincr:N \g__ptr_counter_int
}
\cs_generate_variant:Nn \__ptr_init:Nnn { N V n }
% \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\__ptr_get_var_prefix:NN}
%
% Gets the first character of the name of the variable given as |#1|.
% The first character is assumed to be one of |c|, |l| or |g| by
% usual naming conventions.
%
% \begin{macrocode}
\cs_new:Npn \__ptr_get_var_prefix:NN #1 #2
{
\tl_if_head_eq_charcode:fNTF { \cs_to_str:N #1 } l
{
\str_set:Nn #2 { l }
}
{
\tl_if_head_eq_charcode:fNTF { \cs_to_str:N #1 } g
{
\str_set:Nn #2 { g }
}
{
\tl_if_head_eq_charcode:fNTF { \cs_to_str:N #1 } c
{
\str_set:Nn #2 { c }
}
{
\msg_error:nnx { ptr } { variable-name-illegal-prefix }
{
\token_to_str:N #1
}
}
}
}
}
% \end{macrocode}
% \begin{macrocode}
\msg_new:nnnn { ptr } { variable-name-illegal-prefix }
{
Requested ~ new ~ pointer ~ '#1' ~ has ~ illegal ~ prefix.
}
{
Prefix ~ should ~ be ~ one ~ of ~ 'l', ~ 'g' ~ or ~ 'c'.
}
% \end{macrocode}
% \end{macro}
%
%
%
% \begin{macro}{\ptr_clear:N}
%
% Clears this pointer.
% This makes the pointer equivalent to a new |nullptr|.
%
% \begin{macrocode}
\cs_new:Npn \ptr_clear:N #1
{
\__ptr_get_var_prefix:NN #1 \l__ptr_var_prefix_str
\__ptr_init:NVn #1 \l__ptr_var_prefix_str { any }
}
\cs_new:Npn \ptr_clear:Nn #1 #2
{
\__ptr_init:Nnn #1 { #2 } { any }
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\ptr_set:NN}
%
% Sets the pointer to represent the given argument.
%
% \begin{macrocode}
\cs_set_eq:NN \ptr_set:NN \tl_set:Nn
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\ptr_set_eq:NN}
%
% Accepts two pointers.
% The first is set to be equivalent to the second.
%
% \begin{macrocode}
\cs_set_eq:NN \ptr_set_eq:NN \tl_set_eq:NN
% \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\ptr_use:N}
%
% Uses the pointer, i.e.~expands to the stored \TeX{}-pointer.
%
% \begin{macrocode}
\cs_set_eq:NN \ptr_use:N \tl_use:N
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\__ptr_check:N}
%
% Checks that the given argument is a pointer.
%
% \begin{macrocode}
\cs_new:Npn \__ptr_check:N #1
{
\tl_if_single:NF #1
{
\msg_error:nnx { ptr } { is-not-a-pointer }
{
\token_to_str:N #1
}
}
}
% \end{macrocode}
% \begin{macrocode}
\msg_new:nnn { ptr } { is-not-a-pointer }
{
The ~ control ~ sequence ~ '#1' ~ is ~ not ~ a ~ valid ~ pointer.
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\__ptr_check:NN}
%
% Checks that the second argument is a pointer.
%
% \begin{macrocode}
\cs_new:Npn \__ptr_check:NN #1 #2
{
\__ptr_check:N #2
#1 #2
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\__ptr_check:nN}
%
% Checks that the second argument is a pointer.
%
% \begin{macrocode}
\cs_new:Npn \__ptr_check:nN #1 #2
{
\__ptr_check:N #2
{ #1 } #2
}
% \end{macrocode}
% \end{macro}
%
%
%
% \begin{variable}{\l__ptr_content_tl}
%
% Stores the (internal) \TeX-pointer
% of a |pointer|.
%
% \begin{macrocode}
\tl_new:N \l__ptr_content_tl
% \end{macrocode}
% \end{variable}
%
% \begin{macro}{\exp_args:NP, \exp_args:NNP, \exp_args:NNNP, \exp_args:NNNNP, \exp_args:NPP}
%
% Expands a pointer.
% This leaves the first tokens as a single token in the input
% stream, followed by the value of the pointer
% as a single token.
%
% If the last argument does not expand to
% a single token,
% an error is given.
%
% \begin{macrocode}
\cs_new:Npn \exp_args:NP #1 #2
{
\__ptr_check:N #2
\exp_last_unbraced:No #1 #2
}
\cs_new:Npn \exp_args:NNP #1 #2 #3
{
\__ptr_check:N #3
\exp_last_unbraced:NNo #1 #2 #3
}
\cs_new:Npn \exp_args:NNNP #1 #2 #3 #4
{
\__ptr_check:N #4
\exp_last_unbraced:NNNo #1 #2 #3 #4
}
\cs_new:Npn \exp_args:NNNNP #1 #2 #3 #4 #5
{
\__ptr_check:N #5
\exp_last_unbraced:NNNNo #1 #2 #3 #4 #5
}
\cs_new:Npn \exp_args:NPP #1 #2 #3
{
\__ptr_check:N #2
\__ptr_check:N #3
\exp_last_two_unbraced:Noo #1 #2 #3
}
% \end{macrocode}
% \end{macro}
%
%
% \begin{macro}[TF]{\ptr_if_null:N}
%
% Checkes if the pointer is |NULL|.
%
% \begin{macrocode}
\cs_new:Npn \ptr_if_null:NT
{
\exp_args:NP \cs_if_exist:NF
}
\cs_new:Npn \ptr_if_null:NF
{
\exp_args:NP \cs_if_exist:NT
}
\cs_new:Npn \ptr_if_null:NTF #1 #2 #3
{
\exp_args:NP \cs_if_exist:NTF #1 { #3 } { #2 }
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\tl_set_eq:NP, \tl_set_eq:PN, \tl_set_eq:PP, \tl_use:P}
% \begin{macro}{\exp_not:P}
% \begin{macro}{\clist_new:P, \clist_put_right:Pn, \clist_gput_right:Pn, \clist_map_function:PN, \prop_show:P, \clist_show:P}
%
%
% Just variants of \cs{tl_set_eq:NN} with indicated signature.
%
% \begin{macrocode}
\cs_new:Npn \tl_set_eq:NP
{
\exp_args:NNP \tl_set_eq:NN
}
\cs_new:Npn \tl_set_eq:PN
{
\exp_args:NP \tl_set_eq:NN
}
\cs_new:Npn \tl_set_eq:PP
{
\exp_args:NPP \tl_set_eq:NN
}
\cs_new:Npn \tl_use:P
{
\exp_args:NP \tl_use:N
}
\cs_new:Npn \exp_not:P
{
\exp_args:NP\exp_not:N
}
\cs_new:Npn \clist_new:P
{
\exp_args:NP \clist_new:N
}
\cs_new:Npn \clist_show:P
{
\exp_args:NP \clist_show:N
}
\cs_new:Npn \clist_put_right:Pn
{
\exp_args:NP \clist_put_right:Nn
}
\cs_new:Npn \clist_gput_right:Pn
{
\exp_args:NP \clist_gput_right:Nn
}
\cs_new:Npn \clist_map_function:PN
{
\exp_args:NP \clist_map_function:NN
}
\cs_new:Npn \prop_show:P
{
\exp_args:NP \prop_show:N
}
% \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
%
%
%
% \begin{macro}{\ptr_show:N}
%
% Shows information about this pointer,
% namely:
%
% If it is |NULL|, then it indicates this.
% If it is not |NULL|, then the \TeX-pointer
% and the contained contents of the \TeX-pointer
% (in unexpanded form) are shown.
%
% \begin{macrocode}
\cs_new:Npn \ptr_show:N #1
{
\__ptr_check:N #1
\ptr_if_null:NTF #1
{
\tl_show:x
{
\token_to_str:N #1 -> \exp_not:P #1 = NULL
}
}
{
\tl_show:x
{
\token_to_str:N #1 -> \exp_not:P #1 -> \exp_args:NP \exp_not:V #1
}
}
}
% \end{macrocode}
% \end{macro}
%
%
% \subsection{Structs}
%
% We will model |C|-style |struct|s as property-lists in this package.
% Each struct member is put into the property list, using its
% 'name' as a key, and we store the corresponding contents there.
%
% We will also have a local variable named correspondingly for each
% |struct| member. In case we deal with a struct and want to acces
% its data, we load the values from the property-list into these
% local variables.
% Thus, the full information about a |struct| is contained in the
% property-list, and we can work with them quite conveniently
% when implementing functions.
%
%
% \subsection{Entries}
%
% An entry is for us the following:
%
% \begin{verbatim}
% struct Entry {
% tl description;
% int points;
% }
% \end{verbatim}
%
% \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}
%
% Do what their signature suggests.
% We just forward them to the property lists.
%
% \begin{macrocode}
\cs_set_eq:NN \grading_scheme_entry_new:N \prop_new:N
\cs_set_eq:NN \grading_scheme_entry_clear:N \prop_clear:N
\cs_set_eq:NN \grading_scheme_entry_set_eq:NN \prop_set_eq:NN
\cs_set_eq:NN \grading_scheme_entry_gclear:N \prop_gclear:N
\cs_set_eq:NN \grading_scheme_entry_gset_eq:NN \prop_gset_eq:NN
% \end{macrocode}
% \end{macro}
%
% \begin{variable}{\l_@@_entry_points_int, \l_@@_entry_description_tl}
%
% The mentioned local variables where we retrieve values.
%
% \begin{macrocode}
\int_new:N \l_@@_entry_points_int
\tl_new:N \l_@@_entry_description_tl
% \end{macrocode}
% \end{variable}
%
%
% \begin{macro}{\grading_scheme_entry_set_description:Nn, \grading_scheme_entry_gset_description:Nn}
%
% Sets the description.
%
% \begin{macrocode}
\cs_new:Npn \grading_scheme_entry_set_description:Nn #1 % implicit description
{
\prop_put:Nnn #1 { description }
}
\cs_new:Npn \grading_scheme_entry_gset_description:Nn #1 % implicit description
{
\prop_gput:Nnn #1 { description }
}
% \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\grading_scheme_entry_set_points:Nn, \grading_scheme_entry_gset_points:Nn}
%
% Sets the points.
%
% \begin{macrocode}
\cs_new:Npn \grading_scheme_entry_set_points:Nn #1 #2
{
\prop_put:Nnx #1 { points } { \int_eval:n { #2 } }
}
\cs_new:Npn \grading_scheme_entry_gset_points:Nn #1 #2
{
\prop_gput:Nnn #1 { points } { \int_eval:n { #2 } }
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\grading_scheme_entry_get_description:NN}
%
% Gets the description of the entry and stores it in |#2|.
% The assignment is local.
%
% \begin{macrocode}
\cs_new:Npn \grading_scheme_entry_get_description:NN #1 %implicit #2
{
\prop_get:NnN #1 { description }
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\grading_scheme_entry_get_points:NN}
%
% Gets the points of the entry and stores it in |#2|.
% The assignment is local.
%
% \begin{macrocode}
\cs_new:Npn \grading_scheme_entry_get_points:NN #1 %implicit #2
{
\prop_get:NnN #1 { points }
}
% \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\@@_entry_load_points:N}
%
% Loads the points into the local variable
%
% \begin{macrocode}
\cs_new:Npn \@@_entry_load_points:N #1
{
\grading_scheme_entry_get_points:NN #1 \l_@@_entry_points_int
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_entry_load_description:N}
%
% Loads the description of an entry
%
% \begin{macrocode}
\cs_new:Npn \@@_entry_load_description:N #1
{
\grading_scheme_entry_get_description:NN #1 \l@@_entry_description_tl
}
% \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\grading_scheme_entry_format:NnnN, \grading_scheme_entry_gformat:NnnN,\grading_scheme_entry_format:PnnN, \grading_scheme_entry_gformat:PnnN}
% \begin{syntax}
% \cs{grading_scheme_entry_put:NnnN}\Arg{entry}\Arg{indent}\Arg{width}\Arg{tl var}
% \end{syntax}
%
% Puts the formatted contents of the entry into the \meta{tl var}.
% The \meta{indent} specify how many tabs will be inserted
% before adding the contents.
% The \meta{width} specifies how many columns this entry will occupy.
% This \meta{width} has to be at least 2.
%
% An |\\| is inserted at the end of the entry.
%
% \begin{macrocode}
\cs_new:Npn \grading_scheme_entry_format:NnnN
{
\cs_set_eq:NN \@@_tl_put_right:Nx \tl_put_right:Nx
\@@_entry_format:NnnN
}
\cs_new:Npn \grading_scheme_entry_gformat:NnnN
{
\cs_set_eq:NN \@@_tl_put_right:Nx \tl_gput_right:Nx
\@@_entry_format:NnnN
}
\cs_new:Npn \grading_scheme_entry_format:PnnN
{
\exp_args:NP \grading_scheme_entry_format:NnnN
}
\cs_new:Npn \grading_scheme_entry_gformat:PnnN
{
\exp_args:NP \grading_scheme_entry_gformat:NnnN
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_entry_format:NnnN, \@@_entry_format:PnnN}
%
% Aux function that assumes that \cs{@@_tl_put_right:Nx}
% has been so to globally or locally putting into the token list.
%
% \begin{macrocode}
\cs_new:Npn \@@_entry_format:NnnN #1 #2 #3 #4
{
%<*log>
\@@_log:x
{ Formatting ~ entry ~ '\token_to_str:N #1' ~ into ~ '\token_to_str:N #4' with }
\@@_log:n { indent = '#2' ~ and ~ width ~ '#3' }
\prop_log:N #1
\@@_log_incr:
%</log>
\@@_entry_assert_description:N #1 % implicitly loads value
\@@_entry_assert_points:N #1 % implicitly loads value
\@@_tl_put_right:Nx #4
{
\prg_replicate:nn { #2 } { & }
\exp_not:N \@@_multicolumn:nnn
{
\int_eval:n { #3 -1 }
}
{ l }
{
\exp_not:V \l_@@_entry_description_tl
}
&
\exp_not:N \@@_points:n
{
\tl_use:N \l_@@_entry_points_int
}
\\
}
%<*log>
\@@_log_decr:
\@@_log:x { / Formatting ~ entry ~ '\token_to_str:N #1' }
%</log>
}
\cs_new:Npn \@@_entry_forrmat:PnnN % implicit #1-4
{
\exp_args:NP \@@_entry_format:NnnN
}
% \end{macrocode}
% \end{macro}
%
%
%
% \begin{macro}{\@@_entry_assert_description:N, \@@_entry_assert_points:N}
%
% These functions check the presence of values of an entry.
% If an entry is absent, an error message is omitted.
%
% \begin{macrocode}
\cs_new:Npn \@@_entry_assert_description:N #1
{
\@@_entry_load_description:N #1
\quark_if_no_value:NT \l_@@_entry_description_tl
{
\msg_error:nnxxx { grading-scheme } { missing-value }
{ entry } { \token_to_str:N #1 } { description }
}
}
\cs_new:Npn \@@_entry_assert_points:N #1
{
\@@_entry_load_points:N #1
\quark_if_no_value:NT \l_@@_entry_points_int
{
\msg_error:nnxxx { grading-scheme } { missing-value }
{ entry } { \token_to_str:N #1 } { points }
}
}
\msg_new:nnn { grading-scheme } { missing-value }
{
#1 ~ '#2' ~ has ~ no ~ #3.
}
% \end{macrocode}
% \end{macro}
%
%
% \subsection{Blocks}
%
% \subsubsection{Struct setting / reading}
%
% A \meta{block} is for us the following:
%
% \begin{verbatim}
% struct Block {
% clist* elements;
% tl text;
% tl operation;
% }
% \end{verbatim}
%
% \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}
%
% Do what thear names suggest. We just forward these to the property lists.
%
% \begin{macrocode}
\cs_set_eq:NN \grading_scheme_block_new:N \prop_new:N
\cs_set_eq:NN \grading_scheme_block_clear:N \prop_clear:N
\cs_set_eq:NN \grading_scheme_block_set_eq:NN \prop_gset_eq:NN
\cs_set_eq:NN \grading_scheme_block_gclear:N \prop_gclear:N
\cs_set_eq:NN \grading_scheme_block_gset_eq:NN \prop_gset_eq:NN
% \end{macrocode}
% \end{macro}
%
% \begin{variable}{\l_@@_block_elements_clist_ptr, \l_@@_block_description_tl, \l_@@_block_operation_tl}
%
% The mentioned local variables where we retrieve values.
%
% \begin{macrocode}
\ptr_new:N \l_@@_block_elements_clist_ptr
\tl_new:N \l_@@_block_description_tl
\tl_new:N \l_@@_block_operation_tl
% \end{macrocode}
% \end{variable}
%
% \begin{macro}
% {
% \grading_scheme_block_set_description:Nn, \grading_scheme_block_gset_description:Nn,
% \grading_scheme_block_set_operation_tl:Nn, \grading_scheme_block_gset_operation_tl:Nn,
% \grading_scheme_block_set_elements:NN, \grading_scheme_block_gset_elements:NN,
% \grading_scheme_block_set_elements:NP, \grading_scheme_block_gset_elements:NP,
% }
%
% Set the description / operation or elements of the block.
%
% When setting elements, a \meta{clist var} is expected.
%
% \begin{macrocode}
\cs_new:Npn \grading_scheme_block_set_description:Nn #1 % implicit description
{
\prop_put:Nnn #1 { description }
}
\cs_new:Npn \grading_scheme_block_gset_description:Nn #1 % implicit description
{
\prop_gput:Nnn #1 { description }
}
\cs_new:Npn \grading_scheme_block_set_operation:Nn #1 % implicit operation
{
\prop_put:Nnn #1 { operation }
}
\cs_new:Npn \grading_scheme_block_gset_operation:Nn #1 % implicit operation
{
\prop_gput:Nnn #1 { operation }
}
\cs_new:Npn \grading_scheme_block_set_elements:NN #1 % implicit elements clist
{
\prop_put:Nnn #1 { elements }
}
\cs_new:Npn \grading_scheme_block_gset_elements:NN #1 % implicit elements clist
{
\prop_gput:Nnn #1 { elements }
}
\cs_new:Npn \grading_scheme_block_set_elements:NP
{
\exp_args:NNP \grading_scheme_block_set_elements:NN
}
\cs_new:Npn \grading_scheme_block_gset_elements:NP
{
\exp_args:NNP \grading_scheme_block_gset_elements:NN
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\grading_scheme_block_get_description:NN, \grading_scheme_block_get_operation:NN, \grading_scheme_block_get_elements:NN}
%
% \begin{syntax}
% \cs{grading_scheme_block_get_description:NN}\meta{block var}\meta{tl var}
% \cs{grading_scheme_block_get_operation:NN}\meta{block var}\meta{tl var}
% \cs{grading_scheme_block_get_elements:NN}\meta{block var}\meta{clist ptr}
% \end{syntax}
%
% Get access to the members of the block.
% The assignment is local.
% The returned values might be \cs{q_no_value}
% if no value is present.
%
% \begin{macrocode}
\cs_new:Npn \grading_scheme_block_get_description:NN #1 % implicit #2
{
\prop_get:NnN #1 { description }
}
\cs_new:Npn \grading_scheme_block_get_operation:NN #1 % implicit #2
{
\prop_get:NnN #1 { operation }
}
\cs_new:Npn \grading_scheme_block_get_elements:NN #1 % implicit #2
{
\prop_get:NnN #1 { elements }
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_block_load_description:N, \@@_block_load_operation:N, \@@_block_load_elements:NN}
%
% Loads the members into the corresponding local variables.
%
% \begin{macrocode}
\cs_new:Npn \@@_block_load_description:N #1
{
\grading_scheme_block_get_description:NN #1 \l_@@_block_description_tl
}
\cs_new:Npn \@@_block_load_operation:N #1
{
\grading_scheme_block_get_operation:NN #1 \l_@@_block_operation_tl
}
\cs_new:Npn \@@_block_load_elements:N #1
{
\grading_scheme_block_get_elements:NN #1 \l_@@_block_elements_clist_ptr
}
% \end{macrocode}
% \end{macro}
%
%
%
% \begin{macro}{\@@_block_ensure_elements:N}
%
% Ensures that this block has an elements attribute that is a valid
% clist pointer.
%
% If no value is present, or the pointer is |NULL|,
% a pointer and/or the clist variable
% are created.
%
% \begin{macrocode}
\cs_new:Npn \@@_block_ensure_elements:N % implicit #1
{
\cs_set_eq:NN
\@@_block_set_elements_optg:NP
\grading_scheme_block_set_elements:NP
\@@_block_ensure_elements_aux:nN { l }
}
\cs_new:Npn \@@_block_gensure_elements:N % implicit #1
{
\cs_set_eq:NN
\@@_block_set_elements_optg:NP
\grading_scheme_block_gset_elements:NP
\@@_block_ensure_elements_aux:nN { g } %i #1
}
% prefix, block
% assumes that \@@_block_set_elements_optg:NP has been
\cs_new:Npn \@@_block_ensure_elements_aux:nN #1 #2
{
\@@_block_load_elements:N #2
\quark_if_no_value:NT \l_@@_block_elements_clist_ptr
{
\ptr_clear:Nn \l_@@_block_elements_clist_ptr { #1 }
\@@_block_set_elements_optg:NP
#2
\l_@@_block_elements_clist_ptr
}
\ptr_if_null:NT \l_@@_block_elements_clist_ptr
{
\clist_new:P \l_@@_block_elements_clist_ptr
}
}
% \end{macrocode}
% \end{macro}
%
%
% \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}
% \begin{syntax}
% \cs{grading_scheme_block_add_element:NN}\meta{block var}\meta{element var}
% \end{syntax}
%
% Add an element to the block.
%
% \begin{macrocode}
\cs_new:Npn \grading_scheme_block_add_element:NN #1 % implicit element
{
\@@_block_ensure_elements:N #1 % also loads local variable
\clist_put_right:Pn \l_@@_block_elements_clist_ptr
}
\cs_new:Npn \grading_scheme_block_gadd_element:NN #1 % implicit element
{
\@@_block_gensure_elements:N #1 % also loads local variable
\clist_gput_right:Pn \l_@@_block_elements_clist_ptr
}
\cs_new:Npn \grading_scheme_block_add_element:PP
{
\exp_args:NPP \grading_scheme_block_add_element:NN
}
\cs_new:Npn \grading_scheme_block_gadd_element:PP
{
\exp_args:NPP \grading_scheme_block_gadd_element:NN
}
\cs_new:Npn \grading_scheme_block_add_element:PN
{
\exp_args:NP \grading_scheme_block_add_element:NN
}
\cs_new:Npn \grading_scheme_block_gadd_element:PN
{
\exp_args:NP \grading_scheme_block_gadd_element:NN
}
% \end{macrocode}
% \end{macro}
%
% \subsubsection{Formatting blocks}
%
%
% \begin{macro}{\grading_scheme_block_format:NnnnN, \grading_scheme_block_gformat:NnnnN, \grading_scheme_block_format:PnnnN, \grading_scheme_block_gformat:PnnnN}
%
% \begin{syntax}
% \cs{grading_scheme_block_format:NnnnN}\meta{block var}\Arg{indent}\Arg{width}\Arg{indent first row}\meta{tl var}
% \end{syntax}
%
% Formats this block and puts the control sequence into \meta{tl var}.
%
% The \meta{indent} and \meta{width} work as in \cs{grading_scheme_entry_format:NnnN}.
%
% \meta{indent first row} can be any \meta{boolean expression} and indicates
% if the first row is also indented.
% Set this to false to start the block in a row of the tabular that already
% has contents.
%
% \begin{macrocode}
\cs_new:Npn \grading_scheme_block_format:NnnnN %implicit #1-5
{
\cs_set_eq:NN \@@_tl_put_right:Nx \tl_put_right:Nx
\cs_set_eq:NN \@@_element_format_optg:NnnnN \grading_scheme_element_format:NnnnN
\cs_set_eq:NN \@@_tl_set:Nn \tl_set:Nn
\@@_block_format:NnnnN
}
\cs_new:Npn \grading_scheme_block_gformat:NnnnN %implicit #1-5
{
\cs_set_eq:NN \@@_tl_put_right:Nx \tl_gput_right:Nx
\cs_set_eq:NN \@@_element_format_optg:NnnnN \grading_scheme_element_gformat:NnnnN
\cs_set_eq:NN \@@_tl_set:Nn \tl_gset:Nn
\@@_block_format:NnnnN
}
\cs_new:Npn \grading_scheme_block_format:PnnnN % implicit #1-5
{
\exp_args:NP
\grading_scheme_block_format:NnnnN
}
\cs_new:Npn \grading_scheme_block_gformat:PnnnN % implicit #1-5
{
\exp_args:NP
\grading_scheme_block_gformat:NnnnN
}
% \end{macrocode}
% \end{macro}
%
%
% For formatting the block, we need some local variables:
%
%
% \begin{variable}{\l_@@_block_indent_bool}
%
% Controls whether the \cs{@@_block_indent:nN} macro
% will actually perform an indent.
%
% \begin{macrocode}
\bool_new:N \l_@@_block_indent_bool
% \end{macrocode}
% \end{variable}
%
% \begin{variable}{\@@_block_height_int}
%
% Locally stores the height of the block to be typeset.
%
% \begin{macrocode}
\int_new:N \l_@@_block_height_int
% \end{macrocode}
% \end{variable}
%
%
%
% \begin{macro}{\@@_block_format:NnnnN, \@@_block_format:PnnnN}
%
% Aux function.
% Assumes that \cs{@@__tl_put_right:Nx}
% has been set properly.
%
% \begin{macrocode}
\cs_new:Npn \@@_block_format:NnnnN #1 #2 #3 #4 #5
{
%<*log>
\@@_log:x
{
Formatting ~ block ~ '\token_to_str:N #1' ~ into ~ '\token_to_str:N #5'
~ with ~ indent ='#2', ~ width ~ '#3' ~ and ~ first ~
row = '\bool_to_str:n { #4 }'
}
\prop_log:N #1
\@@_block_load_elements:N #1
\exp_args:NP \clist_log:N \l_@@_block_elements_clist_ptr
\@@_log_incr:
%</log>
% \end{macrocode}
% We need grouping here so that our indentation boolean
% is not messed up by recursive calls:
% \begin{macrocode}
\bool_set:Nn \l_@@_block_indent_bool { #4 && \c_true_bool }
\group_begin:
\@@_block_load_description:N #1
\grading_scheme_block_get_height:NN #1 \l_@@_block_height_int
% \end{macrocode}
% We now format the description of the block if a value is present.
% \begin{macrocode}
\quark_if_no_value:NF \l_@@_block_description_tl
{
\@@_block_indent:nN { #2 } #5
\@@_tl_put_right:Nx #5
{
\exp_not:N \@@_multicolumn:nnn
{
\int_eval:n { #3 }
}
{ l| }
{
\exp_not:V \l_@@_block_description_tl
}
\\
\exp_not:N \@@_cline:nn
{
\int_eval:n { #2 + 2 }
}
{
\int_eval:n { #2 + #3 }
}
}
}
% \end{macrocode}
% Now, we have to format the operation of this block.
% This is a multirow with rotated description
% \begin{macrocode}
\@@_block_indent:nN { #2 } #5
\@@_block_assert_operation:N #1
\@@_tl_put_right:Nx #5
{
\exp_not:N \@@_multirow:nnn
{
\int_eval:n { \int_use:N \l_@@_block_height_int - 1 }
}
{ * }
{
\exp_not:N \@@_rotatebox:nnn
{ origin = c }
{ 90 }
{
\exp_not:N \@@_operation:n
{
\exp_not:V \l_@@_block_operation_tl
}
}
}
&
}
% \end{macrocode}
% The first element of our block must not be indented:
% \begin{macrocode}
\bool_set_false:N \l_@@_block_indent_bool
% \end{macrocode}
% Now, we want to recursively typeset all elements of this block.
% We need a customized function for this to map over the elements.
% \begin{macrocode}
\cs_set:Npn \@@_block_format_element:N ##1
{
\@@_element_format_optg:NnnnN
##1
{ #2 + 1 } % indent is one more that the current block
{ #3 - 1 } % width is one less than current block
{ \l_@@_block_indent_bool }
#5
% \end{macrocode}
% This ensures that the second and all further elements will get indented:
% \begin{macrocode}
\bool_set_true:N \l_@@_block_indent_bool
}
\@@_block_ensure_elements:N #1 % load + sanitize elements
\clist_map_function:PN
\l_@@_block_elements_clist_ptr
\@@_block_format_element:N
% \end{macrocode}
% Now, we need to 'smuggle out' the output token list of the current group.
% \begin{macrocode}
\exp_args:NNNV
\group_end:
\@@_tl_set:Nn
#5
#5
%<*log>
\@@_log_decr:
\@@_log:x { / Formatting ~ block ~ '\token_to_str:N #1' }
%</log>
}
\cs_new:Npn \@@_block_format:PnnnN
{
\exp_args:NP \@@_block_format:NnnnN
}
% \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\@@_block_assert_operation:N}
%
% Asserts that the block has an operation
% and loads it.
% If no operation is set,
% an error is emitted.
%
% \begin{macrocode}
\cs_new:Npn \@@_block_assert_operation:N #1
{
\@@_block_load_operation:N #1
\quark_if_no_value:NT \l_@@_block_operation_tl
{
\msg_error:nnxxx { grading-scheme } { missing-value}
{ block }
{ \token_to_str:N #1 }
{ operation }
}
}
% \end{macrocode}
% \end{macro}
%
%
%
% \begin{macro}{\@@_block_indent:nN}
% \begin{syntax}
% \cs{@@_block_indent:nN}\Arg{indent}\meta{tl var}
% \end{syntax}
%
% Performs the indent into \meta{tl var}
% iff \cs{l_@@_block_indent_bool} is true.
%
% Sets \cs{l_@@_block_indent_bool} to true afterwards.
%
% \begin{macrocode}
\cs_new:Npn \@@_block_indent:nN #1 #2
{
\bool_if:NT \l_@@_block_indent_bool
{
\@@_tl_put_right:Nx #2
{
\prg_replicate:nn { #1 } { & }
}
}
\bool_set_true:N \l_@@_block_indent_bool
}
% \end{macrocode}
% \end{macro}
%
%
% \subsubsection{Width and height of a block}
%
% \begin{variable}{\l_@@_height_sum_int, \l_@@_height_acc_int}
%
% Some temporary int values
%
% \begin{macrocode}
\int_new:N \l_@@_height_sum_int
\int_new:N \l_@@_height_acc_int
% \end{macrocode}
% \end{variable}
%
%
% \begin{macro}{\grading_scheme_block_get_height:NN, \grading_scheme_block_get_height:PN}
% \begin{syntax}
% \cs{grading_scheme_block_get_height:NN}\meta{block var}\meta{int var}
% \end{syntax}
%
% Gets the height of a block and stores
% it into the \meta{int var}.
%
% \begin{macrocode}
\cs_new:Npn \grading_scheme_block_get_height:NN #1 #2
{
%<*log>
\@@_log:x { Getting ~ height ~ of ~ block ~ '\token_to_str:N #1' }
\@@_log_incr:
%</log>
% \end{macrocode}
% Grouping is needed to not mess up local variables in the recursion:
% \begin{macrocode}
\group_begin:
\@@_block_load_elements:N #1
\int_zero:N \l_@@_height_sum_int
\clist_map_function:PN
\l_@@_block_elements_clist_ptr
\@@_block_height_accumulator:N
\grading_scheme_block_if_description:NT #1
{
\int_incr:N \l_@@_height_sum_int
}
% \end{macrocode}
% Smuggle out this length at return it to the caller:
% \begin{macrocode}
\exp_args:NNNV
\group_end:
\int_set:Nn #2 \l_@@_height_sum_int
%<*log>
\@@_log_decr:
\@@_log:x
{
/ Getting ~ height ~ of ~ block ~ '\token_to_str:N #1':
'\int_use:N #2'
}
%</log>
}
\cs_new:Npn \grading_scheme_block_get_height:PN
{
\exp_args:NP \grading_scheme_block_get_height:NN
}
% \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\@@_block_height_accumulator:N}
%
% This is mapped on the elements of a block
% and accumulates the heights.
%
% \begin{macrocode}
\cs_new:Npn \@@_block_height_accumulator:N #1
{
\grading_scheme_element_get_height:NN #1 \l_@@_height_acc_int
\int_add:Nn \l_@@_height_sum_int
{ \int_use:N \l_@@_height_acc_int }
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}[TF]{\grading_scheme_block_if_description:N}
%
% Tests if the given \meta{block var} has a description
% set or not.
% Also loads this description
%
% \begin{macrocode}
\cs_new:Npn \grading_scheme_block_if_description:NT #1 % implicit #2
{
\@@_block_load_description:N #1
\quark_if_no_value:NF \l_@@_block_description_tl
}
\cs_new:Npn \grading_scheme_block_if_description:NF #1 % implicit #2
{
\@@_block_load_description:N #1
\quark_if_no_value:NT \l_@@_block_description_tl
}
\cs_new:Npn \grading_scheme_block_if_description:NTF #1 #2 #3
{
\@@_block_load_description:N #1
\quark_if_no_value:NTF \l_@@_block_description_tl
{ #3 }
{ #2 }
}
% \end{macrocode}
% \end{macro}
%
%
% \begin{variable}{\l_@@_max_width_int}
%
% \begin{macrocode}
% \end{macrocode}
% \end{variable}
%
% \begin{variable}{\l_@@_width_acc_int,\l_@@_max_width_int}
%
% Some temporary int values
%
% \begin{macrocode}
\int_new:N \l_@@_max_width_int
\int_new:N \l_@@_width_acc_int
% \end{macrocode}
% \end{variable}
%
%
%
%
% \begin{macro}{\grading_scheme_block_get_natural_width:NN,\grading_scheme_block_get_natural_width:PN}
%
% Gets the \enquote{natural} width of a block,
% that is: The minimal width of this block so
% that it can be typeset properly.
%
% \begin{macrocode}
\cs_new:Npn \grading_scheme_block_get_natural_width:NN #1 #2
{
%<*log>
\@@_log:x
{ Getting ~ natural ~ width ~ of ~ block ~ '\token_to_str:N #1'. }
\@@_log_incr:
%</log>
\group_begin:
\@@_block_load_elements:N #1
\int_zero:N \l_@@_max_width_int
\clist_map_function:PN
\l_@@_block_elements_clist_ptr
\@@_block_width_accumulator:N
\int_incr:N \l_@@_max_width_int
\exp_args:NNNV
\group_end:
\int_set:Nn #2 \l_@@_max_width_int
%<*log>
\@@_log_decr:
\@@_log:x
{ / Getting ~ natural ~ width ~ of ~ block ~ '\token_to_str:N #1'. }
%</log>
}
\cs_new:Npn \grading_scheme_block_get_natural_width:PN
{
\exp_args:NP \grading_scheme_block_get_natural_width:NN
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_block_width_accumulator:N}
%
% Gets the natural width of subelements
% and accumulates the maximum of them.
%
% \begin{macrocode}
\cs_new:Npn \@@_block_width_accumulator:N #1
{
%<*log>
\@@_log:x { Accumulating ~ width ~ of ~ '\token_to_str:N #1' }
\@@_log_incr:
%</log>
\grading_scheme_element_get_natural_width:NN #1 \l_@@_width_acc_int
\int_set:Nn \l_@@_max_width_int
{
\int_max:nn
\l_@@_width_acc_int
\l_@@_max_width_int
}
%<*log>
\@@_log_decr:
\@@_log:x { / Accumulationg ~ width ~ of ~ '\token_to_str:N #1' }
%</log>
}
% \end{macrocode}
% \end{macro}
%
%
% \subsection{Elements}
%
% As discussed earlier, an \meta{element} is either a \meta{block}
% or an \meta{entry}.
% Thus, our natural representation is as follows:
%
% \begin{verbatim}
% struct Element {
% void* content;
% tl type;
% }
% \end{verbatim}
%
% which essentially just implements a |union| that knows of its current
% member.
%
%
% \begin{macro}{\@@_element_new:N, \@@_element_clear:N, \@@_element_set_eq:NN, \@@_element_gclear:N, \@@_element_gset_eq:NN}
%
% Do what these say. Forward to the underlying property lists.
%
% \begin{macrocode}
\cs_set_eq:NN \grading_scheme_element_new:N \prop_new:N
\cs_set_eq:NN \grading_scheme_element_clear:N \prop_clear:N
\cs_set_eq:NN \grading_scheme_element_set_eq:NN \prop_set_eq:NN
\cs_set_eq:NN \grading_scheme_element_gclear:N \prop_gclear:N
\cs_set_eq:NN \grading_scheme_element_gset_eq:NN \prop_gset_eq:NN
% \end{macrocode}
% \end{macro}
%
% \begin{variable}{\l_@@_element_content_void_ptr, \l_@@_element_type_str}
%
% Mentioned local variables.
%
% \begin{macrocode}
\ptr_new:N \l_@@_element_content_void_ptr
\str_new:N \l_@@_element_type_str
% \end{macrocode}
% \end{variable}
%
%
% \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}
% \begin{syntax}
% \cs{grading_scheme_element_set_block:NN} \meta{element var}\meta{block var}
% \end{syntax}
%
% \begin{macrocode}
\cs_new:Npn \grading_scheme_element_set_block:NN #1 % implicit #2
{
\prop_put:Nnn #1 { type } { block }
\prop_put:Nnn #1 { content }
}
\cs_new:Npn \grading_scheme_element_gset_block:NN #1 % implicit #2
{
\prop_gput:Nnn #1 { type } { block }
\prop_gput:Nnn #1 { content }
}
\cs_new:Npn \grading_scheme_element_set_entry:NN #1 % implicit #2
{
\prop_put:Nnn #1 { type } { entry }
\prop_put:Nnn #1 { content }
}
\cs_new:Npn \grading_scheme_element_gset_entry:NN #1 % implicit #2
{
\prop_gput:Nnn #1 { type } { entry }
\prop_gput:Nnn #1 { content }
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\grading_scheme_element_get_content:NN, \grading_scheme_element_get_type:NN}
% \begin{syntax}
% \cs{grading_scheme_element_get_content:NN} \meta{element var}\meta{void ptr}
% \cs{grading_scheme_element_get_type:NN} \meta{element var}\meta{str var}
% \end{syntax}
%
% Get the contents. The assignment is local.
%
% \begin{macrocode}
\cs_new:Npn \grading_scheme_element_get_content:NN #1 % implicit #2
{
\prop_get:NnN #1 { content }
}
\cs_new:Npn \grading_scheme_element_get_type:NN #1 % implicit #2
{
\prop_get:NnN #1 { type }
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_element_load_content:N, \@@_element_load_type:NN}
%
% Loads the element into the local variables.
%
% \begin{macrocode}
\cs_new:Npn \@@_element_load_content:N #1
{
\grading_scheme_element_get_content:NN #1 \l_@@_element_content_void_ptr
}
\cs_new:Npn \@@_element_load_type:N #1
{
\grading_scheme_element_get_type:NN #1 \l_@@_element_type_str
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}[noTF]{\grading_scheme_element_cases:Nnn}
% \begin{syntax}
% \cs{grading_scheme_element_cases}\meta{element var}\Arg{entry code}\Arg{block code}
% \end{syntax}
%
% Distinguishes between the
% cases of the element type.
%
% Also loads the element type.
%
% \begin{macrocode}
\cs_new:Npn \grading_scheme_element_cases:Nnn % implicit #1-3
{
\cs_set_eq:NN \@@_str_case:Vnw \str_case:Vn
\@@_element_cases:Nnnw
}
\cs_new:Npn \grading_scheme_element_cases:NnnT % implicit #1-4
{
\cs_set_eq:NN \@@_str_case:Vnw \str_case:VnT
\@@_element_cases:Nnnw
}
\cs_new:Npn \grading_scheme_element_cases:NnnF % implicit #1-4
{
\cs_set_eq:NN \@@_str_case:Vnw \str_case:VnF
\@@_element_cases:Nnnw
}
\cs_new:Npn \grading_scheme_element_cases:NnnTF % implicit #1-5
{
\cs_set_eq:NN \@@_str_case:Vnw \str_case:VnTF
\@@_element_cases:Nnnw
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_element_cases:Nnnw}
%
% This assumes that \cs{@@_str_case:Vnw}
% has been set to a \cs{str_case:VnTF}
% variant and uses this variant for
% switching the type cases.
%
% \begin{macrocode}
\cs_new:Npn \@@_element_cases:Nnnw #1 #2 #3 % implicit branches
{
\@@_element_load_type:N #1
\@@_str_case:Vnw \l_@@_element_type_str
{
{ entry } { #2 }
{ block } { #3 }
}
% implicit branches
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\grading_scheme_element_format:NnnnN, \grading_scheme_element_gformat:NnnnN, \grading_scheme_element_format:PnnnN, \grading_scheme_element_gformat:PnnnN}
%
% Same syntax as \cs{grading_scheme_block_format:NnnnN}.
%
% \begin{macrocode}
\cs_new:Npn \grading_scheme_element_format:NnnnN % implicit #1-5
{
\cs_set_eq:NN \@@_entry_format_aux:PnnN \grading_scheme_entry_format:PnnN
\cs_set_eq:NN \@@_block_format_aux:PnnnN \grading_scheme_block_format:PnnnN
\cs_set_eq:NN \@@_tl_put_right:Nx \tl_put_right:Nx
\@@_element_format:NnnnN
}
\cs_new:Npn \grading_scheme_element_gformat:NnnnN % implicit #1-5
{
\cs_set_eq:NN \@@_entry_format_aux:PnnN \grading_scheme_entry_gformat:PnnN
\cs_set_eq:NN \@@_block_format_aux:PnnnN \grading_scheme_block_gformat:PnnnN
\cs_set_eq:NN \@@_tl_put_right:Nx \tl_put_gright:Nx
\@@_element_format:NnnnN
}
\cs_new:Npn \grading_scheme_element_format:PnnnN % implicit #1-5
{
\exp_args:NP \grading_scheme_element_format:NnnnN
}
\cs_new:Npn \grading_scheme_element_gformat:PnnnN % implicit #1-5
{
\exp_args:NP \grading_scheme_element_gformat:NnnnN
}
% \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\@@_element_format:NnnnN, \@@_element_format:PnnnN}
%
% Aux function.
%
% \begin{macrocode}
\cs_new:Npn \@@_element_format:NnnnN #1 #2 #3 #4 #5
{
%<*log>
\@@_log:x
{
Formatting ~ element ~ '\token_to_str:N #1' ~ into ~ '\token_to_str:N #5'.
}
\@@_log_incr:
\prop_log:N #1
%</log>
\@@_element_load_content:N #1
\grading_scheme_element_cases:NnnF #1
{
\bool_if:nTF { #4 }
{
\@@_entry_format_aux:PnnN
\l_@@_element_content_void_ptr
{ #2 }
{ #3 }
#5
}
{
\@@_entry_format_aux:PnnN
\l_@@_element_content_void_ptr
{ 0 }
{ #3 }
#5
}
}
{
\@@_block_format_aux:PnnnN
\l_@@_element_content_void_ptr
{ #2 }
{ #3 }
{ #4 }
#5
}
{
\msg_error:nnxxx { grading-scheme } { missing-value }
{ element }
{ \token_to_str:N #1 }
{ type / content }
}
\@@_tl_put_right:Nx #5
{
\exp_not:N \@@_cline:nn
{
\int_eval:n { #2 +1 }
}
{
\int_eval:n { #2 + #3 }
}
}
%<*log>
\@@_log_decr:
\@@_log:x { Done typesetting ~ element ~ '\token_to_str:N #1' }
%</log>
}
\cs_new:Npn \@@_element_format:PnnnN % implicit #1-5
{
\exp_args:NP \@@_element_format:NnnnN
}
% \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\grading_scheme_element_get_height:NN, \grading_scheme_element_get_height:PN}
%
% Get the the height of an element.
%
% \begin{macrocode}
\cs_new:Npn \grading_scheme_element_get_height:NN #1 #2
{
\grading_scheme_element_cases:NnnF #1
{
\int_set:Nn #2 { 1 }
}
{
\@@_element_load_content:N #1
\grading_scheme_block_get_height:PN
\l_@@_element_content_void_ptr
#2
}
{
\msg_error:nnxxx { grading-scheme } { missing-value }
{ element }
{ \token_to_str:N #1 }
{ type / content }
}
}
\cs_new:Npn \grading_scheme_element_get_height:PN
{
\exp_args:NP \grading_scheme_element_get_height:NN
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\grading_scheme_element_get_natural_width:NN, \grading_scheme_element_get_natural_width:PN}
%
% Get the natural width of an element
%
% \begin{macrocode}
\cs_new:Npn \grading_scheme_element_get_natural_width:NN #1 #2
{
\grading_scheme_element_cases:NnnF #1
{
\int_set:Nn { #2 } { 2 }
}
{
\@@_element_load_content:N #1
\grading_scheme_block_get_natural_width:PN
\l_@@_element_content_void_ptr
#2
}
{
\msg_error:nnxxx { grading-scheme } { missing-value }
{ element }
{ \token_to_str:N #1 }
{ type / content }
}
}
\cs_new:Npn \grading_scheme_element_get_natural_width:PN
{
\exp_args:NP \grading_scheme_element_get_natural_width:NN
}
% \end{macrocode}
% \end{macro}
%
%
% \begin{variable}{\l_@@_width_int}
%
% Local int vars for typesetting.
%
% \begin{macrocode}
\int_new:N \l_@@_width_int
% \end{macrocode}
% \end{variable}
%
% \begin{variable}{\g_@@_table_tl}
%
% Token list where we will build the table.
%
% \begin{macrocode}
\tl_new:N \g_@@_table_tl
% \end{macrocode}
% \end{variable}
%
%
%
%
% \begin{macro}{\grading_scheme_element_typeset:N, \grading_scheme_element_typeset:P}
%
% Typesets this element as a tabular and inserts this into the output stream.
%
% \begin{macrocode}
\cs_new:Npn \grading_scheme_element_typeset:N #1
{
\grading_scheme_element_get_natural_width:NN #1 \l_@@_width_int
\tl_gclear:N \g_@@_table_tl
\tl_gput_right:Nn \g_@@_table_tl
{
\begin{tabular}
}
\tl_gput_right:Nx \g_@@_table_tl
{
{
\prg_replicate:nn { \l_@@_width_int -1 } { |l }
| l |
}
\exp_not:N \@@_hline:
}
\grading_scheme_element_gformat:NnnnN
#1
{ 0 }
{ \l_@@_width_int }
{ \c_false_bool }
\g_@@_table_tl
\tl_gput_right:Nn \g_@@_table_tl
{
\end{tabular}
}
\group_begin:
\tl_set:Nn \arraystretch { 1.5 }
\tl_use:N \g_@@_table_tl
\group_end:
}
\cs_new:Npn \grading_scheme_element_typeset:P
{
\exp_args:NP \grading_scheme_element_typeset:N
}
% \end{macrocode}
% \end{macro}
%
%
% \subsection{Facilities for populating data structures}
%
% TODO: what about global / local assignments here?
%
%
% \begin{macro}{\grading_scheme_entry_new:Nnn, \grading_scheme_entry_new:Pnn}
% \begin{syntax}
% \cs{grading_scheme_entry_new:Nnn}\meta{entry var}\Arg{description}\Arg{points}
% \end{syntax}
%
% \begin{macrocode}
\cs_new:Npn \grading_scheme_entry_new:Nnn #1 #2 % implcit #3
{
\grading_scheme_entry_new:N #1
\grading_scheme_entry_gset_description:Nn #1 { #2 }
\grading_scheme_entry_gset_points:Nn #1
}
\cs_new:Npn \grading_scheme_entry_new:Pnn
{
\exp_args:NP \grading_scheme_entry_new:Nnn
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\grading_scheme_block_new:Nnn, \grading_scheme_block_new:Pnn}
% \begin{syntax}
% \cs{grading_scheme_block_new:Nnn}\meta{block var}\Arg{description}\Arg{operation}
% \end{syntax}
%
% \begin{macrocode}
\cs_new:Npn \grading_scheme_block_new:Nnn #1 #2 % implicit #3
{
\grading_scheme_block_new:N #1
\grading_scheme_block_gset_description:Nn #1 { #2 }
\grading_scheme_block_gset_operation:Nn #1
}
\cs_new:Npn \grading_scheme_block_new:Pnn
{
\exp_args:NP \grading_scheme_block_new:Nnn
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\grading_scheme_block_new:Nn, \grading_scheme_block_new:Pn}
% \begin{syntax}
% \cs{grading_scheme_block_new:Nn}\meta{block var}\Arg{operation}
% \end{syntax}
%
% Same as above, but no description provided.
%
% \begin{macrocode}
\cs_new:Npn \grading_scheme_block_new:Nn #1 % implicit #2
{
\grading_scheme_block_new:N #1
\grading_scheme_block_gset_operation:Nn #1
}
\cs_new:Npn \grading_scheme_block_new:Pn
{
\exp_args:NP \grading_scheme_block_new:Nn
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\grading_scheme_element_from_entry_new:NN, \grading_scheme_element_from_entry_new:NP, \grading_scheme_element_from_entry_new:PP,
% \grading_scheme_element_gfrom_entry_new:NN, \grading_scheme_element_gfrom_entry_new:NP, \grading_scheme_element_gfrom_entry_new:PP}
% \begin{syntax}
% \cs{grading_scheme_element_from_entry_new:NN}\meta{element var}\meta{entry var}
% \end{syntax}
%
% wraps the entry into a new element.
%
% \begin{macrocode}
\cs_new:Npn \grading_scheme_element_from_entry_new:NN #1 #2
{
\grading_scheme_element_new:N #1
\grading_scheme_element_set_entry:NN #1 #2
}
\cs_new:Npn \grading_scheme_element_from_entry_new:NP
{
\exp_args:NP \grading_scheme_element_from_entry_new:NN
}
\cs_new:Npn \grading_scheme_element_from_entry_new:PP
{
\exp_args:NPP \grading_scheme_element_from_entry_new:NN
}
\cs_new:Npn \grading_scheme_element_gfrom_entry_new:NN #1 #2
{
\grading_scheme_element_new:N #1
\grading_scheme_element_gset_entry:NN #1 #2
}
\cs_new:Npn \grading_scheme_element_gfrom_entry_new:NP
{
\exp_args:NP \grading_scheme_element_gfrom_entry_new:NN
}
\cs_new:Npn \grading_scheme_element_gfrom_entry_new:PP
{
\exp_args:NPP \grading_scheme_element_gfrom_entry_new:NN
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\grading_scheme_element_from_block_new:NN, \grading_scheme_element_from_block_new:NP, \grading_scheme_element_from_block_new:NP,
% \grading_scheme_element_gfrom_block_new:NN, \grading_scheme_element_from_gblock_new:NP, \grading_scheme_element_gfrom_block_new:NP}
% \begin{syntax}
% \cs{grading_scheme_element_from_block_new:NN}\meta{element var}\meta{block var}
% \end{syntax}
%
% wraps the block into a new element.
%
% \begin{macrocode}
\cs_new:Npn \grading_scheme_element_from_block_new:NN #1 #2
{
\grading_scheme_element_new:N #1
\grading_scheme_element_set_block:NN #1 #2
}
\cs_new:Npn \grading_scheme_element_from_block_new:NP
{
\exp_args:NP \grading_scheme_element_from_block_new:NN
}
\cs_new:Npn \grading_scheme_element_from_block_new:PP
{
\exp_args:NPP \grading_scheme_element_from_block_new:NN
}
\cs_new:Npn \grading_scheme_element_gfrom_block_new:NN #1 #2
{
\grading_scheme_element_new:N #1
\grading_scheme_element_gset_block:NN #1 #2
}
\cs_new:Npn \grading_scheme_element_gfrom_block_new:NP
{
\exp_args:NP \grading_scheme_element_gfrom_block_new:NN
}
\cs_new:Npn \grading_scheme_element_gfrom_block_new:PP
{
\exp_args:NPP \grading_scheme_element_gfrom_block_new:NN
}
% \end{macrocode}
% \end{macro}
%
% \subsection{Grading scheme environment}
%
% When building a grading scheme,
% we introduce a \cs{g_@@_curr_block_ptr}
% that is a pointer to the current block
% that is being populated.
%
% Block environments and entries will create
% new blocks/entries and add themselves to
% the block pointed out by \cs{g_@@_curr_block_ptr}
%
%
% \begin{variable}{\l_@@_entry_ptr, \l_@@_element_ptr, \l_@@_curr_block_ptr}
%
% \begin{macrocode}
\ptr_new:Nn \l_@@_entry_ptr { g }
\ptr_new:Nn \l_@@_element_ptr { g }
\ptr_new:Nn \l_@@_curr_block_ptr { g }
% \end{macrocode}
% \end{variable}
%
%
%
% \begin{macro}{\@@_entry:nn}
%
% Creates an entry in the current block.
%
% \begin{macrocode}
\cs_new:Npn \@@_entry:nn #1 #2
{
\ptr_clear:Nn \l_@@_entry_ptr { g }
\ptr_clear:Nn \l_@@_element_ptr { g }
\grading_scheme_entry_new:Pnn
\l_@@_entry_ptr
{ #1 }
{ #2 }
\grading_scheme_element_gfrom_entry_new:PP
\l_@@_element_ptr
\l_@@_entry_ptr
\grading_scheme_block_gadd_element:PP
\l_@@_curr_block_ptr
\l_@@_element_ptr
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_block_begin:nn, \@@_block_begin:n, \@@_block_end:}
%
%
%
% \begin{macrocode}
\cs_new:Npn \@@_block_begin:nn % implicit #1, #2
{
\ptr_clear:Nn \l_@@_curr_block_ptr { g }
\grading_scheme_block_new:Pnn \l_@@_curr_block_ptr
}
\cs_new:Npn \@@_block_begin:n % implicit #1
{
\ptr_clear:Nn \l_@@_curr_block_ptr { g }
\grading_scheme_block_new:Pn \l_@@_curr_block_ptr
}
\cs_new:Npn \@@_block_end:
{
\ptr_clear:Nn \l_@@_element_ptr { g }
\grading_scheme_element_gfrom_block_new:PP
\l_@@_element_ptr
\l_@@_curr_block_ptr
\cs_gset:Npx \@@_after_group:
{
\exp_not:N \grading_scheme_block_gadd_element:PN
\exp_not:N \l_@@_curr_block_ptr
\exp_not:P \l_@@_element_ptr
}
\group_insert_after:N \@@_after_group:
}
% \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\entry}
%
%
%
% \begin{macrocode}
\NewDocumentCommand \entry { m m }
{
\@@_entry:nn { #1 } { #2 }
}
% \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{block}
%
% \begin{macrocode}
\NewDocumentEnvironment { block } { o m }
{
\IfValueTF { #1 }
{
\@@_block_begin:nn { #1 } { #2 }
}
{
\@@_block_begin:n { #2 }
}
}
{
\@@_block_end:
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{gradingscheme}
%
%
%
% \begin{macrocode}
\NewDocumentEnvironment {gradingscheme} { o m }
{
\bool_if:NT \g_@@_pipe_syntax_bool
{
\char_set_active_eq:NN | \@@_entry_oneline:w
\char_set_catcode_active:N |
}
\IfValueTF { #1 }
{
\@@_block_begin:nn { #1 } { #2 }
}
{
\@@_block_begin:n { #2 }
}
}
{
\ptr_clear:Nn \l_@@_element_ptr { g }
\grading_scheme_element_gfrom_block_new:PP
\l_@@_element_ptr
\l_@@_curr_block_ptr
\grading_scheme_element_typeset:P \l_@@_element_ptr
}
% \end{macrocode}
% \end{macro}
%
% \subsection{Implementing the pipe syntax}
%
% Everything left is conditional on the pipe option having been specified:
% \begin{macrocode}
\bool_if:NF \g_@@_pipe_syntax_bool
{
\endinput
}
% \end{macrocode}
%
%
% In order to offer syntax based on $\mid$, we make $\mid$ an active character
% that will read until the end of the line, split at the |@| character,
% and pass this on to a \cs{@@_entry:nn}
%
% \begin{macro}{\s_@@_endline}
%
% A scan mark that will denote the end of the line
% for us.
%
% \begin{macrocode}
\scan_new:N \s_@@_endline
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_parse_entry:w}
% \begin{syntax}
% \cs{@@_parse_entry:w} \meta{description} \& \meta{points} \cs{s_endline}
% \end{syntax}
%
% Creates a new entry based on our scan mark.
%
% \begin{macrocode}
\cs_new:Npn \@@_parse_entry:w #1 & #2 \s_endline
{
\@@_entry:nn { #1 } { #2 }
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_replace_newline:w, \@@_replace_newline_aux:w}
%
% Calling \cs{@@_replace_newline:w}
% replaces the next occurence of a newline character with
% \cs{s_@@_endline}.
%
% This is done by briefly switching category codes.
%
% \begin{macrocode}
\cs_new:Npn \@@_replace_newline:w
{
\group_begin:
\char_set_catcode_active:N\^^M
\@@_replace_newline_aux:w
}
% \end{macrocode}
%
% We need to briefly make the newline character an active character
% in this source file so that pattern matching works correctly.
% \begin{macrocode}
\char_set_catcode_active:N\^^M
\cs_new:Npn \@@_replace_newline_aux:w #1 ^^M
{
\group_end:
#1 \s_endline
}
\char_set_catcode_end_line:N\^^M
% \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\@@_entry_oneline:w}
%
% Parses a one-line entry.
%
% \begin{macrocode}
\cs_new:Npn \@@_entry_oneline:w
{
\@@_replace_newline:w
\@@_parse_entry:w
}
% \end{macrocode}
% \end{macro}
%
%
% \begin{macrocode}
%</package>
% \end{macrocode}
%
% \end{implementation}
%
% \PrintIndex
%