diff options
author | Karl Berry <karl@freefriends.org> | 2012-02-28 00:40:31 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2012-02-28 00:40:31 +0000 |
commit | e20ea4bdd670e0418363a2a38a54b422a4d83231 (patch) | |
tree | e75e065101424a1535a03f6d071b8cc17d22eb2d /Master/texmf-dist/source/latex/l3packages/xparse | |
parent | ed49b3dfe19b91f9fd96ab70fe95dcda8fba24c8 (diff) |
l3packages 3471 (26feb12)
git-svn-id: svn://tug.org/texlive/trunk@25524 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/l3packages/xparse')
-rw-r--r-- | Master/texmf-dist/source/latex/l3packages/xparse/xparse.dtx | 264 |
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 |