path: root/macros/latex/contrib/koma-script/scraddr.dtx

% \iffalse meta-comment
% ======================================================================
% scraddr.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: scraddr.dtx 4032 2023-04-17 09:45:11Z kohm $
%<*dtx>
\ifx\ProvidesFile\undefined\def\ProvidesFile#1[#2]{}\fi
\ProvidesFile{scraddr.dtx}
%</dtx>>
%<scraddr>\NeedsTeXFormat{LaTeX2e}[1995/12/01]
%<driver>\ProvidesFile{scraddr.drv}
%<scraddr>\ProvidesPackage{scraddr}
%<*dtx|scraddr|driver>
              [2022/01/24 v1.1d KOMA-Script
%</dtx|scraddr|driver>
%<scraddr>               package]
%<*dtx|driver>
              Script bundle]
%</dtx|driver>
%<*dtx>
\ifx\documentclass\undefined
  \input scrdocstrip.tex
  \@@input scrkernel-version.dtx
  \@@input scrstrip.inc
  \KOMAdefVariable{COPYRIGHTFROM}{2006}
  \generate{\usepreamble\defaultpreamble
    \file{scraddr.sty}{%
      \from{scraddr.dtx}{scraddr}%
      \from{scrlogo.dtx}{logo}%
    }%
  }
  \@@input scrstrop.inc
\else
  \let\endbatchfile\relax
\fi
\endbatchfile
%</dtx>
%<*driver>
\documentclass{koma-script-source-doc}
\usepackage[USenglish]{babel}
\begin{document}
  \DocInput{scraddr.dtx}
\end{document}
%</driver>
% \fi
%
% \changes{v1.1a}{2002/05/19}{first version, separated from \cls{scrlettr}}
% \changes{v1.1d}{2022/01/24}{switched from \cls{scrdoc} to
%   \cls{koma-script-source-doc}}
% \changes{v1.1d}{2022/01/24}{whole implementation documentation in English}
% \changes{v3.40}{2023/04/17}{guide names changed}
%
% \GetFileInfo{scraddr.dtx}
% \title{Parsing Address Files \\
%   Using Package \pkg*{scraddr}}
% \author{\href{mailto:komascript@gmx.info}{Markus Kohm}
%   \and Jens-Uwe Morawski}
% \date{Version \fileversion{} of \filedate}
% \maketitle
% \begin{abstract}
% Address files are not only of interest for letters using the \KOMAScript{}
% class \cls*{scrlttr2} or the \KOMAScript{} package \pkg*{scrletter}. Other
% applications such as the creation of address books or telephone directories
% are also quite common. In addition, it can also be useful to access not only
% the addressee's record in a letter, but also other records in an address
% file. This is exactly the task of the \pkg*{scraddr} package.
% \end{abstract}
% \tableofcontents
%
% \section{User Manual}
%
% You can find the user manual of \pkg*{scraddr} in the \KOMAScript{} manual,
% either the German \file{scrguide-de.pdf} or the English
% \file{scrguide-en.pdf}.
%
% \MaybeStop{\PrintIndex}
%
% \section{Implementation}
%
%\iffalse
%    \begin{macrocode}
%<*scraddr>
%<*beta>
\PackageWarningNoLine{scraddr}
  {THIS IS A BETA VERSION!\MessageBreak
    YOU SHOULD NOT USE THIS VERSION!\MessageBreak
    YOU SHOULD INSTALL THE RELEASE FROM CTAN\MessageBreak
    AND USE THAT INSTEAD OF THIS BETA VERSION}
%</beta>
%</scraddr>
%\fi
%
% \changes{v1.0}{1996/01/22}{New package \pkg*{scraddr}}
%
%    \begin{macrocode}
%<*scraddr>
%    \end{macrocode}
%
% \subsection{Options}
%
% Preliminary note: \pkg*{scraddr} is a very, very old package from the early
% days of \KOMAScript. Therefore it does not support \emph{key=value} options
% as other \KOMAScript{} packages do.
%
% \begin{option}{adrFreeIVempty}
% \changes{v1.1a}{2002/05/19}{new}
% \begin{option}{adrFreeIVshow}
% \changes{v1.1a}{2002/05/19}{new}
% \begin{option}{adrFreeIVwarn}
% \changes{v1.1a}{2002/05/19}{new}
% \begin{option}{adrFreeIVstop}
% \changes{v1.1a}{2002/05/19}{new}
% \begin{macro}{\@adrFIVerror}
% \changes{v1.1a}{2002/05/19}{new}
% The options allow the choice whether \cs{FreeIV}, defined by \cs{adrentry},
% should be ignored, output, result in a warning or an error message. Default
% is \opt{adrFreeIVshow}. The selected choice is stored as a number in
% \cs{@adrFIVerror} (0 = \opt{adrFreeIVempty}, 1 = \opt{adrFreeIVshow},
% 2 = \opt{adrFreewarn}, 3 = \opt{adrFreeIVstop}). Unknown values should
% be handled as \opt{adrFreeIVstop} too, but are not recommended.
%    \begin{macrocode}
\newcommand*{\@adrFIVerror}{}
\DeclareOption{adrFreeIVempty}{\renewcommand*{\@adrFIVerror}{0}}
\DeclareOption{adrFreeIVshow}{\renewcommand*{\@adrFIVerror}{1}}
\DeclareOption{adrFreeIVwarn}{\renewcommand*{\@adrFIVerror}{2}}
\DeclareOption{adrFreeIVstop}{\renewcommand*{\@adrFIVerror}{3}}
%    \end{macrocode}
%  \end{macro}
%  \end{option}
%  \end{option}
%  \end{option}
%  \end{option}
%
% \changes{v1.0a}{2001/08/07}{\cs{ExecuteOption}\cs{relax} fixed}
% \changes{v1.1a}{2002/05/19}{\texttt{adrFreeIVshow} is default}
%    \begin{macrocode}
\ExecuteOptions{adrFreeIVshow}
\ProcessOptions\relax
%    \end{macrocode}
%
% \subsection{Reading address files}
% \begin{command}{\InputAdressFile}
% This command reads the address file given as mandatory argument. While
% reading global internal macros are generated for every \cs{adrentry} or
% \cs{addrentry}. To do so, these two macros are redefined locally only.
% \changes{v1.1}{2002/05/18}{extended by \cs{addrentry} handling}
% \changes{v1.1b}{2002/06/02}{\cs{addrchar} and \cs{adrchar} are defined also
%   if undefined}
%    \begin{macrocode}
\newcommand{\InputAddressFile}[1]{\begingroup
  \ifcase\@adrFIVerror
    \def\adrentry##1##2##3##4##5##6##7{%
      \addrentry{##1}{##2}{##3}{##4}{##5}{##6}{##7}{}}%
  \or
    \def\adrentry##1##2##3##4##5##6##7##8{%
      \addrentry{##1}{##2}{##3}{##4}{##5}{##6}{##7}{%
        (entry FreeIV undefined at `##8')}{##8}}%
  \or
    \def\adrentry##1##2##3##4##5##6##7##8{%
      \addrentry{##1}{##2}{##3}{##4}{##5}{##6}{##7}{%
        \PackageWarning{scraddr}{%
          `##8' was defined using \string\adrentry\MessageBreak
          so \string\FreeIV-entry is not defined}}{##8}}%
  \else
    \def\adrentry##1##2##3##4##5##6##7##8{%
      \addrentry{##1}{##2}{##3}{##4}{##5}{##6}{##7}{%
        \PackageError{scraddr}{%
          \string\FreeIV\space undefined at `##8'}{%
          `##8' was defined using \string\adrentry\MessageBreak
           so \string\FreeIV-entry is not defined.\MessageBreak
          You may continue but you should check output}}{##8}}%
  \fi
  \providecommand*{\addrchar}[1]{}%
  \providecommand*{\adrchar}{\addrchar}%
  \def\addrentry##1##2##3##4##5##6##7##8##9{%
    \def\@tempa{##9}\ifx\@tempa\@empty\else
      \expandafter\gdef\csname ##9.LN\endcsname{##1}
      \expandafter\gdef\csname ##9.FN\endcsname{##2}
      \expandafter\gdef\csname ##9.A\endcsname{##3}
      \expandafter\gdef\csname ##9.P\endcsname{##4}
      \expandafter\gdef\csname ##9.FI\endcsname{##5}
      \expandafter\gdef\csname ##9.FII\endcsname{##6}
      \expandafter\gdef\csname ##9.FIII\endcsname{##7}
      \expandafter\gdef\csname ##9.FIV\endcsname{##8}    
    \fi}
%    \end{macrocode}
% Not existing files result in an error message. Found files are only noted.
%    \begin{macrocode}
  \InputIfFileExists{#1.adr}
                    {\typeout{Load addressfile: #1.adr.}}
                    {\PackageError{scraddr}
                                  {File #1.adr not found}
                                  {The addressfile you wanted is not
                                   available}}
  \endgroup}
%    \end{macrocode}
%  \end{command}
%
% \subsection{Using an element of an address file}
%
% Selecting the elements by names instead of cryptic macros, could be
% easier. So we use well named macros for the selection. All these macros have
% exactly one mandatory argument: the \meta{shortcut} which is argument 8 of
% \cs{adrentry} resp. argument 9 of \cs{addrentry} in the address file.
%
% \begin{command}{\Name}
% The \cs{Name} is a combination of \cs{Firstname} and \cs{Lastname} with a
% normal word separator space in between.
%    \begin{macrocode}
\newcommand*{\Name}[1]{\FirstName{#1}\ \LastName{#1}}
%    \end{macrocode}
% \end{command}
% \begin{command}{\FirstName}
% Firstname or given from internal macro \cs{\meta{shortcut}.FN}.
%    \begin{macrocode}
\newcommand*{\FirstName}[1]{\csname #1.FN\endcsname}
%    \end{macrocode}
% \end{command}
% \begin{command}{\LastName}
% Lastname from internal macro \cs{\meta{shortcut}.LN}.
%    \begin{macrocode}
\newcommand*{\LastName}[1]{\csname #1.LN\endcsname}
%    \end{macrocode}
% \end{command}
% \begin{command}{\Address}
% Address from internal macro \cs{\meta{shortcut}.A}.
%    \begin{macrocode}
\newcommand*{\Address}[1]{\csname #1.A\endcsname}
%    \end{macrocode}
% \end{command}
% \begin{command}{\Telephone}
% Telephone number from internal macro \cs{\meta{shortcut}.P}.
%    \begin{macrocode}
\newcommand*{\Telephone}[1]{\csname #1.P\endcsname}
%    \end{macrocode}
% \end{command}
% \begin{command}{\FreeI,\FreeII}
% Two free entries from internal macros \cs{\meta{shortcut}.FI} and
% \cs{\meta{shortcut}.FII}.
%    \begin{macrocode}
\newcommand*{\FreeI}[1]{\csname #1.FI\endcsname}
\newcommand*{\FreeII}[1]{\csname #1.FII\endcsname}
%    \end{macrocode}
% \end{command}
% \begin{command}{\Comment,\FreeIII}
% The third free element is available by two commands, because originally it
% was specified as \meta{comment}. It is stored in the internal macro
% \cs{\meta{shortcut}.FIII}.
% \changes{v1.1}{2002/05/18}{extended to \cs{addrentry}}
%    \begin{macrocode}
\newcommand*{\Comment}{}
\newcommand*{\FreeIII}[1]{\csname #1.FIII\endcsname}
\let\Comment\FreeIII
%    \end{macrocode}
% \end{command}
% \begin{command}{\FreeIV}
% Forth free entry from internal macro \cs{\meta{shortcut}.FIV} only available
% with \cs{addrentry} but not woth \cs{adreentry}.
% \changes{v1.1}{2002/05/18}{extended to \cs{addrentry}}
%    \begin{macrocode}
\newcommand*{\FreeIV}[1]{\csname #1.FIV\endcsname}
%    \end{macrocode}
% \end{command}
%
% \subsection{Ende of package}
%    \begin{macrocode}
%</scraddr>
%    \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: