summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/expl3/l3basics.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2010-03-31 00:04:47 +0000
committerKarl Berry <karl@freefriends.org>2010-03-31 00:04:47 +0000
commit3ab55a61f6f8d2218a8f3175bc7481ce162b60d3 (patch)
treef606e0c2117a8058213441400e50ba25400ba94a /Master/texmf-dist/source/latex/expl3/l3basics.dtx
parent035ea73193af75f6ade46e306603e61d82b24950 (diff)
expl3 1881 (30mar10)
git-svn-id: svn://tug.org/texlive/trunk@17631 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/expl3/l3basics.dtx')
-rw-r--r--Master/texmf-dist/source/latex/expl3/l3basics.dtx120
1 files changed, 82 insertions, 38 deletions
diff --git a/Master/texmf-dist/source/latex/expl3/l3basics.dtx b/Master/texmf-dist/source/latex/expl3/l3basics.dtx
index f49489bd17f..d4466987e6d 100644
--- a/Master/texmf-dist/source/latex/expl3/l3basics.dtx
+++ b/Master/texmf-dist/source/latex/expl3/l3basics.dtx
@@ -35,7 +35,7 @@
\RequirePackage{l3names}
%</driver|package>
%\fi
-\GetIdInfo$Id: l3basics.dtx 1700 2009-11-04 21:15:58Z joseph $
+\GetIdInfo$Id: l3basics.dtx 1853 2010-03-21 09:11:08Z joseph $
{L3 Experimental basic definitions}
%\iffalse
%<*driver>
@@ -438,13 +438,25 @@
% \begin{syntax}
% "\use:c" \Arg{cs}
% \end{syntax}
-% Function that returns to the input stream the control sequence created from
+% Function that returns to the input stream the control sequence created from
% its argument. Requires two expansions before a control sequence is returned.
% \begin{texnote}
% "\use:c" is \LaTeXe's "\@nameuse".
% \end{texnote}
% \end{function}
%
+% \begin{function}{ \use:x }
+% \begin{syntax}
+% "\use:x" \Arg{expandable tokens}
+% \end{syntax}
+% Function that fully expands its argument before passing it to the input
+% stream. Contents of the argument must be fully expandable.
+% \begin{texnote}
+% Lua\TeX\ provides "\expanded" which performs this operation in an expandable
+% manner, but we cannot assume this behaviour on all platforms yet.
+% \end{texnote}
+% \end{function}
+%
% \begin{function}{ \use_none:n / (EXP) |
% \use_none:nn / (EXP) |
% \use_none:nnn / (EXP) |
@@ -1113,14 +1125,20 @@
%
% \subsection{Undefining functions}
%
-% \begin{function}{
+% \begin{function}{
+% \cs_undefine:N |
+% \cs_undefine:c |
% \cs_gundefine:N |
% \cs_gundefine:c
% }
% \begin{syntax}
% "\cs_gundefine:N" <cs>
% \end{syntax}
-% Undefines the control sequence globally.
+% Undefines the control sequence locally or globally.
+% In a global context, this is useful for reclaiming a small amount of
+% memory but shouldn't often be needed for this purpose.
+% In a local context, this can be useful if you need to clear a definition
+% before applying a short-term modification to something.
% \end{function}
%
%
@@ -1603,6 +1621,20 @@
% \end{macrocode}
% \end{macro}
%
+% \begin{macro}{\use:x}
+% Fully expands its argument and passes it to the input stream.
+% Uses "\cs_tmp:" as a scratch register but does not affect it.
+% \begin{macrocode}
+\cs_set_protected:Npn \use:x #1 {
+ \group_begin:
+ \cs_set:Npx \cs_tmp: {#1}
+ \exp_args:wN
+ \group_end:
+ \cs_tmp:
+}
+% \end{macrocode}
+% \end{macro}
+%
% \begin{macro}{\use:n}
% \begin{macro}{\use:nn}
% \begin{macro}{\use:nnn}
@@ -1825,25 +1857,25 @@
% function into name and signature and then use, e.g., |\cs_set:Npn|
% to define it with.
% \begin{macrocode}
-\cs_set:Npn \prg_set_conditional:Npnn #1{
+\cs_set_protected:Npn \prg_set_conditional:Npnn #1{
\prg_get_parm_aux:nw{
\cs_split_function:NN #1 \prg_generate_conditional_aux:nnNNnnnn
\cs_set:Npn {parm}
}
}
-\cs_set:Npn \prg_new_conditional:Npnn #1{
+\cs_set_protected:Npn \prg_new_conditional:Npnn #1{
\prg_get_parm_aux:nw{
\cs_split_function:NN #1 \prg_generate_conditional_aux:nnNNnnnn
\cs_new:Npn {parm}
}
}
-\cs_set:Npn \prg_set_protected_conditional:Npnn #1{
+\cs_set_protected:Npn \prg_set_protected_conditional:Npnn #1{
\prg_get_parm_aux:nw{
\cs_split_function:NN #1 \prg_generate_conditional_aux:nnNNnnnn
\cs_set_protected:Npn {parm}
}
}
-\cs_set:Npn \prg_new_protected_conditional:Npnn #1{
+\cs_set_protected:Npn \prg_new_protected_conditional:Npnn #1{
\prg_get_parm_aux:nw{
\cs_split_function:NN #1 \prg_generate_conditional_aux:nnNNnnnn
\cs_new_protected:Npn {parm}
@@ -1860,27 +1892,27 @@
% into name and signature and then use, e.g., |\cs_set:Npn| to
% define it with.
% \begin{macrocode}
-\cs_set:Npn \prg_set_conditional:Nnn #1{
+\cs_set_protected:Npn \prg_set_conditional:Nnn #1{
\exp_args:Nnf \prg_get_count_aux:nn{
\cs_split_function:NN #1 \prg_generate_conditional_aux:nnNNnnnn
\cs_set:Npn {count}
}{\cs_get_arg_count_from_signature:N #1}
}
-\cs_set:Npn \prg_new_conditional:Nnn #1{
+\cs_set_protected:Npn \prg_new_conditional:Nnn #1{
\exp_args:Nnf \prg_get_count_aux:nn{
\cs_split_function:NN #1 \prg_generate_conditional_aux:nnNNnnnn
\cs_new:Npn {count}
}{\cs_get_arg_count_from_signature:N #1}
}
-\cs_set:Npn \prg_set_protected_conditional:Nnn #1{
+\cs_set_protected:Npn \prg_set_protected_conditional:Nnn #1{
\exp_args:Nnf \prg_get_count_aux:nn{
\cs_split_function:NN #1 \prg_generate_conditional_aux:nnNNnnnn
\cs_set_protected:Npn {count}
}{\cs_get_arg_count_from_signature:N #1}
}
-\cs_set:Npn \prg_new_protected_conditional:Nnn #1{
+\cs_set_protected:Npn \prg_new_protected_conditional:Nnn #1{
\exp_args:Nnf \prg_get_count_aux:nn{
\cs_split_function:NN #1 \prg_generate_conditional_aux:nnNNnnnn
\cs_new_protected:Npn {count}
@@ -1892,10 +1924,10 @@
% \begin{macro}{\prg_set_eq_conditional:NNn,\prg_new_eq_conditional:NNn}
% The obvious setting-equal functions.
% \begin{macrocode}
-\cs_set:Npn \prg_set_eq_conditional:NNn #1#2#3 {
+\cs_set_protected:Npn \prg_set_eq_conditional:NNn #1#2#3 {
\prg_set_eq_conditional_aux:NNNn \cs_set_eq:cc #1#2 {#3}
}
-\cs_set:Npn \prg_new_eq_conditional:NNn #1#2#3 {
+\cs_set_protected:Npn \prg_new_eq_conditional:NNn #1#2#3 {
\prg_set_eq_conditional_aux:NNNn \cs_new_eq:cc #1#2 {#3}
}
% \end{macrocode}
@@ -2303,7 +2335,7 @@
% \begin{macro}{\c_sixteen}
% We need the constants |\c_minus_one| and |\c_sixteen| now for
% writing information to the log and the terminal and |\c_zero|
-% which is used by some functions in the \textsf{l3num}module. The
+% which is used by some functions in the \textsf{l3alloc} module. The
% rest are defined in the \textsf{l3int} module -- at least for the
% ones that can be defined with |\tex_chardef:D| or
% |\tex_mathchardef:D|. For other constants the \textsf{l3int} module is
@@ -2343,10 +2375,10 @@
% similar one for writing to both the log file and the terminal.
%
% \begin{macrocode}
-\cs_set_nopar:Npn \iow_log:x {
+\cs_set_protected_nopar:Npn \iow_log:x {
\tex_immediate:D \iow_shipout_x:Nn \c_minus_one
}
-\cs_set_nopar:Npn \iow_term:x {
+\cs_set_protected_nopar:Npn \iow_term:x {
\tex_immediate:D \iow_shipout_x:Nn \c_sixteen
}
% \end{macrocode}
@@ -2356,7 +2388,7 @@
% \begin{macro}{\msg_kernel_bug:x}
% This will show internal errors.
% \begin{macrocode}
-\cs_set_nopar:Npn \msg_kernel_bug:x #1 {
+\cs_set_protected_nopar:Npn \msg_kernel_bug:x #1 {
\iow_term:x { This~is~a~LaTeX~bug:~check~coding! }
\tex_errmessage:D {#1}
}
@@ -2383,7 +2415,7 @@
% issued. We have to make sure we don't put the argument into the
% conditional processing since it may be an |\if...| type function!
% \begin {macrocode}
-\cs_set_nopar:Npn \chk_if_free_cs:N #1{
+\cs_set_protected_nopar:Npn \chk_if_free_cs:N #1{
\cs_if_free:NF #1
{
\msg_kernel_bug:x {Command~name~`\token_to_str:N #1'~
@@ -2398,7 +2430,9 @@
line~\tex_the:D \tex_inputlineno:D}
%</trace>
}
-\cs_set_nopar:Npn \chk_if_free_cs:c { \exp_args:Nc \chk_if_free_cs:N }
+\cs_set_protected_nopar:Npn \chk_if_free_cs:c {
+ \exp_args:Nc \chk_if_free_cs:N
+}
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -2408,14 +2442,16 @@
% This function issues a warning message when the control sequence
% in its argument does not exist.
% \begin{macrocode}
-\cs_set_nopar:Npn \chk_if_exist_cs:N #1 {
+\cs_set_protected_nopar:Npn \chk_if_exist_cs:N #1 {
\cs_if_exist:NF #1
{
\msg_kernel_bug:x {Command~ `\token_to_str:N #1'~
not~ yet~ defined!}
}
}
-\cs_set_nopar:Npn \chk_if_exist_cs:c {\exp_args:Nc \chk_if_exist_cs:N }
+\cs_set_protected_nopar:Npn \chk_if_exist_cs:c {
+ \exp_args:Nc \chk_if_exist_cs:N
+}
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -2764,9 +2800,9 @@
%
% \begin{macrocode}
\cs_set_protected:Npn \cs_set_eq:NN #1 { \cs_set_eq:NwN #1=~ }
-\cs_set_nopar:Npn \cs_set_eq:cN { \exp_args:Nc \cs_set_eq:NN }
-\cs_set_nopar:Npn \cs_set_eq:Nc { \exp_args:NNc \cs_set_eq:NN }
-\cs_set_nopar:Npn \cs_set_eq:cc { \exp_args:Ncc \cs_set_eq:NN }
+\cs_set_protected_nopar:Npn \cs_set_eq:cN { \exp_args:Nc \cs_set_eq:NN }
+\cs_set_protected_nopar:Npn \cs_set_eq:Nc { \exp_args:NNc \cs_set_eq:NN }
+\cs_set_protected_nopar:Npn \cs_set_eq:cc { \exp_args:Ncc \cs_set_eq:NN }
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -2782,9 +2818,9 @@
\chk_if_free_cs:N #1
\cs_set_eq:NN #1
}
-\cs_new_nopar:Npn \cs_new_eq:cN { \exp_args:Nc \cs_new_eq:NN }
-\cs_new_nopar:Npn \cs_new_eq:Nc { \exp_args:NNc \cs_new_eq:NN }
-\cs_new_nopar:Npn \cs_new_eq:cc { \exp_args:Ncc \cs_new_eq:NN }
+\cs_new_protected_nopar:Npn \cs_new_eq:cN { \exp_args:Nc \cs_new_eq:NN }
+\cs_new_protected_nopar:Npn \cs_new_eq:Nc { \exp_args:NNc \cs_new_eq:NN }
+\cs_new_protected_nopar:Npn \cs_new_eq:cc { \exp_args:Ncc \cs_new_eq:NN }
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -2797,9 +2833,9 @@
% \begin{macro}{\cs_gset_eq:cc}
% \begin{macrocode}
\cs_new_protected:Npn \cs_gset_eq:NN { \pref_global:D \cs_set_eq:NN }
-\cs_new_nopar:Npn \cs_gset_eq:Nc { \exp_args:NNc \cs_gset_eq:NN }
-\cs_new_nopar:Npn \cs_gset_eq:cN { \exp_args:Nc \cs_gset_eq:NN }
-\cs_new_nopar:Npn \cs_gset_eq:cc { \exp_args:Ncc \cs_gset_eq:NN }
+\cs_new_protected_nopar:Npn \cs_gset_eq:Nc { \exp_args:NNc \cs_gset_eq:NN }
+\cs_new_protected_nopar:Npn \cs_gset_eq:cN { \exp_args:Nc \cs_gset_eq:NN }
+\cs_new_protected_nopar:Npn \cs_gset_eq:cc { \exp_args:Ncc \cs_gset_eq:NN }
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -2815,9 +2851,9 @@
\chk_if_free_cs:N #1
\pref_global:D \cs_set_eq:NN #1
}
-\cs_new_nopar:Npn \cs_gnew_eq:cN { \exp_args:Nc \cs_gnew_eq:NN }
-\cs_new_nopar:Npn \cs_gnew_eq:Nc { \exp_args:NNc \cs_gnew_eq:NN }
-\cs_new_nopar:Npn \cs_gnew_eq:cc { \exp_args:Ncc \cs_gnew_eq:NN }
+\cs_new_protected_nopar:Npn \cs_gnew_eq:cN { \exp_args:Nc \cs_gnew_eq:NN }
+\cs_new_protected_nopar:Npn \cs_gnew_eq:Nc { \exp_args:NNc \cs_gnew_eq:NN }
+\cs_new_protected_nopar:Npn \cs_gnew_eq:cc { \exp_args:Ncc \cs_gnew_eq:NN }
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -2827,13 +2863,21 @@
%
% \subsection{Undefining functions}
%
-% \begin{macro}{\cs_gundefine:N }
-% \begin{macro}{\cs_gundefine:c }
+% \begin{macro}{\cs_undefine:N , \cs_undefine:c }
+% \begin{macro}{\cs_gundefine:N , \cs_gundefine:c }
% The following function is used to free the main memory from the
% definition of some function that isn't in use any longer.
% \begin{macrocode}
-\cs_new_nopar:Npn \cs_gundefine:N #1{\cs_gset_eq:NN #1\c_undefined:D}
-\cs_new_nopar:Npn \cs_gundefine:c #1{
+\cs_new_protected_nopar:Npn \cs_undefine:N #1 {
+ \cs_set_eq:NN #1 \c_undefined:D
+}
+\cs_new_protected_nopar:Npn \cs_undefine:c #1 {
+ \cs_set_eq:cN {#1} \c_undefined:D
+}
+\cs_new_protected_nopar:Npn \cs_gundefine:N #1 {
+ \cs_gset_eq:NN #1 \c_undefined:D
+}
+\cs_new_protected_nopar:Npn \cs_gundefine:c #1 {
\cs_gset_eq:cN {#1} \c_undefined:D
}
% \end{macrocode}