summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3candidates.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3candidates.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3candidates.dtx258
1 files changed, 86 insertions, 172 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3candidates.dtx b/Master/texmf-dist/source/latex/l3kernel/l3candidates.dtx
index e144922e224..1eaf1bdeb0f 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3candidates.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3candidates.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-%% File: l3candidates.dtx Copyright(C) 2012 The LaTeX3 Project
+%% File: l3candidates.dtx Copyright(C) 2012,2013 The LaTeX3 Project
%%
%% It may be distributed and/or modified under the conditions of the
%% LaTeX Project Public License (LPPL), either version 1.3c of this
@@ -36,7 +36,7 @@
%
%<*driver|package>
\RequirePackage{l3bootstrap}
-\GetIdInfo$Id: l3candidates.dtx 4468 2013-03-14 20:30:45Z joseph $
+\GetIdInfo$Id: l3candidates.dtx 4521 2013-07-09 11:45:31Z joseph $
{L3 Experimental additions to l3kernel}
%</driver|package>
%<*driver>
@@ -264,7 +264,7 @@
%
% \section{Additions to \pkg{l3clist}}
%
-% \begin{function}{\clist_item:Nn, \clist_item:cn, \clist_item:nn}
+% \begin{function}[EXP]{\clist_item:Nn, \clist_item:cn, \clist_item:nn}
% \begin{syntax}
% \cs{clist_item:Nn} \meta{comma list} \Arg{integer expression}
% \end{syntax}
@@ -326,37 +326,6 @@
% is not empty.
% \end{function}
%
-% \begin{function}[EXP, added = 2012-06-26]{\clist_use:Nnnn}
-% \begin{syntax}
-% \cs{clist_use:Nnnn} \meta{clist~var} \Arg{separator~between~two} \Arg{separator~between~more~than~two} \Arg{separator~between~final~two}
-% \end{syntax}
-% Places the contents of the \meta{clist~var} in the input stream,
-% with the appropriate \meta{separator} between the items. Namely, if
-% the comma list has more than $2$ items, the \meta{separator between
-% more than two} is placed between each pair of items except the
-% last, for which the \meta{separator between final two} is used. If
-% the comma list has $2$ items, then they are placed in the input
-% stream separated by the \meta{separator between two}. If the comma
-% list has $1$ item, it is placed in the input stream, and a comma
-% list with no items produces no output. An error will be raised if
-% the variable does not exist or if it is invalid.
-%
-% For example,
-% \begin{verbatim}
-% \clist_set:Nn \l_tmpa_clist { a , b , , c , {de} , f }
-% \clist_use:Nnnn \l_tmpa_clist { ~and~ } { ,~ } { ,~and~ }
-% \end{verbatim}
-% will insert \enquote{\texttt{a, b, c, de, and f}} in the input
-% stream. The first separator argument is not used in this case
-% because the comma list has more than $2$ items.
-% \begin{texnote}
-% The result is returned within the \tn{unexpanded}
-% primitive (\cs{exp_not:n}), which means that the \meta{items}
-% will not expand further when appearing in an \texttt{x}-type
-% argument expansion.
-% \end{texnote}
-% \end{function}
-%
% \section{Additions to \pkg{l3coffins}}
%
% \begin{function}{\coffin_resize:Nnn, \coffin_resize:cnn}
@@ -622,38 +591,45 @@
% \end{texnote}
% \end{function}
%
-% \begin{function}[EXP, added = 2012-06-26]{\seq_use:Nnnn}
+% \section{Additions to \pkg{l3skip}}
+%
+% \begin{function}[added = 2013-05-06, EXP]{\dim_to_pt:n}
% \begin{syntax}
-% \cs{seq_use:Nnnn} \meta{seq~var} \Arg{separator~between~two} \Arg{separator~between~more~than~two} \Arg{separator~between~final~two}
+% \cs{dim_to_pt:n} \Arg{dimexpr}
% \end{syntax}
-% Places the contents of the \meta{seq~var} in the input stream, with
-% the appropriate \meta{separator} between the items. Namely, if the
-% sequence has more than $2$ items, the \meta{separator between more
-% than two} is placed between each pair of items except the last,
-% for which the \meta{separator between final two} is used. If the
-% sequence has $2$ items, then they are placed in the input stream
-% separated by the \meta{separator between two}. If the sequence has
-% $1$ item, it is placed in the input stream, and an empty sequence
-% produces no output. An error will be raised if the variable does
-% not exist or if it is invalid.
-%
-% For example,
+% Evaluates the \meta{dimension expression}, and leaves the result,
+% expressed in points (\texttt{pt}) in the input stream, with \emph{no
+% units}. The result is rounded by \TeX{} to four or five decimal
+% places. If the decimal part of the result is zero, it is omitted,
+% together with the decimal marker.
+%
+% If the \meta{dimension expression} contains additional tokens such
+% as redundant units, these will be ignored, so for example
% \begin{verbatim}
-% \seq_set_split:Nnn \l_tmpa_seq { | } { a | b | c | {de} | f }
-% \seq_use:Nnnn \l_tmpa_seq { ~and~ } { ,~ } { ,~and~ }
+% \dim_to_pt:n { 1 bp pt }
% \end{verbatim}
-% will insert \enquote{\texttt{a, b, c, de, and f}} in the input
-% stream. The first separator argument is not used in this case
-% because the sequence has more than $2$ items.
-% \begin{texnote}
-% The result is returned within the \tn{unexpanded}
-% primitive (\cs{exp_not:n}), which means that the \meta{items}
-% will not expand further when appearing in an \texttt{x}-type
-% argument expansion.
-% \end{texnote}
+% leaves |1.00374| in the input stream, \emph{i.e.}~the magnitude of
+% one \enquote{big point} when converted to points.
% \end{function}
%
-% \section{Additions to \pkg{l3skip}}
+% \begin{function}[added = 2013-05-06, EXP]{\dim_to_unit:nn}
+% \begin{syntax}
+% \cs{dim_to_unit:nn} \Arg{dimexpr_1} \Arg{dimexpr_2}
+% \end{syntax}
+% Evaluates the \meta{dimension expressions}, and leaves the value of
+% \meta{dimexpr_1}, expressed in a unit given by \meta{dimexpr_2}, in
+% the input stream. The result is a decimal number, rounded by \TeX{}
+% to four or five decimal places. If the decimal part of the result
+% is zero, it is omitted, together with the decimal marker.
+%
+% If the \meta{dimension expressions} contain additional tokens such
+% as redundant units, these will be ignored, so for example
+% \begin{verbatim}
+% \dim_to_unit:nn { 1 bp pt } { 1 mm }
+% \end{verbatim}
+% leaves |0.35277| in the input stream, \emph{i.e.}~the magnitude of
+% one \enquote{big point} when converted to millimeters.
+% \end{function}
%
% \begin{function}{\skip_split_finite_else_action:nnNN}
% \begin{syntax}
@@ -940,8 +916,8 @@
% The next step is to work out the $x$ and $y$ coordinates of vertices of
% the rotated box in relation to its original coordinates. The box can be
% visualized with vertices $B$, $C$, $D$ and $E$ is illustrated
-% (Figure~\ref{fig:rotation}). The vertex $O$ is the reference point on the
-% baseline, and in this implementation is also the centre of rotation.
+% (Figure~\ref{fig:l3candidates:rotation}). The vertex $O$ is the reference point
+% on the baseline, and in this implementation is also the centre of rotation.
% \begin{figure}
% \centering
% \setlength{\unitlength}{3pt}^^A
@@ -958,7 +934,7 @@
% \put(21,59){O}
% \end{picture}
% \caption{Co-ordinates of a box prior to rotation.}
-% \label{fig:rotation}
+% \label{fig:l3candidates:rotation}
% \end{figure}
% The formulae are, for a point $P$ and angle $\alpha$:
% \[
@@ -1602,7 +1578,7 @@
% any argument: this avoids losing braces. The argument
% of \cs{tl_if_empty:oTF} is empty if |#1| is |?| followed
% by blank spaces (besides, this particular variant of
-% the emptyness test is optimized). If the item of the
+% the emptiness test is optimized). If the item of the
% comma list is blank, grab the next one. As soon as one
% item is non-blank, exit: the second auxiliary will grab
% \cs{prg_return_false:} as |#2|, unless every item in
@@ -1628,62 +1604,6 @@
% \end{macro}
% \end{macro}
%
-% \begin{macro}[EXP]{\clist_use:Nnnn}
-% \begin{macro}[EXP, aux]
-% {\@@_use:wwn, \@@_use:nwwwwnwn, \@@_use:nwwn}
-% First check that the variable exists. Then count the items in the
-% comma list. If it has none, output nothing. If it has one item,
-% output that item, brace stripped (note that space-trimming has
-% already been done when the comma list was assigned). If it has two,
-% place the \meta{separator~between~two} in the middle.
-%
-% Otherwise, \cs{@@_use:nwwwwnwn} takes the following arguments; 1:
-% a \meta{separator}, 2, 3, 4: three items from the comma list (or
-% quarks), 5: the rest of the comma list, 6: a \meta{continuation}
-% function (\texttt{use_ii} or \texttt{use_iii} with its
-% \meta{separator} argument), 7: junk, and 8: the temporary result,
-% which is built in a brace group following \cs{q_stop}. The
-% \meta{separator} and the first of the three items are placed in the
-% result, then we use the \meta{continuation}, placing the remaining
-% two items after it. When we begin this loop, the three items really
-% belong to the comma list, the first \cs{q_mark} is taken as a
-% delimiter to the \texttt{use_ii} function, and the continuation is
-% \texttt{use_ii} itself. When we reach the last two items of the
-% original token list, \cs{q_mark} is taken as a third item, and now
-% the seconf \cs{q_mark} serves as a delimiter to \texttt{use_ii},
-% switching to the other \meta{continuation}, \texttt{use_iii}, which
-% uses the \meta{separator between final two}.
-% \begin{macrocode}
-\cs_new:Npn \clist_use:Nnnn #1#2#3#4
- {
- \clist_if_exist:NTF #1
- {
- \int_case:nnn { \clist_count:N #1 }
- {
- { 0 } { }
- { 1 } { \exp_after:wN \@@_use:wwn #1 , , { } }
- { 2 } { \exp_after:wN \@@_use:wwn #1 , {#2} }
- }
- {
- \exp_after:wN \@@_use:nwwwwnwn
- \exp_after:wN { \exp_after:wN } #1 ,
- \q_mark , { \@@_use:nwwwwnwn {#3} }
- \q_mark , { \@@_use:nwwn {#4} }
- \q_stop { }
- }
- }
- { \__msg_kernel_expandable_error:nnn { kernel } { bad-variable } {#1} }
- }
-\cs_new:Npn \@@_use:wwn #1 , #2 , #3 { \exp_not:n { #1 #3 #2 } }
-\cs_new:Npn \@@_use:nwwwwnwn
- #1#2 , #3 , #4 , #5 \q_mark , #6#7 \q_stop #8
- { #6 {#3} , {#4} , #5 \q_mark , {#6} #7 \q_stop { #8 #1 #2 } }
-\cs_new:Npn \@@_use:nwwn #1#2 , #3 \q_stop #4
- { \exp_not:n { #4 #1 #2 } }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
% \subsection{Additions to \pkg{l3coffins}}
%
% \begin{macrocode}
@@ -2260,25 +2180,24 @@
% \end{macro}
%
% \begin{macro}[EXP]{\prop_get:Nn, \prop_get:cn}
-% \begin{macro}[aux, EXP]{\@@_get:Nn, \@@_get:No}
% \begin{macro}[aux, EXP]{\@@_get_Nn:nwn}
% Getting the value corresponding to a key in a property list in an
-% expandable fashion is a simple instance of mapping some tokens.
-% Map the function \cs{prop_get:nnn} which takes as its three
-% arguments the \meta{key} that we are looking for, the current
-% \meta{key} and the current \meta{value}. If the \meta{keys} match,
-% the \meta{value} is returned. If none of the keys match, this expands
-% to nothing.
+% expandable fashion is similar to mapping some tokens. Go through
+% the property list one \meta{key}--\meta{value} pair at a time: the
+% arguments of \cs{@@_get_Nn:nwn} are the \meta{key} we are looking
+% for, a \meta{key} of the property list, and its associated value.
+% The \meta{keys} are compared (as strings). If they match, the
+% \meta{value} is returned, within \cs{exp_not:n}. The loop
+% terminates even if the \meta{key} is missing, and yields an empty
+% value, because we have appended the appropriate
+% \meta{key}--\meta{empty value} pair to the property list.
% \begin{macrocode}
\cs_new:Npn \prop_get:Nn #1#2
- { \@@_get:No #1 { \tl_to_str:n {#2} } }
-\cs_new:Npn \@@_get:Nn #1#2
{
- \exp_last_unbraced:Nno \@@_get_Nn:nwn {#2} #1
- \s_@@ #2 \s_@@ { }
+ \exp_last_unbraced:Noo \@@_get_Nn:nwn { \tl_to_str:n {#2} } #1
+ \s_@@ \tl_to_str:n {#2} \s_@@ { }
\__prg_break_point:
}
-\cs_generate_variant:Nn \@@_get:Nn { No }
\cs_new:Npn \@@_get_Nn:nwn #1 \s_@@ #2 \s_@@ #3
{
\str_if_eq_x:nnTF {#1} {#2}
@@ -2289,7 +2208,6 @@
% \end{macrocode}
% \end{macro}
% \end{macro}
-% \end{macro}
%
% \subsection{Additions to \pkg{l3seq}}
%
@@ -2531,50 +2449,46 @@
% \end{macro}
% \end{macro}
%
-% \begin{macro}[EXP]{\seq_use:Nnnn}
-% \begin{macro}[EXP, aux]
-% {\@@_use:NnNnn, \@@_use:nwwwwnwn, \@@_use:nwwn}
-% See \cs{clist_use:Nnnn} for a general explanation. The main
-% difference is that we use \cs{@@_item:n} as a delimiter rather than
-% commas. We also need to add \cs{@@_item:n} at various places.
+% \subsection{Additions to \pkg{l3skip}}
+%
+% \begin{macrocode}
+%<@@=dim>
+% \end{macrocode}
+%
+% \begin{macro}[EXP]{\dim_to_pt:n}
+% A copy of the internal function \cs{@@_strip_pt:n}, which should
+% perhaps be eliminated in favor of \cs{dim_to_pt:n}.
% \begin{macrocode}
-\cs_new:Npn \seq_use:Nnnn #1#2#3#4
+\cs_new_eq:NN \dim_to_pt:n \@@_strip_pt:n
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}[EXP]{\dim_to_unit:nn}
+% \begin{macro}[aux, EXP]{\@@_to_unit:n}
+% An analog of \cs{dim_ratio:nn} that produces a decimal number as its
+% result, rather than a rational fraction for use within dimension
+% expressions. The naive implementation as
+% \begin{verbatim}
+% \cs_new:Npn \dim_to_unit:nn #1#2
+% { \dim_to_pt:n { 1pt * \dim_ratio:nn {#1} {#2} } }
+% \end{verbatim}
+% would not ignore trailing tokens (see documentation), so we need a
+% bit more work.
+% \begin{macrocode}
+\cs_new:Npn \dim_to_unit:nn #1#2
{
- \seq_if_exist:NTF #1
+ \dim_to_pt:n
{
- \int_case:nnn { \seq_count:N #1 }
- {
- { 0 } { }
- { 1 } { \exp_after:wN \@@_use:NnNnn #1 \@@_item:n { } { } }
- { 2 } { \exp_after:wN \@@_use:NnNnn #1 {#2} }
- }
- {
- \exp_after:wN \@@_use:nwwwwnwn
- \exp_after:wN { \exp_after:wN } #1 \@@_item:n
- \q_mark { \@@_use:nwwwwnwn {#3} }
- \q_mark { \@@_use:nwwn {#4} }
- \q_stop { }
- }
+ 1pt * \@@_to_unit:n { \dim_to_pt:n {#1} pt }
+ / \@@_to_unit:n { \dim_to_pt:n {#2} pt }
}
- { \__msg_kernel_expandable_error:nnn { kernel } { bad-variable } {#1} }
}
-\cs_new:Npn \@@_use:NnNnn \@@_item:n #1 \@@_item:n #2#3
- { \exp_not:n { #1 #3 #2 } }
-\cs_new:Npn \@@_use:nwwwwnwn
- #1 \@@_item:n #2 \@@_item:n #3 \@@_item:n #4#5
- \q_mark #6#7 \q_stop #8
- {
- #6 \@@_item:n {#3} \@@_item:n {#4} #5
- \q_mark {#6} #7 \q_stop { #8 #1 #2 }
- }
-\cs_new:Npn \@@_use:nwwn #1 \@@_item:n #2 #3 \q_stop #4
- { \exp_not:n { #4 #1 #2 } }
+\cs_new:Npn \@@_to_unit:n #1
+ { \__int_value:w \@@_eval:w #1 \@@_eval_end: }
% \end{macrocode}
% \end{macro}
% \end{macro}
%
-% \subsection{Additions to \pkg{l3skip}}
-%
% \begin{macrocode}
%<@@=skip>
% \end{macrocode}
@@ -2613,7 +2527,7 @@
% There are four cases: empty token list, token list starting with
% a normal token, with a brace group, or with a space token.
% If the token list starts with a normal token, remove it
-% and check for emptyness. Otherwise, compare with a single
+% and check for emptiness. Otherwise, compare with a single
% space, only case where we have a single token.
% \begin{macrocode}
\prg_new_conditional:Npnn \tl_if_single_token:n #1 { p , T , F , TF }
@@ -2668,7 +2582,7 @@
% \begin{macro}[EXP]{\tl_count_tokens:n}
% \begin{macro}[EXP,aux]{\@@_act_count_normal:nN,
% \@@_act_count_group:nn,\@@_act_count_space:n}
-% The token coung is computed through an \cs{int_eval:n} construction.
+% The token count is computed through an \cs{int_eval:n} construction.
% Each \texttt{1+} is output to the \emph{left}, into the integer
% expression, and the sum is ended by the \cs{c_zero} inserted by
% \cs{@@_act_end:wn}. Somewhat a hack.
@@ -2694,7 +2608,7 @@
% \end{macro}
%
% \begin{variable}{\c_@@_act_uppercase_tl, \c_@@_act_lowercase_tl}
-% These constants contain the correspondance between lowercase
+% These constants contain the correspondence between lowercase
% and uppercase letters, in the form |aAbBcC...| and |AaBbCc...|
% respectively.
% \begin{macrocode}
@@ -2715,7 +2629,7 @@
% \begin{macro}[EXP,aux]{\@@_act_case_normal:nN,
% \@@_act_case_group:nn,\@@_act_case_space:n}
% The only difference between uppercasing and lowercasing is
-% the table of correspondance that is used. As for other
+% the table of correspondence that is used. As for other
% token list actions, we feed \cs{@@_act:NNNnn} three
% functions, and this time, we use the \meta{parameters}
% argument to carry which case-changing we are applying.