[latex3-commits] [git/LaTeX3-latex3-latex3] options: Add support for validity scope for keys (23f83f898)

[Joseph Wright]

Repository : https://github.com/latex3/latex3
On branch  : options
Link       : https://github.com/latex3/latex3/commit/23f83f89883ec855608be6e6523be34e8e61bfa6

>---------------------------------------------------------------

commit 23f83f89883ec855608be6e6523be34e8e61bfa6
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date:   Thu Nov 25 22:43:22 2021 +0000

    Add support for validity scope for keys


>---------------------------------------------------------------

23f83f89883ec855608be6e6523be34e8e61bfa6
 l3kernel/CHANGELOG.md |  1 +
 l3kernel/l3keys.dtx   | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 72 insertions(+)

diff --git a/l3kernel/CHANGELOG.md b/l3kernel/CHANGELOG.md
index ef2c26764..0d3b525de 100644
--- a/l3kernel/CHANGELOG.md
+++ b/l3kernel/CHANGELOG.md
@@ -9,6 +9,7 @@ this project uses date-based 'snapshot' version identifiers.
 
 ### Added
 - `\prop_to_keyval:N`
+- Support for validity scope for keys
 
 ### Changed
 - Allow indirect conversions between colorspaces though fallback models
diff --git a/l3kernel/l3keys.dtx b/l3kernel/l3keys.dtx
index a0c6b470f..c81aafb87 100644
--- a/l3kernel/l3keys.dtx
+++ b/l3kernel/l3keys.dtx
@@ -679,6 +679,29 @@
 % \cs{l_keys_choice_tl} and \cs{l_keys_choice_int} in exactly
 % the same way as described for \texttt{.choices:nn}.
 %
+% \subsection{Key validity}
+%
+% Some keys will be used as settings which have a strictly limited scope
+% of validity. Some will be only available once, others will only be valid
+% until typesetting begins. To allow formats to support this in a structured
+% way, \pkg{l3keys} allows this information to be specified using the
+% \texttt{.validity:n} property.
+%
+% \begin{function}[added = 2021-11-25]{.validity:n}
+%   \begin{syntax}
+%     \meta{key} .validity:n = \meta{scope}
+%   \end{syntax}
+%   Defines the \meta{key} to have validty within the \meta{scope}, which
+%   should be one of \texttt{general}, \texttt{preamble} or \texttt{load-time}.
+% \end{function}
+%
+% \begin{variable}{\g_keys_load_time_seq, \g_keys_preamble_seq}
+%   \pkg{l3keys} itself does \emph{not} attempt to redefine keys based on the
+%   validity scope. Rather, this information is made available with these
+%   sequences. Each entry will be a full key path, which can therefore
+%   be used to disable each key when it is out-of-scope.
+% \end{variable}
+%
 % \section{Setting keys}
 %
 % \begin{function}[updated = 2017-11-14]
@@ -1625,6 +1648,14 @@
 %    \end{macrocode}
 % \end{variable}
 %
+% \begin{variable}{\g_keys_load_time_seq, \g_keys_preamble_seq}
+%   Global data for document-level information.
+%    \begin{macrocode}
+\seq_new:N \g_keys_load_time_seq
+\seq_new:N \g_keys_preamble_seq
+%    \end{macrocode}
+% \end{variable}
+%
 % \subsubsection{Internal auxiliaries}
 %
 % \begin{variable}{\s_@@_nil,\s_@@_mark,\s_@@_stop}
@@ -2146,6 +2177,39 @@
 % \end{macro}
 % \end{macro}
 %
+% \begin{macro}{\@@_validity:n}
+%   Save the relevant data.
+%    \begin{macrocode}
+\cs_new_protected:Npn \@@_validity:n #1
+  {
+    \str_case:nnF {#1}
+      {
+        { general }
+          {
+            \seq_gremove:NV \g_keys_load_time_seq \l_keys_path_str
+            \seq_gremove:NV \g_keys_preamble_seq \l_keys_path_str
+          }
+        { load-time }
+          {
+            \seq_gput:NV \g_keys_load_time_seq \l_keys_path_str
+            \seq_gremove:NV \g_keys_preamble_seq \l_keys_path_str
+          }
+        { preamble }
+          {
+            \seq_gremove:NV \g_keys_load_time_seq \l_keys_path_str
+            \seq_gput:NV \g_keys_preamble_seq \l_keys_path_str
+
+          }
+      }
+      {
+        \msg_error:nnx { keys }
+          { choice-unknown }
+          { .validity:n }
+      }
+  }
+%    \end{macrocode}
+% \end{macro}
+%
 % \begin{macro}{\@@_variable_set:NnnN, \@@_variable_set:cnnN}
 % \begin{macro}{\@@_variable_set_required:NnnN, \@@_variable_set_required:cnnN}
 %   Setting a variable takes the type and scope separately so that
@@ -2547,6 +2611,13 @@
 %    \end{macrocode}
 % \end{macro}
 %
+% \begin{macro}{.validity:n}
+%    \begin{macrocode}
+\cs_new_protected:cpn { \c_@@_props_root_str .valdity:n } #1
+  { \@@_validty:n {#1} }
+%    \end{macrocode}
+% \end{macro}
+%
 % \begin{macro}{.value_forbidden:n}
 % \begin{macro}{.value_required:n}
 %   These are very similar, so both call the same function.