% \iffalse meta-comment
% ======================================================================
% scrkernel-variables.dtx
% Copyright (c) Markus Kohm, 2006-2023
%
% This file is part of the LaTeX2e KOMA-Script bundle.
%
% This work may be distributed and/or modified under the conditions of
% the LaTeX Project Public License, version 1.3c of the license.
% The latest version of this license is in
% http://www.latex-project.org/lppl.txt
% and version 1.3c or later is part of all distributions of LaTeX
% version 2005/12/01 or later and of this work.
%
% This work has the LPPL maintenance status "author-maintained".
%
% The Current Maintainer and author of this work is Markus Kohm.
%
% This work consists of all files listed in MANIFEST.md.
% ======================================================================
%%% From File: $Id: scrkernel-variables.dtx 4151 2025-06-02 11:34:40Z kohm $
%<option>%%% (run: option)
%<body>%%% (run: body)
%<*dtx>
\ifx\ProvidesFile\undefined\def\ProvidesFile#1[#2]{}\fi
\begingroup
\def\filedate$#1: #2-#3-#4 #5${\def\filedate{#2/#3/#4}}
\filedate$Date: 2025-06-02 13:34:40 +0200 (Mo, 02 Jun 2025) $
\def\filerevision$#1: #2 ${\def\filerevision{r#2}}
\filerevision$Revision: 4151 $
\xdef\fileinfo{\filedate\space\filerevision\space}
\edef\reserved@a{%
\noexpand\endgroup
\noexpand\ProvidesFile{scrkernel-variables.dtx}%
[\filedate\space\filerevision\space
KOMA-Script source(koma variables)]
}%
\reserved@a
\documentclass[USenglish]{koma-script-source-doc}
\usepackage{babel}
\setcounter{StandardModuleDepth}{2}
\begin{document}
\DocInput{scrkernel-variables.dtx}
\end{document}
%</dtx>
% \fi
%
% \changes{v2.95}{2006/03/20}{new by splitting \file{scrclass.dtx}}
% \changes{v3.36}{2022/02/15}{switch over from \cls*{scrdoc} to
% \cls*{koma-script-source-doc}}
% \changes{v3.36}{2022/02/15}{whole implementation documentation in English}
% \changes{v3.40}{2023/04/17}{guide names changed}
%
% \GetFileInfo{scrkernel-variables.dtx}
% \title{Using Variables in
% \href{https://komascript.de}{\KOMAScript} Letter Classes and Package}
% \author{\href{mailto:komascript@gmx.info}{Markus Kohm}}
% \date{Revision \fileversion{} of \filedate}
% \maketitle
% \begin{abstract}
% Letters have several variables like the name and address of the sender and
% the addressee, for fields like customer ids phone numbers, email addresses
% etc. Depending on the purpose of a letter or a corporate identity much
% more field and so variables are possible. For all of them
% \file{scrkernel-variables.dtx} provides a general mechanism and user
% interface.
% \end{abstract}
% \tableofcontents
%
% \section{User Manual}
%
% You can find the user documentation the commands implemented here in the
% \KOMAScript{} manual, either the German \file{scrguide-de.pdf} or the
% English \file{scrguide-en.pdf}.
%
% \DescribeCommand{\Ifkomavarxempty}
% Similar to \cs{Ifkomavarempty} but the variable or description will be
% expanded before testing.
%
% \MaybeStop{\PrintIndex}
%
% \section{Implementation of Variables}
%
% \begin{macrocode}
%<*letter>
% \end{macrocode}
%
% \subsection{Options}
% The mechanism does not depend on options.
%
%
% \subsection{Commands and macros for variables}
%
% \begin{command}{newkomavar}
% \changes{v2.8q}{2002/01/14}{added}
% \changes{v3.20}{2016/04/12}{\cs{@ifstar} replaced \cs{kernel@ifstar} by}
% \changes{v3.42}{2023/08/25}{new implementation using \cs{NewDocumentCommand}}
% We have two kinds of fields and so variables:
% \begin{itemize}
% \item to be printed in the reference line,
% \item for other purpose, but not printed in the reference line.
% \end{itemize}
% But it is also possible to add variables later to (or even remove them from
% the reference line. But the star variant \cs{newkomavar*} automatically adds
% a variable to (the end of) the reference line. Both \cs{newkomavar} and
% \cs{newkomavar*} have one optional argument, the \meta{description}. It is
% intended to be printed. In opposite to this the first mandatory argument is
% the \meta{name} of the variable. It is not indented to be printed but used
% for access only. Only \emph{command sequence} characters are allowed
% here. It is recommended to use only letters for the \meta{name}. Internally
% macro \cs{scr@\meta{name}@name} and \cs{scr@\meta{name}@var} are
% defined. The second one is initialized to be empty.
% \begin{macrocode}
%<*body>
\NewDocumentCommand{\newkomavar}{som}{%
\@ifundefined{scr@#3@name}{%
\@ifundefined{scr@#3@var}{%
\IfValueT{#2}{\@namedef{scr@#3@name}{#2}}%
\@namedef{scr@#3@var}{}%
\IfBooleanT{#1}{\addtoreffields{#3}}%
}{%
%<class> \ClassError{scrlttr2}
%<package> \PackageError{scrletter}
{%
This should never happen%
}{%
The description of the KOMA-Script variable `#3'\MessageBreak
is undefined, but the name of the variable is
defined.\MessageBreak
This should never happen. So someone crashs me!%
}%
}%
}{%
%<class> \ClassError{scrlttr2}
%<package> \PackageError{scrletter}
{%
Variable `#3' already defined%
}{%
I'll ignore this command, if you'll continue.%
}%
}%
}
% \end{macrocode}
% \begin{macro}{\@newkomavar}
% \changes{v3.42}{2023/08/25}{removed}
% \end{macro}
% \end{command}
%
% \begin{command}{\setkomavar}
% \changes{v2.8q}{2002/01/14}{added}
% \changes{v3.08}{2010/10/28}{\cs{scr@\emph{Name}@postsetname} and
% \cs{scr@\emph{Name}@postsetvar} added}
% \changes{v3.20}{2016/04/12}{\cs{@ifstar} replaced by \cs{kernel@ifstar}}
% \changes{v3.20}{2016/04/12}{\cs{@ifnextchar} replaced by
% \cs{kernel@ifnextchar}}
% \changes{v3.42}{2024/04/24}{new implementation using
% \cs{NewDocumentCommand}}
% \changes{v3.43}{2024/10/23}{add missing call of \cs{scr@\emph{name}@postsetname}
% and \cs{scr@\meta{name}@postsetvar}}
% \changes{v3.44}{2025/06/02}{fix of error message macro}
% After defining a new variable we also need a command to set the
% \meta{value}. This is the second mandatory argument (\texttt{\#3}) of
% \cs{setkomavar}. The first mandatory argument (\texttt{\#2}) once again is
% the \meta{name}. The \meta{description} can be set with the optional first
% argument (\texttt{\#1}). But for the case only the \meta{description}
% should be changed but not the \meta{value} there is an additional star
% variant \cs{setkomavar*}. This has only two mandatory argument: \meta{name}
% (\texttt{\#1}) and \meta{description} (\texttt{\#2}). Both also executes two
% hooks \cs{scr@\meta{name}@postsetname} and \cs{scr@\meta{name}@postsetvar}
% after setting the \meta{description} resp. the \meta{value}. So package
% authors can define additional actions for the case a variable changes.
% \begin{macrocode}
\NewDocumentCommand{\setkomavar}{smo+m}{%
\Ifkomavar{#2}{%
\IfValueT{#3}{\@namedef{scr@#2@name}{#3}}%
\@namedef{scr@#2@\IfBooleanTF{#1}{name}{var}}{#4}%
\csname scr@#2@postset\IfBooleanTF{#1}{name}{var}\endcsname
}{%
\@komavar@err{set}{#2}%
}%
}
% \end{macrocode}
% \begin{macro}{\@setkomavar,\@@setkomavar,\@setkomaname}
% \changes{v2.8q}{2002/01/14}{added}
% \changes{v3.42}{2023/08/25}{removed}
% \end{macro}^^A \@setkomavar, \@@setkomavar, \@setkomaname
% \end{command}^^A \setkomavar*,\setkomavar
%
% \begin{macro}{\@komavar@err}
% \changes{v2.8q}{2002/01/14}{added}
% Error message for using or setting (\texttt{\#1}) unknown variables
% (\texttt{\#2}), used by \cs{setkomavar} or \cs{usekomavar}.
% \begin{macrocode}
\newcommand*{\@komavar@err}[2]{%
%<class> \ClassError{scrlttr2}
%<package> \PackageError{scrletter}
{%
KOMA-Script variable not defined%
}{%
You've tried to #1 the not defined KOMA-Script variable
`#2'.\MessageBreak
You have to define the variable using \string\newkomavar\space
before\MessageBreak
you do this.%
}%
}
% \end{macrocode}
% \end{macro}
%
% \begin{command}{\usekomavar}
% \changes{v2.8q}{2002/01/14}{added}
% \changes{v2.9i}{2002/09/04}{robust}
% \changes{v2.9i}{2002/09/04}{optional argument}
% \changes{v2.9j}{2002/09/18}{\cs{@firstofone} as default for the optional
% argument}
% \changes{v3.20}{2016/04/12}{\cs{@ifstar} replaced by \cs{kernel@ifstar}}
% \changes{v3.42}{2023/08/25}{new implementation using \cs{NewDocumentCommand}}
% \changes{v3.44}{2025/06/02}{fix of error message macro}
% User command to get either the \meta{description} (star variant) or the
% \meta{value} (non-star variant) of a variable. Once again the first
% mandatory argument (\texttt{\#2}) is the \meta{name} of the value. Both also
% have an optional first argument (\texttt{\#1}) \meta{code}. The \meta{code}
% is added before the \meta{description} or \meta{value} in the output stream
% and these are used as argument. You use it, e.g., to define a command with
% the content of \meta{description} or \meta{value} or change the formatting.
% \begin{macrocode}
\NewDocumentCommand{\usekomavar}{sO{\@firstofone}m}{%
\Ifkomavar{#3}{%
\IfBooleanTF{#1}{%
#2{\@nameuse{scr@#3@name}}%
}{%
#2{\@nameuse{scr@#3@var}}%
}%
}{%
\@komavar@err{use}{#3}%
}%
}
% \end{macrocode}
% \begin{macro}{\@usekomavar,\@usekomaname}
% \changes{v2.8q}{2002/01/14}{added}
% \changes{v3.42}{2023/08/25}{removed}
% \end{macro}^^A \@usekomavar,\@usekomaname
% \end{command}
%
% \begin{command}{\ifkomavar,\Ifkomavar}
% \changes{v3.03}{2009/03/04}{added}
% \changes{v3.28}{2019/11/15}{\cs{ifkomavar} renamed to {Ifkomavar}}
% \cs{Ifkomavar} tests if the variable with the \meta{name} of \texttt{\#1} is
% defined and execute the \meta{code} of \texttt{\#2} and otherwise the
% \meta{code} of \texttt{\#3}. The old command \cs{ifkomavar} is deprecated
% and should not be used any longer. This incompatible change has been done,
% because of a new recommendation of The \LaTeX{} Team (who does break its own
% recommendation, e.g., with \cs{ifToplevel}, \cs{ifthenelse} \dots).
% \begin{macrocode}
\newcommand*{\ifkomavar}{%
%<package> \PackageWarning{scrletter}{%
%<class> \ClassWarning{\KOMAClassName}{%
Usage of deprecated command `\string\ifkomavar'.\MessageBreak
The command has been renamed to because of a\MessageBreak
recommendation of LaTeX3 team members.\MessageBreak
Please replace `\string\ifkomavar' by `\string\Ifkomavar'%
}%
\Ifkomavar
}
\DeclareRobustCommand*{\Ifkomavar}[1]{%
\scr@ifundefinedorrelax{scr@#1@var}{%
\expandafter\@secondoftwo
}{%
\expandafter\@firstoftwo
}%
}
% \end{macrocode}
% \end{command}
%
%
% \begin{command}{\ifkomavarempty,\Ifkomavarempty}
% \changes{v2.8q}{2002/01/14}{added}
% \changes{v2.9i}{2002/09/04}{spurious spaced removed}
% \changes{v2.9i}{2002/09/04}{robust}
% \changes{v3.03}{2009/03/04}{using \cs{ifkomavar}}
% \changes{v3.03}{2009/03/04}{don't read the arguments but delegate them}
% \changes{v3.20}{2016/04/12}{\cs{@ifstar} replaced by \cs{kernel@ifstar}}
% \changes{v3.28}{2019/11/15}{\cs{ifkomavarempty} renamed to \cs{Ifkomavar}}
% \changes{v3.28}{2019/11/15}{\cs{ifkomavar} replaced by \cs{Ifkomavar}}
% \changes{v3.42}{2023/08/25}{new implementation using \cs{NewDocumentCommand}}
% \cs{Ifkomavarempty} tests if the variable with the \meta{name} of
% \texttt{\#1} is defined and the \meta{value} (non-star variant)
% resp. \meta{description} (star variant) is empty. If it is undefined or
% empty the \meta{code} of \texttt{\#2} is executed. If is defined and not
% empty the \meta{code} of \texttt{\#3} is executed.
% The old command \cs{ifkomavarempty} resp. \cs{ifkomavarempty*} is deprecated
% and should not be used any longer. This incompatible change has been done,
% because of a new recommendation of The \LaTeX{} Team (who does break its own
% recommendation, e.g., with \cs{ifToplevel}, \cs{ifthenelse} \dots).
% \begin{macrocode}
\newcommand*{\ifkomavarempty}{%
%<package> \PackageWarning{scrletter}{%
%<class> \ClassWarning{\KOMAClassName}{%
Usage of deprecated command `\string\ifkomavarempty'.\MessageBreak
The command has been renamed to because of a\MessageBreak
recommendation of LaTeX3 team members.\MessageBreak
Please replace `\string\ifkomavarempty' by `\string\Ifkomavarempty'%
}%
\Ifkomavarempty
}
\NewDocumentCommand{\Ifkomavarempty}{sm}{%
\Ifkomavar{#2}{%
\IfBooleanTF{#1}{%
\@ifundefined{scr@#2@name}\@firstoftwo{%
\expandafter\ifx\csname scr@#2@name\endcsname\@empty
\expandafter\@firstoftwo
\else
\expandafter\@secondoftwo
\fi
}%
}{%
\expandafter\ifx\csname scr@#2@var\endcsname\@empty
\expandafter\@firstoftwo
\else
\expandafter\@secondoftwo
\fi
}
}{%
\@komavar@err{use}{#2}%
\@gobbletwo
}%
}
% \end{macrocode}
% \begin{macro}{\if@komavarempty}
% \changes{v2.8q}{2002/01/14}{added}
% \changes{v3.42}{2023/08/25}{removed}
% \end{macro}%^^A \@ifkomavarempty
% \end{command}%^^A \ifkomavarempty, \Ifkomavarempty
%
% \begin{command}{\Ifkomavarxempty}
% \changes{v3.42}{2023/08/25}{added}
% This command is similar to the \cs{Ifkomavarempty} but uses \cs{Ifstr} for
% the comparison and therefore does a full expansion of the variable
% or output name.
% \begin{macrocode}
\NewDocumentCommand{\Ifkomavarxempty}{sm}{%
\Ifkomavar{#2}{%
\IfBooleanTF{#1}{%
\@ifundefined{scr@#2@name}\@firstoftwo{%
\Ifstr{\@nameuse{scr@#2@name}}{}%
}%
}{%
\Ifstr{\@nameuse{scr@#2@var}}{}%
}%
}{%
\@komavar@err{use}{#2}%
\@gobbletwo
}%
}
% \end{macrocode}
% \end{command}
%
%
% \begin{command}{\foreachkomavar}
% \changes{v3.27}{2019/03/13}{added}
% Executes \texttt{\#2} for each variable in the comma separated list
% \texttt{\#1}. An argument is appended to \texttt{\#2} which is the current
% variable to be processed. This command is short. So if you want so execute
% long code you should define a command for it. Sideeffect: \cs{reserved@a} is
% changed.
% \begin{macrocode}
\newcommand*{\foreachkomavar}[2]{%
\@for \reserved@a:=#1\do{%
\scr@trim@spaces\reserved@a
\ifx\reserved@a\@empty\else
\edef\reserved@a{\unexpanded{#2}{\reserved@a}}\expandafter\reserved@a
\fi
}%
}
% \end{macrocode}
% \end{command}
%
%
% \begin{command}{\foreachkomavarifempty}
% \changes{v3.27}{2019/03/13}{added}
% \changes{v3.28}{2019/11/15}{\cs{ifkomavarempty} replaced by \cs{Ifkomavarempty}}
% Same like \cs{foreachkomavar} but \texttt{\#2} is called only for empty
% variables and \texttt{\#3} is called for non empty.
% \begin{macrocode}
\newcommand*{\foreachkomavarifempty}[3]{%
\@for \reserved@a:=#1\do{%
\scr@trim@spaces\reserved@a
\ifx\reserved@a\@empty\else
\edef\reserved@a{%
\noexpand\Ifkomavarempty{\reserved@a}%
{\unexpanded{#2}{\reserved@a}}%
{\unexpanded{#3}{\reserved@a}}%
}\expandafter\reserved@a
\fi
}%
}
% \end{macrocode}
% \end{command}
%
% \begin{command}{\foreachemptykomavar}
% \changes{v3.27}{2019/03/13}{added}
% \changes{v3.28}{2019/11/15}{\cs{ifkomavarempty} replaced by \cs{Ifkomavarempty}}
% Similar to \cs{foreachemptykomavar} with \texttt{\#3}=\cs{@gobble}.
% \begin{macrocode}
\newcommand*{\foreachemptykomavar}[2]{%
\@for \reserved@a:=#1\do{%
\scr@trim@spaces\reserved@a
\ifx\reserved@a\@empty\else
\edef\reserved@a{%
\noexpand\Ifkomavarempty{\reserved@a}{\unexpanded{#2}{\reserved@a}}{}%
}\expandafter\reserved@a
\fi
}%
}
% \end{macrocode}
% \end{command}
%
% \begin{command}{\foreachnonemptykomavar}
% \changes{v3.27}{2019/03/13}{added}
% \changes{v3.28}{2019/11/15}{\cs{ifkomavarempty} replaced by \cs{Ifkomavarempty}}
% Similar to \cs{foreachemptykomavar} with \texttt{\#2}=\cs{@gobble}.
% \begin{macrocode}
\newcommand*{\foreachnonemptykomavar}[2]{%
\@for \reserved@a:=#1\do{%
\scr@trim@spaces\reserved@a
\ifx\reserved@a\@empty\else
\edef\reserved@a{%
\noexpand\Ifkomavarempty{\reserved@a}{}{\unexpanded{#2}{\reserved@a}}%
}\expandafter\reserved@a
\fi
}%
}
%</body>
% \end{macrocode}
% \end{command}
%
%
% \begin{macrocode}
%</letter>
% \end{macrocode}
%
% \Finale
% \PrintChanges
%
\endinput
% Local Variables:
% mode: doctex
% ispell-local-dictionary: "en_US"
% eval: (flyspell-mode 1)
% TeX-master: t
% TeX-engine: luatex-dev
% eval: (setcar (or (cl-member "Index" (setq-local TeX-command-list (copy-alist TeX-command-list)) :key #'car :test #'string-equal) (setq-local TeX-command-list (cons nil TeX-command-list))) '("Index" "mkindex %s" TeX-run-index nil t :help "makeindex for dtx"))
% End: