Make -NoValue- a kernel concept (fixes #415)

This moves -NoValue- from xparse to l3kernel, with the result that it is
a generalised 'no value given' token. The test goes with it as it is
more complex than doing \tl_if_eq:NN(FT) (as it needs to be expandable).

l3kernel/l3tl.dtx

@@ -433,6 +433,17 @@
 %   (begin-group) or $2$ (end-group), and tokens with category code $6$).
 % \end{function}
 %
+% \begin{function}[added = 2017-11-14, EXP,pTF]{\tl_if_novalue:n}
+%   \begin{syntax}
+%     \cs{tl_if_novalue_p:n} \Arg{token list}
+%     \cs{tl_if_novalue:nTF} \Arg{token list} \Arg{true code} \Arg{false code}
+%   \end{syntax}
+%   Tests if the \meta{token list} is exactly equal to the special
+%   \cs{c_novalue_tl} marker. This function is indented to allow construction
+%   of flexible document interface structures in which missing optional
+%   arguments are detected.
+% \end{function}
+%
 % \begin{function}[updated = 2011-08-13, EXP,pTF]
 %   {\tl_if_single:N, \tl_if_single:c}
 %   \begin{syntax}
@@ -744,8 +755,8 @@
 %   \end{texnote}
 % \end{function}
 %
-% \begin{function}[added = 2011-07-09, updated = 2017-11-09, EXP]
-%   {\tl_trim_spaces:n, \tl_trim_spaces:o}
+% \begin{function}[added = 2011-07-09, updated = 2012-06-25, EXP]
+%   {\tl_trim_spaces:n}
 %   \begin{syntax}
 %     \cs{tl_trim_spaces:n} \Arg{token list}
 %   \end{syntax}
@@ -1034,6 +1045,21 @@
 %   Constant that is always empty.
 % \end{variable}
 %
+% \begin{variable}[added = 2017-11-14]{\c_novalue_tl}
+%   A marker for the absence of an argument. This constant |tl| can safely
+%   be typeset (\emph{cf.}~|\q_nil|), with the result being |-NoValue-|.
+%   It is important to note that \cs{c_novalue_tl} is constructed such that it
+%   will \emph{not} match the simple text input |-NoValue-|, \emph{i.e.}
+%   that
+%   \begin{verbatim}
+%     \tl_if_eq:VnTF \c_novalue_tl { -NoValue- }
+%   \end{verbatim}
+%   is logically \texttt{false}. The \cs{c_novalue_tl} marker is intended for
+%   use in creating document-level interfaces, where it serves as an indicator
+%   that an (optional) argument was omitted. In particular, it is distinct
+%   from a simple empty |tl|.
+% \end{variable}
+%
 % \begin{variable}{\c_space_tl}
 %   An explicit space character contained in a token list (compare this with
 %   \cs{c_space_token}). For use where an explicit space is required.
@@ -1227,6 +1253,22 @@
 %    \end{macrocode}
 % \end{variable}
 %
+% \begin{variable}{\c_novalue_tl}
+%   A special marker: as we don't have |\char_generate:nn| yet, has to be
+%   created the old-fashioned way.
+%    \begin{macrocode}
+\group_begin:
+\tex_lccode:D `A = `-
+\tex_lccode:D `N = `N
+\tex_lccode:D `V = `V
+\tex_lowercase:D
+  {
+    \group_end:
+    \tl_const:Nn \c_novalue_tl { ANoValue- }
+  }
+%    \end{macrocode}
+% \end{variable}
+%
 % \begin{variable}{\c_space_tl}
 %   A space as a token list (as opposed to as a character).
 %    \begin{macrocode}
@@ -2035,6 +2077,33 @@
 %    \end{macrocode}
 % \end{macro}
 %
+% \begin{macro}[TF, EXP]{\tl_if_novalue:n}
+% \begin{macro}[EXP, aux]{\@@_if_novalue:w}
+%   Tests for |-NoValue-|: this is similar to \cs{tl_if_in:nn} but set
+%   up to be expandable and to check the value exactly.  The question
+%   mark prevents the auxiliary from losing braces.
+%    \begin{macrocode}
+\use:x
+  {
+    \prg_new_conditional:Npnn \exp_not:N \tl_if_novalue:n ##1
+      { T ,  F , TF }
+      {
+        \exp_not:N \str_if_eq:onTF
+          {
+            \exp_not:N \@@_if_novalue:w ? ##1 { }
+              \c_novalue_tl
+          }
+          { ? { } \c_novalue_tl }
+          { \exp_not:N \prg_return_true: }
+          { \exp_not:N \prg_return_false: }
+      }
+    \cs_new:Npn \exp_not:N \@@_if_novalue:w ##1 \c_novalue_tl
+      {##1}
+  }
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
 % \begin{macro}[EXP,pTF]{\tl_if_single:N}
 %   Expand the token list and feed it to \cs{tl_if_single:n}.
 %    \begin{macrocode}

l3kernel/testfiles/m3expl001.luatex.tlg

@@ -275,6 +275,7 @@ Defining \tl_if_exist:cT on line ...
 Defining \tl_if_exist:cF on line ...
 Defining \tl_if_exist_p:c on line ...
 Defining \c_empty_tl on line ...
+Defining \c_novalue_tl on line ...
 Defining \c_space_tl on line ...
 Defining \tl_set:Nn on line ...
 Defining \tl_set:No on line ...
@@ -448,6 +449,10 @@ Defining \tl_if_in:noF on line ...
 Defining \tl_if_in:VnTF on line ...
 Defining \tl_if_in:onTF on line ...
 Defining \tl_if_in:noTF on line ...
+Defining \tl_if_novalue:nT on line ...
+Defining \tl_if_novalue:nF on line ...
+Defining \tl_if_novalue:nTF on line ...
+Defining \__tl_if_novalue:w on line ...
 Defining \tl_if_single_p:N on line ...
 Defining \tl_if_single:NT on line ...
 Defining \tl_if_single:NF on line ...

l3kernel/testfiles/m3expl001.ptex.tlg

@@ -274,6 +274,7 @@ Defining \tl_if_exist:cT on line ...
 Defining \tl_if_exist:cF on line ...
 Defining \tl_if_exist_p:c on line ...
 Defining \c_empty_tl on line ...
+Defining \c_novalue_tl on line ...
 Defining \c_space_tl on line ...
 Defining \tl_set:Nn on line ...
 Defining \tl_set:No on line ...
@@ -447,6 +448,10 @@ Defining \tl_if_in:noF on line ...
 Defining \tl_if_in:VnTF on line ...
 Defining \tl_if_in:onTF on line ...
 Defining \tl_if_in:noTF on line ...
+Defining \tl_if_novalue:nT on line ...
+Defining \tl_if_novalue:nF on line ...
+Defining \tl_if_novalue:nTF on line ...
+Defining \__tl_if_novalue:w on line ...
 Defining \tl_if_single_p:N on line ...
 Defining \tl_if_single:NT on line ...
 Defining \tl_if_single:NF on line ...

l3kernel/testfiles/m3expl001.tlg

@@ -274,6 +274,7 @@ Defining \tl_if_exist:cT on line ...
 Defining \tl_if_exist:cF on line ...
 Defining \tl_if_exist_p:c on line ...
 Defining \c_empty_tl on line ...
+Defining \c_novalue_tl on line ...
 Defining \c_space_tl on line ...
 Defining \tl_set:Nn on line ...
 Defining \tl_set:No on line ...
@@ -447,6 +448,10 @@ Defining \tl_if_in:noF on line ...
 Defining \tl_if_in:VnTF on line ...
 Defining \tl_if_in:onTF on line ...
 Defining \tl_if_in:noTF on line ...
+Defining \tl_if_novalue:nT on line ...
+Defining \tl_if_novalue:nF on line ...
+Defining \tl_if_novalue:nTF on line ...
+Defining \__tl_if_novalue:w on line ...
 Defining \tl_if_single_p:N on line ...
 Defining \tl_if_single:NT on line ...
 Defining \tl_if_single:NF on line ...

l3kernel/testfiles/m3expl001.uptex.tlg

@@ -274,6 +274,7 @@ Defining \tl_if_exist:cT on line ...
 Defining \tl_if_exist:cF on line ...
 Defining \tl_if_exist_p:c on line ...
 Defining \c_empty_tl on line ...
+Defining \c_novalue_tl on line ...
 Defining \c_space_tl on line ...
 Defining \tl_set:Nn on line ...
 Defining \tl_set:No on line ...
@@ -447,6 +448,10 @@ Defining \tl_if_in:noF on line ...
 Defining \tl_if_in:VnTF on line ...
 Defining \tl_if_in:onTF on line ...
 Defining \tl_if_in:noTF on line ...
+Defining \tl_if_novalue:nT on line ...
+Defining \tl_if_novalue:nF on line ...
+Defining \tl_if_novalue:nTF on line ...
+Defining \__tl_if_novalue:w on line ...
 Defining \tl_if_single_p:N on line ...
 Defining \tl_if_single:NT on line ...
 Defining \tl_if_single:NF on line ...

l3kernel/testfiles/m3expl001.xetex.tlg

@@ -274,6 +274,7 @@ Defining \tl_if_exist:cT on line ...
 Defining \tl_if_exist:cF on line ...
 Defining \tl_if_exist_p:c on line ...
 Defining \c_empty_tl on line ...
+Defining \c_novalue_tl on line ...
 Defining \c_space_tl on line ...
 Defining \tl_set:Nn on line ...
 Defining \tl_set:No on line ...
@@ -447,6 +448,10 @@ Defining \tl_if_in:noF on line ...
 Defining \tl_if_in:VnTF on line ...
 Defining \tl_if_in:onTF on line ...
 Defining \tl_if_in:noTF on line ...
+Defining \tl_if_novalue:nT on line ...
+Defining \tl_if_novalue:nF on line ...
+Defining \tl_if_novalue:nTF on line ...
+Defining \__tl_if_novalue:w on line ...
 Defining \tl_if_single_p:N on line ...
 Defining \tl_if_single:NT on line ...
 Defining \tl_if_single:NF on line ...

l3kernel/testfiles/m3expl003.luatex.tlg

@@ -275,6 +275,7 @@ Defining \tl_if_exist:cT on line ...
 Defining \tl_if_exist:cF on line ...
 Defining \tl_if_exist_p:c on line ...
 Defining \c_empty_tl on line ...
+Defining \c_novalue_tl on line ...
 Defining \c_space_tl on line ...
 Defining \tl_set:Nn on line ...
 Defining \tl_set:No on line ...
@@ -448,6 +449,10 @@ Defining \tl_if_in:noF on line ...
 Defining \tl_if_in:VnTF on line ...
 Defining \tl_if_in:onTF on line ...
 Defining \tl_if_in:noTF on line ...
+Defining \tl_if_novalue:nT on line ...
+Defining \tl_if_novalue:nF on line ...
+Defining \tl_if_novalue:nTF on line ...
+Defining \__tl_if_novalue:w on line ...
 Defining \tl_if_single_p:N on line ...
 Defining \tl_if_single:NT on line ...
 Defining \tl_if_single:NF on line ...

l3kernel/testfiles/m3expl003.ptex.tlg

@@ -274,6 +274,7 @@ Defining \tl_if_exist:cT on line ...
 Defining \tl_if_exist:cF on line ...
 Defining \tl_if_exist_p:c on line ...
 Defining \c_empty_tl on line ...
+Defining \c_novalue_tl on line ...
 Defining \c_space_tl on line ...
 Defining \tl_set:Nn on line ...
 Defining \tl_set:No on line ...
@@ -447,6 +448,10 @@ Defining \tl_if_in:noF on line ...
 Defining \tl_if_in:VnTF on line ...
 Defining \tl_if_in:onTF on line ...
 Defining \tl_if_in:noTF on line ...
+Defining \tl_if_novalue:nT on line ...
+Defining \tl_if_novalue:nF on line ...
+Defining \tl_if_novalue:nTF on line ...
+Defining \__tl_if_novalue:w on line ...
 Defining \tl_if_single_p:N on line ...
 Defining \tl_if_single:NT on line ...
 Defining \tl_if_single:NF on line ...

l3kernel/testfiles/m3expl003.tlg

@@ -274,6 +274,7 @@ Defining \tl_if_exist:cT on line ...
 Defining \tl_if_exist:cF on line ...
 Defining \tl_if_exist_p:c on line ...
 Defining \c_empty_tl on line ...
+Defining \c_novalue_tl on line ...
 Defining \c_space_tl on line ...
 Defining \tl_set:Nn on line ...
 Defining \tl_set:No on line ...
@@ -447,6 +448,10 @@ Defining \tl_if_in:noF on line ...
 Defining \tl_if_in:VnTF on line ...
 Defining \tl_if_in:onTF on line ...
 Defining \tl_if_in:noTF on line ...
+Defining \tl_if_novalue:nT on line ...
+Defining \tl_if_novalue:nF on line ...
+Defining \tl_if_novalue:nTF on line ...
+Defining \__tl_if_novalue:w on line ...
 Defining \tl_if_single_p:N on line ...
 Defining \tl_if_single:NT on line ...
 Defining \tl_if_single:NF on line ...

l3kernel/testfiles/m3expl003.uptex.tlg

@@ -274,6 +274,7 @@ Defining \tl_if_exist:cT on line ...
 Defining \tl_if_exist:cF on line ...
 Defining \tl_if_exist_p:c on line ...
 Defining \c_empty_tl on line ...
+Defining \c_novalue_tl on line ...
 Defining \c_space_tl on line ...
 Defining \tl_set:Nn on line ...
 Defining \tl_set:No on line ...
@@ -447,6 +448,10 @@ Defining \tl_if_in:noF on line ...
 Defining \tl_if_in:VnTF on line ...
 Defining \tl_if_in:onTF on line ...
 Defining \tl_if_in:noTF on line ...
+Defining \tl_if_novalue:nT on line ...
+Defining \tl_if_novalue:nF on line ...
+Defining \tl_if_novalue:nTF on line ...
+Defining \__tl_if_novalue:w on line ...
 Defining \tl_if_single_p:N on line ...
 Defining \tl_if_single:NT on line ...
 Defining \tl_if_single:NF on line ...

l3kernel/testfiles/m3expl003.xetex.tlg

@@ -274,6 +274,7 @@ Defining \tl_if_exist:cT on line ...
 Defining \tl_if_exist:cF on line ...
 Defining \tl_if_exist_p:c on line ...
 Defining \c_empty_tl on line ...
+Defining \c_novalue_tl on line ...
 Defining \c_space_tl on line ...
 Defining \tl_set:Nn on line ...
 Defining \tl_set:No on line ...
@@ -447,6 +448,10 @@ Defining \tl_if_in:noF on line ...
 Defining \tl_if_in:VnTF on line ...
 Defining \tl_if_in:onTF on line ...
 Defining \tl_if_in:noTF on line ...
+Defining \tl_if_novalue:nT on line ...
+Defining \tl_if_novalue:nF on line ...
+Defining \tl_if_novalue:nTF on line ...
+Defining \__tl_if_novalue:w on line ...
 Defining \tl_if_single_p:N on line ...
 Defining \tl_if_single:NT on line ...
 Defining \tl_if_single:NF on line ...

l3packages/xparse/testfiles/xparse001.ptex.tlg

@@ -580,9 +580,8 @@ l. ...}
 *************************************************
 > \foo=\protected macro:->\__xparse_start:nNNnnn {+t\par O{default}mmm}\foo 
 \foo code {\__xparse_grab_t_long:w \par \__xparse_grab_D:w
-[]\__xparse_grab_m_3:w }{\c__xparse_no_value_tl {\prg_do_nothing:
-default}\c__xparse_no_value_tl \c__xparse_no_value_tl \c__xparse_no_value_tl
-}{}.
+[]\__xparse_grab_m_3:w }{\c_novalue_tl {\prg_do_nothing: default}\c_novalue_tl
+\c_novalue_tl \c_novalue_tl }{}.
 <recently read> }
 l. ...}
 > \foo code=\protected\long macro:#1#2#3#4#5->(#1)(#2)(#3)(#4).
@@ -635,8 +634,8 @@ l. ...}
 *************************************************
 > \foo=\protected macro:->\__xparse_start:nNNnnn {mG{test}sm}\foo  \foo code
 {\__xparse_grab_m_1:w \__xparse_grab_G:w \__xparse_grab_t:w
-*\__xparse_grab_m_1:w }{\c__xparse_no_value_tl {\prg_do_nothing:
-test}\c__xparse_no_value_tl \c__xparse_no_value_tl }{}.
+*\__xparse_grab_m_1:w }{\c_novalue_tl {\prg_do_nothing: test}\c_novalue_tl
+\c_novalue_tl }{}.
 <recently read> }
 l. ...}
 > \foo code=\protected\long macro:#1#2#3#4->(#1)(#2)(#3)(#4).

l3packages/xparse/testfiles/xparse001.tlg

@@ -580,9 +580,8 @@ l. ...}
 *************************************************
 > \foo=\protected macro:->\__xparse_start:nNNnnn {+t\par O{default}mmm}\foo 
 \foo code {\__xparse_grab_t_long:w \par \__xparse_grab_D:w
-[]\__xparse_grab_m_3:w }{\c__xparse_no_value_tl {\prg_do_nothing:
-default}\c__xparse_no_value_tl \c__xparse_no_value_tl \c__xparse_no_value_tl
-}{}.
+[]\__xparse_grab_m_3:w }{\c_novalue_tl {\prg_do_nothing: default}\c_novalue_tl
+\c_novalue_tl \c_novalue_tl }{}.
 <recently read> }
 l. ...}
 > \foo code=\protected\long macro:#1#2#3#4#5->(#1)(#2)(#3)(#4).
@@ -635,8 +634,8 @@ l. ...}
 *************************************************
 > \foo=\protected macro:->\__xparse_start:nNNnnn {mG{test}sm}\foo  \foo code
 {\__xparse_grab_m_1:w \__xparse_grab_G:w \__xparse_grab_t:w
-*\__xparse_grab_m_1:w }{\c__xparse_no_value_tl {\prg_do_nothing:
-test}\c__xparse_no_value_tl \c__xparse_no_value_tl }{}.
+*\__xparse_grab_m_1:w }{\c_novalue_tl {\prg_do_nothing: test}\c_novalue_tl
+\c_novalue_tl }{}.
 <recently read> }
 l. ...}
 > \foo code=\protected\long macro:#1#2#3#4->(#1)(#2)(#3)(#4).

l3packages/xparse/testfiles/xparse001.uptex.tlg

@@ -580,9 +580,8 @@ l. ...}
 *************************************************
 > \foo=\protected macro:->\__xparse_start:nNNnnn {+t\par O{default}mmm}\foo 
 \foo code {\__xparse_grab_t_long:w \par \__xparse_grab_D:w
-[]\__xparse_grab_m_3:w }{\c__xparse_no_value_tl {\prg_do_nothing:
-default}\c__xparse_no_value_tl \c__xparse_no_value_tl \c__xparse_no_value_tl
-}{}.
+[]\__xparse_grab_m_3:w }{\c_novalue_tl {\prg_do_nothing: default}\c_novalue_tl
+\c_novalue_tl \c_novalue_tl }{}.
 <recently read> }
 l. ...}
 > \foo code=\protected\long macro:#1#2#3#4#5->(#1)(#2)(#3)(#4).
@@ -635,8 +634,8 @@ l. ...}
 *************************************************
 > \foo=\protected macro:->\__xparse_start:nNNnnn {mG{test}sm}\foo  \foo code
 {\__xparse_grab_m_1:w \__xparse_grab_G:w \__xparse_grab_t:w
-*\__xparse_grab_m_1:w }{\c__xparse_no_value_tl {\prg_do_nothing:
-test}\c__xparse_no_value_tl \c__xparse_no_value_tl }{}.
+*\__xparse_grab_m_1:w }{\c_novalue_tl {\prg_do_nothing: test}\c_novalue_tl
+\c_novalue_tl }{}.
 <recently read> }
 l. ...}
 > \foo code=\protected\long macro:#1#2#3#4->(#1)(#2)(#3)(#4).