Skip to content

Commit 5dbc00a

Browse files
FrankMittelbachmuzimuzhi
FrankMittelbach
and
muzimuzhi
authored
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]>
1 parent cd9093f commit 5dbc00a

14 files changed

+229
-38
lines changed

‎base/changes.txt

+5
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,11 @@ to completeness or accuracy and it contains some references to files that are
66
not part of the distribution.
77
================================================================================
88

9+
2024-12-27 Frank Mittelbach <[email protected]>
10+
11+
* ltsockets.dtx:
12+
Add conditionals for sockets, plugs, and assignments (gh/1577)
13+
914
2024-12-25 Frank Mittelbach <[email protected]>
1015

1116
* doc.dtx (subsection{Producing the actual index entries}):

‎base/doc/ltnews41.tex

+11
Original file line numberDiff line numberDiff line change
@@ -233,6 +233,17 @@ \subsection{Fixing the spacing after display math}
233233

234234
\section{New or improved commands}
235235

236+
\subsection{Socket and plug conditionals}
237+
238+
It is sometimes necessary/helpful to know if a particular socket or
239+
plug exists (or is assigned to a certain socket) and based on that
240+
take different actions. With the current release we added
241+
conditionals, such as \cs{IfSocketExistsTF}, to support such
242+
scenarios. Corresponding L3 programming layer conditionals are also
243+
provided.
244+
%
245+
\githubissue{1577}
246+
236247
\section{Code improvements}
237248

238249
\subsection{Refinement of \cs{MakeTitlecase}}

‎base/ltsockets.dtx

+139-18
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@
3333
%<*driver>
3434
% \fi
3535
\ProvidesFile{ltsockets.dtx}
36-
[2024/10/27 v0.9b LaTeX Kernel (Sockets)]
36+
[2024/12/27 v0.9c LaTeX Kernel (Sockets)]
3737
% \iffalse
3838
%
3939
\documentclass{l3doc}
@@ -645,6 +645,43 @@
645645
% \cs{LogSocket} and \cs{socket_log:n} only differ in that they don't stop.
646646
% \end{function}
647647
%
648+
%
649+
% It is sometimes necessary/helpful to know if a particular socket or
650+
% plug exists (or is assigned to a certain socket) and based on that
651+
% take different actions.
652+
%
653+
% \begin{function}[EXP]{\IfSocketExistsTF,\socket_if_exist:nTF}
654+
% \begin{syntax}
655+
% \cs{IfSocketExistsTF} \Arg{socket-name} \Arg{true code} \Arg{false code}
656+
% \end{syntax}
657+
% If socket \meta{socket-name} exists then execute \meta{true code}
658+
% otherwise \meta{false code}. Variants with only \texttt{T} or
659+
% \texttt{F} are also available.
660+
% \end{function}
661+
%
662+
% \begin{function}[EXP]{\IfSocketPlugExistsTF,\socket_if_plug_exist:nnTF}
663+
% \begin{syntax}
664+
% \cs{IfSocketPlugExistsTF} \Arg{socket-name} \Arg{plug-name}
665+
% \qquad \Arg{true code} \Arg{false code}
666+
% \end{syntax}
667+
% If plug \meta{plug-name} for socket \meta{socket-name} exists then
668+
% execute \meta{true code} otherwise \meta{false code}. Variants
669+
% with only \texttt{T} or \texttt{F} are also available.
670+
% \end{function}
671+
%
672+
% \begin{function}[EXP]{\IfSocketPlugAssignedTF,\socket_if_plug_assigned:nnTF}
673+
% \begin{syntax}
674+
% \cs{IfSocketPlugAssignedTF} \Arg{socket-name} \Arg{plug-name}
675+
% \qquad \Arg{true code} \Arg{false code}
676+
% \end{syntax}
677+
% If plug \meta{plug-name} is assigned to socket \meta{socket-name}
678+
% then execute \meta{true code} otherwise \meta{false
679+
% code}. Variants with only \texttt{T} or \texttt{F} are also
680+
% available.
681+
% \end{function}
682+
%
683+
%
684+
%
648685
%
649686
% \begin{function}{\DebugSocketsOn,\DebugSocketsOff,
650687
% \socket_debug_on:,\socket_debug_off:}
@@ -654,6 +691,8 @@
654691
% Turns debugging of sockets on or off.
655692
% \end{function}
656693
%
694+
%
695+
%
657696
% \subsubsection{Rationale for error handling}
658697
%
659698
% The errors during the declarations are produced to help with
@@ -766,7 +805,7 @@
766805
% does nothing by default other than swallowing its inputs (if any).
767806
% \begin{macrocode}
768807
\cs_new_protected:Npn \socket_new:nn #1 #2 {
769-
\str_if_exist:cTF { l_@@_#1_plug_str }
808+
\socket_if_exist:nTF {#1}
770809
{
771810
\msg_error:nnn { socket } { already-declared } {#1}
772811
}
@@ -796,15 +835,31 @@
796835
}
797836
% \end{macrocode}
798837
% \end{macro}
799-
%
838+
%
839+
%
840+
%
841+
% \begin{macro}[pTF, EXP] { \socket_if_exist:n }
842+
% Conditional testing the existance of a socket.
843+
% The argument is fully expanded as part of the csname generation.
844+
% \changes{v0.9c}{2024/12/27}{Conditionals for sockets, plugs, and
845+
% assignments (gh/1577)}
846+
% \begin{macrocode}
847+
\prg_new_conditional:Npnn \socket_if_exist:n #1 { p , T , F , TF }
848+
{ \str_if_exist:cTF { l_@@_#1_plug_str }
849+
\prg_return_true:
850+
\prg_return_false:
851+
}
852+
% \end{macrocode}
853+
% \end{macro}
854+
%
800855
%
801856
% \begin{macro}{\socket_log:n,\socket_show:n}
802857
% Show the current state of the socket --- for now this is just a
803858
% quick draft and should be redone and extended.
804859
% \begin{macrocode}
805860
\cs_new_protected:Npn \socket_log:n #1 {
806861
\typeout{ Socket~ #1:}
807-
\str_if_exist:cTF { l_@@_#1_plug_str }
862+
\socket_if_exist:nTF {#1}
808863
{
809864
\typeout{ \@spaces number~ of~ inputs~ =~
810865
\int_use:c { c_@@_#1_args_int } }
@@ -842,9 +897,9 @@
842897
% the number of arguments from the saved int.
843898
% \begin{macrocode}
844899
\cs_new_protected:Npn \socket_new_plug:nnn #1#2#3 {
845-
\str_if_exist:cTF { l_@@_#1_plug_str }
900+
\socket_if_exist:nTF {#1}
846901
{
847-
\cs_if_exist:cTF { @@_#1_plug_#2:w }
902+
\socket_if_plug_exist:nnTF {#1} {#2}
848903
{
849904
\msg_error:nnnn { socket } { plug-already-declared } {#1} {#2}
850905
}
@@ -863,19 +918,17 @@
863918
{ Plug~ '#2'~ for~ socket~ '#1'~ declared. }
864919
}
865920
}
866-
{
867-
\msg_error:nnn { socket } { undeclared } {#1}
868-
}
921+
{ \msg_error:nnn { socket } { undeclared } {#1} }
869922
}
870923
% \end{macrocode}
871924
% Changing the plug of an existing socket is rather similar, except
872925
% that we don't have to deal with adding it to the debugging
873926
% sequence.
874927
% \begin{macrocode}
875928
\cs_new_protected:Npn \socket_set_plug:nnn #1#2#3 {
876-
\str_if_exist:cTF { l_@@_#1_plug_str }
929+
\socket_if_exist:nTF {#1}
877930
{
878-
\cs_if_exist:cTF { @@_#1_plug_#2:w }
931+
\socket_if_plug_exist:nnTF {#1} {#2}
879932
{
880933
\cs_generate_from_arg_count:cNnn
881934
{ @@_#1_plug_#2:w }
@@ -889,24 +942,38 @@
889942
\msg_error:nnnn { socket } { plug-undeclared } {#1} {#2}
890943
}
891944
}
892-
{
893-
\msg_error:nnn { socket } { undeclared } {#1}
894-
}
945+
{ \msg_error:nnn { socket } { undeclared } {#1} }
895946
}
896947
% \end{macrocode}
897948
% \end{macro}
898949
%
899-
%
950+
%
951+
%
952+
% \begin{macro}[pTF, EXP] { \socket_if_plug_exist:nn }
953+
% Conditional testing the existance of a plug.
954+
% Both arguments are fully expanded as part of the csname generation.
955+
% \changes{v0.9c}{2024/12/27}{Conditionals for sockets, plugs, and
956+
% assignments (gh/1577)}
957+
% \begin{macrocode}
958+
\prg_new_conditional:Npnn \socket_if_plug_exist:nn #1#2 { p , T , F , TF }
959+
{ \cs_if_exist:cTF { @@_#1_plug_#2:w }
960+
\prg_return_true:
961+
\prg_return_false:
962+
}
963+
% \end{macrocode}
964+
% \end{macro}
965+
%
966+
%
900967
%
901968
% \begin{macro}{\socket_assign_plug:nn}
902969
%
903970
% Assigning a plug to a socket just changes the name in
904971
% the socket string. The assignment is local to the current group.
905972
% \begin{macrocode}
906973
\cs_new_protected:Npn \socket_assign_plug:nn #1 #2 {
907-
\str_if_exist:cTF { l_@@_#1_plug_str }
974+
\socket_if_exist:nTF {#1}
908975
{
909-
\cs_if_exist:cTF { @@_#1_plug_#2:w }
976+
\socket_if_plug_exist:nnTF {#1} {#2}
910977
{
911978
\@@_debug_term:n
912979
{ Replacing~ plug~ '\str_use:c { l_@@_#1_plug_str }'~
@@ -921,7 +988,25 @@
921988
}
922989
% \end{macrocode}
923990
% \end{macro}
924-
%
991+
%
992+
%
993+
%
994+
% \begin{macro}[pTF, EXP] { \socket_if_plug_assigned:nn }
995+
% Conditional testing the assignment of a plug.
996+
% Both arguments are fully expanded.
997+
% \changes{v0.9c}{2024/12/27}{Conditionals for sockets, plugs, and
998+
% assignments (gh/1577)}
999+
% \begin{macrocode}
1000+
\prg_new_conditional:Npnn \socket_if_plug_assigned:nn #1#2 { p , T , F , TF }
1001+
{ \exp_args:Ne
1002+
\str_if_eq:nvTF {#2} { l__socket_#1_plug_str }
1003+
\prg_return_true:
1004+
\prg_return_false:
1005+
}
1006+
% \end{macrocode}
1007+
% \end{macro}
1008+
%
1009+
%
9251010
%
9261011
% \begin{macro}{\socket_use:nw,\socket_use:n,\socket_use:nn,\socket_use:nnn,\socket_use:nnnn}
9271012
%
@@ -1044,6 +1129,32 @@
10441129
% \end{macro}
10451130
%
10461131
%
1132+
% \begin{macro}{\IfSocketExistsTF,\IfSocketExistsT,\IfSocketExistsF,
1133+
% \IfSocketPlugExistsTF,\IfSocketPlugExistsT,
1134+
% \IfSocketPlugExistsF,
1135+
% \IfSocketPlugAssignedTF,\IfSocketPlugAssignedT,
1136+
% \IfSocketPlugAssignedF}
1137+
% A bunch of conditionals:
1138+
% \changes{v0.9c}{2024/12/27}{Conditionals for sockets, plugs, and
1139+
% assignments (gh/1577)}
1140+
% \begin{macrocode}
1141+
\cs_new_eq:NN \IfSocketExistsTF \socket_if_exist:nTF
1142+
\cs_new_eq:NN \IfSocketExistsT \socket_if_exist:nT
1143+
\cs_new_eq:NN \IfSocketExistsF \socket_if_exist:nF
1144+
% \end{macrocode}
1145+
%
1146+
% \begin{macrocode}
1147+
\cs_new_eq:NN \IfSocketPlugExistsTF \socket_if_plug_exist:nnTF
1148+
\cs_new_eq:NN \IfSocketPlugExistsT \socket_if_plug_exist:nnT
1149+
\cs_new_eq:NN \IfSocketPlugExistsF \socket_if_plug_exist:nnF
1150+
% \end{macrocode}
1151+
%
1152+
% \begin{macrocode}
1153+
\cs_new_eq:NN \IfSocketPlugAssignedTF \socket_if_plug_assigned:nnTF
1154+
\cs_new_eq:NN \IfSocketPlugAssignedT \socket_if_plug_assigned:nnT
1155+
\cs_new_eq:NN \IfSocketPlugAssignedF \socket_if_plug_assigned:nnF
1156+
% \end{macrocode}
1157+
% \end{macro}
10471158
%
10481159
% \begin{macrocode}
10491160
%
@@ -1061,6 +1172,16 @@
10611172
%<latexrelease>\let \DebugSocketsOn \@undefined
10621173
%<latexrelease>\let \DebugSocketsOff \@undefined
10631174
%<latexrelease>
1175+
%<latexrelease>\let \IfSocketExistsTF \@undefined
1176+
%<latexrelease>\let \IfSocketExistsT \@undefined
1177+
%<latexrelease>\let \IfSocketExistsF \@undefined
1178+
%<latexrelease>\let \IfSocketPlugExistsTF \@undefined
1179+
%<latexrelease>\let \IfSocketPlugExistsT \@undefined
1180+
%<latexrelease>\let \IfSocketPlugExistsF \@undefined
1181+
%<latexrelease>\let \IfSocketPlugAssignedTF \@undefined
1182+
%<latexrelease>\let \IfSocketPlugAssignedT \@undefined
1183+
%<latexrelease>\let \IfSocketPlugAssignedF \@undefined
1184+
%<latexrelease>
10641185
%<latexrelease>\EndModuleRelease
10651186
% \end{macrocode}
10661187
%

‎base/testfiles/sockets-002.luatex.tlg

+12
Original file line numberDiff line numberDiff line change
@@ -52,3 +52,15 @@ modified noop
5252
A socket plug
5353
----------------------
5454
A socket plug
55+
----------------------
56+
should be true
57+
should be false
58+
true
59+
----------------------
60+
should be true
61+
should be false
62+
true
63+
----------------------
64+
should be true
65+
should be false
66+
true

‎base/testfiles/sockets-002.lvt

+18
Original file line numberDiff line numberDiff line change
@@ -47,4 +47,22 @@
4747
\UseSocket{foo}
4848

4949

50+
\typeout{----------------------}
51+
\IfSocketExistsTF{foo}{\typeout{should be true}}{\typeout{false}}
52+
\IfSocketExistsTF{bar}{\typeout{true}}{\typeout{should be false}}
53+
\IfSocketExistsT{foo}{\typeout{true}}
54+
\IfSocketExistsF{foo}{\typeout{false}}
55+
56+
\typeout{----------------------}
57+
\IfSocketPlugExistsTF{foo}{default}{\typeout{should be true}}{\typeout{false}}
58+
\IfSocketPlugExistsTF{foo}{undefined}{\typeout{true}}{\typeout{should be false}}
59+
\IfSocketPlugExistsT{foo}{default}{\typeout{true}}
60+
\IfSocketPlugExistsF{foo}{default}{\typeout{false}}
61+
62+
\typeout{----------------------}
63+
\IfSocketPlugAssignedTF{foo}{default}{\typeout{should be true}}{\typeout{false}}
64+
\IfSocketPlugAssignedTF{foo}{noop}{\typeout{true}}{\typeout{should be false}}
65+
\IfSocketPlugAssignedT{foo}{default}{\typeout{true}}
66+
\IfSocketPlugAssignedF{foo}{default}{\typeout{false}}
67+
5068
\END

‎base/testfiles/sockets-002.tlg

+12
Original file line numberDiff line numberDiff line change
@@ -52,3 +52,15 @@ modified noop
5252
A socket plug
5353
----------------------
5454
A socket plug
55+
----------------------
56+
should be true
57+
should be false
58+
true
59+
----------------------
60+
should be true
61+
should be false
62+
true
63+
----------------------
64+
should be true
65+
should be false
66+
true

‎required/latex-lab/changes.txt

+6
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
2024-12-27 Frank Mittelbach <[email protected]>
2+
3+
* latex-lab-table.dtx,latex-lab-toc-kernel-changes.dtx,
4+
latex-lab-footnotes.dtx,latex-lab-float.dtx:
5+
Use new socket conditional.
6+
17
2024-12-21 Ulrike Fischer <[email protected]>
28
* documentmetadata-support.dtx: added "latest" as a testphase value.
39
* remove now unneeded tests.

‎required/latex-lab/latex-lab-float.dtx

+5-5
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,8 @@
1616
%
1717
% for those people who are interested or want to report an issue.
1818
%
19-
\def\ltlabfloatdate{2024-11-21}
20-
\def\ltlabfloatversion{0.81g}
19+
\def\ltlabfloatdate{2024-12-27}
20+
\def\ltlabfloatversion{0.81h}
2121
%<*driver>
2222
\documentclass{l3doc}
2323
\EnableCrossrefs
@@ -297,7 +297,7 @@
297297
% \subsection{Tagging sockets}
298298
% For now we test if the sockets are already defined
299299
% \begin{macrocode}
300-
\str_if_exist:cF { l__socket_tagsupport/float/begin_plug_str }
300+
\socket_if_exist:nF {tagsupport/float/begin}
301301
{
302302
\NewSocket{tagsupport/float/hmode/begin}{0}
303303
\NewSocket{tagsupport/float/hmode/end}{0}
@@ -540,7 +540,7 @@
540540
% First some temporary sockets.
541541
% These sockets are in lttagging.
542542
% \begin{macrocode}
543-
\str_if_exist:cF { l__socket_tagsupport/caption/begin_plug_str }
543+
\socket_if_exist:nF {tagsupport/caption/begin}
544544
{
545545
\NewSocket{tagsupport/caption/begin}{1}
546546
\NewSocket{tagsupport/caption/end}{0}
@@ -551,7 +551,7 @@
551551
% These socket are currently defined in tagpdf.
552552
% \changes{v0.81g}{2024-11-21}{add missing argument to socket}
553553
% \begin{macrocode}
554-
\str_if_exist:cF { l__socket_tagsupport/para/begin_plug_str }
554+
\socket_if_exist:nF {tagsupport/para/begin}
555555
{
556556
\NewSocket{tagsupport/para/begin}{0}
557557
\NewSocket{tagsupport/para/end}{0}

0 commit comments

Comments
 (0)