summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3packages/xparse/xparse.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/l3packages/xparse/xparse.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3packages/xparse/xparse.dtx264
1 files changed, 136 insertions, 128 deletions
diff --git a/Master/texmf-dist/source/latex/l3packages/xparse/xparse.dtx b/Master/texmf-dist/source/latex/l3packages/xparse/xparse.dtx
index bb1d17cac39..0c632a9179e 100644
--- a/Master/texmf-dist/source/latex/l3packages/xparse/xparse.dtx
+++ b/Master/texmf-dist/source/latex/l3packages/xparse/xparse.dtx
@@ -41,8 +41,8 @@
%<*driver|package>
% The version of expl3 required is tested as early as possible, as
% some really old versions do not define \ProvidesExplPackage.
-\RequirePackage{expl3}[2012/02/08]
-%<package>\@ifpackagelater{expl3}{2012/02/08}
+\RequirePackage{expl3}[2012/02/26]
+%<package>\@ifpackagelater{expl3}{2012/02/26}
%<package> {}
%<package> {
%<package> \PackageError{xparse}{Support package l3kernel too old.}
@@ -53,7 +53,7 @@
%<package> }
%<package> \endinput
%<package> }
-\GetIdInfo$Id: xparse.dtx 3342 2012-02-08 19:34:51Z joseph $
+\GetIdInfo$Id: xparse.dtx 3471 2012-02-26 20:12:23Z joseph $
{L3 Experimental document command parser}
%</driver|package>
%<*driver>
@@ -231,10 +231,10 @@
% argument processors is a somewhat advanced topic, (or at least a less
% commonly used feature) and is covered in Section~\ref{sec:processors}.
%
-% By default, an argument of type \texttt{v} must be at most one line.
-% Prefixing with \texttt{+} allows line breaks within the argument.
-% The argument is given as a string of characters with category code~$12$,
-% except spaces, which have category code~$10$ (see \cs{tl_to_str:n}).
+% By default, an argument of type~\texttt{v} must be at most one line.
+% Prefixing with \texttt{+} allows line breaks within the argument. The
+% argument is given as a string of characters with category codes~$12$
+% or~$13$, except spaces, which have category code~$10$.
%
% \subsection{Spacing and optional arguments}
%
@@ -277,16 +277,16 @@
%
% \subsection{Verbatim arguments}
%
-% Arguments of type \enquote{\texttt{v}} are read in verbatim mode, which will
-% result in the grabbed argument consisting of tokens of category code
-% $12$~(\enquote{other}), except spaces, which are given category code
-% $10$~(\enquote{space}). The argument will be
+% 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.
%
% 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{}.
+% tokenized by \TeX{} in an irreversible way.
%
% Users should note that support for verbatim arguments is somewhat
% experimental. Feedback is therefore very welcome on the \texttt{LaTeX-L}
@@ -486,7 +486,7 @@
% \end{verbatim}
% \end{function}
%
-% \begin{function}{\SplitArgument}
+% \begin{function}[updated = 2012-02-12]{\SplitArgument}
% \begin{syntax}
% \cs{SplitArgument} \Arg{number} \Arg{token}
% \end{syntax}
@@ -505,7 +505,8 @@
% { \InternalFunctionOfThreeArguments #1 }
% \end{verbatim}
% Any category code $13$ (active) \meta{tokens} will be replaced
-% before the split takes place.
+% before the split takes place. Spaces are trimmed at each end of each
+% item parsed.
% \end{function}
%
% \begin{function}{\SplitList}
@@ -907,7 +908,7 @@
% \end{macro}
% \end{macro}
% \end{macro}
-%
+%
% \begin{macro}{\xparse_break_point:n}
% A marker used to escape from creating a definition if necessary.
% \begin{macrocode}
@@ -1115,7 +1116,7 @@
% the rest are simply there to ensure the loop continues correctly. There are
% no count functions for \texttt{l} or \texttt{v} argument types as they are
% exactly the same as \texttt{m}, and so a little code can be saved.
-%
+%
% The second thing that can be done here is to check that the signature is
% actually valid, such that all of the various argument types have the
% correct number of data items associated with them. If this fails to be
@@ -1125,7 +1126,7 @@
% \begin{macrocode}
\cs_new_protected:cpn { xparse_count_type_>:w } #1
{
- \quark_if_recursion_tail_stop_do:nn {#1} { \xparse_bad_signature:wn }
+ \quark_if_recursion_tail_stop_do:nn {#1} { \xparse_bad_arg_spec:wn }
\xparse_count_mandatory:N
}
\cs_new_protected_nopar:cpn { xparse_count_type_+:w }
@@ -1134,21 +1135,21 @@
{
\xparse_single_token_check:n {#1}
\xparse_single_token_check:n {#2}
- \quark_if_recursion_tail_stop_do:Nn #2 { \xparse_bad_signature:wn }
+ \quark_if_recursion_tail_stop_do:Nn #2 { \xparse_bad_arg_spec:wn }
\xparse_count_mandatory:N
}
\cs_new_protected:Npn \xparse_count_type_D:w #1#2#3
{
\xparse_single_token_check:n {#1}
\xparse_single_token_check:n {#2}
- \quark_if_recursion_tail_stop_do:nn {#3} { \xparse_bad_signature:wn }
+ \quark_if_recursion_tail_stop_do:nn {#3} { \xparse_bad_arg_spec:wn }
\xparse_count_mandatory:N
}
\cs_new_protected_nopar:Npn \xparse_count_type_g:w
{ \xparse_count_mandatory:N }
\cs_new_protected:Npn \xparse_count_type_G:w #1
{
- \quark_if_recursion_tail_stop_do:nn {#1} { \xparse_bad_signature:wn }
+ \quark_if_recursion_tail_stop_do:nn {#1} { \xparse_bad_arg_spec:wn }
\xparse_count_mandatory:N
}
\cs_new_protected_nopar:Npn \xparse_count_type_m:w
@@ -1160,7 +1161,7 @@
{
\xparse_single_token_check:n {#1}
\xparse_single_token_check:n {#2}
- \quark_if_recursion_tail_stop_do:Nn #2 { \xparse_bad_signature:wn }
+ \quark_if_recursion_tail_stop_do:Nn #2 { \xparse_bad_arg_spec:wn }
\int_incr:N \l_xparse_mandatory_args_int
\xparse_count_mandatory:N
}
@@ -1168,25 +1169,25 @@
{
\xparse_single_token_check:n {#1}
\xparse_single_token_check:n {#2}
- \quark_if_recursion_tail_stop_do:nn {#3} { \xparse_bad_signature:wn }
+ \quark_if_recursion_tail_stop_do:nn {#3} { \xparse_bad_arg_spec:wn }
\int_incr:N \l_xparse_mandatory_args_int
\xparse_count_mandatory:N
}
\cs_new_protected:Npn \xparse_count_type_t:w #1
{
\xparse_single_token_check:n {#1}
- \quark_if_recursion_tail_stop_do:Nn #1 { \xparse_bad_signature:wn }
+ \quark_if_recursion_tail_stop_do:Nn #1 { \xparse_bad_arg_spec:wn }
\xparse_count_mandatory:N
}
\cs_new_protected:Npn \xparse_count_type_u:w #1
{
- \quark_if_recursion_tail_stop_do:nn {#1} { \xparse_bad_signature:wn }
+ \quark_if_recursion_tail_stop_do:nn {#1} { \xparse_bad_arg_spec:wn }
\int_incr:N \l_xparse_mandatory_args_int
\xparse_count_mandatory:N
}
% \end{macrocode}
% \end{macro}
-%
+%
% \begin{macro}{\xparse_single_token_check:n}
% \begin{macro}[aux]{\xparse_single_token_check_aux:nwn}
% A spin-out function to check that what should be single tokens really
@@ -1206,13 +1207,13 @@
% \end{macrocode}
% \end{macro}
% \end{macro}
-%
-% \begin{macro}{\xparse_bad_signature:wn}
+%
+% \begin{macro}{\xparse_bad_arg_spec:wn}
% If the signature is wrong, this provides an escape from the entire
% definition process.
% \begin{macrocode}
-\cs_new_protected:Npn \xparse_bad_signature:wn #1 \xparse_break_point:n #2
- { \msg_kernel_error:nnx { xparse } { bad-signature } { \tl_to_str:n {#2} } }
+\cs_new_protected:Npn \xparse_bad_arg_spec:wn #1 \xparse_break_point:n #2
+ { \msg_kernel_error:nnx { xparse } { bad-arg-spec } { \tl_to_str:n {#2} } }
% \end{macrocode}
% \end{macro}
%
@@ -2149,7 +2150,7 @@
% \end{macro}
% \end{macro}
% \end{macro}
-%\end{macro}
+% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
@@ -2300,14 +2301,10 @@
}
\cs_new_protected_nopar:Npn \xparse_grab_v_group_end:
{
- \tl_set:Nx \l_xparse_tmp_tl
- {
- \tl_set:Nn \exp_not:N \l_xparse_v_arg_tl
- { \exp_not:o \l_xparse_v_arg_tl }
- }
- \exp_after:wN \group_align_safe_end:
- \exp_after:wN \group_end:
- \l_xparse_tmp_tl
+ \group_align_safe_end:
+ \exp_args:NNNo
+ \group_end:
+ \tl_set:Nn \l_xparse_v_arg_tl { \l_xparse_v_arg_tl }
}
% \end{macrocode}
% \end{variable}
@@ -2344,7 +2341,7 @@
% \begin{macrocode}
\cs_new_protected:Npn \xparse_grab_v_aux_test:N #1
{
- \tl_put_right:Nn \l_xparse_v_arg_tl {#1}
+ \xparse_grab_v_aux_put:N #1
\xparse_grab_v_token_if_char:NTF #1
{
\xparse_grab_v_aux_catcodes:
@@ -2365,7 +2362,7 @@
\token_if_eq_charcode:NNTF #1 #2
{ \xparse_grab_v_aux_loop_end: }
{
- \tl_put_right:Nn \l_xparse_v_arg_tl { #2 }
+ \xparse_grab_v_aux_put:N #2
\xparse_grab_v_aux_loop:N #1
}
}
@@ -2374,8 +2371,7 @@
\cs_new_protected_nopar:Npn \xparse_grab_v_aux_loop_end:
{
\xparse_grab_v_group_end:
- \exp_args:Nx \xparse_add_arg:n
- { \exp_args:No \str_tail:n { \l_xparse_v_arg_tl } }
+ \exp_args:Nx \xparse_add_arg:n { \tl_tail:N \l_xparse_v_arg_tl }
\l_xparse_v_rest_of_signature_tl \l_xparse_args_tl
}
% \end{macrocode}
@@ -2399,12 +2395,12 @@
% normal undelimited argument.
% \begin{macrocode}
\int_new:N \l_xparse_v_nesting_int
-\cs_new_protected_nopar:Npn \xparse_grab_v_bgroup:
+\cs_new_protected_nopar:Npx \xparse_grab_v_bgroup:
{
- \xparse_grab_v_aux_catcodes:
- \int_set_eq:NN \l_xparse_v_nesting_int \c_one
- \tl_set:Nx \l_xparse_v_arg_tl { \iow_char:N \{ }
- \xparse_grab_v_bgroup_loop:
+ \exp_not:N \xparse_grab_v_aux_catcodes:
+ \exp_not:n { \int_set_eq:NN \l_xparse_v_nesting_int \c_one }
+ \exp_not:N \xparse_grab_v_aux_put:N \iow_char:N \{
+ \exp_not:N \xparse_grab_v_bgroup_loop:
}
\cs_new_protected:Npn \xparse_grab_v_bgroup_loop:
{
@@ -2421,7 +2417,7 @@
\int_decr:N \l_xparse_v_nesting_int
\int_compare:nNnTF \l_xparse_v_nesting_int > \c_zero
{
- \tl_put_right:Nn \l_xparse_v_arg_tl { #1 }
+ \xparse_grab_v_aux_put:N #1
\xparse_grab_v_bgroup_loop:
}
{ \xparse_grab_v_aux_loop_end: }
@@ -2429,7 +2425,7 @@
{
\token_if_eq_charcode:NNT \c_group_begin_token #1
{ \int_incr:N \l_xparse_v_nesting_int }
- \tl_put_right:Nn \l_xparse_v_arg_tl { #1 }
+ \xparse_grab_v_aux_put:N #1
\xparse_grab_v_bgroup_loop:
}
}
@@ -2498,6 +2494,22 @@
% \end{macro}
% \end{macro}
%
+% \begin{macro}{\xparse_grab_v_aux_put:N}
+% Storing one token in the collected argument. Most tokens are
+% converted to category code $12$, with the exception of active
+% characters, and spaces (not sure what should be done for those).
+% \begin{macrocode}
+\cs_new_protected:Npn \xparse_grab_v_aux_put:N #1
+ {
+ \tl_put_right:Nx \l_xparse_v_arg_tl
+ {
+ \token_if_active:NTF #1
+ { \exp_not:N #1 } { \token_to_str:N #1 }
+ }
+ }
+% \end{macrocode}
+% \end{macro}
+%
% \begin{macro}{\xparse_grab_v_token_if_char:NTF}
% This function assumes that the escape character is printable.
% Then the string representation of control sequences is at least
@@ -2794,7 +2806,7 @@
% \begin{macrocode}
\cs_new:Npn \xparse_grab_expandable_end:wN #1 \q_xparse #2 {#1}
% \end{macrocode}
-%\end{macro}
+% \end{macro}
%
% \subsection{Argument processors}
%
@@ -2816,7 +2828,7 @@
\cs_new_protected:Npn \xparse_process_to_str:n #1
{ \tl_set:Nx \ProcessedArgument { \tl_to_str:n {#1} } }
% \end{macrocode}
-%\end{macro}
+% \end{macro}
%
% \begin{macro}{\xparse_bool_reverse:N}
% A simple reversal.
@@ -2830,71 +2842,6 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\l_xparse_split_argument_tl}
-% \begin{macro}{\xparse_split_argument:nnn}
-% \begin{macro}[aux]{\xparse_split_argument_aux_i:w}
-% \begin{macro}[aux]{\xparse_split_argument_aux_ii:w}
-% \begin{macro}[aux]{\xparse_split_argument_aux_iii:w}
-% The idea of this function is to split the input $n + 1$ times using
-% a given token.
-% \begin{macrocode}
-\tl_new:N \l_xparse_split_argument_tl
-\group_begin:
- \char_set_catcode_active:N \@
- \cs_new_protected:Npn \xparse_split_argument:nnn #1#2#3
- {
- \tl_set:Nn \l_xparse_split_argument_tl {#3}
- \group_begin:
- \char_set_lccode:nn { `\@ } { `#2}
- \tl_to_lowercase:n
- {
- \group_end:
- \tl_replace_all:Nnn \l_xparse_split_argument_tl { @ } {#2}
- }
- \cs_set_protected:Npn \xparse_split_argument_aux_i:w
- ##1 \q_mark ##2 #2 ##3 \q_stop
- {
- \tl_put_right:Nn \ProcessedArgument { {##2} }
- ##1 \q_mark ##3 \q_stop
- }
- \cs_set_protected:Npn \xparse_split_argument_aux_iii:w
- ##1 #2 ##2 \q_stop
- {
- \IfNoValueF {##1}
- {
- \msg_kernel_error:nnxxx { xparse } { split-excess-tokens }
- { \tl_to_str:n {#2} } { \tl_to_str:n {#1} }
- { \tl_to_str:n {#3} }
- }
- }
- \tl_set:Nx \l_xparse_tmp_tl
- {
- \prg_replicate:nn { #1 + 1 }
- { \xparse_split_argument_aux_i:w }
- \xparse_split_argument_aux_ii:w
- \exp_not:N \q_mark
- \exp_not:o \l_xparse_split_argument_tl
- \prg_replicate:nn {#1} { \exp_not:n {#2} \NoValue }
- \exp_not:n { #2 \q_stop }
- }
- \l_xparse_tmp_tl
- }
-\group_end:
-\cs_new_protected:Npn \xparse_split_argument_aux_i:w { }
-\cs_new_protected:Npn \xparse_split_argument_aux_ii:w
- #1 \q_mark #2 \q_stop
- {
- \tl_if_empty:nF {#2}
- { \xparse_split_argument_aux_iii:w #2 \q_stop }
- }
-\cs_new_protected:Npn \xparse_split_argument_aux_iii:w { }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-%
% \begin{variable}{\l_xparse_split_list_seq, \l_xparse_split_list_tl}
% \begin{macro}{\xparse_split_list:nn}
% \begin{macro}[aux]{\xparse_split_list_multi:nn, \xparse_split_list_multi:nV}
@@ -2910,7 +2857,7 @@
\bool_if:nTF
{
\tl_if_single_p:n {#1} &&
- ! (\token_if_cs_p:N #1 )
+ ! ( \token_if_cs_p:N #1 )
}
{ \xparse_split_list_single:Nn #1 {#2} }
{ \xparse_split_list_multi:nn {#1} {#2} }
@@ -2944,6 +2891,68 @@
% \end{macro}
% \end{variable}
%
+% \begin{macro}{\xparse_split_argument:nnn}
+% \begin{macro}[aux]{\xparse_split_argument_aux:nnnn}
+% \begin{macro}[aux, EXP]{\xparse_split_argument_aux:n}
+% \begin{macro}[aux, EXP]{\xparse_split_argument_aux:wn}
+% Splitting to a known number of items is a special version of splitting
+% a list, in which the limit is hard-coded and where there will always be
+% exactly the correct number of output items. An auxiliary function is
+% used to save on working out the token list length several times.
+% \begin{macrocode}
+\cs_new_protected:Npn \xparse_split_argument:nnn #1#2#3
+ {
+ \xparse_split_list:nn {#2} {#3}
+ \exp_args:Nf \xparse_split_argument_aux:nnnn
+ { \tl_length:N \ProcessedArgument }
+ {#1} {#2} {#3}
+ }
+\cs_new_protected:Npn \xparse_split_argument_aux:nnnn #1#2#3#4
+ {
+ \int_compare:nNnF {#1} = { #2 + \c_one }
+ {
+ \int_compare:nNnTF {#1} > { #2 + \c_one }
+ {
+ \tl_set:Nx \ProcessedArgument
+ {
+ \exp_last_unbraced:NnNo
+ \xparse_split_argument_aux:n
+ { #2 + \c_one }
+ \use_none_delimit_by_q_stop:w
+ \ProcessedArgument
+ \q_stop
+ }
+ \msg_kernel_error:nnxxx { xparse } { split-excess-tokens }
+ { \tl_to_str:n {#3} } { \int_eval:n { #2 + \c_one } }
+ { \tl_to_str:n {#4} }
+ }
+ {
+ \tl_put_right:Nx \ProcessedArgument
+ {
+ \prg_replicate:nn { #2 + \c_one - (#1) }
+ { { \exp_not:n { \NoValue } } }
+ }
+ }
+ }
+ }
+% \end{macrocode}
+% Auxiliaries to leave exactly the correct number of arguments in
+% \cs{ProcessedArgument}.
+% \begin{macrocode}
+\cs_new:Npn \xparse_split_argument_aux:n #1
+ { \prg_replicate:nn {#1} { \xparse_split_argument_aux:wn } }
+\cs_new:Npn \xparse_split_argument_aux:wn #1 \use_none_delimit_by_q_stop:w #2
+ {
+ \exp_not:n { {#2} }
+ #1
+ \use_none_delimit_by_q_stop:w
+ }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
% \begin{macro}{\xparse_trim_spaces:n}
% This one is almost trivial.
% \begin{macrocode}
@@ -2987,11 +2996,10 @@
% \begin{macro}{\xparse_show_arg_spec:N}
% \begin{macro}{\xparse_show_arg_spec:n}
% Showing the argument specification simply means finding it and then
-% calling the \cs{tl_show:c} function.
+% calling the \cs{tl_show:N} function.
% \begin{macrocode}
\cs_new_protected:Npn \xparse_show_arg_spec:N #1
{
- \tl_set:Nx \l_xparse_function_tl { \cs_to_str:N #1 }
\prop_get:NnNTF \l_xparse_command_arg_specs_prop {#1}
\ArgumentSpecification
{ \tl_show:N \ArgumentSpecification }
@@ -3026,16 +3034,16 @@
%
% \subsection{Messages}
%
-%\subsection{Messages}
+% \subsection{Messages}
%
% Some messages intended as errors.
% \begin{macrocode}
-\msg_kernel_new:nnnn { xparse } { bad-signature }
- { Bad~signature~'#1'. }
+\msg_kernel_new:nnnn { xparse } { bad-arg-spec }
+ { Bad~argument~specification~'#1'. }
{
\c_msg_coding_error_text_tl
- The~signature~provided~was~not~valid:~one~or~more~mandatory~pieces~
- of~information~were~missing. \\ \\
+ The~argument~specification~provided~was~not~valid:~
+ one~or~more~mandatory~pieces~of~information~were~missing. \\ \\
LaTeX~will~ignore~this~entire~definition.
}
\msg_kernel_new:nnnn { xparse } { command-already-defined }
@@ -3080,7 +3088,7 @@
The~command~will~be~ignored.
}
\msg_kernel_new:nnnn { xparse } { expandable-ending-optional }
- { Signature~for~expandable~command~ends~with~optional~argument. }
+ { Argument~specification~for~expandable~command~ends~with~optional~argument. }
{
\c_msg_coding_error_text_tl
Expandable~commands~must~have~a~final~mandatory~argument~
@@ -3114,8 +3122,8 @@
{ Argument~delimiter~should~be~a~single~token:~'#1'. }
{
\c_msg_coding_error_text_tl
- The~signature~provided~was~not~valid:~in~a~place~where~a~single~token~is~
- required,~LaTeX~found~'#1'. \\ \\
+ The~argument~specification~provided~was~not~valid:~
+ in~a~place~where~a~single~token~is~required,~LaTeX~found~'#1'. \\ \\
LaTeX~will~ignore~this~entire~definition.
}
\msg_kernel_new:nnnn { xparse } { processor-in-expandable }
@@ -3314,7 +3322,7 @@
% \begin{macrocode}
\cs_new_protected:Npn \NoValue { -NoValue- }
% \end{macrocode}
-%\end{variable}
+% \end{variable}
%
% \begin{macro}{\ProcessedArgument}
% Processed arguments are returned using this name, which is reserved