summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/l3packages/xparse.dtx
blob: 97dd2f8fd9e551546096b5004c4cd57fc5fd257b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
% \iffalse meta-comment
%
%% File: xparse.dtx
%
% Copyright (C) 1999 Frank Mittelbach, Chris Rowley, David Carlisle
%           (C) 2004-2008 Frank Mittelbach, The LaTeX Project
%           (C) 2009-2023 The LaTeX Project
%
% It may be distributed and/or modified under the conditions of the
% LaTeX Project Public License (LPPL), either version 1.3c of this
% license or (at your option) any later version.  The latest version
% of this license is in the file
%
%    https://www.latex-project.org/lppl.txt
%
% This file is part of the "l3packages bundle" (The Work in LPPL)
% and all files in that bundle must be distributed together.
%
% -----------------------------------------------------------------------
%
% The development version of the bundle can be found at
%
%    https://github.com/latex3/latex3
%
% for those people who are interested.
%
%<*driver|package>
% The version of expl3 required is tested as early as possible, as
% some really old versions do not define \ProvidesExplPackage.
\RequirePackage{expl3}[2018-04-12]
%<package>\@ifpackagelater{expl3}{2018-04-12}
%<package>  {}
%<package>  {%
%<package>    \PackageError{xparse}{Support package l3kernel too old}
%<package>      {%
%<package>        Please install an up to date version of l3kernel\MessageBreak
%<package>        using your TeX package manager or from CTAN.\MessageBreak
%<package>        \MessageBreak
%<package>        Loading xparse will abort!%
%<package>      }%
%<package>    \endinput
%<package>  }
%</driver|package>
%<*driver>
\documentclass[full]{l3doc}
\usepackage{amstext}
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
%
% \providecommand\acro[1]{\textsc{\MakeLowercase{#1}}}
% \newenvironment{arg-description}{%
%   \begin{itemize}\def\makelabel##1{\hss\llap{\bfseries##1}}}{\end{itemize}}
%
% \title{^^A
%   The \textsf{xparse} package\\ Document command parser^^A
% }
%
% \author{^^A
%  The \LaTeX{} Project\thanks
%    {^^A
%      E-mail:
%        \href{mailto:latex-team@latex-project.org}
%          {latex-team@latex-project.org}^^A
%    }^^A
% }
%
% \date{Released 2023-01-16}
%
% \maketitle
%
% \begin{documentation}
%
% The \pkg{xparse} package provides a high-level interface for
% producing document-level commands. In that way, it is intended as
% a replacement for the \LaTeXe{} \cs{newcommand} macro. However,
% \pkg{xparse} works so that the interface to a function (optional
% arguments, stars and mandatory arguments, for example) is separate
% from the internal implementation. \pkg{xparse} provides a normalised
% input for the internal form of a function, independent of the
% document-level argument arrangement.
%
% At present, the functions in \pkg{xparse} which are regarded as
% \enquote{stable} are:
% \begin{itemize}
%   \item \cs{NewDocumentCommand}\\
%     \cs{RenewDocumentCommand}\\
%     \cs{ProvideDocumentCommand}\\
%     \cs{DeclareDocumentCommand}
%   \item \cs{NewDocumentEnvironment}\\
%     \cs{RenewDocumentEnvironment}\\
%     \cs{ProvideDocumentEnvironment}\\
%     \cs{DeclareDocumentEnvironment}
%   \item \cs{NewExpandableDocumentCommand}\\
%     \cs{RenewExpandableDocumentCommand}\\
%     \cs{ProvideExpandableDocumentCommand}\\
%     \cs{DeclareExpandableDocumentCommand}
%   \item \cs{IfNoValue(TF)}
%   \item \cs{IfValue(TF)}
%   \item \cs{IfBoolean(TF)}
% \end{itemize}
% with the other functions currently regarded as \enquote{experimental}. Please
% try all of the commands provided here, but be aware that the
% experimental ones may change or disappear.
%
% \section{Specifying arguments}
%
% Before introducing the functions used to create document commands,
% the method for specifying arguments with \pkg{xparse} will be
% illustrated. In order to allow each argument to be defined
% independently, \pkg{xparse} does not simply need to know the
% number of arguments for a function, but also the nature of each
% one. This is done by constructing an \emph{argument specification},
% which defines the number of arguments, the type of each argument
% and any additional information needed for \pkg{xparse} to read the
% user input and properly pass it through to internal functions.
%
% The basic form of the argument specifier is a list of letters, where
% each letter defines a type of argument. As will be described below,
% some of the types need additional information, such as default values.
% The argument types can be divided into two, those which define
% arguments that are mandatory (potentially raising an error if not
% found) and those which define optional arguments. The mandatory types
% are:
% \begin{itemize}[font=\ttfamily]
%   \item[m] A standard mandatory argument, which can either be a single
%     token alone or multiple tokens surrounded by curly braces |{}|.
%     Regardless of the input, the argument will be passed to the
%     internal code without the outer braces. This is the \pkg{xparse}
%     type specifier for a normal \TeX{} argument.
%   \item[r] Given as \texttt{r}\meta{token1}\meta{token2}, this denotes a
%     \enquote{required} delimited argument, where the delimiters are
%     \meta{token1} and \meta{token2}. If the opening delimiter
%     \meta{token1} is missing, the default marker |-NoValue-| will be
%     inserted after a suitable error.
%   \item[R] Given as \texttt{R}\meta{token1}\meta{token2}\marg{default},
%     this is a \enquote{required} delimited argument as for~\texttt{r},
%     but it has a user-definable recovery \meta{default} instead of
%     |-NoValue-|.
%   \item[v] Reads an argument \enquote{verbatim}, between the following
%     character and its next occurrence, in a way similar to the argument
%     of the \LaTeXe{} command \cs{verb}. Thus a \texttt{v}-type argument
%     is read between two identical characters, which cannot be any of |%|, |\|,
%     |#|, |{|, |}| or \verb*| |.
%     The verbatim argument can also be enclosed between braces, |{| and |}|.
%     A command with a verbatim
%     argument will produce an error when it appears within an argument of
%     another function.
%   \item[b] Only suitable in the argument specification of an
%     environment, it denotes the body of the environment, between
%     |\begin|\marg{environment} and |\end|\marg{environment}.  See
%     Section~\ref{sec:body} for details.
% \end{itemize}
% The types which define optional arguments are:
% \begin{itemize}[font=\ttfamily]
%   \item[o] A standard \LaTeX{} optional argument, surrounded with square
%     brackets, which will supply
%     the special |-NoValue-| marker if not given (as described later).
%   \item[d] Given as \texttt{d}\meta{token1}\meta{token2}, an optional
%     argument which is delimited by \meta{token1} and \meta{token2}.
%     As with \texttt{o}, if no
%     value is given the special marker |-NoValue-| is returned.
%   \item[O] Given as \texttt{O}\marg{default}, is like \texttt{o}, but
%     returns \meta{default} if no value is given.
%   \item[D] Given as \texttt{D}\meta{token1}\meta{token2}\marg{default},
%     it is as for \texttt{d}, but returns \meta{default} if no value is given.
%     Internally, the \texttt{o}, \texttt{d} and \texttt{O} types are
%     short-cuts to an appropriated-constructed \texttt{D} type argument.
%   \item[s] An optional star, which will result in a value
%     \cs{BooleanTrue} if a star is present and \cs{BooleanFalse}
%     otherwise (as described later).
%   \item[t] An optional \meta{token}, which will result in a value
%     \cs{BooleanTrue} if \meta{token} is present and \cs{BooleanFalse}
%     otherwise. Given as \texttt{t}\meta{token}.
%   \item[e] Given as \texttt{e}\marg{tokens}, a set of optional
%     \emph{embellishments}, each of which requires a \emph{value}.
%     If an embellishment is not present, |-NoValue-| is returned.  Each
%     embellishment gives one argument, ordered as for the list of
%     \meta{tokens} in the argument specification.  All \meta{tokens}
%     must be distinct.  \emph{This is an experimental type}.
%   \item[E] As for \texttt{e} but returns one or more \meta{defaults}
%     if values are not given: \texttt{E}\marg{tokens}\marg{defaults}. See
%     Section~\ref{sec:embellishment} for more details.
% \end{itemize}
%
% Using these specifiers, it is possible to create complex input syntax
% very easily. For example, given the argument definition
% `|s o o m O{default}|', the input `|*[Foo]{Bar}|' would be parsed as:
% \begin{itemize}[nolistsep]
%   \item |#1| = |\BooleanTrue|
%   \item |#2| = |Foo|
%   \item |#3| = |-NoValue-|
%   \item |#4| = |Bar|
%   \item |#5| = |default|
% \end{itemize}
% whereas `|[One][Two]{}[Three]|' would be parsed as:
% \begin{itemize}[nolistsep]
%   \item |#1| = |\BooleanFalse|
%   \item |#2| = |One|
%   \item |#3| = |Two|
%   \item |#4| = ||
%   \item |#5| = |Three|
% \end{itemize}
%
% Delimited argument types (\texttt{d}, \texttt{o} and \texttt{r}) are
% defined such that they require matched pairs of delimiters when collecting
% an argument. For example
% \begin{verbatim}
%   \NewDocumentCommand{\foo}{o}{#1}
%   \foo[[content]] % #1 = "[content]"
%   \foo[[]         % Error: missing closing "]"
% \end{verbatim}
% Also note that |{| and |}| cannot be used as delimiters as they are used
% by \TeX{} as grouping tokens. Implicit begin- or end-group tokens (\emph{e.g.},
% |\bgroup| and |\egroup|) are not allowed for delimited argument tipes.
% Arguments to be grabbed inside these tokens
% must be created as either \texttt{m}- or \texttt{g}-type arguments.
%
% Within delimited arguments, non-balanced or otherwise awkward tokens may
% be included by protecting the entire argument with a brace pair
% \begin{verbatim}
%   \NewDocumentCommand{\foobar}{o}{#1}
%   \foobar[{[}]         % Allowed as the "[" is 'hidden'
% \end{verbatim}
% These braces will be stripped only if they surround the \emph{entire} content
% of the optional argument
% \begin{verbatim}
%   \NewDocumentCommand{\foobaz}{o}{#1}
%   \foobaz[{abc}]         % => "abc"
%   \foobaz[ {abc}]         % => " {abc}"
% \end{verbatim}
%
% Two more characters have a special meaning when creating an argument
% specifier. First, \texttt{+} is used to make an argument long (to
% accept paragraph tokens). In contrast to \LaTeXe's \cs{newcommand},
% this applies on an argument-by-argument basis. So modifying the
% example to `|s o o +m O{default}|' means that the mandatory argument
% is now \cs{long}, whereas the optional arguments are not.
%
% Secondly, the character \texttt{>} is used to declare so-called
% \enquote{argument processors}, which can be used to modify the contents of an
% argument before it is passed to the macro definition. The use of
% argument processors is a somewhat advanced topic, (or at least a less
% commonly used feature) and is covered in Section~\ref{sec:processors}.
%
% When an optional argument is followed by a mandatory argument with the
% same delimiter, \pkg{xparse} issues a warning because the optional
% argument could not be omitted by the user, thus becoming in effect
% mandatory.  This can apply to \texttt{o}, \texttt{d}, \texttt{O},
% \texttt{D}, \texttt{s}, \texttt{t}, \texttt{e}, and \texttt{E} type
% arguments followed by \texttt{r} or \texttt{R}-type required
% arguments, but also to \texttt{g} or \texttt{G} type arguments
% followed by \texttt{m} type arguments.
%
% As \pkg{xparse} is also used to describe interfaces that have appeared
% in the wider \LaTeXe{} eco-system, it also defines additional argument
% types, described in Section~\ref{sec:backwards}: the mandatory types
% \texttt{l} and \texttt{u} and the optional brace group types
% \texttt{g} and \texttt{G}.  Their use is not recommended because it is
% simpler for a user if all packages use a similar syntax.  For the same
% reason, delimited arguments \texttt{r}, \texttt{R}, \texttt{d} and
% \texttt{D} should normally use delimiters that are naturally paired,
% such as |[| and |]| or |(| and |)|, or that are identical, such as |"|
% and~|"|.  A very common syntax is to have one optional argument
% \texttt{o} treated as a key--value list (using for instance
% \pkg{l3keys}) followed by some mandatory arguments~\texttt{m} (or
% \texttt{+m}).
%
% \subsection{Spacing and optional arguments}
%
% \TeX{} will find the first argument after a function name irrespective
% of any intervening spaces. This is true for both mandatory and
% optional arguments. So |\foo[arg]| and \verb*|\foo   [arg]| are
% equivalent. Spaces are also ignored when collecting arguments up
% to the last mandatory argument to be collected (as it must exist).
% So after
% \begin{verbatim}
%   \NewDocumentCommand \foo { m o m } { ... }
% \end{verbatim}
% the user input |\foo{arg1}[arg2]{arg3}| and
% \verb*|\foo{arg1}  [arg2]   {arg3}| will both be parsed in the same
% way.
% 
% The behavior of optional arguments \emph{after} any mandatory arguments is
% selectable. The standard settings will allow spaces here, and thus
% with
% \begin{verbatim}
%   \NewDocumentCommand \foobar { m o } { ... }
% \end{verbatim}
% both |\foobar{arg1}[arg2]| and \verb*|\foobar{arg1} [arg2]| will find an
% optional argument. This can be changed by giving the modified |!| in
% the argument specification:
% \begin{verbatim}
%   \NewDocumentCommand \foobar { m !o } { ... }
% \end{verbatim}
% where \verb*|\foobar{arg1} [arg2]| will not find an optional argument.
%
% There is one subtlety here due to the difference in handling by \TeX{}
% of \enquote{control symbols}, where the command name is made up of a single
% character, such as \enquote{\cmd{\\}}. Spaces are not ignored by \TeX{}
% here, and thus it is possible to require an optional argument directly
% follow such a command. The most common example is the use of \cmd{\\} in
% \pkg{amsmath} environments. In \pkg{xparse} terms it has signature
% \begin{verbatim}
%   \DeclareDocumentCommand \\ { !s !o } { ... }
% \end{verbatim}
%
% \subsection{Required delimited arguments}
%
% The contrast between a delimited (\texttt{D}-type) and \enquote{required
% delimited} (\texttt{R}-type) argument is that an error will be raised if
% the latter is missing. Thus for example
% \begin{verbatim}
%   \NewDocumentCommand {\foobaz} {r()m} {}
%   \foobaz{oops}
% \end{verbatim}
% will lead to an error message being issued. The marker |-NoValue-|
% (\texttt{r}-type) or user-specified default (for \texttt{R}-type) will be
% inserted to allow error recovery.
%
% \subsection{Verbatim arguments}
%
% Arguments of type~\texttt{v} are read in verbatim mode, which will
% result in the grabbed argument consisting of tokens of category codes
% $12$~(\enquote{other}) and $13$~(\enquote{active}), except spaces,
% which are given category code $10$~(\enquote{space}). The argument is
% delimited in a similar manner to the \LaTeXe{} \cs{verb} function, or
% by (correctly nested) pairs of braces.
%
% Functions containing verbatim arguments cannot appear in the arguments
% of other functions. The \texttt{v}~argument specifier includes code to check
% this, and will raise an error if the grabbed argument has already been
% tokenized by \TeX{} in an irreversible way.
%
% By default, an argument of type~\texttt{v} must be at most one line.
% Prefixing with \texttt{+} allows line breaks within the argument.
%
% Users should note that support for verbatim arguments is somewhat
% experimental. Feedback is therefore very welcome on the \texttt{LaTeX-L}
% mailing list.
%
% \subsection{Default values of arguments}
% \label{sec:defaultvaluesofarguments}
%
% Uppercase argument types (\texttt{O}, \texttt{D}, \ldots{}) allow to
% specify a default value to be used when the argument is missing; their
% lower-case counterparts use the special marker |-NoValue-|.  The
% default value can be expressed in terms of the value of any other
% arguments by using |#1|, |#2|, and so on.
% \begin{verbatim}
%   \NewDocumentCommand {\conjugate} { m O{#1ed} O{#2} } {(#1,#2,#3)}
%   \conjugate {walk}            % => (walk,walked,walked)
%   \conjugate {find} [found]    % => (find,found,found)
%   \conjugate {do} [did] [done] % => (do,did,done)
% \end{verbatim}
% The default values may refer to arguments that appear later in the
% argument specification.  For instance a command could accept two
% optional arguments, equal by default:
% \begin{verbatim}
%   \NewDocumentCommand {\margins} { O{#3} m O{#1} m } {(#1,#2,#3,#4)}
%   \margins {a} {b}              % => {(-NoValue-,a,-NoValue-,b)}
%   \margins [1cm] {a} {b}        % => {(1cm,a,1cm,b)}
%   \margins {a} [1cm] {b}        % => {(1cm,a,1cm,b)}
%   \margins [1cm] {a} [2cm] {b}  % => {(1cm,a,2cm,b)}
% \end{verbatim}
%
% Users should note that support for default arguments referring to
% other arguments is somewhat experimental. Feedback is therefore very
% welcome on the \texttt{LaTeX-L} mailing list.
%
% \subsection{Default values for \enquote{embellishments}}
% \label{sec:embellishment}
%
% The \texttt{E}-type argument allows one default value per test token.
% This is achieved by giving a list of defaults for each entry in the
% list, for example:
% \begin{verbatim}
%   E{^_}{{UP}{DOWN}}
% \end{verbatim}
% If the list of default values is \emph{shorter} than the list of test tokens,
% the special |-NoValue-| marker will be returned (as for the \texttt{e}-type
% argument). Thus for example
% \begin{verbatim}
%   E{^_}{{UP}}
% \end{verbatim}
% has default \texttt{UP} for the |^| test character, but will return the
% |-NoValue-| marker as a default for |_|. This allows mixing of explicit
% defaults with testing for missing values.
%
% \subsection{Body of an environment}
% \label{sec:body}
%
% While environments |\begin|\marg{environment} \dots{}
%   |\end|\marg{environment} are typically used in cases where the code
% implementing the \meta{environment} does not need to access the
% contents of the environment (its \enquote{body}), it is sometimes
% useful to have the body as a standard argument.
%
% This is achieved in \pkg{xparse} by ending the argument specification
% with~\texttt{b}. The approach taken in \pkg{xparse} is
% different from the earlier packages \pkg{environ} or \pkg{newenviron}:
% the body of the environment is provided to the code part as a usual
% argument |#1|, |#2| etc.\@, rather than stored in a macro such as
% \cs[no-index]{BODY}.
%
% For instance
% \begin{verbatim}
%   \NewDocumentEnvironment { twice }
%     { O{\ttfamily} +b }
%     {#2#1#2} {}
%   \begin{twice}[\itshape]
%     Hello world!
%   \end{twice}
% \end{verbatim}
% typesets \enquote{Hello world!{\itshape Hello world!}}.
%
% The prefix |+| is used to allow multiple paragraphs in the
% environment's body.  Argument processors can also be applied to
% \texttt{b}~arguments.
%
% By default, spaces are trimmed at both ends of the body: in the
% example there would otherwise be spaces coming from the ends the lines
% after |[\itshape]| and |world!|.  Putting the prefix |!| before
% \texttt{b} suppresses space-trimming.
%
% When \texttt{b} is used in the argument specification,
% the last argument of \cs{NewDocumentEnvironment}, which consists of
% an \meta{end code} to insert at |\end|\marg{environment}, is
% redundant since one can simply put that code at the end of the
% \meta{start code}.  Nevertheless this (empty) \meta{end code} must be
% provided.
%
% Environments that use this feature can be nested.
%
% Users should note that this feature is somewhat experimental. Feedback
% is therefore very welcome on the \texttt{LaTeX-L} mailing list.
%
% \subsection{Starred environments}
%
% Many packages define environments with and without \texttt{*} in their
% name, for instance \texttt{tabular} and \texttt{tabular*}.  At
% present, \pkg{xparse} does not provide specific tools to define these:
% one should simply define the two environment separately, for instance
% \begin{verbatim}
% \NewDocumentEnvironment { tabular } { o +m } {...} {...}
% \NewDocumentEnvironment { tabular* } { m o +m } {...} {...}
% \end{verbatim}
% Of course the implementation of these two environments, denoted
% \enquote{\texttt{...}} in this example, can rely on the same internal
% commands.
%
% Note that this situation is different from the \texttt{s} argument
% type: if the signature of an environment starts with~\texttt{s} then
% the star is searched for after the argument of \cs{begin}.  For
% instance, the following typesets \texttt{star}.
% \begin{verbatim}
% \NewDocumentEnvironment { envstar } { s }
%   {\IfBooleanTF {#1} {star} {no star}} {}
% \begin{envstar}*
% \end{envstar}
% \end{verbatim}
%
% \subsection{Backwards Compatibility}
% \label{sec:backwards}
%
% One role of \pkg{xparse} is to describe existing \LaTeX{} interfaces,
% including some that are rather unusual in \LaTeX{} (as opposed to
% formats such as plain \TeX{}) such as delimited arguments.  As such,
% the package defines some argument specifiers that should largely be
% avoided nowadays as using them in packages leads to inconsistent user
% interfaces.  The simplest syntax is often best, with argument
% specifications such as |mmmm| or |ommmm|, namely an optional argument
% followed by some standard mandatory ones.  The optional argument can
% be made to support key--value syntax using tools from \pkg{l3keys}.
%
% The argument types that are not recommended any longer are:
% \begin{itemize}[font=\ttfamily]
%   \item[l] A mandatory argument which reads everything up to the first
%     begin-group token: in standard \LaTeX{} this is a left brace.
%   \item[u] Reads a mandatory argument \enquote{until} \meta{tokens} are encountered,
%     where the desired \meta{tokens} are given as an argument to the
%     specifier: \texttt{u}\marg{tokens}.
%   \item[g] An optional argument given inside a pair of \TeX{} group
%     tokens (in standard \LaTeX{}, |{| \ldots |}|), which returns
%     |-NoValue-| if not present.
%   \item[G] As for \texttt{g} but returns \meta{default} if no value
%     is given: \texttt{G}\marg{default}.
% \end{itemize}
%
% \subsection{Details about argument delimiters}
%
% In normal (non-expandable) commands, the delimited types look for the
% initial delimiter by peeking ahead (using \pkg{expl3}'s |\peek_...|
% functions) looking for the delimiter token.  The token has to have the
% same meaning and \enquote{shape} of the token defined as delimiter.
% There are three possible cases of delimiters: character tokens, control
% sequence tokens, and active character tokens.  For all practical purposes
% of this description, active character tokens will behave exactly as
% control sequence tokens.
%
% \subsubsection{Character tokens}
%
% A character token is characterised by its character code, and its meaning
% is the category code~(|\catcode|).  When a command is defined, the meaning
% of the character token is fixed into the definition of the command and
% cannot change.  A command will correctly see an argument delimiter if
% the open delimiter has the same character and category codes as at the
% time of the definition.  For example in:
% \begin{verbatim}
%   \NewDocumentCommand { \foobar } { D<>{default} } {(#1)}
%   \foobar <hello> \par
%   \char_set_catcode_letter:N <
%   \foobar <hello>
% \end{verbatim}
% the output would be:
% \begin{verbatim}
%   (hello)
%   (default)<hello>
% \end{verbatim}
% as the open-delimter |<| changed in meaning between the two calls to
% |\foobar|, so the second one doesn't see the |<| as a valid delimiter.
% Commands assume that if a valid open-delimiter was found, a matching
% close-delimiter will also be there.  If it is not (either by being
% omitted or by changing in meaning), a low-level \TeX{} error is raised
% and the command call is aborted.
%
% \subsubsection{Control sequence tokens}
%
% A control sequence (or control character) token is characterised by is
% its name, and its meaning is its definition.
% A token cannot have two different meanings at the same time.
% When a control sequence is defined as delimiter in a command,
% it will be detected as delimiter whenever the control sequence name
% is found in the document regardless of its current definition.
% For example in:
% \begin{verbatim}
%   \cs_set:Npn \x { abc }
%   \NewDocumentCommand { \foobar } { D\x\y{default} } {(#1)}
%   \foobar \x hello\y \par
%   \cs_set:Npn \x { def }
%   \foobar \x hello\y
% \end{verbatim}
% the output would be:
% \begin{verbatim}
%   (hello)
%   (hello)
% \end{verbatim}
% with both calls to the command seeing the delimiter |\x|.
%
% \section{Declaring commands and environments}
%
% With the concept of an argument specifier defined, it is now
% possible to describe the methods available for creating both
% functions and environments using \pkg{xparse}.
%
% The interface-building commands are the preferred method for
% creating document-level functions in \LaTeX3. All of the functions
% generated in this way are naturally robust (using the \eTeX{}
% \cs{protected} mechanism).
%
% \begin{function}
%   {
%     \NewDocumentCommand     ,
%     \RenewDocumentCommand   ,
%     \ProvideDocumentCommand ,
%     \DeclareDocumentCommand
%   }
%   \begin{syntax}
%     \cs{NewDocumentCommand} \meta{function} \Arg{arg spec} \Arg{code}
%   \end{syntax}
%   This family of commands are used to create a document-level
%   \meta{function}. The argument specification for the function is
%   given by \meta{arg spec}, and the function expands to the
%   \meta{code} with |#1|, |#2|, etc.\ replaced by the arguments found
%   by \pkg{xparse}.
% \end{function}
%
%   As an example:
%   \begin{verbatim}
%     \NewDocumentCommand \chapter { s o m }
%       {
%         \IfBooleanTF {#1}
%           { \typesetstarchapter {#3} }
%           { \typesetnormalchapter {#2} {#3} }
%       }
%   \end{verbatim}
%   would be a way to define a \cs{chapter} command which would
%   essentially behave like the current \LaTeXe{} command (except that it
%   would accept an optional argument even when a \texttt{*} was parsed).
%   The \cs{typesetnormalchapter} could test its first argument for being
%   |-NoValue-| to see if an optional argument was present.
%
%   The difference between the \cs{New\ldots} \cs{Renew\ldots},
%   \cs{Provide\ldots} and \cs{Declare\ldots} versions is the behaviour
%   if \meta{function} is already defined.
%   \begin{itemize}
%    \item \cs{NewDocumentCommand} will issue an error if \meta{function}
%      has already been defined.
%    \item \cs{RenewDocumentCommand} will issue an error if \meta{function}
%      has not previously been defined.
%    \item \cs{ProvideDocumentCommand} creates a new definition for
%      \meta{function} only if one has not already been given.
%     \item \cs{DeclareDocumentCommand} will always create the new
%       definition, irrespective of any existing \meta{function} with the
%       same name.  This should be used sparingly.
%   \end{itemize}
%
%   \begin{texnote}
%      Unlike \LaTeXe{}'s \cs{newcommand} and relatives, the
%      \cs{NewDocumentCommand} family of functions do not prevent creation of
%      functions with names starting \cs{end\ldots}.
%   \end{texnote}
%
% \begin{function}
%   {
%     \NewDocumentEnvironment     ,
%     \RenewDocumentEnvironment   ,
%     \ProvideDocumentEnvironment ,
%     \DeclareDocumentEnvironment
%   }
%   \begin{syntax}
%     \cs{NewDocumentEnvironment} \Arg{environment} \Arg{arg spec}
%     ~~\Arg{start code} \Arg{end code}
%   \end{syntax}
%   These commands work in the same way as \cs{NewDocumentCommand},
%   etc.\@, but create environments (\cs{begin}\Arg{environment} \ldots{}
%   \cs{end}\Arg{environment}). Both the \meta{start code} and
%   \meta{end code}
%   may access the arguments as defined by \meta{arg spec}.
%   The arguments will be given following \cs{begin}\Arg{environment}.
% \end{function}
%
% \section{Other \pkg{xparse} commands}
%
% \subsection{Testing special values}
%
% Optional arguments created using \pkg{xparse} make use of dedicated
% variables to return information about the nature of the argument
% received.
%
% \begin{function}[EXP]{\IfNoValueT, \IfNoValueF, \IfNoValueTF}
%   \begin{syntax}
%     \cs{IfNoValueTF} \Arg{argument} \Arg{true code} \Arg{false code}
%     \cs{IfNoValueT} \Arg{argument} \Arg{true code}
%     \cs{IfNoValueF} \Arg{argument} \Arg{false code}
%   \end{syntax}
%   The \cs{IfNoValue(TF)} tests are used to check if \meta{argument} (|#1|,
%   |#2|, \emph{etc.}) is the special |-NoValue-| marker For example
%   \begin{verbatim}
%     \NewDocumentCommand \foo { o m }
%       {
%         \IfNoValueTF {#1}
%           { \DoSomethingJustWithMandatoryArgument {#2} }
%           {  \DoSomethingWithBothArguments {#1} {#2}   }
%       }
%   \end{verbatim}
%   will use a different internal function if the optional argument
%   is given than if it is not present.
%
%   Note that three tests are available, depending on which outcome
%   branches are required: \cs{IfNoValueTF}, \cs{IfNoValueT} and
%   \cs{IfNoValueF}.
%
%   As the \cs{IfNoValue(TF)} tests are expandable, it is possible to
%   test these values later, for example at the point of typesetting or
%   in an expansion context.
%
%   It is important to note that |-NoValue-| is constructed such that it
%   will \emph{not} match the simple text input |-NoValue-|, \emph{i.e.}
%   that
%   \begin{verbatim}
%     \IfNoValueTF{-NoValue-}
%   \end{verbatim}
%   will be logically \texttt{false}.
%
%   When two optional arguments follow each other (a syntax we typically
%   discourage), it can make sense to allow users of the command to
%   specify only the second argument by providing an empty first
%   argument.  Rather than testing separately for emptyness and for
%   |-NoValue-| it is then best to use the argument type~|O| with an
%   empty default value, and simply test for emptyness using the
%   \pkg{expl3} conditional \cs{tl_if_blank:nTF} or its \pkg{etoolbox}
%   analogue \tn{ifblank}.
% \end{function}
%
% \begin{function}[EXP]{\IfValueT, \IfValueF, \IfValueTF}
%   \begin{syntax}
%     \cs{IfValueTF} \Arg{argument} \Arg{true code} \Arg{false code}
%    \end{syntax}
%   The reverse form of the \cs{IfNoValue(TF)} tests are also available
%   as \cs{IfValue(TF)}. The context will determine which logical
%   form makes the most sense for a given code scenario.
% \end{function}
%
% \begin{variable}{\BooleanFalse, \BooleanTrue}
%   The \texttt{true} and \texttt{false} flags set when searching for
%   an optional character (using \texttt{s} or \texttt{t\meta{char}}) have
%   names which are accessible outside of code blocks.
% \end{variable}
%
% \begin{function}[EXP]{\IfBooleanT, \IfBooleanF, \IfBooleanTF}
%   \begin{syntax}
%     \cs{IfBooleanTF} \Arg{argument} \Arg{true code} \Arg{false code}
%   \end{syntax}
%   Used to test if \meta{argument} (|#1|, |#2|, \emph{etc.}) is
%   \cs{BooleanTrue} or \cs{BooleanFalse}. For example
%   \begin{verbatim}
%     \NewDocumentCommand \foo { s m }
%       {
%         \IfBooleanTF {#1}
%           { \DoSomethingWithStar {#2} }
%           { \DoSomethingWithoutStar {#2} }
%       }
%   \end{verbatim}
%   checks for a star as the first argument, then chooses the action to
%   take based on this information.
% \end{function}
%
% \subsection{Argument processors}
% \label{sec:processors}
%
% \pkg{xparse} introduces the idea of an argument processor, which is
% applied to an argument \emph{after} it has been grabbed by the
% underlying system but before it is passed to \meta{code}. An argument
% processor can therefore be used to regularise input at an early stage,
% allowing the internal functions to be completely independent of input
% form. Processors are applied to user input and to default values for
% optional arguments, but \emph{not} to the special |-NoValue-| marker.
%
% Each argument processor is specified by the syntax
% \texttt{>}\marg{processor} in the argument specification. Processors
% are applied from right to left, so that
% \begin{verbatim}
%   >{\ProcessorB} >{\ProcessorA} m
% \end{verbatim}
% would apply \cs{ProcessorA}
% followed by \cs{ProcessorB} to the tokens grabbed by the \texttt{m}
% argument.
%
% It might sometimes be useful to use the value of another argument as
% one of the arguments of a processor.  For example, using the
% \cs{SplitList} processor defined below,
% \begin{verbatim}
%   \NewDocumentCommand \foo { O{,} >{\SplitList{#1}} m } { \foobar{#2} }
%   \foo{a,b;c,d}
% \end{verbatim}
% results in |\foobar| receiving the argument |{a}{b;c}{d}| because
% \cs{SplitList} receives as its two arguments the optional one (whose
% value here is the default, a comma) and the mandatory one.  To
% summarize, first the arguments are searched for in the input, then any
% default argument is determined as explained in
% Section~\ref{sec:defaultvaluesofarguments}, then these default
% arguments are passed to any processor.  When referring to arguments
% (through |#1|, |#2| and so on) in a processor, the arguments used are
% always those before applying any processor.
%
% \begin{variable}{\ProcessedArgument}
%   \pkg{xparse} defines a very small set of processor functions. In the
%   main, it is anticipated that code writers will want to create their
%   own processors. These need to accept one argument, which is the
%   tokens as grabbed (or as returned by a previous processor function).
%   Processor functions should return the processed argument as the
%   variable \cs{ProcessedArgument}.
% \end{variable}
%
% \begin{function}{\ReverseBoolean}
%   \begin{syntax}
%     \cs{ReverseBoolean}
%   \end{syntax}
%   This processor reverses the logic of \cs{BooleanTrue} and
%   \cs{BooleanFalse}, so that the example from earlier would become
%   \begin{verbatim}
%     \NewDocumentCommand \foo { > { \ReverseBoolean } s m }
%       {
%         \IfBooleanTF #1
%           { \DoSomethingWithoutStar {#2} }
%           { \DoSomethingWithStar {#2} }
%       }
%   \end{verbatim}
% \end{function}
%
% \begin{function}[updated = 2012-02-12]{\SplitArgument}
%   \begin{syntax}
%     \cs{SplitArgument} \Arg{number} \Arg{token(s)}
%   \end{syntax}
%   This processor splits the argument given at each occurrence of the
%   \meta{tokens} up to a maximum of \meta{number} tokens (thus
%   dividing the input into $\text{\meta{number}} + 1$ parts).
%   An error is given if too many \meta{tokens} are present in the
%   input. The processed input is placed inside
%   $\text{\meta{number}} + 1$ sets of braces for further use.
%   If there are fewer than \Arg{number} of \Arg{tokens} in the argument
%   then |-NoValue-| markers are added at the end of the processed
%   argument.
%   \begin{verbatim}
%     \NewDocumentCommand \foo
%       { > { \SplitArgument { 2 } { ; } } m }
%       { \InternalFunctionOfThreeArguments #1 }
%   \end{verbatim}
%   If only a single character \meta{token} is used for the split, any
%   category code $13$ (active) character matching the \meta{token} will
%   be replaced before the split takes place.
%   Spaces are trimmed at each end of each item parsed.
% \end{function}
%
% \begin{function}{\SplitList}
%   \begin{syntax}
%     \cs{SplitList} \Arg{token(s)}
%   \end{syntax}
%   This processor splits the argument given at each occurrence of the
%   \meta{token(s)} where the number of items is not fixed. Each item is
%   then wrapped in braces within |#1|. The result is that the
%   processed argument can be further processed using a mapping function.
%   \begin{verbatim}
%     \NewDocumentCommand \foo
%       { > { \SplitList { ; } } m }
%       { \MappingFunction #1 }
%   \end{verbatim}
%   If only a single character \meta{token} is used for the split, any
%   category code $13$ (active) character matching the \meta{token} will
%   be replaced before the split takes place.
%   Spaces are trimmed at each end of each item parsed.
% \end{function}
%
% \begin{function}[EXP]{\ProcessList}
%   \begin{syntax}
%     \cs{ProcessList} \Arg{list} \Arg{function}
%   \end{syntax}
%   To support \cs{SplitList}, the function \cs{ProcessList} is available
%   to apply a \meta{function} to every entry in a \meta{list}. The
%   \meta{function} should absorb one argument: the list entry. For example
%   \begin{verbatim}
%     \NewDocumentCommand \foo
%       { > { \SplitList { ; } } m }
%       { \ProcessList {#1} { \SomeDocumentFunction } }
%   \end{verbatim}
%
%   \textbf{This function is experimental.}
% \end{function}
%
% \begin{function}{\TrimSpaces}
%   \begin{syntax}
%     \cs{TrimSpaces}
%   \end{syntax}
%   Removes any leading and trailing spaces (tokens with character code~$32$
%   and category code~$10$) for the ends of the argument. Thus for example
%   declaring a function
%   \begin{verbatim}
%     \NewDocumentCommand \foo
%       { > { \TrimSpaces } m }
%       { \showtokens {#1} }
%   \end{verbatim}
%   and using it in a document as
%   \begin{verbatim}
%     \foo{ hello world }
%   \end{verbatim}
%   will show \texttt{hello world} at the terminal, with the space at each
%   end removed. \cs{TrimSpaces} will remove multiple spaces from the ends of
%   the input in cases where these have been included such that the standard
%   \TeX{} conversion of multiple spaces to a single space does not apply.
%
%   \textbf{This function is experimental.}
% \end{function}
%
% \subsection{Fully-expandable document commands}
%
% There are \emph{very rare} occasion when it may be useful to create
% functions using a fully-expandable argument grabber. To support this,
% \pkg{xparse} can create expandable functions as well as the usual
% robust ones. This imposes a number of restrictions on the nature of
% the arguments accepted by a function, and the code it implements.
% This facility should only be used when \emph{absolutely necessary};
% if you do not understand when this might be, \emph{do not use these
% functions}!
%
% \begin{function}
%   {
%     \NewExpandableDocumentCommand     ,
%     \RenewExpandableDocumentCommand   ,
%     \ProvideExpandableDocumentCommand ,
%     \DeclareExpandableDocumentCommand
%   }
%   \begin{syntax}
%     \cs{NewExpandableDocumentCommand}
%     ~~~~\meta{function} \Arg{arg spec} \Arg{code}
%   \end{syntax}
%   This family of commands is used to create a document-level \meta{function},
%   which will grab its arguments in a fully-expandable manner. The
%   argument specification for the function is given by \meta{arg spec},
%   and the function will execute \meta{code}. In  general, \meta{code} will
%   also be fully expandable, although it is possible that this will
%   not be the case (for example, a function for use in a table might
%   expand so that \cs{omit} is the first non-expandable non-space token).
%
%   Parsing arguments expandably imposes a number of restrictions on
%   both the type of arguments that can be read and the error checking
%   available:
%   \begin{itemize}
%     \item The last argument (if any are present) must be one of the
%       mandatory types \texttt{m}, \texttt{r}, \texttt{R}, \texttt{l}
%       or~\texttt{u}.
%     \item All short arguments appear before long arguments.
%     \item The mandatory argument types \texttt{l} and \texttt{u} may
%       not be used after optional arguments.
%     \item The optional argument types \texttt{g}
%       and \texttt{G} are not available.
%     \item The \enquote{verbatim} argument type \texttt{v} is not available.
%     \item Argument processors (using \texttt{>}) are not available.
%     \item It is not possible to differentiate between, for example
%       |\foo[| and |\foo{[}|: in both cases the \texttt{[} will be
%       interpreted as the start of an optional argument. As a
%       result, checking for optional arguments is less robust than
%       in the standard version.
%   \end{itemize}
%   \pkg{xparse} will issue an error if an argument specifier is given
%   which does not conform to the first six requirements. The last
%   item is an issue when the function is used, and so is beyond the
%   scope of \pkg{xparse} itself.
% \end{function}
%
% \subsection{Access to the argument specification}
%
% The argument specifications for document commands and environments are
% available for examination and use.
%
% \begin{function}{\GetDocumentCommandArgSpec, \GetDocumentEnvironmentArgSpec}
%   \begin{syntax}
%     \cs{GetDocumentCommandArgSpec} \meta{function}
%     \cs{GetDocumentEnvironmentArgSpec} \Arg{environment}
%   \end{syntax}
%   These functions transfer the current argument specification for the
%   requested \meta{function} or \meta{environment} into the token list
%   variable \cs{ArgumentSpecification}. If the \meta{function} or
%   \meta{environment} has no known argument specification then an error
%   is issued. The assignment to \cs{ArgumentSpecification} is local to
%   the current \TeX{} group.
% \end{function}
%
% \begin{function}
%   {\ShowDocumentCommandArgSpec,  \ShowDocumentEnvironmentArgSpec}
%   \begin{syntax}
%     \cs{ShowDocumentCommandArgSpec} \meta{function}
%     \cs{ShowDocumentEnvironmentArgSpec} \Arg{environment}
%   \end{syntax}
%   These functions show the current argument specification for the
%   requested \meta{function} or \meta{environment} at the terminal. If
%   the \meta{function} or \meta{environment} has no known argument
%   specification then an error is issued.
% \end{function}
%
% \section{Load-time options}
%
% \DescribeOption{log-declarations}
% The package recognises the load-time option \texttt{log-declarations},
% which is a key--value option taking the value \texttt{true} and
% \texttt{false}. By default, the option is set to \texttt{false}, meaning
% that no command or environment declared is logged. By loading
% \pkg{xparse} using
% \begin{verbatim}
%   \usepackage[log-declarations=true]{xparse}
% \end{verbatim}
% each new, declared or renewed command or environment is logged.
%
% \end{documentation}
%
% \begin{implementation}
%
% \section{\pkg{xparse} implementation}
%
%    \begin{macrocode}
%<*2ekernel|package>
%    \end{macrocode}
%
%    \begin{macrocode}
%<@@=cmd>
%    \end{macrocode}
%
% This package file, along with the frozen versions in
% \pkg{xparse-2018-04-12}, \pkg{xparse-2020-10-01}, and
% |xparse-generic.tex|, is intended to work across different \LaTeX{}
% releases, respected the minimum \pkg{expl3} version required by
% \pkg{xparse}.
%
% We can't use the \pkg{latexrelease} mechanism with \cs{DeclareRelease}
% here because cases of rolling forwards or backwards differ, due to the
% prefix change from |xparse| to |cmd|, so we do our own checks to
% ensure the right version is loaded.
%
% All this loading assumes that if \pkg{latexrelease} should be loaded,
% it is before \pkg{xparse}.  The other way around was not tested at all
% and is likely to break.
%
% In releases prior to 2020-10-01, \cs{NewDocumentCommand} is undefined,
% so \pkg{xparse} was not loaded, thus we can load the full version from
% \pkg{xparse-2018-04-12}.  Otherwise we will load only the deprecated
% argument types from \pkg{xparse-2020-10-01}.  If we're in |2ekernel|
% mode, it means rolling forward so load only the code code from
% |xparse-generic.tex|.
%
% In |2ekernel| mode we anticipate the definition of two macros to parse
% dates so that we can compare \cs{fmtdate} properly.
%    \begin{macrocode}
%<*2ekernel>
\def\@parse@version#1/#2/#3#4#5\@nil{%
  \@parse@version@dash#1-#2-#3#4\@nil}
\def\@parse@version@dash#1-#2-#3#4#5\@nil{%
  \if\relax#2\relax\else#1\fi#2#3#4 }
%</2ekernel>
\ExplSyntaxOn
\cs_set_protected:Npn \@@_tmp:w #1
  {
    \DeclareOption* { \PassOptionsToPackage { \CurrentOption } {#1} }
    \ProcessOptions \relax
    \RequirePackage {#1}
  }
\cs_if_free:NTF \NewDocumentCommand
  {
    \ExplSyntaxOff
    \ifnum\expandafter
        \@parse@version\fmtversion//00\@nil <
        \@parse@version 2020-10-01//00\@nil
      \@@_tmp:w { xparse-2018-04-12 }
    \else
%<2ekernel>      \@@@@input xparse-generic.tex ~
%<package>      \@@_tmp:w { xparse-2020-10-01 }
    \fi
    \file_input_stop:
  }
%    \begin{macrocode}
%
% In case \cs{NewDocumentCommand} is already defined, we're either in
% \LaTeX{} 2020-10-01 or later.  In the former case, the code loaded in
% the kernel has the |__xparse| prefix, so we'll load
% \pkg{xparse-2020-10-01}, otherwise we'll continue in |xparse.sty|,
% which contains the final remains of \pkg{xparse} with the |__cmd|
% prefix.  To check that we simply look at an internal command with the
% |__cmd| prefix.
%    \end{macrocode}
  {
    \ExplSyntaxOff
    \cs_if_exist:NF \@@_start:nNNnnn
      {
        \@@_tmp:w { xparse-2020-10-01 }
        \file_input_stop:
      }
  }
\ExplSyntaxOff
%    \end{macrocode}
%
%    \begin{macrocode}
%</2ekernel|package>
%    \end{macrocode}
%
% In older releases, the prefix was |xparse|, but since the 2021 Spring
% release of \LaTeXe, the core code is included in the kernel, and this
% file only holds the deprecated argument specifiers |G|, |l|, and |u|.
% To match the prefix in the \LaTeXe{} kernel, so that the deprecated
% types work if |xparse.sty| is loaded, the prefix has changed to |cmd|.
%
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
%    \begin{macrocode}
\ProvidesExplPackage{xparse}{2023-01-16}{}
  {L3 Experimental document command parser}
%    \end{macrocode}
%
% \subsection{Package options}
%
% \begin{variable}{\l_@@_options_clist}
% \begin{variable}{\l_@@_log_bool}
%   Key--value option to log information: done by hand to keep dependencies
%   down.
%    \begin{macrocode}
\clist_new:N \l_@@_options_clist
\DeclareOption* { \clist_put_right:NV \l_@@_options_clist \CurrentOption }
\ProcessOptions \relax
\cs_set_protected:Npn \@@_tmp:w #1
  {
    \keys_define:nn {#1}
      {
        log-declarations .bool_set:N = \l_@@_log_bool ,
        log-declarations .initial:n  = false
      }
    \keys_set:nV {#1} \l_@@_options_clist
    \bool_if:NTF \l_@@_log_bool
      { \msg_redirect_module:nnn {#1} { info } { } }
      { \msg_redirect_module:nnn {#1} { info } { none } }
    \cs_new_protected:Npn \@@_unknown_argument_type_error:n ##1
      {
        \msg_error:nnxx {#1} { unknown-argument-type }
          { \@@_environment_or_command: } { \tl_to_str:n {##1} }
      }
  }
\msg_if_exist:nnTF { cmd } { define-command }
  { \@@_tmp:w { cmd } }
  { \@@_tmp:w { ltcmd } }
%    \end{macrocode}
% \end{variable}
% \end{variable}
%
% \subsection{Normalizing the argument specifications}
%
% \begin{macro}{\@@_normalize_arg_spec_loop:n}
%   Loop through the argument specification, calling an auxiliary
%   specific to each argument type.  If any argument is unknown stop the
%   definition.
%    \begin{macrocode}
\cs_gset_protected:Npn \@@_normalize_arg_spec_loop:n #1
  {
    \quark_if_recursion_tail_stop:n {#1}
    \int_incr:N \l_@@_current_arg_int
    \cs_if_exist_use:cF { @@_normalize_type_ \tl_to_str:n {#1} :w }
      {
        \@@_unknown_argument_type_error:n {#1}
        \@@_bad_def:wn
      }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_normalize_type_g:w}
%   These argument types are aliases of more general ones, for example
%   with the default argument |-NoValue-|.
%    \begin{macrocode}
\cs_new_protected:Npx \@@_normalize_type_g:w
  { \exp_not:N \@@_normalize_type_G:w { \exp_not:V \c_novalue_tl } }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_normalize_type_G:w}
%   Optional argument types.  Check that all required data is present
%   (and consists of single characters if applicable) and check for
%   forbidden types for expandable commands.  Then in each case
%   store the data in \cs{l_@@_arg_spec_tl}, and
%   for later checks store in \cs{l_@@_last_delimiters_tl} the tokens
%   whose presence determines whether there is an optional argument (for
%   braces store |{}|, seen later as an empty delimiter).
%    \begin{macrocode}
\cs_new_protected:Npn \@@_normalize_type_G:w #1
  {
    \quark_if_recursion_tail_stop_do:nn {#1} { \@@_bad_arg_spec:wn }
    \@@_normalize_check_gv:N G
    \@@_add_arg_spec:n { G {#1} }
    \tl_put_right:Nn \l_@@_last_delimiters_tl { { } }
    \@@_normalize_arg_spec_loop:n
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_normalize_type_l:w,\@@_normalize_type_u:w}
%   Mandatory arguments.  First check the required data is present,
%   consists of single characters where applicable, and that the argument
%   type is allowed for expandable commands if applicable.  Then save data in
%   \cs{l_@@_arg_spec_tl}, count the mandatory argument, and empty the
%   list of last delimiters.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_normalize_type_l:w
  {
    \@@_normalize_check_lu:N l
    \@@_add_arg_spec_mandatory:n { l }
    \@@_normalize_arg_spec_loop:n
  }
\cs_new_protected:Npn \@@_normalize_type_u:w #1
  {
    \quark_if_recursion_tail_stop_do:nn {#1} { \@@_bad_arg_spec:wn }
    \@@_normalize_check_lu:N u
    \@@_add_arg_spec_mandatory:n { u {#1} }
    \@@_normalize_arg_spec_loop:n
  }
%    \end{macrocode}
% \end{macro}
%
% \subsection{Setting up a standard signature}
%
% \begin{macro}{\@@_add_type_G:w}
%   For the \texttt{G} type, the grabber and the default are added to the
%   signature.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_add_type_G:w #1
  {
    \@@_flush_m_args:
    \@@_add_default:n {#1}
    \@@_add_grabber:N G
    \@@_prepare_signature:N
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_add_type_l:w}
%   Finding \texttt{l} arguments is very simple: there is nothing to do
%   other than add the grabber.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_add_type_l:w
  {
    \@@_flush_m_args:
    \@@_add_default:
    \@@_add_grabber:N l
    \@@_prepare_signature:N
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_add_type_u:w}
%   At the set up stage, the \texttt{u} type argument is identical to the
%   \texttt{G} type except for the name of the grabber function.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_add_type_u:w #1
  {
    \@@_flush_m_args:
    \@@_add_default:
    \@@_add_grabber:N u
    \tl_put_right:Nn \l_@@_signature_tl { {#1} }
    \@@_prepare_signature:N
  }
%    \end{macrocode}
% \end{macro}
%
% \subsection{Setting up expandable types}
%
% \begin{macro}{\@@_add_expandable_type_l:w}
%   Reuse type \texttt{u}, thanks to the fact that \TeX{} macros whose
%   parameter text ends with |#| in fact end up being delimited by an
%   open brace.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_add_expandable_type_l:w
  { \@@_add_expandable_type_u:w ## }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_add_expandable_type_u:w}
%   Define an auxiliary that will be used directly in the signature.  It
%   grabs one argument delimited by |#1| and places it before \cs{q_@@}.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_add_expandable_type_u:w #1
  {
    \@@_add_default:
    \bool_if:NTF \l_@@_long_bool
      { \cs_set:cpn }
      { \cs_set_nopar:cpn }
      { \l_@@_expandable_aux_name_tl } ##1 \q_@@ ##2 ##3 ##4 #1
      { ##1 {##4} \q_@@ ##2 ##3 }
    \@@_add_expandable_grabber:nn { u }
      { \exp_not:c  { \l_@@_expandable_aux_name_tl } }
    \@@_prepare_signature:N
  }
%    \end{macrocode}
% \end{macro}
%
% \subsection{Copying a command and its internal structure}
%
% The apparatus for copying commands is almost entirely in |ltcmd.dtx|,
% preloaded in the \LaTeXe{} kernel.  The missing parts, regarding
% copying the deprecated argument types |G|, |l| and |u| boil down to
% copying the expandable grabber for |u|.
%
% \begin{macro}{\@@_copy_grabber_u:w}
%   An expandable |u|-type uses a dedicated grabber just like a
%   |D|-type, except that both its delimiter tokens are omitted, so to
%   copy that we just copy a |D|-type and leave the last two arguments
%   empty:
%    \begin{macrocode}
\cs_new_protected:Npn \@@_copy_grabber_u:w #1 #2 #3
  { \@@_copy_grabber_D:w {#1} {#2} {#3} { } { } }
%    \end{macrocode}
% \end{macro}
%
% \subsubsection{Showing the definition of a command}
%
% \begin{macro}{\c_@@_show_type_u_tl,\c_@@_show_type_G_tl}
%   Same as for copying, only small bits are missing here.  Namely, two
%   token lists that tell the \pkg{ltcmd} mechanism how to deal with the
%   argument types defined here.  Both |G| and |u| are classified
%   as~|3|: commands that take a default value.  That's not really true
%   for~|u|, but it's a close enough approximation to get the output we
%   want.
%    \begin{macrocode}
\tl_const:Nn \c_@@_show_type_u_tl { 3 }
\tl_const:Nn \c_@@_show_type_G_tl { 3 }
%    \end{macrocode}
% \end{macro}
%
% \subsection{Grabbing arguments}
%
% \begin{macro}{\@@_grab_G:w}
% \begin{macro}{\@@_grab_G_long:w}
% \begin{macro}{\@@_grab_G_obey_spaces:w}
% \begin{macro}{\@@_grab_G_long_obey_spaces:w}
% \begin{macro}{\@@_grab_G_aux:nNN}
%   Optional groups are checked by meaning, so that the same code will
%   work with, for example, \ConTeXt{}-like input.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_grab_G:w #1 \@@_run_code:
  {
    \@@_grab_G_aux:nNN {#1} \cs_set_protected_nopar:Npn
      \@@_peek_nonspace:NTF
  }
\cs_new_protected:Npn \@@_grab_G_long:w #1 \@@_run_code:
  {
    \@@_grab_G_aux:nNN {#1} \cs_set_protected:Npn
      \@@_peek_nonspace:NTF
  }
\cs_new_protected:Npn \@@_grab_G_obey_spaces:w #1 \@@_run_code:
  {
    \@@_grab_G_aux:nNN {#1} \cs_set_protected_nopar:Npn
      \peek_meaning:NTF
  }
\cs_new_protected:Npn \@@_grab_G_long_obey_spaces:w #1 \@@_run_code:
  {
    \@@_grab_G_aux:nNN {#1} \cs_set_protected:Npn
      \peek_meaning:NTF
  }
\cs_new_protected:Npn \@@_grab_G_aux:nNN #1#2#3
  {
    \tl_set:Nn \l_@@_signature_tl {#1}
    \exp_after:wN #2 \l_@@_fn_tl ##1
      { \@@_add_arg:n {##1} }
    #3 \c_group_begin_token
      { \l_@@_fn_tl }
      { \@@_add_arg:o \c_novalue_tl }
  }
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\@@_grab_l:w}
% \begin{macro}{\@@_grab_l_long:w}
% \begin{macro}{\@@_grab_l_aux:nN}
%   Argument grabbers for mandatory \TeX{} arguments are pretty simple.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_grab_l:w #1 \@@_run_code:
  { \@@_grab_l_aux:nN {#1} \cs_set_protected_nopar:Npn }
\cs_new_protected:Npn \@@_grab_l_long:w #1 \@@_run_code:
  { \@@_grab_l_aux:nN {#1} \cs_set_protected:Npn }
\cs_new_protected:Npn \@@_grab_l_aux:nN #1#2
  {
    \tl_set:Nn \l_@@_signature_tl {#1}
    \exp_after:wN #2 \l_@@_fn_tl ##1##
      { \@@_add_arg:n {##1} }
    \l_@@_fn_tl
  }
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\@@_grab_u:w}
% \begin{macro}{\@@_grab_u_long:w}
% \begin{macro}{\@@_grab_u_aux:nnN}
%   Grabbing up to a list of tokens is quite easy: define the grabber,
%   and then collect.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_grab_u:w #1#2 \@@_run_code:
  { \@@_grab_u_aux:nnN {#1} {#2} \cs_set_protected_nopar:Npn }
\cs_new_protected:Npn \@@_grab_u_long:w #1#2 \@@_run_code:
  { \@@_grab_u_aux:nnN {#1} {#2} \cs_set_protected:Npn }
\cs_new_protected:Npn \@@_grab_u_aux:nnN #1#2#3
  {
    \tl_set:Nn \l_@@_signature_tl {#2}
    \exp_after:wN #3 \l_@@_fn_tl ##1 #1
      { \@@_add_arg:n {##1} }
    \l_@@_fn_tl
  }
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}[EXP]{\@@_expandable_grab_u:w}
%   It turns out there is nothing to do: this is followed by an
%   auxiliary named after the function, that does everything.
%    \begin{macrocode}
\cs_new_eq:NN \@@_expandable_grab_u:w \prg_do_nothing:
%    \end{macrocode}
% \end{macro}
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \end{implementation}
%
% \PrintIndex