summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/l3kernel/l3candidates.dtx
blob: 4c08d8e422c6602f4a3e92cb512d83fd5ad0b4a4 (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
% \iffalse meta-comment
%
%% File: l3candidates.dtx
%
% Copyright (C) 2012-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 "l3kernel 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>
\documentclass[full,kernel]{l3doc}
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
%
% \title{^^A
%   The \textsf{l3candidates} package\\ Experimental additions to
%   \pkg{l3kernel}^^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-05-05}
%
% \maketitle
%
% \begin{documentation}
%
% \section{Important notice}
%
% This module provides a space in which functions can be added to
% \pkg{l3kernel} (\pkg{expl3}) while still being experimental.
% \begin{quote}
%  \bfseries
% As such, the
% functions here may not remain in their current form, or indeed at all,
% in \pkg{l3kernel} in the future.
% \end{quote}
%  In contrast to the material in
% \pkg{l3experimental}, the functions here are all \emph{small} additions to
% the kernel. We encourage programmers to test them out and report back on
% the \texttt{LaTeX-L} mailing list.
%
% \medskip
%
%   Thus, if you intend to use any of these functions from the candidate module in a public package
%  offered to others for productive use (e.g., being placed on CTAN) please consider the following points carefully:
% \begin{itemize}
% \item Be prepared that your public packages might require updating when such functions
%        are being finalized.
% \item Consider informing us that you use a particular function in your public package, e.g., by
%         discussing this on the \texttt{LaTeX-L}
%    mailing list. This way it becomes easier to coordinate any updates necessary without issues
%    for the users of your package.
% \item Discussing and understanding use cases for a particular addition or concept also helps to
%         ensure that we provide the right interfaces in the final version so please give us feedback
%         if you consider a certain candidate function useful (or not).
% \end{itemize}
% We only add functions in this space if we consider them being serious candidates for a final inclusion
% into the kernel. However, real use sometimes leads to better ideas, so functions from this module are
% \textbf{not necessarily stable} and we may have to adjust them!
%
% \section{Additions to \pkg{l3seq}}
%
% \begin{function}[rEXP]
%   {
%     \seq_mapthread_function:NNN, \seq_mapthread_function:NcN,
%     \seq_mapthread_function:cNN, \seq_mapthread_function:ccN
%   }
%   \begin{syntax}
%     \cs{seq_mapthread_function:NNN} \meta{seq_1} \meta{seq_2} \meta{function}
%   \end{syntax}
%   Applies \meta{function} to every pair of items
%   \meta{seq_1-item}--\meta{seq_2-item} from the two sequences, returning
%   items from both sequences from left to right.   The \meta{function}
%   receives two \texttt{n}-type arguments for each iteration. The  mapping
%   terminates when
%   the end of either sequence is reached (\emph{i.e.}~whichever sequence has
%   fewer items determines how many iterations
%   occur).
% \end{function}
%
% \begin{function}{\seq_set_filter:NNn, \seq_gset_filter:NNn}
%   \begin{syntax}
%     \cs{seq_set_filter:NNn} \meta{sequence_1} \meta{sequence_2} \Arg{inline boolexpr}
%   \end{syntax}
%   Evaluates the \meta{inline boolexpr} for every \meta{item} stored
%   within the \meta{sequence_2}. The \meta{inline boolexpr}
%   receives the \meta{item} as |#1|. The sequence of all \meta{items}
%   for which the \meta{inline boolexpr} evaluated to \texttt{true}
%   is assigned to \meta{sequence_1}.
%   \begin{texnote}
%     Contrarily to other mapping functions, \cs{seq_map_break:} cannot
%     be used in this function, and would lead to low-level \TeX{} errors.
%   \end{texnote}
% \end{function}
%
% \begin{function}[added = 2021-04-29, noTF]
%   {\seq_set_item:Nnn, \seq_set_item:cnn, \seq_gset_item:Nnn, \seq_gset_item:cnn}
%   \begin{syntax}
%     \cs{seq_set_item:Nnn} \meta{seq~var} \Arg{int expr} \Arg{item}
%     \cs{seq_set_item:NnnTF} \meta{seq~var} \Arg{int expr} \Arg{item} \Arg{true code} \Arg{false code}
%   \end{syntax}
%   Removes the item of \meta{sequence} at the position given by
%   evaluating the \meta{int expr} and replaces it by
%   \meta{item}.  Items are indexed from $1$ on the left/top of the
%   \meta{sequence}, or from $-1$ on the right/bottom.  If the
%   \meta{int expr} is zero or is larger (in absolute value)
%   than the number of items in the sequence, the \meta{sequence} is not
%   modified.  In these cases, \cs{seq_set_item:Nnn} raises an error
%   while \cs{seq_set_item:NnnTF} runs the \meta{false code}.  In cases
%   where the assignment was successful, \meta{true code} is run
%   afterwards.
% \end{function}
%
% \begin{function}[added = 2021-04-28, noTF]
%   {\seq_pop_item:NnN, \seq_pop_item:cnN, \seq_gpop_item:NnN, \seq_gpop_item:cnN}
%   \begin{syntax}
%     \cs{seq_pop_item:NnN} \meta{seq~var} \Arg{int expr} \Arg{tl~var}
%     \cs{seq_pop_item:NnNTF} \meta{seq~var} \Arg{int expr} \Arg{tl~var} \Arg{true code} \Arg{false code}
%   \end{syntax}
%   Removes the \meta{item} at position \meta{int expr} in the
%   \meta{sequence}, and places it in the \meta{token list variable}.
%   Items are indexed from $1$ on the left/top of the \meta{sequence},
%   or from $-1$ on the right/bottom.  If the position is zero or is
%   larger (in absolute value) than the number of items in the sequence,
%   the \meta{seq~var} is not modified, the \meta{token list} is set to
%   the special marker \cs{q_no_value}, and the \meta{false code} is
%   left in the input stream; otherwise the \meta{true code} is.  The
%   \meta{token list} assignment is local while the \meta{sequence} is
%   assigned locally for |pop| or globally for |gpop| functions.
% \end{function}
%
% \section{Additions to \pkg{l3tl}}
%
% \begin{function}[added = 2018-04-01]{\tl_build_begin:N, \tl_build_gbegin:N}
%   \begin{syntax}
%     \cs{tl_build_begin:N} \meta{tl~var}
%   \end{syntax}
%   Clears the \meta{tl~var} and sets it up to support other
%   \cs[no-index]{tl_build_\ldots{}} functions, which allow accumulating
%   large numbers of tokens piece by piece much more efficiently than
%   standard \pkg{l3tl} functions.  Until \cs{tl_build_end:N}
%   \meta{tl~var} is called, applying any function from \pkg{l3tl} other
%   than \cs[no-index]{tl_build_\ldots{}} will lead to incorrect
%   results.  The |begin| and |gbegin| functions must be used for local
%   and global \meta{tl~var} respectively.
% \end{function}
%
% \begin{function}[added = 2018-04-01]{\tl_build_clear:N, \tl_build_gclear:N}
%   \begin{syntax}
%     \cs{tl_build_clear:N} \meta{tl~var}
%   \end{syntax}
%   Clears the \meta{tl~var} and sets it up to support other
%   \cs[no-index]{tl_build_\ldots{}} functions.  The |clear| and
%   |gclear| functions must be used for local and global \meta{tl~var}
%   respectively.
% \end{function}
%
% \begin{function}[added = 2018-04-01]
%   {
%     \tl_build_put_left:Nn, \tl_build_put_left:Nx,
%     \tl_build_gput_left:Nn, \tl_build_gput_left:Nx,
%     \tl_build_put_right:Nn, \tl_build_put_right:Nx,
%     \tl_build_gput_right:Nn, \tl_build_gput_right:Nx,
%   }
%   \begin{syntax}
%     \cs{tl_build_put_left:Nn} \meta{tl~var} \Arg{tokens}
%     \cs{tl_build_put_right:Nn} \meta{tl~var} \Arg{tokens}
%   \end{syntax}
%   Adds \meta{tokens} to the left or right side of the current contents
%   of \meta{tl~var}.  The \meta{tl~var} must have been set up with
%   \cs{tl_build_begin:N} or \cs{tl_build_gbegin:N}.  The |put| and
%   |gput| functions must be used for local and global \meta{tl~var}
%   respectively.  The |right| functions are about twice faster than the
%   |left| functions.
% \end{function}
%
% \begin{function}[added = 2018-04-01]{\tl_build_get:NN}
%   \begin{syntax}
%     \cs{tl_build_get:NN} \meta{tl~var_1} \meta{tl~var_2}
%   \end{syntax}
%   Stores the contents of the \meta{tl~var_1} in the \meta{tl~var_2}.
%   The \meta{tl~var_1} must have been set up with \cs{tl_build_begin:N}
%   or \cs{tl_build_gbegin:N}.  The \meta{tl~var_2} is a
%   \enquote{normal} token list variable, assigned locally using
%   \cs{tl_set:Nn}.
% \end{function}
%
% \begin{function}[added = 2018-04-01]{\tl_build_end:N, \tl_build_gend:N}
%   \begin{syntax}
%     \cs{tl_build_end:N} \meta{tl~var}
%   \end{syntax}
%   Gets the contents of \meta{tl~var} and stores that into the
%   \meta{tl~var} using \cs{tl_set:Nn} or \cs{tl_gset:Nn}.
%   The \meta{tl~var} must have
%   been set up with \cs{tl_build_begin:N} or \cs{tl_build_gbegin:N}.
%   The |end| and |gend| functions must be used for local and global
%   \meta{tl~var} respectively.  These functions completely remove the
%   setup code that enabled \meta{tl~var} to be used for other
%   \cs[no-index]{tl_build_\ldots{}} functions.
% \end{function}
%
% \end{documentation}
%
% \begin{implementation}
%
% \section{\pkg{l3candidates} implementation}
%
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
% \subsection{Additions to \pkg{l3seq}}
%
%    \begin{macrocode}
%<@@=seq>
%    \end{macrocode}
%
% \begin{macro}
%   {
%     \seq_mapthread_function:NNN, \seq_mapthread_function:NcN,
%     \seq_mapthread_function:cNN, \seq_mapthread_function:ccN
%   }
% \begin{macro}
%   {
%     \@@_mapthread_function:wNN, \@@_mapthread_function:wNw,
%     \@@_mapthread_function:Nnnwnn
%   }
%   The idea is to first expand both sequences, adding the
%   usual |{ ? \prg_break: } { }| to the end of each one.  This is
%   most conveniently done in two steps using an auxiliary function.
%   The mapping then throws away the first tokens of |#2| and |#5|,
%   which for items in both sequences are \cs{s_@@}
%   \cs{@@_item:n}.  The function to be mapped are then be applied to
%   the two entries.  When the code hits the end of one of the
%   sequences, the break material stops the entire loop and tidy up.
%   This avoids needing to find the count of the two sequences, or
%   worrying about which is longer.
%    \begin{macrocode}
\cs_new:Npn \seq_mapthread_function:NNN #1#2#3
  { \exp_after:wN \@@_mapthread_function:wNN #2 \s_@@_stop #1 #3 }
\cs_new:Npn \@@_mapthread_function:wNN \s_@@ #1 \s_@@_stop #2#3
  {
    \exp_after:wN \@@_mapthread_function:wNw #2 \s_@@_stop #3
      #1 { ? \prg_break: } { }
    \prg_break_point:
  }
\cs_new:Npn \@@_mapthread_function:wNw \s_@@ #1 \s_@@_stop #2
  {
    \@@_mapthread_function:Nnnwnn #2
      #1 { ? \prg_break: } { }
    \s_@@_stop
  }
\cs_new:Npn \@@_mapthread_function:Nnnwnn #1#2#3#4 \s_@@_stop #5#6
  {
    \use_none:n #2
    \use_none:n #5
    #1 {#3} {#6}
    \@@_mapthread_function:Nnnwnn #1 #4 \s_@@_stop
  }
\cs_generate_variant:Nn \seq_mapthread_function:NNN { Nc , c , cc }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\seq_set_filter:NNn, \seq_gset_filter:NNn}
% \begin{macro}{\@@_set_filter:NNNn}
%   Similar to \cs{seq_map_inline:Nn}, without a
%   \cs{prg_break_point:} because the user's code
%   is performed within the evaluation of a boolean expression,
%   and skipping out of that would break horribly.
%   The \cs{@@_wrap_item:n} function inserts the relevant
%   \cs{@@_item:n} without expansion in the input stream,
%   hence in the \texttt{x}-expanding assignment.
%    \begin{macrocode}
\cs_new_protected:Npn \seq_set_filter:NNn
  { \@@_set_filter:NNNn \__kernel_tl_set:Nx }
\cs_new_protected:Npn \seq_gset_filter:NNn
  { \@@_set_filter:NNNn \__kernel_tl_gset:Nx }
\cs_new_protected:Npn \@@_set_filter:NNNn #1#2#3#4
  {
    \@@_push_item_def:n { \bool_if:nT {#4} { \@@_wrap_item:n {##1} } }
    #1 #2 { #3 }
    \@@_pop_item_def:
  }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\@@_int_eval:w}
%   Useful to more quickly go through items.
%    \begin{macrocode}
\cs_new_eq:NN \@@_int_eval:w \tex_numexpr:D
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[noTF]{\seq_set_item:Nnn, \seq_set_item:cnn, \seq_gset_item:Nnn, \seq_gset_item:cnn}
% \begin{macro}{\@@_set_item:NnnNN, \@@_set_item:nnNNNN, \@@_set_item_false:nnNNNN, \@@_set_item:nNnnNNNN}
% \begin{macro}[rEXP]{\@@_set_item:wn, \@@_set_item_end:w}
%   The conditionals are distinguished from the |Nnn| versions by the
%   last argument \cs{use_ii:nn} vs \cs{use_i:nn}.
%    \begin{macrocode}
\cs_new_protected:Npn \seq_set_item:Nnn #1#2#3
  { \@@_set_item:NnnNN #1 {#2} {#3} \__kernel_tl_set:Nx \use_i:nn }
\cs_new_protected:Npn \seq_gset_item:Nnn #1#2#3
  { \@@_set_item:NnnNN #1 {#2} {#3} \__kernel_tl_gset:Nx \use_i:nn }
\cs_generate_variant:Nn \seq_set_item:Nnn { c }
\cs_generate_variant:Nn \seq_gset_item:Nnn { c }
\prg_new_protected_conditional:Npnn \seq_set_item:Nnn #1#2#3 { TF , T , F }
  { \@@_set_item:NnnNN #1 {#2} {#3} \__kernel_tl_set:Nx \use_ii:nn }
\prg_new_protected_conditional:Npnn \seq_gset_item:Nnn #1#2#3 { TF , T , F }
  { \@@_set_item:NnnNN #1 {#2} {#3} \__kernel_tl_gset:Nx \use_ii:nn }
\prg_generate_conditional_variant:Nnn \seq_set_item:Nnn { c } { TF , T , F }
\prg_generate_conditional_variant:Nnn \seq_gset_item:Nnn { c } { TF , T , F }
%    \end{macrocode}
%   Save the item to be stored and evaluate the position and the sequence
%   length only once.  Then depending on the sign of the position, check
%   that it is not bigger than the length (in absolute value) nor zero.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_set_item:NnnNN #1#2#3
  {
    \tl_set:Nn \l_@@_internal_a_tl { \@@_item:n {#3} }
    \exp_args:Nff \@@_set_item:nnNNNN
      { \int_eval:n {#2} } { \seq_count:N #1 } #1 \use_none:nn
  }
\cs_new_protected:Npn \@@_set_item:nnNNNN #1#2
  {
    \int_compare:nNnTF {#1} > 0
      { \int_compare:nNnF {#1} > {#2} { \@@_set_item:nNnnNNNN { #1 - 1 } } }
      {
        \int_compare:nNnF {#1} < {-#2}
          {
            \int_compare:nNnF {#1} = 0
              { \@@_set_item:nNnnNNNN { #2 + #1 } }
          }
      }
    \@@_set_item_false:nnNNNN {#1} {#2}
  }
%    \end{macrocode}
%   If the position is not ok, \cs{@@_set_item_false:nnNNNN} calls an
%   error or returns \texttt{false} (depending on the \cs{use_i:nn} vs
%   \cs{use_ii:nn} argument mentioned above).
%    \begin{macrocode}
\cs_new_protected:Npn \@@_set_item_false:nnNNNN #1#2#3#4#5#6
  {
    #6
      {
        \msg_error:nnxxx { seq } { item-too-large }
          { \token_to_str:N #3 } {#2} {#1}
      }
      { \prg_return_false: }
  }
\msg_new:nnnn { seq } { item-too-large }
  { Sequence~'#1'~does~not~have~an~item~#3 }
  {
    An~attempt~was~made~to~push~or~pop~the~item~at~position~#3~
    of~'#1',~but~this~
    \int_compare:nTF { #3 = 0 }
      { position~does~not~exist. }
      { sequence~only~has~#2~item \int_compare:nF { #2 = 1 } {s}. }
  }
%    \end{macrocode}
%   If the position is ok, \cs{@@_set_item:nNnnNNNN} makes the assignment
%   and returns \texttt{true} (in the case of conditionnals).  Here |#1|
%   is an integer expression (position minus one), it needs to be
%   evaluated.  The sequence |#5| starts with \cs{s_@@} (even if empty),
%   which stops the integer expression and is absorbed by it.  The
%   \cs{if_meaning:w} test is slightly faster than an integer test (but
%   only works when testing against zero, hence the offset we chose in
%   the position).  When we are done skipping items, insert the saved
%   item \cs{l_@@_internal_a_tl}.  For |put| functions the last argument
%   of \cs{@@_set_item_end:w} is \cs{use_none:nn} and it absorbs the
%   item |#2| that we are removing: this is only useful for the |pop|
%   functions.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_set_item:nNnnNNNN #1#2#3#4#5#6#7#8
  {
    #7 #5
      {
        \s_@@
        \exp_after:wN \@@_set_item:wn
        \int_value:w \@@_int_eval:w #1
        #5 \s_@@_stop #6
      }
    #8 { } { \prg_return_true: }
  }
\cs_new:Npn \@@_set_item:wn #1 \@@_item:n #2
  {
    \if_meaning:w 0 #1 \@@_set_item_end:w \fi:
    \exp_not:n { \@@_item:n {#2} }
    \exp_after:wN \@@_set_item:wn
    \int_value:w \@@_int_eval:w #1 - 1 \s_@@
  }
\cs_new:Npn \@@_set_item_end:w #1 \exp_not:n #2 #3 \s_@@ #4 \s_@@_stop #5
  {
    #1
    \exp_not:o \l_@@_internal_a_tl
    \exp_not:n {#4}
    #5 #2
  }
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}[noTF]{\seq_pop_item:NnN, \seq_pop_item:cnN, \seq_gpop_item:NnN, \seq_gpop_item:cnN}
% \begin{macro}{\@@_pop_item:NnNNN}
%   The |NnN| versions simply call the conditionals, for which we will
%   rely on the internals of \cs{seq_set_item:Nnn}.
%    \begin{macrocode}
\cs_new_protected:Npn \seq_pop_item:NnN #1#2#3
  { \seq_pop_item:NnNTF #1 {#2} #3 { } { } }
\cs_new_protected:Npn \seq_gpop_item:NnN #1#2#3
  { \seq_gpop_item:NnNTF #1 {#2} #3 { } { } }
\cs_generate_variant:Nn \seq_pop_item:NnN { c }
\cs_generate_variant:Nn \seq_gpop_item:NnN { c }
\prg_new_protected_conditional:Npnn \seq_pop_item:NnN #1#2#3 { TF , T , F }
  { \@@_pop_item:NnNN #1 {#2} #3 \__kernel_tl_set:Nx }
\prg_new_protected_conditional:Npnn \seq_gpop_item:NnN #1#2#3 { TF , T , F }
  { \@@_pop_item:NnNN #1 {#2} #3 \__kernel_tl_gset:Nx }
\prg_generate_conditional_variant:Nnn \seq_pop_item:NnN { c } { TF , T , F }
\prg_generate_conditional_variant:Nnn \seq_gpop_item:NnN { c } { TF , T , F }
%    \end{macrocode}
%   Save in \cs{l_@@_internal_b_tl} the token list variable |#3| in
%   which we will store the item.  The \cs{@@_set_item:nnNNNN} auxiliary
%   eventually inserts \cs{l_@@_internal_a_tl} in place of the item
%   found in the sequence, so we empty that.  Instead of the last
%   argument \cs{use_i:nn} or \cs{use_ii:nn} used for |put| functions,
%   we introduce \cs{@@_pop_item:nn}, which stores \cs{q_no_value}
%   before calling its second argument
%   (\cs{prg_return_true:}/\texttt{false:}) to end the conditional.  The
%   item found is passed to \cs{@@_pop_item_aux:w}, which interrupts the
%   |x|-expanding sequence assignment and stores the item using the
%   assignment function in \cs{l_@@_internal_b_tl}.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_pop_item:NnNN #1#2#3#4
  {
    \tl_clear:N \l_@@_internal_a_tl
    \tl_set:Nn \l_@@_internal_b_tl { \__kernel_tl_set:Nx #3 }
    \exp_args:Nff \@@_set_item:nnNNNN
      { \int_eval:n {#2} } { \seq_count:N #1 }
      #1 \@@_pop_item_aux:w #4 \@@_pop_item:nn
  }
\cs_new_protected:Npn \@@_pop_item:nn #1#2
  {
    \if_meaning:w \prg_return_false: #2
      \l_@@_internal_b_tl { \exp_not:N \q_no_value }
    \fi:
    #2
  }
\cs_new:Npn \@@_pop_item_aux:w \@@_item:n #1
  {
    \if_false: { \fi: }
    \l_@@_internal_b_tl { \if_false: } \fi: \exp_not:n {#1}
  }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \subsection{Additions to \pkg{l3tl}}
%
% \subsubsection{Building a token list}
%
%    \begin{macrocode}
%<@@=tl>
%    \end{macrocode}
%
% Between \cs{tl_build_begin:N} \meta{tl~var} and \cs{tl_build_end:N}
% \meta{tl~var}, the \meta{tl~var} has the structure
% \begin{quote}
%   \cs{exp_end:} \ldots{} \cs{exp_end:} \cs{@@_build_last:NNn}
%   \meta{assignment} \meta{next~tl} \Arg{left} \meta{right}
% \end{quote}
% where \meta{right} is not braced.  The \enquote{data} it represents is
% \meta{left} followed by the \enquote{data} of \meta{next~tl} followed
% by \meta{right}.  The \meta{next~tl} is a token list variable whose
% name is that of \meta{tl~var} followed by~|'|.  There are between $0$
% and $4$ \cs{exp_end:} to keep track of when \meta{left} and
% \meta{right} should be put into the \meta{next~tl}.  The
% \meta{assignment} is \cs{cs_set_nopar:Npx} if the variable is local,
% and \cs{cs_gset_nopar:Npx} if it is global.
%
% \begin{macro}{\tl_build_begin:N, \tl_build_gbegin:N}
% \begin{macro}{\@@_build_begin:NN, \@@_build_begin:NNN}
%   First construct the \meta{next~tl}: using a prime here conflicts
%   with the usual \pkg{expl3} convention but we need a name that can be
%   derived from |#1| without any external data such as a counter.
%   Empty that \meta{next~tl} and setup the structure.  The local and
%   global versions only differ by a single function
%   \cs[no-index]{cs_(g)set_nopar:Npx} used for all assignments: this is
%   important because only that function is stored in the \meta{tl~var}
%   and \meta{next~tl} for subsequent assignments.  In principle
%   \cs{@@_build_begin:NNN} could use \cs[no-index]{tl_(g)clear_new:N}
%   to empty |#1| and make sure it is defined, but logging the
%   definition does not seem useful so we just do |#3| |#1| |{}| to
%   clear it locally or globally as appropriate.
%    \begin{macrocode}
\cs_new_protected:Npn \tl_build_begin:N #1
  { \@@_build_begin:NN \cs_set_nopar:Npx #1 }
\cs_new_protected:Npn \tl_build_gbegin:N #1
  { \@@_build_begin:NN \cs_gset_nopar:Npx #1 }
\cs_new_protected:Npn \@@_build_begin:NN #1#2
  { \exp_args:Nc \@@_build_begin:NNN { \cs_to_str:N #2 ' } #2 #1 }
\cs_new_protected:Npn \@@_build_begin:NNN #1#2#3
  {
    #3 #1 { }
    #3 #2
      {
        \exp_not:n { \exp_end: \exp_end: \exp_end: \exp_end: }
        \exp_not:n { \@@_build_last:NNn #3 #1 { } }
      }
  }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\tl_build_clear:N, \tl_build_gclear:N}
%   The |begin| and |gbegin| functions already clear enough to make the
%   token list variable effectively empty.  Eventually the |begin| and
%   |gbegin| functions should check that |#1'| is empty or undefined,
%   while the |clear| and |gclear| functions ought to empty |#1'|,
%   |#1''| and so on, similar to \cs{tl_build_end:N}.  This only affects
%   memory usage.
%    \begin{macrocode}
\cs_new_eq:NN \tl_build_clear:N \tl_build_begin:N
\cs_new_eq:NN \tl_build_gclear:N \tl_build_gbegin:N
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}
%   {
%     \tl_build_put_right:Nn, \tl_build_put_right:Nx,
%     \tl_build_gput_right:Nn, \tl_build_gput_right:Nx,
%     \@@_build_last:NNn, \@@_build_put:nn, \@@_build_put:nw
%   }
%   Similar to \cs{tl_put_right:Nn}, but apply \cs{exp:w} to |#1|.  Most
%   of the time this just removes one \cs{exp_end:}.  When there are
%   none left, \cs{@@_build_last:NNn} is expanded instead.  It resets
%   the definition of the \meta{tl~var} by ending the \cs{exp_not:n} and
%   the definition early.  Then it makes sure the \meta{next~tl} (its
%   argument |#1|) is set-up and starts a new definition.  Then
%   \cs{@@_build_put:nn} and \cs{@@_build_put:nw} place the \meta{left}
%   part of the original \meta{tl~var} as appropriate for the definition
%   of the \meta{next~tl} (the \meta{right} part is left in the right
%   place without ever becoming a macro argument).  We use
%   \cs{exp_after:wN} rather than some \cs{exp_args:No} to avoid reading
%   arguments that are likely very long token lists.  We use
%   \cs[no-index]{cs_(g)set_nopar:Npx} rather than
%   \cs[no-index]{tl_(g)set:Nx} partly for the same reason and partly
%   because the assignments are interrupted by brace tricks, which
%   implies that the assignment does not simply set the token list to an
%   |x|-expansion of the second argument.
%    \begin{macrocode}
\cs_new_protected:Npn \tl_build_put_right:Nn #1#2
  {
    \cs_set_nopar:Npx #1
      { \exp_after:wN \exp_not:n \exp_after:wN { \exp:w #1 #2 } }
  }
\cs_new_protected:Npn \tl_build_put_right:Nx #1#2
  {
    \cs_set_nopar:Npx #1
      { \exp_after:wN \exp_not:n \exp_after:wN { \exp:w #1 } #2 }
  }
\cs_new_protected:Npn \tl_build_gput_right:Nn #1#2
  {
    \cs_gset_nopar:Npx #1
      { \exp_after:wN \exp_not:n \exp_after:wN { \exp:w #1 #2 } }
  }
\cs_new_protected:Npn \tl_build_gput_right:Nx #1#2
  {
    \cs_gset_nopar:Npx #1
      { \exp_after:wN \exp_not:n \exp_after:wN { \exp:w #1 } #2 }
  }
\cs_new_protected:Npn \@@_build_last:NNn #1#2
  {
    \if_false: { { \fi:
          \exp_end: \exp_end: \exp_end: \exp_end: \exp_end:
          \@@_build_last:NNn #1 #2 { }
        }
      }
    \if_meaning:w \c_empty_tl #2
      \@@_build_begin:NN #1 #2
    \fi:
    #1 #2
      {
        \exp_after:wN \exp_not:n \exp_after:wN
          {
            \exp:w \if_false: } } \fi:
            \exp_after:wN \@@_build_put:nn \exp_after:wN {#2}
  }
\cs_new_protected:Npn \@@_build_put:nn #1#2 { \@@_build_put:nw {#2} #1 }
\cs_new_protected:Npn \@@_build_put:nw #1#2 \@@_build_last:NNn #3#4#5
  { #2 \@@_build_last:NNn #3 #4 { #1 #5 } }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}
%   {
%     \tl_build_put_left:Nn, \tl_build_put_left:Nx,
%     \tl_build_gput_left:Nn, \tl_build_gput_left:Nx, \@@_build_put_left:NNn
%   }
%   See \cs{tl_build_put_right:Nn} for all the machinery.  We could
%   easily provide \cs[no-index]{tl_build_put_left_right:Nnn}, by just
%   add the \meta{right} material after the \Arg{left} in the
%   |x|-expanding assignment.
%    \begin{macrocode}
\cs_new_protected:Npn \tl_build_put_left:Nn #1
  { \@@_build_put_left:NNn \cs_set_nopar:Npx #1 }
\cs_generate_variant:Nn \tl_build_put_left:Nn { Nx }
\cs_new_protected:Npn \tl_build_gput_left:Nn #1
  { \@@_build_put_left:NNn \cs_gset_nopar:Npx #1 }
\cs_generate_variant:Nn \tl_build_gput_left:Nn { Nx }
\cs_new_protected:Npn \@@_build_put_left:NNn #1#2#3
  {
    #1 #2
      {
        \exp_after:wN \exp_not:n \exp_after:wN
          {
            \exp:w \exp_after:wN \@@_build_put:nn
              \exp_after:wN {#2} {#3}
          }
      }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\tl_build_get:NN}
% \begin{macro}{\@@_build_get:NNN, \@@_build_get:w, \@@_build_get_end:w}
%   The idea is to expand the \meta{tl~var} then the \meta{next~tl} and
%   so on, all within an |x|-expanding assignment, and wrap as
%   appropriate in \cs{exp_not:n}.  The various \meta{left} parts are
%   left in the assignment as we go, which enables us to expand the
%   \meta{next~tl} at the right place.  The various \meta{right} parts
%   are eventually picked up in one last \cs{exp_not:n}, with a brace
%   trick to wrap all the \meta{right} parts together.
%    \begin{macrocode}
\cs_new_protected:Npn \tl_build_get:NN
  { \@@_build_get:NNN \__kernel_tl_set:Nx }
\cs_new_protected:Npn \@@_build_get:NNN #1#2#3
  { #1 #3 { \if_false: { \fi: \exp_after:wN \@@_build_get:w #2 } } }
\cs_new:Npn \@@_build_get:w #1 \@@_build_last:NNn #2#3#4
  {
    \exp_not:n {#4}
    \if_meaning:w \c_empty_tl #3
      \exp_after:wN \@@_build_get_end:w
    \fi:
    \exp_after:wN \@@_build_get:w #3
  }
\cs_new:Npn \@@_build_get_end:w #1#2#3
  { \exp_after:wN \exp_not:n \exp_after:wN { \if_false: } \fi: }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\tl_build_end:N, \tl_build_gend:N, \@@_build_end_loop:NN}
%   Get the data then clear the \meta{next~tl} recursively until finding
%   an empty one.  It is perhaps wasteful to repeatedly use
%   \cs{cs_to_str:N}.  The local/global scope is checked by
%   \cs{tl_set:Nx} or \cs{tl_gset:Nx}.
%    \begin{macrocode}
\cs_new_protected:Npn \tl_build_end:N #1
  {
    \@@_build_get:NNN \__kernel_tl_set:Nx #1 #1
    \exp_args:Nc \@@_build_end_loop:NN { \cs_to_str:N #1 ' } \tl_clear:N
  }
\cs_new_protected:Npn \tl_build_gend:N #1
  {
    \@@_build_get:NNN \__kernel_tl_gset:Nx #1 #1
    \exp_args:Nc \@@_build_end_loop:NN { \cs_to_str:N #1 ' } \tl_gclear:N
  }
\cs_new_protected:Npn \@@_build_end_loop:NN #1#2
  {
    \if_meaning:w \c_empty_tl #1
      \exp_after:wN \use_none:nnnnnn
    \fi:
    #2 #1
    \exp_args:Nc \@@_build_end_loop:NN { \cs_to_str:N #1 ' } #2
  }
%    \end{macrocode}
% \end{macro}
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \end{implementation}
%
% \PrintIndex