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

[Joseph Wright]

Repository : https://github.com/latex3/latex3
On branch  : options
Link       : https://github.com/latex3/latex3/commit/95b2f9584b7ce8974415856a82c1b7a722a09fe8

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

commit 95b2f9584b7ce8974415856a82c1b7a722a09fe8
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


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

95b2f9584b7ce8974415856a82c1b7a722a09fe8
 l3kernel/CHANGELOG.md |  3 +++
 l3kernel/l3keys.dtx   | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 74 insertions(+)

diff --git a/l3kernel/CHANGELOG.md b/l3kernel/CHANGELOG.md
index d464de69f..7030674d1 100644
--- a/l3kernel/CHANGELOG.md
+++ b/l3kernel/CHANGELOG.md
@@ -7,6 +7,9 @@ this project uses date-based 'snapshot' version identifiers.
 
 ## [Unreleased]
 
+### Added
+- Support for validity scope for keys
+
 ## [2021-11-22]
 
 ### Added
diff --git a/l3kernel/l3keys.dtx b/l3kernel/l3keys.dtx
index 4add41fe5..4bbbc085f 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.