summaryrefslogtreecommitdiff
path: root/macros/generic/expkv-bundle/pkg-cs.tex
blob: 850b9af62053d879542653cd7eec70b677d394cd (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
\genericekv\expkvc{-cs}

\expkvc\ aids in creating fully expandable macros that take a \kv\ argument. It
implements somewhat efficient solutions to expandable \kv\ parsing without the
user having to worry too much about the details.

The package supports two main approaches for this. The first is splitting the
keys up into individual arguments, the second preparses the \kv\ list into a
single argument in which accessing the value of individual keys is fast. The
behaviour of the second type is similar to a hash table, so we call that variant
|Hash|, the first type is called |Split|. Both these variants support a number
of so called \emph{primary keys} (a primary key matches an argument, roughly
speaking).

In addition to these methods there is a structured way to define additional keys
which might build upon the primary keys but not directly relate to an argument.
These keys are called \emph{secondary keys}. Primary and secondary keys belong
to a specific macro (the macro name serves as the \emph{set}).

A word of advice you should consider: Macros defined with \expkvc\ are simple to
create, and there might be good use cases for them (for instance since they
don't work by assignments but only by argument forwarding logic they have no
issues with implicit or explicit groups whatsoever). But they don't scale as
well as established \kv\ interfaces (think of the idiomatic key definitions with
\pkg{keyval}, or \pkg{l3keys}, or \expkv\ with or without \expkvd), and they are
slower than idiomatic key definitions in packages with fast \kv\ parsing.


\subsection{Defining Macros and Primary Keys}

All macros defined with \expkvc\ have to be previously undefined (or have the
|\meaning| of |\relax|). There is no way to automatically undefine keys once
they are set up -- so to make sure there are no conflicts only new definitions
are allowed. The \emph{set} name (as used by \cs[no-index]{ekvset}) will be
\cs[no-index]{string}\cs[no-index]{\meta{macro}}.


\subsubsection{Primary Keys\label{sec:c:primary}}

The notion of primary keys needs a bit of explanation, or better, the input
syntax for the argument \meta{primary keys} in the following explanations. The
\meta{primary keys} argument should be a \kv\ list in which each \key\ will be
one primary key and \val\ the initial value of said \key\ (and that value is
mandatory, even if you leave it blank that's fine, but you have to explicitly
state it). By default all keys are defined short, but you can define |\long|
keys by prefixing \key\ with |long| (\emph{e.g.},
|long name=Jonathan P. Spratte| to define a |\long| key called |name|). Due to
some internal implementations it's worth noting that |\long| keys are a
microscopic grain faster. The \meta{cs} will only be defined |\long| if at least
one of the keys was |\long|. For obvious reasons there is no interface in place
to define something as |\protected|.

To allow keys to start with the word |long| even if you don't want them to be
|\long| you can also prefix them with |short|. The first found prefix of the two
will stop the parsing for prefixes and what remains becomes the \key.

These rules culminate in the following:

\begin{enverb}[no-tcb]
  \ekvcSplit\foo
    {
       long short = abc\par
      ,short long = def
    }
    {#1#2}
\end{enverb}
will define a macro |\foo| that knows two primary keys, |short| which is defined
|\long| (so will accept explicit |\par| tokens inside its value at use time),
and |long| which doesn't accept explicit |\par| tokens (leading to a low level
\TeX\ error). The description of |\ekvcSplit| follows shortly.

There is one exception to the rule that each \key\ in \meta{primary keys} needs
to get a value: If you include a key named |...| without a value this will be a
primary key in which every unknown key will be collected -- and \meta{cs} will
be defined |\long|. The unknown keys will be stored in a way that \emph{most}
\kv\ parsers will parse them correctly (but this is no general guarantee, for
instance \pkg{pgfkeys} can accidentally strip multiple sets of braces at the
wrong moment). See some examples in \autoref{sec:c:unknown}.

At the moment \expkvc\ doesn't require any internal keys, but I can't foresee
whether this will be the case in the future as well, as it might turn out that
some features I deem useful can't be implemented without such internal keys.
Because of this, please don't use key names starting with "EKVC|" as that
should be the private name space.


\subsubsection{Split\label{sec:c:split}}

The split variants will provide the key values as separate arguments. This
limits the number of keys for which this is truly useful.

\begin{function}{\ekvcSplit}
  \begin{syntax}
    \cs{ekvcSplit}\meta{cs}\marg{primary keys}\marg{definition}
  \end{syntax}
  This defines \meta{cs} to be a macro taking one mandatory argument which
  should contain a \kv\ list. The \meta{primary keys} will be defined for this
  macro (see \autoref{sec:c:primary}). The \meta{definition} is the code that
  will be executed. You can access the \val\ of a \key\ by using a macro
  parameter from |#1| to |#9|. The order of the macro parameters will be the
  order provided in the \meta{primary keys} list (so |#1| is the \val\ of the
  \key\ defined first). With \cs{ekvcSplit} you can define macros using at most
  nine primary keys.
\end{function}
\begin{example}{Simple macro with \cs[no-index]{ekvcSplit}}
  The following defines a macro |\foo| that takes the keys |a| and |b|
  and outputs their values in a textual form:
  \begin{enverb}
    \ekvcSplit\foo{a=a,b=b}{a is #1.\par b is #2.\par}
    \foo{}
    \foo{b=e}
  \end{enverb}
\end{example}

\begin{function}{\ekvcSplitAndForward}
  \begin{syntax}
    \cs{ekvcSplitAndForward}\meta{cs}\marg{after}\marg{primary keys}
  \end{syntax}
  This defines \meta{cs} to be a macro taking one mandatory argument which
  should contain a \kv\ list. You can use as many primary keys as you want with
  this. The primary keys will be forwarded to \meta{after} as braced arguments
  (as many as necessary for your primary keys). The order of the braced
  arguments will be the order of your primary key definitions. In \meta{after}
  you can use just a single control sequence, or some arbitrary stuff which will
  be left in the input stream before your braced values (with one set of braces
  stripped from \meta{after}), so both of the following would be fine:
  \begin{enverb}[no-tcb]
    \ekvcSplitAndForward\foo\foo@aux{keyA = A, keyB = B}
    \ekvcSplitAndForward\foo{\foo@aux{more args}}{keyA = A, keyB = B}
  \end{enverb}
\end{function}
\noindent
In the first case |\foo@aux| should take at least two arguments (|keyA| and
|keyB|), in the second case at least three (|more args|, |keyA|, and |keyB|).

\begin{function}{\ekvcSplitAndUse}
  \begin{syntax}
    \cs{ekvcSplitAndUse}\meta{cs}\marg{primary keys}
  \end{syntax}
  This will roughly do the same as \cs{ekvcSplitAndForward}, but instead of
  specifying what will be used after splitting the keys, \meta{cs} will use what
  follows the \kv\ list. So its syntax will be
\end{function}
\begin{quote}
  \ttfamily
  \meta{cs}\kvarg\marg{after}
\end{quote}
and the code in |after| should expect at least as many arguments as the number
of keys defined for \meta{cs}.


\subsubsection{Hash\label{sec:c:hash}}

The hash variants will provide the key values as a single argument in which you
can access specific values using a special macro. The implementation might be
more convenient and scale better, \emph{but} it is slower (for a rudimentary
macro with a single key benchmarking was almost 1.7~times slower, the root of
which being the key access with \cs{ekvcValue}, not the parsing, and for a key
access using \cs{ekvcValueFast} it was still about 1.2~times slower). Still to
be future proof, considering the hash variants is a good idea, and to get best
performance but less maintainable code you can resort to the split approach.

\begin{function}{\ekvcHash}
  \begin{syntax}
    \cs{ekvcHash}\meta{cs}\marg{primary keys}\marg{definition}
  \end{syntax}
  This defines \meta{cs} to be a macro taking one mandatory argument which
  should contain a \kv\ list. You can use as many primary keys as you want. The
  primary keys will be forwarded as a single argument containing every key to
  the underlying macro. The underlying macro is defined as \meta{definition}, in
  which you can access the \val\ of a \key\ by using
  \cs{ekvcValue}\marg{key}|{#1}| (or similar).
\end{function}
\begin{example}{Simple macro with \cs[no-index]{ekvcHash}}
  This defines an equivalent macro to the |\foo| defined with \cs{ekvcSplit}
  earlier:
  \begin{enverb}
    \ekvcHash\foo{a=a,b=b}{a is \ekvcValue{a}{#1}.\par
                           b is \ekvcValue{b}{#1}.\par}
    \foo{}
    \foo{b=e}
  \end{enverb}
\end{example}

\begin{function}{\ekvcHashAndForward}
  \begin{syntax}
    \cs{ekvcHashAndForward}\meta{cs}\marg{after}\marg{primary keys}
  \end{syntax}
  This defines \meta{cs} to be a macro taking one mandatory argument which
  should contain a \kv\ list. You can use as many primary keys as you want. The
  primary keys will be forwarded as a single argument containing every key to
  \meta{after}. You can use a single macro for \meta{after} or use some
  arbitrary stuff, which will be left in the input stream before the hashed \kv\
  list with one set of braces stripped. In the macro called in \meta{after} you
  can access the \val\ of a \key\ by using \cs{ekvcValue}\marg{key}|{#1}| (or
  whichever argument the hashed \kv\ list will be in).
\end{function}
\begin{example}{Using \cs[no-index]{ekvcHashAndForward}}
  This defines a macro |\foo| processing two keys, and passing the result to
  |\foobar|:
  \begin{enverb}
    \ekvcHashAndForward\foo\foobar{a=a,b=b}
    \newcommand*\foobar[1]{a is \ekvcValue{a}{#1}.\par
                           b is \ekvcValue{b}{#1}.\par}
    \foo{}
    \foo{b=e}
  \end{enverb}
\end{example}

\begin{function}{\ekvcHashAndUse}
  \begin{syntax}
    \cs{ekvcHashAndUse}\meta{cs}\marg{primary keys}
  \end{syntax}
  This will roughly do the same as \cs{ekvcHashAndForward}, but instead of
  specifying what will be used after hashing the keys during the definition,
  \meta{cs} will use what follows the \kv\ list. So its syntax will be
  \begin{quote}
    \ttfamily
    \meta{cs}\kvarg\marg{after}
  \end{quote}
\end{function}

\begin{function}{\ekvcValue}
  \begin{syntax}
    \cs{ekvcValue}\marg{key}\marg{key list}
  \end{syntax}
  This is a safe way to access your keys in a hash variant. \key\ is the key
  which's \val\ you want to use out of the \meta{key list}. \meta{key list}
  should be the key list argument forwarded to your underlying macro by
  \cs{ekvcHash}, \cs{ekvcHashAndForward}, or \cs{ekvcHashAndUse}. It will be
  tested whether the hash function to access that \key\ exists, the \key\
  argument is not empty, and that the \meta{key list} really contains a \val\ of
  that \key. This macro needs exactly two steps of expansion and if used inside
  of an |\edef| or |\expanded| context will protect the \val\ from further
  expanding.
\end{function}

\begin{function}{\ekvcValueFast}
  \begin{syntax}
    \cs{ekvcValueFast}\marg{key}\marg{key list}
  \end{syntax}
  This behaves similar to \cs{ekvcValue}, but \emph{without any} safefy tests.
  As a result this is about 1.4~times faster \emph{but} will throw low level
  \TeX\ errors eventually if the hash function isn't defined or the \key\ isn't
  part of the \meta{key list} (\emph{e.g.}, because it was defined as a key for
  another macro -- all macros share the same hash function per \meta{key} name).
  Note that this will not only throw low level errors but result in undefined
  behaviour as well! This macro needs exactly three steps of expansion in the
  no-error case.
\end{function}

\begin{function}{\ekvcValueSplit}
  \begin{syntax}
    \cs{ekvcValueSplit}\marg{key}\marg{key list}\marg{next}
  \end{syntax}
  If you need a specific \key\ from a \meta{key list} more than once, it'll be a
  good idea to only extract it once and from then on keep it as a separate
  argument (or if you want to forward this value to another macro). Hence the
  macro \cs{ekvcValueSplit} will extract one specific \key's \val\ from the list
  and forward it as an argument to \meta{next}, so the result of this will be
  \meta{next}\marg{value}. This is roughly as fast as \cs{ekvcValue} and runs
  the same tests.
\end{function}
\begin{example}
    {Splitting of a key from a hash list using \cs[no-index]{ekvcValueSplit}}
  The following defines a macro |\foo| which will take three keys. Since the
  next parsing step will need the value of one of the keys multiple times we
  split that key off the list (in this example the next step doesn't use the key
  multiple times for simplicity though), and the entire list is forwarded as the
  second argument:
  \begin{enverb}
    \ekvcHash\foo{a=a,b=b,c=c}
      {\ekvcValueSplit{a}{#1}\foobar{#1}}
    \newcommand*\foobar[2]{a is #1.\par
                           b is \ekvcValue{b}{#2}.\par
                           c is \ekvcValue{c}{#2}.\par}
    \foo{}
  \end{enverb}
\end{example}

\begin{function}{\ekvcValueSplitFast}
  \begin{syntax}
    \cs{ekvcValueSplitFast}\marg{key}\marg{key list}\marg{next}
  \end{syntax}
  This behaves just like \cs{ekvcValueSplit}, but it won't run the safety tests,
  hence it is faster but more error prone, just like the relation between
  \cs{ekvcValue} and \cs{ekvcValueFast}.
\end{function}


\subsection{Secondary Keys\label{sec:c:secondary}}

To lift some limitations of each primary key matching one argument or hash
entry, you can define secondary keys. Those have to be defined for each macro
individually but it doesn't matter whether that macro was set up as a split or
hash variant.

Secondary keys can have a \prefix\ (|long|), and must have a \type\
(like |meta|). Some \types\ might require some \prefix\ while other
\types\ might forbid the usage of a specific \prefix.

Please keep in mind that key names shouldn't start with "EKVC|".

\begin{function}{\ekvcSecondaryKeys}
  \begin{syntax}
    \cs{ekvcSecondaryKeys}\meta{cs}\kvarg
  \end{syntax}
  This is the front facing macro to define secondary keys. For the macro
  \meta{cs} define \key\ to have definition \val. The general syntax for \key\
  should be
  \begin{quote}\ttfamily
    \meta{prefix} \meta{name}
  \end{quote}
  Where \meta{prefix} is a space separated list of optional \prefixes\
  followed by one \type. The syntax of \meta{value} is dependent on the
  used \type.
\end{function}


\subsubsection{\textit{Prefixes}}

Currently there is only one \prefix\ available, which is
\begin{function}[module=expkv-cs prefix]{long}
  The following key will be defined |\long|.
\end{function}


\subsubsection{\textit{Types}\label{sec:c:secondarytypes}}

Compared to \expkvd\ you might notice that the \types\ here are much fewer.
Unfortunately the expansion only concept doesn't allow for great variety in the
common key \types.

The syntax examples of the \types\ will show which \prefix\ will be
automatically used by printing those black (\texttt{\enfprefix{long}}), which
will be available in grey (\texttt{\allprefix{long}}), and which will be
disallowed in red (\texttt{\notprefix{long}}). This will be put flush right next
to the syntax line.

If a secondary key references another key it doesn't matter whether that other
key is a primary or secondary key (unless explicitly stated otherwise).

\begin{function}[module=expkv-cs type]{meta}
  \begin{syntax}
    meta \key\ = \kvarg \prefixes2
  \end{syntax}
  With a |meta| key you can set other keys. Whenever \meta{key} is used the keys
  in the \kv\ list will be set to the values given there. You can use the \val\
  given to \key\ by using |#1| in the \kv\ list.
\end{function}

\begin{function}[module=expkv-cs type]{nmeta}
  \begin{syntax}
    nmeta \key\ = \kvarg \prefixes3
  \end{syntax}
  An |nmeta| key is like a |meta| key, but it doesn't take a value at use time,
  so the \kv\ list is static.
\end{function}

\begin{function}[module=expkv-cs type]{alias}
  \begin{syntax}
    alias \meta{key} = \marg{key_2} \prefixes3
  \end{syntax}
  This assigns the definition of \meta{key_2} to \key. As a result \key\ is an
  alias for \meta{key_2} behaving just the same. Both the \Vkey\ and the \Nkey\
  will be copied if they are defined when |alias| is used. Of course,
  \meta{key_2} has to be defined as at least one of \Nkey\ or \Vkey.
\end{function}

\begin{function}[module=expkv-cs type]{default}
  \begin{syntax}
    default \key\ = \marg{default} \prefixes3
  \end{syntax}
  If \key\ is defined as a \Vkey\ you can define a \Nkey\ version with this. The
  \Nkey\ will behave as if \key\ was given \meta{default} as its \val. Note that
  this doesn't change the initial values of primary keys set at definition time
  (see \cs{ekvcChange} in \autoref{sec:c:change} for this). If \key\ isn't yet
  defined this results in an error.
\end{function}

\begin{function}[module=expkv-cs type]{enum}
  \begin{syntax}
    enum \key\ = \marg{key_2}\kvarg \prefixes2
  \end{syntax}
  This defines \key\ to only accept the values given in the list of the second
  argument of its definition. It forwards the position of \val\ in that list to
  \meta{key_2} (zero-based). The \meta{key_2} has to already be defined by the
  time an |enum| key is set up. Each \val\ in the list (and at use time) is
  |\detokenize|d, so no expansion takes place here.

  If you use |enum| twice on the same \key\ the new values will again start at
  zero (so it is possible to define multiple values with the same outcome),
  however since you can't skip values you'll have to use the same as in the
  first call for values with just a single variant. There is no interface to
  delete existing values.
\end{function}
\begin{example}{Enumerating choices with the \texttt{enum} \type}
  First a small example that might give you an idea of what the description
  above could mean:
  \begin{enverb}
    \ekvcSplit\foo{k-internal=-1}{#1}
    \ekvcSecondaryKeys\foo
      {enum k = {k-internal}{a,b,c}}
    \foo{}\foo{k=a}\foo{k=b}\foo{k=c}
  \end{enverb}
\end{example}
\begin{example}{A slightly more complicated usage of the \texttt{enum} \type}
  We can define a choice setup that might do different things based on the
  choice encountered, and the numeric value is easy to parse using
  \cs[no-index]{ifcase}:
  \begin{enverb}
    \ekvcSplit\foo{k-internal=-1}
      {%
        \ifcase#1
          is\or
          This\or
          easy%
        \else
          .%
        \fi
      }
    \ekvcSecondaryKeys\foo
      {enum k = {k-internal}{a,b,c}}
    \foo{k=b} \foo{k=a} \foo{k=c}\foo{}
  \end{enverb}
\end{example}

\begin{function}[module=expkv-cs type]{choice}
  \begin{syntax}
    choice \key\ = \marg{key_2}\kvarg \prefixes2
  \end{syntax}
  This is pretty similar to an |enum|, but unlike with |enum| the forwarded
  \val\ will not be numeric, instead the \val\ as given during the definition
  time will be forwarded. This means that while the user input has to match in a
  |\detokenize|d form, the \val\ might still expand further during your macro's
  expansion (if what you provided as a choice is expandable).
\end{function}
\begin{example}{Filtering possible values with the \texttt{choice} \type}
  We could use this to filter out the possible vertical placements of a \LaTeXe\
  |tabular|:
  \begin{enverb}
    \ekvcSplit\foo{v-internal=c,a=t,b=c,c=b}
      {%
        \begin{tabular}[#1]{@{} c @{:} c @{}}
          a & #2\\
          b & #3\\
          c & #4\\
        \end{tabular}%
      }
    \ekvcSecondaryKeys\foo
      {choice v = {v-internal}{t,c,b}}
    \foo{} \foo{v=t} \foo{v=c} \foo{v=b}
  \end{enverb}
\end{example}

\begin{function}[module=expkv-cs type]{aggregate,e-aggregate}
  \begin{syntax}
    aggregate \key\ = \marg{primary}\marg{definition} \prefixes3
  \end{syntax}
  While other key \types\ replace the current value of the associated
  primary key, with |aggregate| you can create keys that append or prepend (or
  whatever you like) the new value to the current one. Your definition of an
  |aggregate| key must be exactly two \TeX\ arguments, where \meta{primary}
  should be the name of a primary key, and \meta{definition} the way you want to
  store the current and the new value. Inside \meta{definition} you can use |#1|
  for the current, and |#2| for the new value. The \meta{definition} will not
  expand any further during the entire parsing for |aggregate|, whereas in
  |e-aggregate| everything that ends up in \meta{definition} (so whatever you
  provide including the values in |#1| and |#2|) will be fully expanded (using
  the |\expanded| primitive), so use |\noexpand| and |\unexpanded| to protect
  what shouldn't be expanded.
  The resulting \meta{key} will inherit being either |short| or |long| from the
  \meta{primary} key.
\end{function}
\begin{example}{Building a list with the \texttt{aggregate} \type}
  The following defines an internal key (|k-internal|), which is used to build a
  comma separated list from each call of the user facing key (|k|):
  \begin{enverb}
    \ekvcSplit\foo
      {k-internal=0,color=red}
      {\textcolor{#2}{#1}}
    \ekvcSecondaryKeys\foo
      {aggregate k = {k-internal}{#1,#2}}
    \foo{}\par
    \foo{k=1,k=2,k=3,k=4}
  \end{enverb}
\end{example}
\begin{example}{Building a convoluted list with the \texttt{aggregate} \type}
  But also more strange stuff could end there, like macros or using the same
  value multiple times:
  \begin{enverb}[no-tcb]
    \ekvcSecondaryKeys\foo
      {aggregate k = {k-internal}{\old{#1}\new{#2\old{#1}}}}
  \end{enverb}
\end{example}

\begin{function}[module=expkv-cs type]{flag-bool}
  \begin{syntax}
    flag-bool \key\ = \meta{cs} \prefixes3
  \end{syntax}
  This is a secondary \type\ that doesn't involve any of the primary or other
  secondary keys. This defines \key\ to take a value, which should be either
  |true| or |false|, and set the flag called \meta{cs} accordingly as a boolean.
  If \meta{cs} isn't defined yet it will be initialised as a flag. Note that the
  flag will not be set to a specific state automatically so a flag set in one
  macro might affect every other macro in the current scope. Please also read
  \autoref{sec:c:flags}.
\end{function}
\begin{example}{Using a Boolean flag with the \texttt{flag-bool} \type}
  Provide a key |bold| to turn the output of our macro bold if the associated
  flag is |true|.
  \begin{enverb}
    \ekvcSplit\foo{a=a,b=b}
      {%
        \ekvcFlagIf\fooFlag
          {\textbf{a is #1 and b is #2}\par}
          {a is #1 and b is #2\par}%
      }
    \ekvcSecondaryKeys\foo{flag-bool bold = \fooFlag}
    \foo{}\foo{bold=true}\foo{}\foo{bold=false}\foo{}
  \end{enverb}
\end{example}

\begin{function}[module=expkv-cs type]{flag-true,flag-false}
  \begin{syntax}
    flag-true \key\ = \meta{cs} \prefixes3
  \end{syntax}
  This is similar to |flag-bool|, but the \meta{key} will be a \Nkey\ and if
  used will set the flag to either |true| or |false|. If \meta{cs} isn't defined
  yet it will be initialised as a flag. Note that the flag will not be set to a
  specific state automatically. Please also read \autoref{sec:c:flags}.
\end{function}

\begin{function}[module=expkv-cs type]{flag-raise}
  \begin{syntax}
    flag-raise \key\ = \meta{cs} \prefixes3
  \end{syntax}
  This defines \key\ to be a \Nkey\ that will raise the flag called \meta{cs} on
  usage. If \meta{cs} isn't defined yet it will be initialised as a flag. Note
  that the flag will not be set to a specific state automatically. Please also
  read \autoref{sec:c:flags}.
\end{function}


\subsection{Changing the Initial Values\label{sec:c:change}}

\begin{function}{\ekvcChange}
  \begin{syntax}
    \cs{ekvcChange}\meta{cs}\kvarg
  \end{syntax}
  This processes the \kv\ list for the macro \meta{cs} to set new defaults for
  it (meaning the initial values used if you don't provide anything at use time,
  not those specified with the |default| \type). \meta{cs} should be defined
  with \expkvc\ (but it doesn't matter if it's a split or hash variant). Inside
  the \kv\ list both primary and secondary keys can be used. If \meta{cs} was
  defined |\long| earlier it will still be |\long|, every other \TeX\ prefix
  will be stripped (but \expkvc\ doesn't support them anywhere else so that
  should be fine). The resulting new defaults will be stored inside the
  \meta{cs} locally (just as the original initial values were). If there was an
  unknown key forwarding added to \meta{cs} (see \autoref{sec:c:unknown}) any
  unknown key will be stored inside the list of unknown keys as well.
  \cs{ekvcChange} is not expandable!
\end{function}
\begin{example}
    {Changing the values for future calls using \cs[no-index]{ekvcChange}}
  With \cs{ekvcChange} we can now do the following:
  \begin{enverb}
    \ekvcSplit\foo{a=a,b=b}{a is #1.\par b is #2.\par}
    \begingroup
      \ekvcChange\foo{b=B}
      \foo{}
      \ekvcSecondaryKeys\foo{meta c={a={#1},b={#1}}}
      \ekvcChange\foo{c=c}
      \foo{}
    \endgroup
    \foo{}
  \end{enverb}
\end{example}
\begin{example}{A typical setup macro for \expkvc\ macros}
  As a result with this the typical setup macro could be implemented:
  \begin{enverb}[no-tcb]
    \ekvcHashAndUse\fooKV{keyA=a,keyB=b}
    \def\fooA#1{\fooKV{#1}\fooAinternal}
    \def\fooB#1{\fooKV{#1}\fooBinternal}
    \protected\def\foosetup{\ekvcChange\fooKV}
  \end{enverb}
  Of course the usage is limited to a single macro |\fooKV|, hence this might
  not be as powerful as similar macros used with other \kv\ interfaces. But at
  least a few similar macros could be grouped using the same key parsing macro
  internally like |\fooA| and |\fooB| do in this example.
\end{example}


\subsection{Handling Unknown Keys\label{sec:c:unknown}}

If your macro should handle unknown keys without directly throwing an error you
can use the special |...| marker in the \meta{primary keys} list. Since those
keys will be processed once by \expkv\ they will be forwarded normalised: The
\key\ and the \val\ will be forwarded with one set of surrounding spaces and
braces, so a \kv\ pair will result in \texttt{\vissp{ \marg{key} = \marg{val} }}
and a \Nkey\ is forwarded as \texttt{\vissp{ \marg{key} }} (this way most other
\kv\ implementations should parse the correct input).

The exact behaviour differs slightly between the two variants (as all primary
keys do). The behaviour inside the split variants will be similar to normal
primary keys, the $n$-th argument (corresponding to the position of |...| inside
the primary keys list) will contain any unknown key encountered while parsing
the argument. And inside the split variant you can use a primary key named |...|
at the same time (since only the position in the list determines the argument,
not the name).
\begin{example}{Using unknown key handlers to wrap another \kv\ enabled macro}
  The following will forward any unknown key to |\includegraphics| to control
  the appearance while processing its own keys:
  \begin{enverb}[same-line=0.6]
    \newcommand*\foo{\ekvoptarg\fooKV{}}
    \ekvcSplitAndForward\fooKV\fooOUT
      {
         a=a
        ,...
        ,b=b
        ,...={}
      }
    \newcommand\fooOUT[5]
      {%
        a is #1 and b is #3.\par
        \includegraphics[{#2}]{#5}\par
        \texttt{...} is #4.\par
      }
    \foo[width=.5\linewidth, b=c,
         ...={a stupid key name, but works}]
        {example-image-duck}
  \end{enverb}
\end{example}

Inside the hash variants the unknown keys list will be put inside the hash named
|...| (we have to use some name, and this one seems reasonable). As a
consequence a primary key named |...| would clash with the unknown key handler.
If you still used such a key it would remove any unknown key stored there until
that point and replace the list with its value.
\begin{example}{Wrapping an existing macro, but with a hash variant}
  The following is more or less equivalent to the above example, but with the
  hash variant, and it will not contain the primary |...| key. We have to make
  sure that |\includegraphics| sees the \kv\ list, so need to expand
  |\ekvcValue{...}{#1}| before |\includegraphics| parses it.
  \begin{enverb}[same-line=0.76]
    \newcommand*\foo{\ekvoptarg\fooKV{}}
    \ekvcHashAndForward\fooKV\fooOUT
      {a=a, b=b, ...}
    \newcommand\fooOUT[2]
      {%
        a is \ekvcValue{a}{#1} and
        b is \ekvcValue{b}{#1}.\par
        \ekvcValueSplit{...}{#1}{\includegraphics[}]%
          {#2}\par
      }
    \foo[width=\linewidth, b=c]
        {example-image-duck-portrait}
  \end{enverb}
\end{example}


\subsection{Flags\label{sec:c:flags}}

The idea of flags is taken from \pkg{expl3}. They provide a way to store
numerical information expandably, however only incrementing and accessing works
expandably, decrementing is unexpandable. A flag has a height, which is a
numerical value, and which can be raised by 1. Flags come at a high
computational cost (accessing them is slow and they require more memory than
normal \TeX\ data types like registers, both issues getting linearly worse with
the height), so don't use them if not necessary.

The state of flags is always changed locally to the current group, but not to
the current macro, so if you're using one of the \types\ involving flags
bear in mind that they can affect other macros using the same flags at the
current scope!

\expkvc\ provides some macros to access, alter, and use flags. Flags of \expkvc\
don't share a name space with the flags of \pkg{expl3}.

\begin{function}{\ekvcFlagNew}
  \begin{syntax}
    \cs{ekvcFlagNew}\meta{flag}
  \end{syntax}
  This initialises the macro \meta{flag} as a new flag. It isn't checked whether
  the macro \meta{flag} is currently undefined. A \meta{flag} will expand to the
  flag's current height with a trailing space (so you can use it directly with
  \cs[no-index]{ifnum} for example and it will terminate the number scanning on
  its own).

  All other macros dealing with flags take as a parameter a macro defined as a
  \meta{flag} with \cs{ekvcFlagNew}.
\end{function}

\begin{function}{\ekvcFlagHeight}
  \begin{syntax}
    \cs{ekvcFlagHeight}\meta{flag}
  \end{syntax}
  This expands to the current height of \meta{flag} in a single step of
  expansion (without a trailing space).
\end{function}

\begin{function}{\ekvcFlagRaise}
  \begin{syntax}
    \cs{ekvcFlagRaise}\meta{flag}
  \end{syntax}
  This expandably raises the height of \meta{flag} by 1.
\end{function}

\begin{function}{\ekvcFlagSetTrue,\ekvcFlagSetFalse}
  \begin{syntax}
    \cs{ekvcFlagSetTrue}\meta{flag}
  \end{syntax}
  By interpreting an even value as false and an odd value as true we can use a
  flag as a boolean. This expandably sets \meta{flag} to true or false,
  respectively, by raising it if necessary.
\end{function}

\begin{function}{\ekvcFlagIf}
  \begin{syntax}
    \cs{ekvcFlagIf}\meta{flag}\marg{true}\marg{false}
  \end{syntax}
  This interprets a \meta{flag} as a boolean and expands to either \meta{true}
  or \meta{false}.
\end{function}

\begin{function}{\ekvcFlagIfRaised}
  \begin{syntax}
    \cs{ekvcFlagIfRaised}\meta{flag}\marg{true}\marg{false}
  \end{syntax}
  This tests whether the \meta{flag} is raised, meaning it has a height greater
  than zero, and if so expands to \meta{true} else to \meta{false}.
\end{function}

\begin{function}{\ekvcFlagReset,\ekvcFlagResetGlobal}
  \begin{syntax}
    \cs{ekvcFlagReset}\meta{flag}
  \end{syntax}
  This resets a flag (so restores its height to 0). This operation is \emph{not}
  expandable and done locally for \cs{ekvcFlagReset} and globally for
  \cs{ekvcFlagResetGlobal}. If you really intend to use flags you can reset them
  every now and then to keep the performance hit low.
\end{function}

\begin{function}{\ekvcFlagGetHeight}
  \begin{syntax}
    \cs{ekvcFlagGetHeight}\meta{flag}\marg{next}
  \end{syntax}
  This retrieves the current height of the \meta{flag} and provides it as a
  braced argument to \meta{next}, leaving \meta{next}\marg{height} in the input
  stream.
\end{function}

\begin{function}{\ekvcFlagGetHeights}
  \begin{syntax}
    \cs{ekvcFlagGetHeights}\marg{flag-list}\marg{next}
  \end{syntax}
  This retrieves the current height of each \meta{flag} in the \meta{flag-list}
  and provides them as a single argument to \meta{next}. Inside that argument
  each height is enclosed in a set of braces individually. The \meta{flag-list}
  is just a single argument containing the \meta{flag}s. So a usage like
  |\ekvcFlagGetHeights{\myflagA\myflagB}{\stuff}| will expand to
  |\stuff{|\marg{height-A}\marg{height-B}|}|.
\end{function}


\subsection{Further Examples}

\begin{example}{Defining an expandable \kv\ macro with an optional argument}
  Using \cs[no-index]{NewExpandableDocumentCommand} or \expkv's \cs{ekvoptarg}
  or \cs{ekvoptargTF} and forwarding arguments one can easily define \kv\ macros
  with actual optional and mandatory arguments as well. A small nonsense
  example:
  \begin{enverb}[below,inter=resulting in]
    \makeatletter
    \newcommand*\nonsense{\ekvoptarg\nonsense@a{}}
    \ekvcHashAndForward\nonsense@a\nonsense@b
      {
        keyA = A,
        keyB = B,
        keyC = c,
        keyD = d,
      }
    \newcommand*\nonsense@b[2]
      {%
        \begin{tabular}{lll|}
          key & A & \ekvcValue{keyA}{#1} \\
              & B & \ekvcValue{keyB}{#1} \\
              & C & \ekvcValue{keyC}{#1} \\
              & D & \ekvcValue{keyD}{#1} \\
          \multicolumn{2}{l}{mandatory} & #2 \\
        \end{tabular}%
      }
    \makeatother
    \nonsense{} % do nonsense
    \nonsense[keyA=hihi]{haha}
    \nonsense[keyA=hihi, keyB=A]{hehe}
    \nonsense[keyC=huhu, keyA=hihi, keyB=A]{haha}
  \end{enverb}
\end{example}

\begin{example}{The \cs[no-index]{sine} example revisited}
  In \autoref{sec:expkv:sneak} I presented an expandable macro to calculate the
  sine of some user input with a few keys, and there I hinted to \expkvc, so
  here's the same function implemented with |\ekvcSplitAndForward|. There is a
  small difference here, we need to use an internal key to store whether degrees
  or radians will be used, but we don't need to use an internal key to collect
  the values of our individual keys in the correct order.
  \begin{enverb}
    \makeatletter
    \newcommand\sine{\ekvoptarg\sine@kv{}}
    \ekvcSplitAndForward\sine@kv\sine@do
      {
         f        = sin
        ,internal = d
        ,round    = 3
      }
    \ekvcSecondaryKeys\sine@kv
      {
         nmeta degree = internal=d
        ,nmeta radian = internal={}
      }
    \newcommand*\sine@do[4]{\fpeval{round(#1#2(#4),#3)}}
    \makeatother
    \sine{60}\par
    \sine[round=10]{60}\par
    \sine[f=cos,radian]{pi}\par
    \edef\myval{\sine[f=tan]{1}}\texttt{\meaning\myval}
  \end{enverb}
\end{example}


\subsection{Freedom for Keys!}

If this had been the \TeX{}book this subsection would have had a double bend
sign. Not because it is overly complicated, but because it shows things which
could break \expkvc's expandability and its alignment safety. This is for
experienced users wanting to get the most flexibility and knowing what they are
doing.

In case you're wondering, it is possible to define other keys than the primaries
and the secondary key \types\ listed in \autoref{sec:c:secondary} for a
macro defined with \expkvc\ by using the low-level interface of \expkv\ or even
the interface provided by \expkvd. The set name used for \expkvc's keys is the
macro name, including the leading backslash, or more precisely the result of
|\string|\meta{cs} is used. This can be exploited to define additional keys with
arbitrary code. Consider the following \emph{bad} example:
\begin{enverb}[no-tcb]
  \ekvcSplit\foo{a=A,b=B}{a is #1.\par b is #2.\par}
  \protected\ekvdef{\string\foo}{c}{\def\fooC{#1}}
\end{enverb}
This would define a key named |c| that will store its \val\ inside a macro. The
issue with this is that this can't be done expandably. As a result, the macro
|\foo| isn't always expandable any more (not that bad if this was never
required; killjoy if it was) and as soon as the key |c| is used it is also no
longer alignment safe\footnote{This means that the \kv\ list can't contain
  alignment markers that are not inside an additional set of braces if used
  inside a \TeX\ alignment}
(might be bad depending on the usage).

So why do I show you this? Because we could as well do something useful like
creating a key that pre-parses the input and after that passes the parsed value
on. This parsing would have to be completely expandable though (and we could
perhaps also implement this using the |e-aggregate| \type). For the
pass-on part we can use the following function:

\begin{function}{\ekvcPass}
  \begin{syntax}
    \cs{ekvcPass}\meta{cs}\marg{key}\marg{value}
  \end{syntax}
  This passes \val\ on to \key\ for the \expkvc-macro \meta{cs}. It should be
  used inside the key parsing of a macro defined with \expkvc, else this most
  likely results in a low level \TeX\ error. You can't forward anything to the
  special unknown key handler |...| as that is no defined key.
\end{function}
\begin{example}
    {Forwarding pre-parsed keys to an \expkvc\ key with \cs[no-index]{ekvcPass}}
  With this we could for example split the value of a key at a hyphen and pass
  the parts to different keys:
  \begin{enverb}
    \ekvcSplit\foo{a=A,b=B}{a is #1.\par b is #2.\par}
    \ekvdef{\string\foo}{c}{\fooSplit#1\par}
    \def\fooSplit#1-#2\par
      {\ekvcPass\foo{a}{#1}\ekvcPass\foo{b}{#2}}
    \foo{}
    \foo{c=1-2}
  \end{enverb}
\end{example}

Additionally, there is a more general version of the |aggregate| secondary key
type, namely the |process| key type:

\begin{function}[module=expkv-cs type]{process}
  \begin{syntax}
    process \key\ = \marg{primary}\marg{definition} \prefixes2
  \end{syntax}
  This will grab the current value of a \meta{primary} key as |#1| (without
  changing the current value) and the new value as |#2| and leave all the
  processing to \meta{definition}. You should use \cs{ekvcPass} to forward the
  values afterwards. Unlike |aggregate| you can specify whether the \meta{key}
  should be long or not, this isn't inherited from the \meta{primary} key. Keep
  in mind that you could easily break things here if your code does not work by
  expansion.
\end{function}
\begin{example}{Filtering out values with the \texttt{process} \type} 
  We could define a key that only accepts values greater than the current value
  with this:
  \begin{enverb}
    \ekvcSplit\foo{internal=5}{a is #1.\par}
    \ekvcSecondaryKeys\foo
      {
        process a={internal}
          {\ifnum#1<#2 \ekvcPass\foo{internal}{#2}\fi}
      }
    \foo{a=1}
    \foo{a=5}
    \foo{a=9}
  \end{enverb}
\end{example}
\begin{example}{Filtering out values with the \texttt{e-aggregate} \type}
  The same is possible with an |e-aggregate| key as well though:
  \begin{enverb}[no-tcb]
    \ekvcSplit\foo{internal=5}{a is #1.\par}
    \ekvcSecondaryKeys\foo
      {
        e-aggregate a={internal}
          {\ifnum#1<#2 \unexpanded{#2}\else\unexpanded{#1}\fi}
      }
  \end{enverb}
\end{example}

\subsection{Useless Macros}

These macros are most likely of little to no interest to users.

\begin{function}{\ekvcDate,\ekvcVersion}
  These two macros store the version and date of the package/generic code.
\end{function}