From 0bc9393ae50667d7ff769a76321a9548a70351fc Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Thu, 29 Dec 2011 23:03:28 +0000 Subject: l3experimental 3109 (29dec11) git-svn-id: svn://tug.org/texlive/trunk@24970 c570f23f-e606-0410-a88d-b1316a301751 --- .../source/latex/l3experimental/l3str/l3flag.dtx | 236 +++++++++++++++++++++ 1 file changed, 236 insertions(+) create mode 100644 Master/texmf-dist/source/latex/l3experimental/l3str/l3flag.dtx (limited to 'Master/texmf-dist/source/latex/l3experimental/l3str/l3flag.dtx') diff --git a/Master/texmf-dist/source/latex/l3experimental/l3str/l3flag.dtx b/Master/texmf-dist/source/latex/l3experimental/l3str/l3flag.dtx new file mode 100644 index 00000000000..eed657ad231 --- /dev/null +++ b/Master/texmf-dist/source/latex/l3experimental/l3str/l3flag.dtx @@ -0,0 +1,236 @@ +% \iffalse meta-comment +% +%% File: l3flag.dtx Copyright (C) 2011 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 +%% license or (at your option) any later version. The latest version +%% of this license is in the file +%% +%% http://www.latex-project.org/lppl.txt +%% +%% This file is part of the "l3experimental bundle" (The Work in LPPL) +%% and all files in that bundle must be distributed together. +%% +%% The released version of this bundle is available from CTAN. +%% +%% ----------------------------------------------------------------------- +%% +%% The development version of the bundle can be found at +%% +%% http://www.latex-project.org/svnroot/experimental/trunk/ +%% +%% for those people who are interested. +%% +%%%%%%%%%%% +%% NOTE: %% +%%%%%%%%%%% +%% +%% Snapshots taken from the repository represent work in progress and may +%% not work or may contain conflicting material! We therefore ask +%% people _not_ to put them into distributions, archives, etc. without +%% prior consultation with the LaTeX3 Project. +%% +%% ----------------------------------------------------------------------- +% +%<*driver|package> +\RequirePackage{expl3} +\GetIdInfo$Id: l3flag.dtx 3039 2011-12-08 09:22:35Z bruno $ + {L3 Experimental Flags} +% +%<*driver> +\documentclass[full]{l3doc} +\usepackage{amsmath} +\begin{document} + \DocInput{\jobname.dtx} +\end{document} +% +% \fi +% +% +% \title{^^A +% The \textsf{l3flag} package: expandable flags^^A +% \thanks{This file describes v\ExplFileVersion, +% last revised \ExplFileDate.}^^A +% } +% +% \author{^^A +% The \LaTeX3 Project\thanks +% {^^A +% E-mail: +% \href{mailto:latex-team@latex-project.org} +% {latex-team@latex-project.org}^^A +% }^^A +% } +% +% \date{Released \ExplFileDate} +% +% \maketitle +% +% \begin{documentation} +% +% Flags are the only data structure on which \TeX{} can perform +% assignments in expansion only contexts. This module is meant +% mostly for kernel use: in almost all cases, booleans should +% be preferred to flags, because they are faster. +% +% A flag can be in two states: \enquote{lowered} or \enquote{raised}. +% The status of a flag can be tested expandably (just like booleans). +% A flag can also be \emph{raised} expandably. However, a flag cannot +% be lowered expandably. +% +% Flag variables are always local. +% +% Testing for the existence of flags with \cs{cs_if_exist:NTF} will +% always result in a negative answer: from the point of view of +% \TeX{}, flags are either undefined control sequences, or let to +% \cs{scan_stop:}. This has a second consequence: flags don't need +% to be declared with \cs{flag_new:N}, although this has error-checking +% benefits. The ability of using flags without declaring them is used +% in \pkg{l3rand}. +% +% \begin{function}{\flag_new:N, \flag_new:c} +% \begin{syntax} +% \cs{flag_new:N} \meta{flag} +% \end{syntax} +% Creates a new \meta{flag} or raises an error if the +% name is already taken. The declaration is global, +% but \meta{flags} are always local variables. +% The \meta{flag} will initially be lowered. +% \end{function} +% +% \begin{function}[EXP,pTF]{\flag_test:N, \flag_test:c} +% \begin{syntax} +% \cs{flag_test:N} \meta{flag} +% \end{syntax} +% This function returns \texttt{true} if the \meta{flag} is raised, +% and \texttt{false} if the \meta{flag} is lowered. +% \end{function} +% +% \begin{function}[EXP]{\flag_raise:N} +% \begin{syntax} +% \cs{flag_raise:N} \meta{flag} +% \end{syntax} +% The \meta{flag} is raised. The assignment is local. +% This function is expandable, despite being an assignment. +% \end{function} +% +% \begin{function}{\flag_lower:N} +% \begin{syntax} +% \cs{flag_lower:N} \meta{flag} +% \end{syntax} +% The \meta{flag} is lowered. The assignment is local. +% \end{function} +% +% \end{documentation} +% +% \begin{implementation} +% +% \section{\pkg{l3str} implementation} +% +% \begin{macrocode} +%<*initex|package> +% \end{macrocode} +% +% \begin{macrocode} +\ProvidesExplPackage + {\ExplFileName}{\ExplFileDate}{\ExplFileVersion}{\ExplFileDescription} +% \end{macrocode} +% +% \begin{variable}{\g_flag_list_tl} +% We keep track of the list of all defined flags in a token list. +% This is only used by \cs{flag_new:N} to check that the flag +% has not yet been defined. +% \begin{macrocode} +\tl_new:N \g_flag_list_tl +% \end{macrocode} +% \end{variable} +% +% \begin{macro}{\flag_new:N, \flag_new:c} +% If the control sequence is already defined, then we raise an error. +% Otherwise we check if it is already a flag, raising an appropriate +% error, finally lower the flag globally (this is the only global +% assignment to a flag\ldots{} perhaps an error?). +% The \texttt{c} variant can be created without worrying for this function. +% \begin{macrocode} +\cs_new_protected:Npn \flag_new:N #1 + { + \tl_if_in:NnTF \g_flag_list_tl {#1} + { + \msg_kernel_error:nnx + { flag } { already-defined } + { \token_to_str:N #1 } + } + { + \tl_gput_right:Nn \g_flag_list_tl {#1} + \cs_new_eq:NN #1 \c_undefined:D + } + } +\cs_generate_variant:Nn \flag_new:N { c } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}[EXP, pTF]{\flag_test:N, \flag_test:c} +% Test if the control sequence is \texttt{undefined} or not. +% \begin{macrocode} +\prg_new_conditional:Npnn \flag_test:N #1 { p , T , F , TF } + { + \if_cs_exist:N #1 + \prg_return_true: + \else: + \prg_return_false: + \fi: + } +\prg_new_conditional:Npnn \flag_test:c #1 { p , T , F , TF } + { + \if_cs_exist:w #1 \cs_end: + \prg_return_true: + \else: + \prg_return_false: + \fi: + } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}[EXP]{\flag_raise:N, \flag_raise:c} +% Raising a flag expandably relies on the fact that \TeX{} +% automatically lets undefined control sequences to \tn{relax} +% when building an unknown csname. We build such a csname, then +% remove it with \cs{use_none:n}, essentially doing +% \cs{use_none:c}, but optimized slightly. When a flag is given +% as an \texttt{N}-type argument, a little more work is needed, +% converting to a csname before raising that. +% \begin{macrocode} +\cs_new:Npn \flag_raise:N #1 + { \exp_after:wN \use_none:n \cs:w \cs_to_str:N #1 \cs_end: } +\cs_new:Npn \flag_raise:c #1 + { \exp_after:wN \use_none:n \cs:w #1 \cs_end: } +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\flag_lower:N, \flag_lower:c} +% Simply undefine the control sequence, locally. +% \begin{macrocode} +\cs_new_protected:Npn \flag_lower:N #1 + { \cs_set_eq:NN #1 \c_undefined:D } +\cs_generate_variant:Nn \flag_lower:N { c } +% \end{macrocode} +% \end{macro} +% +% \begin{macrocode} +\msg_kernel_new:nnnn { flag } { already-defined } + { The~control~sequence~#1~is~already~declared~as~a~flag. } + { + LaTeX~was~asked~to~define~the~flag~#1,~but~it~has~already~ + been~defined~as~a~flag.~The~flag~module~is~mostly~meant~ + for~kernel~use,~and~booleans~should~be~preferred. + } +% \end{macrocode} +% +% \begin{macrocode} +% +% \end{macrocode} +% +% \end{implementation} +% +% \PrintIndex -- cgit v1.2.3