From 4b0f677aea00124171602de9498d50ac10d71eb3 Mon Sep 17 00:00:00 2001
From: Norbert Preining <norbert@preining.info>
Date: Fri, 20 Sep 2019 03:00:40 +0000
Subject: CTAN sync 201909200300

---
 macros/latex/contrib/l3experimental/l3cctab.dtx | 186 ++++++++++++++++++++----
 1 file changed, 160 insertions(+), 26 deletions(-)

(limited to 'macros/latex/contrib/l3experimental/l3cctab.dtx')

diff --git a/macros/latex/contrib/l3experimental/l3cctab.dtx b/macros/latex/contrib/l3experimental/l3cctab.dtx
index 85a029b9bf..a56585c1ff 100644
--- a/macros/latex/contrib/l3experimental/l3cctab.dtx
+++ b/macros/latex/contrib/l3experimental/l3cctab.dtx
@@ -46,7 +46,7 @@
 %    }^^A
 % }
 %
-% \date{Released 2019-08-25}
+% \date{Released 2019-09-19}
 %
 % \maketitle
 %
@@ -59,24 +59,29 @@
 % range. For other engines, only the $8$-bit range ($0$-$255$) is covered by
 % such tables.
 %
-% \begin{function}{\cctab_new:N}
+% \subsection{Creating and initialising category code tables}
+%
+% \begin{function}{\cctab_new:N,\cctab_new:c}
 %   \begin{syntax}
 %     \cs{cctab_new:N} \meta{category code table}
 %   \end{syntax}
-%   Creates a new category code table, initially with the codes as
-%   used by \IniTeX{}.
+%   Creates a new \meta{category code table} variable or raises an error if
+%   the name is already taken. The declaration is global.  The
+%   \meta{category code table} is initialised with the codes
+%   as used by \IniTeX{}.
 % \end{function}
 %
-% \begin{function}{\cctab_const:Nn}
+% \begin{function}{\cctab_const:Nn,\cctab_const:cn}
 %   \begin{syntax}
 %     \cs{cctab_const:Nn} \meta{category code table} \Arg{category code set up}
 %   \end{syntax}
-%   Creates a new category code table and applies the
+%   Creates a new \meta{category code table} with the category code settings in
+%   force at the time the function is called, and applies the
 %   \meta{category code set up} on top of prevailing settings, then saves
 %   as a constant table.
 % \end{function}
 %
-% \begin{function}{\cctab_gset:Nn}
+% \begin{function}{\cctab_gset:Nn,\cctab_gset:cn}
 %   \begin{syntax}
 %     \cs{cctab_gset:Nn} \meta{category code table} \Arg{category code set up}
 %   \end{syntax}
@@ -88,14 +93,16 @@
 %   not respect grouping.
 % \end{function}
 %
-% \begin{function}{\cctab_begin:N}
+% \subsection{Using category code tables}
+%
+% \begin{function}{\cctab_begin:N,\cctab_begin:c}
 %   \begin{syntax}
 %     \cs{cctab_begin:N} \meta{category code table}
 %   \end{syntax}
 %   Switches the category codes in force to those stored in the
 %   \meta{category code table}.  The prevailing codes before the
 %   function is called are added to a stack, for use with
-%   \cs{cctab_end:}.
+%   \cs{cctab_end:}. This function does not start a \TeX{} group.
 % \end{function}
 %
 % \begin{function}{\cctab_end:}
@@ -103,10 +110,24 @@
 %     \cs{cctab_end:}
 %   \end{syntax}
 %   Ends the scope of a \meta{category code table} started using
-%   \cs{cctab_begin:N}, retuning the codes to those in force before the
-%   matching \cs{cctab_begin:N} was used.
+%   \cs{cctab_begin:N}, retuning the codes to those in force before
+%   the matching \cs{cctab_begin:N} was used.
+% \end{function}
+%
+% \subsection{Category code table conditionals}
+%
+% \begin{function}[pTF]{\cctab_if_exist:N,\cctab_if_exist:c}
+%   \begin{syntax}
+%     \cs{cctab_if_exist_p:N} \meta{category code table}
+%     \cs{cctab_if_exist:NTF} \meta{category code table} \Arg{true code} \Arg{false code}
+%   \end{syntax}
+%   Tests whether the \meta{category code table} is currently defined.
+%   This does not check that the \meta{category code table} really is a
+%   category code table.
 % \end{function}
 %
+% \subsection{Constant category code tables}
+%
 % \begin{variable}{\c_code_cctab}
 %   Category code table for the code environment. This does not include
 %   setting the behaviour of the line-end character, which is only
@@ -150,7 +171,7 @@
 %
 %    \begin{macrocode}
 %<*package>
-\ProvidesExplPackage{l3cctab}{2019-08-25}{}
+\ProvidesExplPackage{l3cctab}{2019-09-19}{}
   {L3 Experimental category code tables}
 %</package>
 %    \end{macrocode}
@@ -178,10 +199,10 @@
 %    \end{macrocode}
 % \end{variable}
 %
-% \begin{macro}{\cctab_new:N}
-% \begin{macro}{\cctab_begin:N}
-% \begin{macro}{\cctab_end:}
-% \begin{macro}{\cctab_gset:Nn}
+% \begin{macro}{\cctab_new:N,\cctab_new:c}
+% \begin{macro}{\@@_begin:N,\@@_begin:c}
+% \begin{macro}{\@@_end:}
+% \begin{macro}{\cctab_gset:Nn,\cctab_gset:cn}
 %   As \LuaTeX{} offers engine support for category code tables, and this is
 %   entirely lacking from the other engines, we need two complementary
 %   approaches here. Rather than intermix them, we split the set up based on
@@ -226,7 +247,7 @@
 %   done by using a stack of tables which are not read only, and actually
 %   having them as \enquote{in use} copies.
 %    \begin{macrocode}
-    \cs_new_protected:Npn \cctab_begin:N #1
+    \cs_new_protected:Npn \@@_begin:N #1
       {
         \seq_gpush:Nx \g_@@_stack_seq { \tex_the:D \tex_catcodetable:D }
         \tex_catcodetable:D #1
@@ -236,7 +257,7 @@
         \tex_savecatcodetable:D \g_@@_stack_int
         \tex_catcodetable:D \g_@@_stack_int
       }
-    \cs_new_protected:Npn \cctab_end:
+    \cs_new_protected:Npn \@@_end:
       {
         \int_gsub:Nn \g_@@_stack_int { 2 }
         \seq_if_empty:NTF \g_@@_stack_seq
@@ -252,7 +273,7 @@
     \cs_new_protected:Npn \cctab_gset:Nn #1#2
       {
         \group_begin:
-          #2
+          #2 \scan_stop:
           \tex_savecatcodetable:D #1
         \group_end:
       }
@@ -288,14 +309,14 @@
         \@@_gstore:Nnn #1 { 13 } { 5 }
         \@@_gstore:Nnn #1 { 32 } { 10 }
         \@@_gstore:Nnn #1 { 37 } { 14 }
-        \int_step_inline:nnn { 64 } { 89 }
+        \int_step_inline:nnn { 65 } { 90 }
           { \@@_gstore:Nnn #1 {##1} { 11 } }
         \@@_gstore:Nnn #1 { 92 } { 0 }
         \int_step_inline:nnn { 97 } { 122 }
           { \@@_gstore:Nnn #1 {##1} { 11 } }
         \@@_gstore:Nnn #1 { 127 } { 15 }
       }
-    \cs_new_protected:Npn \cctab_begin:N #1
+    \cs_new_protected:Npn \@@_begin:N #1
       {
         \int_gadd:Nn \g_@@_stack_int { 2 }
         \int_compare:nNnT \g_@@_stack_int > \c_max_register_int
@@ -324,7 +345,7 @@
       }
     \cs_generate_variant:Nn \intarray_new:Nn { c }
     \cs_generate_variant:Nn \intarray_gset:Nnn { c }
-    \cs_new_protected:Npn \cctab_end:
+    \cs_new_protected:Npn \@@_end:
       {
         \int_step_inline:nn { 256 }
           {
@@ -335,13 +356,13 @@
                   {##1}
               }
           }
-        \int_gsub:Nn \g_@@_stack_int { 1 }
+        \int_gsub:Nn \g_@@_stack_int { 2 }
       }
     \cs_generate_variant:Nn \intarray_item:Nn { c }
     \cs_new_protected:Npn \cctab_gset:Nn #1#2
       {
         \group_begin:
-          #2
+          #2 \scan_stop:
           \int_step_inline:nn { 256 }
             {
               \intarray_gset:cnn { g_@@_ \int_use:N #1 _cctab } {##1}
@@ -350,19 +371,119 @@
         \group_end:
       }
   }
+\cs_generate_variant:Nn \cctab_new:N { c }
+\cs_generate_variant:Nn \cctab_gset:Nn { c }
 %    \end{macrocode}
 % \end{macro}
 % \end{macro}
 % \end{macro}
 % \end{macro}
 %
-% \begin{macro}{\cctab_const:Nn}
+% \begin{macro}{\cctab_begin:N,\cctab_end:}
+%   These functions perform a few sanity checks before calling the
+%   functions which will do the heavy-lifting.
+%   \cs{cctab_begin:N} checks if a \meta{cctab~var} exists before trying
+%   to use it. \cs{cctab_end:} checks if a \cs{cctab_begin:N} was used
+%   some time earlier.
+%   
+%   Skipping these checks would result in an \enquote{Undefined control
+%   sequence} error for \cs{cctab_begin:N} with an undefined
+%   \meta{cctab~var}, and a \enquote{Missing font identifier} for an extra
+%   \cs{cctab_end:}.
+%    \begin{macrocode}
+\cs_new_protected:Npn \cctab_begin:N #1
+  { \@@_chk_if_valid:NT #1 { \__cctab_begin:N #1 } }
+\cs_generate_variant:Nn \cctab_begin:N { c }
+\cs_new_protected:Npn \cctab_end:
+  {
+    \int_compare:nNnTF { \g_@@_stack_int } = { \c_zero_int }
+      { \__kernel_msg_error:nn { kernel } { cctab-extra-end } }
+      { \@@_end: }
+  }
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\cctab_if_exist:N,\cctab_if_exist:c}
+%   Checks whether a \meta{cctab~var} is defined.
+%    \begin{macrocode}
+\prg_new_eq_conditional:NNn \cctab_if_exist:N \cs_if_exist:N
+  { TF , T , F , p }
+\prg_new_eq_conditional:NNn \cctab_if_exist:c \cs_if_exist:c
+  { TF , T , F , p }
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@@_chk_if_valid:N}
+%   Checks whether the argument is defined and whether it is a valid
+%   \meta{cctab~var}. In \LuaTeX{} the validity of the \meta{cctab~var}
+%   is checked by the engine, which complains if the argument is not
+%   a \cs{chardef}'ed constant. In other engines, check if the
+%   underlying \cs[no-index]{g_@@_\meta{integer}_cctab}
+%   \meta{intarray~var} exists.
+%    \begin{macrocode}
+\sys_if_engine_luatex:TF
+  {
+    \prg_new_protected_conditional:Npnn \@@_chk_if_valid:N #1
+      { TF , T , F }
+      {
+        \cctab_if_exist:NTF #1
+          {
+%<*initex>
+            \bool_lazy_and:nnTF
+              { \int_if_odd_p:n {#1} }
+              { \int_compare_p:nNn {#1-1} < { \g_@@_allocate_int } }
+%</initex>
+%<*package>
+            \int_compare:nNnTF {#1-1} < { \e@alloc@ccodetable@count }
+%</package>
+              { \prg_return_true: }
+              {
+                \__kernel_msg_error:nnx { kernel } { invalid-cctab }
+                  { \token_to_str:N #1 }
+                \prg_return_false:
+              }
+          }
+          {
+            \__kernel_msg_error:nnx { kernel } { command-not-defined }
+              { \token_to_str:N #1 }
+            \prg_return_false:
+          }
+      }
+  }
+  {
+    \prg_new_protected_conditional:Npnn \@@_chk_if_valid:N #1
+      { TF , T , F }
+      {
+        \cctab_if_exist:NTF #1
+          {
+            \cs_if_exist:cTF { g_@@_ \int_use:N #1 _cctab }
+              { \prg_return_true: }
+              {
+                \__kernel_msg_error:nnx { kernel } { invalid-cctab }
+                  { \token_to_str:N #1 }
+                \prg_return_false:
+              }
+          }
+          {
+            \__kernel_msg_error:nnx { kernel } { command-not-defined }
+              { \token_to_str:N #1 }
+            \prg_return_false:
+          }
+      }
+  }
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\cctab_const:Nn,\cctab_const:cn}
+%  Creates a new \meta{cctab~var} then sets it with the current and
+%  user-supplied codes.
 %    \begin{macrocode}
 \cs_new_protected:Npn \cctab_const:Nn #1#2
   {
     \cctab_new:N #1
     \cctab_gset:Nn #1 {#2}
   }
+\cs_generate_variant:Nn \cctab_const:Nn { c }
 %    \end{macrocode}
 % \end{macro}
 %
@@ -371,7 +492,6 @@
 %     \c_initex_cctab   ,
 %     \c_code_cctab     ,
 %     \c_document_cctab ,
-%     \c_initex_cctab   ,
 %     \c_other_cctab    ,
 %     \c_str_cctab
 %   }  
@@ -379,6 +499,7 @@
 %   The \texttt{other} and \texttt{string} ones are done by completely
 %   ignoring the existing codes as this makes life a lot less complex.
 %    \begin{macrocode}
+\cctab_new:N \c_initex_cctab
 \cctab_const:Nn \c_code_cctab { }
 \cctab_const:Nn \c_document_cctab
   {
@@ -411,6 +532,19 @@
     LaTeX~has~been~asked~to~switch~to~a~new~category~code~table,~
     but~there~is~no~more~space~to~do~this!
   }
+\__kernel_msg_new:nnnn { kernel } { cctab-extra-end }
+  { Extra~\iow_char:N\\cctab_end:~ignored~\msg_line_context:. }
+  {
+    LaTeX~came~across~a~\iow_char:N\\cctab_end:~without~a~matching~
+    \iow_char:N\\cctab_begin:N.~This~command~will~be~ignored.
+  }
+\__kernel_msg_new:nnnn { kernel } { invalid-cctab }
+  { Invalid~\iow_char:N\\catcode~table. }
+  {
+    You~can~only~switch~to~a~\iow_char:N\\catcode~table~that~is~
+    initialized~using~\iow_char:N\\cctab_new:N~or~
+    \iow_char:N\\cctab_const:Nn.
+  }
 %    \end{macrocode}
 %
 %    \begin{macrocode}
-- 
cgit v1.2.3

