Gh1577 socket conditionals (#1598)

* adding conditionals for #1577 * luatex test * Use the socket conditional when applicable * ltnews entry * expand the arguments of all conditionals * Apply suggestions from code review Co-authored-by: Yukai Chou <[email protected]> --------- Co-authored-by: Yukai Chou <[email protected]>
latex3 · Dec 29, 2024 · 5dbc00a · 5dbc00a
1 parent cd9093f
commit 5dbc00a
Show file tree

Hide file tree

Showing 14 changed files with 229 additions and 38 deletions.
diff --git a/base/changes.txt b/base/changes.txt
@@ -6,6 +6,11 @@ to completeness or accuracy and it contains some references to files that are
 not part of the distribution.
 ================================================================================
 
+2024-12-27  Frank Mittelbach  <[email protected]>
+
+	* ltsockets.dtx:
+	Add conditionals for sockets, plugs, and assignments (gh/1577)
+
 2024-12-25  Frank Mittelbach  <[email protected]>
 
 	* doc.dtx (subsection{Producing the actual index entries}):

diff --git a/base/doc/ltnews41.tex b/base/doc/ltnews41.tex
@@ -233,6 +233,17 @@ \subsection{Fixing the spacing after display math}
 
 \section{New or improved commands}
 
+\subsection{Socket and plug conditionals}
+
+It is sometimes necessary/helpful to know if a particular socket or
+plug exists (or is assigned to a certain socket) and based on that
+take different actions. With the current release we added
+conditionals, such as \cs{IfSocketExistsTF}, to support such
+scenarios. Corresponding L3 programming layer conditionals are also
+provided.
+%
+\githubissue{1577}
+
 \section{Code improvements}
 
 \subsection{Refinement of \cs{MakeTitlecase}}

diff --git a/base/ltsockets.dtx b/base/ltsockets.dtx
@@ -33,7 +33,7 @@
 %<*driver> 
 % \fi
 \ProvidesFile{ltsockets.dtx}
-             [2024/10/27 v0.9b LaTeX Kernel (Sockets)]
+             [2024/12/27 v0.9c LaTeX Kernel (Sockets)]
 % \iffalse
 %
 \documentclass{l3doc}
@@ -645,6 +645,43 @@
 %   \cs{LogSocket} and \cs{socket_log:n} only differ in that they don't stop.
 % \end{function}
 %
+%
+% It is sometimes necessary/helpful to know if a particular socket or
+% plug exists (or is assigned to a certain socket) and based on that
+% take different actions.
+%
+% \begin{function}[EXP]{\IfSocketExistsTF,\socket_if_exist:nTF}
+% \begin{syntax}
+% \cs{IfSocketExistsTF} \Arg{socket-name} \Arg{true code} \Arg{false code}
+% \end{syntax}
+%   If socket \meta{socket-name} exists then execute \meta{true code}
+%   otherwise \meta{false code}. Variants with only \texttt{T} or
+%   \texttt{F} are also available.
+% \end{function}
+%
+% \begin{function}[EXP]{\IfSocketPlugExistsTF,\socket_if_plug_exist:nnTF}
+% \begin{syntax}
+% \cs{IfSocketPlugExistsTF} \Arg{socket-name} \Arg{plug-name}
+%                           \qquad \Arg{true code} \Arg{false code}
+% \end{syntax}
+%   If plug \meta{plug-name} for socket \meta{socket-name} exists then
+%   execute \meta{true code} otherwise \meta{false code}. Variants
+%   with only \texttt{T} or \texttt{F} are also available.
+% \end{function}
+%
+% \begin{function}[EXP]{\IfSocketPlugAssignedTF,\socket_if_plug_assigned:nnTF}
+% \begin{syntax}
+% \cs{IfSocketPlugAssignedTF} \Arg{socket-name} \Arg{plug-name}
+%                           \qquad \Arg{true code} \Arg{false code}
+% \end{syntax}
+%   If plug \meta{plug-name} is assigned to socket \meta{socket-name}
+%   then execute \meta{true code} otherwise \meta{false
+%   code}. Variants with only \texttt{T} or \texttt{F} are also
+%   available.
+% \end{function}
+%
+%
+% 
 % 
 % \begin{function}{\DebugSocketsOn,\DebugSocketsOff,
 %                  \socket_debug_on:,\socket_debug_off:}
@@ -654,6 +691,8 @@
 %   Turns debugging of sockets on or off.
 % \end{function}
 %
+%
+%
 % \subsubsection{Rationale for error handling}
 % 
 % The errors during the declarations are produced to help with
@@ -766,7 +805,7 @@
 %    does nothing by default other than swallowing its inputs (if any).
 %    \begin{macrocode}
 \cs_new_protected:Npn \socket_new:nn #1 #2 {
-  \str_if_exist:cTF { l_@@_#1_plug_str }
+   \socket_if_exist:nTF {#1}
       {
         \msg_error:nnn { socket } { already-declared } {#1}
       }
@@ -796,15 +835,31 @@
 }
 %    \end{macrocode}
 %  \end{macro}
-%  
+%
+%
+%
+% \begin{macro}[pTF, EXP] { \socket_if_exist:n }
+%    Conditional testing the existance of a socket.
+%    The argument is fully expanded as part of the csname generation.
+%    \changes{v0.9c}{2024/12/27}{Conditionals for sockets, plugs, and
+%                                assignments (gh/1577)}
+%    \begin{macrocode}
+\prg_new_conditional:Npnn \socket_if_exist:n #1 { p , T , F , TF }
+  { \str_if_exist:cTF { l_@@_#1_plug_str }
+                      \prg_return_true:
+                      \prg_return_false:
+  }
+%    \end{macrocode}
+% \end{macro}
+%
 %  
 %  \begin{macro}{\socket_log:n,\socket_show:n}
 %    Show the current state of the socket --- for now this is just a
 %    quick draft and should be redone and extended.
 %    \begin{macrocode}
 \cs_new_protected:Npn \socket_log:n #1 {
   \typeout{ Socket~ #1:}
-  \str_if_exist:cTF { l_@@_#1_plug_str }
+   \socket_if_exist:nTF {#1}
       {
         \typeout{ \@spaces number~ of~ inputs~ =~
                   \int_use:c { c_@@_#1_args_int } }
@@ -842,9 +897,9 @@
 %    the number of arguments from the saved int.
 %    \begin{macrocode}
 \cs_new_protected:Npn \socket_new_plug:nnn #1#2#3 {
-  \str_if_exist:cTF { l_@@_#1_plug_str }
+   \socket_if_exist:nTF {#1}
       {
-        \cs_if_exist:cTF { @@_#1_plug_#2:w }
+        \socket_if_plug_exist:nnTF {#1} {#2}
           {
             \msg_error:nnnn { socket } { plug-already-declared } {#1} {#2}
           }
@@ -863,19 +918,17 @@
               { Plug~ '#2'~ for~ socket~ '#1'~ declared. }
           }
       }
-      {
-        \msg_error:nnn { socket } { undeclared } {#1}
-      }
+      { \msg_error:nnn { socket } { undeclared } {#1} }
 }
 %    \end{macrocode}
 %    Changing the plug of an existing socket is rather similar, except
 %    that we don't have to deal with adding it to the debugging
 %    sequence.
 %    \begin{macrocode}
 \cs_new_protected:Npn \socket_set_plug:nnn #1#2#3 {
-  \str_if_exist:cTF { l_@@_#1_plug_str }
+   \socket_if_exist:nTF {#1}
       {
-        \cs_if_exist:cTF { @@_#1_plug_#2:w }
+        \socket_if_plug_exist:nnTF {#1} {#2}
           {
             \cs_generate_from_arg_count:cNnn
               { @@_#1_plug_#2:w }
@@ -889,24 +942,38 @@
             \msg_error:nnnn { socket } { plug-undeclared } {#1} {#2}
           }
       }
-      {
-        \msg_error:nnn { socket } { undeclared } {#1}
-      }
+      { \msg_error:nnn { socket } { undeclared } {#1} }
 }
 %    \end{macrocode}
 %  \end{macro}
 %  
-%  
+%
+%
+% \begin{macro}[pTF, EXP] { \socket_if_plug_exist:nn }
+%    Conditional testing the existance of a plug.
+%    Both arguments are fully expanded as part of the csname generation.
+%    \changes{v0.9c}{2024/12/27}{Conditionals for sockets, plugs, and
+%                                assignments (gh/1577)}
+%    \begin{macrocode}
+\prg_new_conditional:Npnn \socket_if_plug_exist:nn #1#2 { p , T , F , TF }
+  { \cs_if_exist:cTF { @@_#1_plug_#2:w }
+                     \prg_return_true:
+                     \prg_return_false:
+  }
+%    \end{macrocode}
+% \end{macro}
+%
+%
 %  
 %  \begin{macro}{\socket_assign_plug:nn}
 %    
 %    Assigning a plug to a socket just changes the name in
 %    the socket string. The assignment is local to the current group.
 %    \begin{macrocode}
 \cs_new_protected:Npn \socket_assign_plug:nn #1 #2 {
-  \str_if_exist:cTF { l_@@_#1_plug_str }
+   \socket_if_exist:nTF {#1}
       {
-        \cs_if_exist:cTF { @@_#1_plug_#2:w }
+        \socket_if_plug_exist:nnTF {#1} {#2}
           {
             \@@_debug_term:n
               { Replacing~ plug~ '\str_use:c { l_@@_#1_plug_str }'~
@@ -921,7 +988,25 @@
 }
 %    \end{macrocode}
 %  \end{macro}
-%  
+%
+%
+%
+% \begin{macro}[pTF, EXP] { \socket_if_plug_assigned:nn }
+%    Conditional testing the assignment of a plug.
+%    Both arguments are fully expanded.
+%    \changes{v0.9c}{2024/12/27}{Conditionals for sockets, plugs, and
+%                                assignments (gh/1577)}
+%    \begin{macrocode}
+\prg_new_conditional:Npnn \socket_if_plug_assigned:nn #1#2 { p , T , F , TF }
+  { \exp_args:Ne
+    \str_if_eq:nvTF {#2} { l__socket_#1_plug_str }
+                    \prg_return_true:
+                    \prg_return_false:
+  }
+%    \end{macrocode}
+% \end{macro}
+%
+%
 %  
 %  \begin{macro}{\socket_use:nw,\socket_use:n,\socket_use:nn,\socket_use:nnn,\socket_use:nnnn}
 %    
@@ -1044,6 +1129,32 @@
 %  \end{macro}
 %
 %
+%  \begin{macro}{\IfSocketExistsTF,\IfSocketExistsT,\IfSocketExistsF,
+%                \IfSocketPlugExistsTF,\IfSocketPlugExistsT,
+%                \IfSocketPlugExistsF,
+%                \IfSocketPlugAssignedTF,\IfSocketPlugAssignedT,
+%                \IfSocketPlugAssignedF}
+%    A bunch of conditionals:
+%    \changes{v0.9c}{2024/12/27}{Conditionals for sockets, plugs, and
+%                                assignments (gh/1577)}
+%    \begin{macrocode}
+\cs_new_eq:NN \IfSocketExistsTF \socket_if_exist:nTF
+\cs_new_eq:NN \IfSocketExistsT  \socket_if_exist:nT
+\cs_new_eq:NN \IfSocketExistsF  \socket_if_exist:nF
+%    \end{macrocode}
+%
+%    \begin{macrocode}
+\cs_new_eq:NN \IfSocketPlugExistsTF \socket_if_plug_exist:nnTF
+\cs_new_eq:NN \IfSocketPlugExistsT  \socket_if_plug_exist:nnT
+\cs_new_eq:NN \IfSocketPlugExistsF  \socket_if_plug_exist:nnF
+%    \end{macrocode}
+%    
+%    \begin{macrocode}
+\cs_new_eq:NN \IfSocketPlugAssignedTF \socket_if_plug_assigned:nnTF
+\cs_new_eq:NN \IfSocketPlugAssignedT  \socket_if_plug_assigned:nnT
+\cs_new_eq:NN \IfSocketPlugAssignedF  \socket_if_plug_assigned:nnF
+%    \end{macrocode}
+%  \end{macro}
 %  
 %    \begin{macrocode}
 %
@@ -1061,6 +1172,16 @@
 %<latexrelease>\let \DebugSocketsOn  \@undefined
 %<latexrelease>\let \DebugSocketsOff \@undefined
 %<latexrelease>
+%<latexrelease>\let \IfSocketExistsTF \@undefined
+%<latexrelease>\let \IfSocketExistsT  \@undefined
+%<latexrelease>\let \IfSocketExistsF  \@undefined
+%<latexrelease>\let \IfSocketPlugExistsTF \@undefined
+%<latexrelease>\let \IfSocketPlugExistsT  \@undefined
+%<latexrelease>\let \IfSocketPlugExistsF  \@undefined
+%<latexrelease>\let \IfSocketPlugAssignedTF \@undefined
+%<latexrelease>\let \IfSocketPlugAssignedT  \@undefined
+%<latexrelease>\let \IfSocketPlugAssignedF  \@undefined
+%<latexrelease>
 %<latexrelease>\EndModuleRelease
 %    \end{macrocode}
 %

diff --git a/base/testfiles/sockets-002.luatex.tlg b/base/testfiles/sockets-002.luatex.tlg
@@ -52,3 +52,15 @@ modified noop
 A socket plug
 ----------------------
 A socket plug
+----------------------
+should be true
+should be false
+true
+----------------------
+should be true
+should be false
+true
+----------------------
+should be true
+should be false
+true
diff --git a/base/testfiles/sockets-002.lvt b/base/testfiles/sockets-002.lvt
@@ -47,4 +47,22 @@
 \UseSocket{foo}
 
 
+\typeout{----------------------}
+\IfSocketExistsTF{foo}{\typeout{should be true}}{\typeout{false}}
+\IfSocketExistsTF{bar}{\typeout{true}}{\typeout{should be false}}
+\IfSocketExistsT{foo}{\typeout{true}}
+\IfSocketExistsF{foo}{\typeout{false}}
+
+\typeout{----------------------}
+\IfSocketPlugExistsTF{foo}{default}{\typeout{should be true}}{\typeout{false}}
+\IfSocketPlugExistsTF{foo}{undefined}{\typeout{true}}{\typeout{should be false}}
+\IfSocketPlugExistsT{foo}{default}{\typeout{true}}
+\IfSocketPlugExistsF{foo}{default}{\typeout{false}}
+
+\typeout{----------------------}
+\IfSocketPlugAssignedTF{foo}{default}{\typeout{should be true}}{\typeout{false}}
+\IfSocketPlugAssignedTF{foo}{noop}{\typeout{true}}{\typeout{should be false}}
+\IfSocketPlugAssignedT{foo}{default}{\typeout{true}}
+\IfSocketPlugAssignedF{foo}{default}{\typeout{false}}
+
 \END
diff --git a/base/testfiles/sockets-002.tlg b/base/testfiles/sockets-002.tlg
@@ -52,3 +52,15 @@ modified noop
 A socket plug
 ----------------------
 A socket plug
+----------------------
+should be true
+should be false
+true
+----------------------
+should be true
+should be false
+true
+----------------------
+should be true
+should be false
+true
diff --git a/required/latex-lab/changes.txt b/required/latex-lab/changes.txt
@@ -1,3 +1,9 @@
+2024-12-27  Frank Mittelbach  <[email protected]>
+
+	* latex-lab-table.dtx,latex-lab-toc-kernel-changes.dtx,
+	  latex-lab-footnotes.dtx,latex-lab-float.dtx:
+	Use new socket conditional.
+
 2024-12-21 Ulrike Fischer <[email protected]>
 	* documentmetadata-support.dtx: added "latest" as a testphase value.
 	* remove now unneeded tests.

diff --git a/required/latex-lab/latex-lab-float.dtx b/required/latex-lab/latex-lab-float.dtx
@@ -16,8 +16,8 @@
 %
 % for those people who are interested or want to report an issue.
 %
-\def\ltlabfloatdate{2024-11-21}
-\def\ltlabfloatversion{0.81g}
+\def\ltlabfloatdate{2024-12-27}
+\def\ltlabfloatversion{0.81h}
 %<*driver>
 \documentclass{l3doc}
 \EnableCrossrefs
@@ -297,7 +297,7 @@
 % \subsection{Tagging sockets}
 % For now we test if the sockets are already defined
 %    \begin{macrocode}
-\str_if_exist:cF { l__socket_tagsupport/float/begin_plug_str }
+\socket_if_exist:nF {tagsupport/float/begin}
   {
     \NewSocket{tagsupport/float/hmode/begin}{0}
     \NewSocket{tagsupport/float/hmode/end}{0}
@@ -540,7 +540,7 @@
 % First some temporary sockets. 
 % These sockets are in lttagging.
 %    \begin{macrocode}
-\str_if_exist:cF { l__socket_tagsupport/caption/begin_plug_str }
+\socket_if_exist:nF {tagsupport/caption/begin}
  {
   \NewSocket{tagsupport/caption/begin}{1}
   \NewSocket{tagsupport/caption/end}{0}
@@ -551,7 +551,7 @@
 % These socket are currently defined in tagpdf.
 % \changes{v0.81g}{2024-11-21}{add missing argument to socket}
 %    \begin{macrocode}
-\str_if_exist:cF { l__socket_tagsupport/para/begin_plug_str } 
+\socket_if_exist:nF {tagsupport/para/begin} 
  {
    \NewSocket{tagsupport/para/begin}{0} 
    \NewSocket{tagsupport/para/end}{0}