path: root/Master/texmf-dist/source/latex/mailmerge/mailmerge.dtx

%% \CheckSum{108}
% \iffalse meta-comment
%
% File: mailmerge.dtx
%
% Copyright (C) 2009 Miguel V. S. Frasson (mvsfrasson@gmail.com)
%
% The LaTeX package mailmerge provides an interface to produce text from
% a template where fields are replaced by actual data, like in a
% database.  It is useful to produce several letters from a template,
% certificates or other such documents.  It allows to access the entry
% number, number of entries and so on.
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{doc}
\usepackage{amstext,makeidx,ae,mailmerge}
\makeindex
\newcommand{\ttabrechaves}{\char123}
\newcommand{\ttfechachaves}{\char125}
\let\ac\ttabrechaves
\let\fc\ttfechachaves
\begin{document}
  \DocInput{mailmerge.dtx}
\end{document}
%</driver>
% \fi
%
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% \StopEventually
%
% \changes{1.0}{2009/09/23}{initial version}
%
% \MakeShortVerb+
%
% \title{\textsf{mailmerge}: repeat amount of text merging fields}
% \author{Miguel Vin\'\i cius Santini Frasson}
% \date{2009--09--23 version 1.0}
%
% \maketitle
%
%
% \tableofcontents
%
% \section{Introduction}
%
% The \LaTeX\ package \textsf{mailmerge} provides an interface to
% produce text from a template where fields are replaced by actual
% data, like in a database.  It is useful to produce several letters
% from a template, certificates or other such documents.  It allows to
% access the entry number, number of entries and so on.
%
% \section{Usage}
%
% In short, one needs to:
% \begin{enumerate}
% \item declare field names,
% \item define the repetition and
% \item provide entries, each one being a set of values for the fields.
% \end{enumerate}
% It is important to define the repetition with
% \texttt{\string\mailrepeat} \emph{before} provide any entry.  We
% present the usage in more detail now.
%
% \begin{enumerate}
% \item \DescribeMacro{\mailfields} Declare the names of the fields,
%   with the command \\\mbox{\qquad}
%   \texttt{\string\mailfields\ac\textit{name1},\textit{name2},...\fc}\\
%  The order declared here is the order in which the values must be
%  provided in the parameter of +\mailentry+ (see below.)
%
% \item
%   \DescribeMacro{\mailrepeat}
%   \DescribeMacro{\field}
%   The block of text to be repeated is given as the parameter of
%   macro +\mailrepeat+ as in\\\mbox{\qquad}
%   \texttt{\string\mailrepeat\ac\textit{...\ text to be
%       repeated...\fc}}\\
%   Inside the text to be repeated, which can be several paragraphs
%   long, each instance of \texttt{\string\field\ac\textit{name}\fc}
%   is replaced by the respective value, this for each entry.
%
%   \DescribeMacro{\numberoffields} \DescribeMacro{\numberofentries}
%   \DescribeMacro{\entrynumber} The command +\numberoffields+ is
%   replaced by the number of fields and +\numberofentries+ is
%   replaced by the number of entries, but it is necessary two runs to
%   update the value.  The command +\entrynumber+ is replaced by the
%   current entry number.  This can be used, for example, in
%   determining if current entry has an odd or even number.
%
%   For conditional text, depending on field value, one can compare
%   value's contents, for example, with the +\ifthenelse+ command
%   provided by
%   the \textsf{ifthen} package.
%
% \item \DescribeMacro{\mailentry} For each entry, provide a
%   command\\\mbox{\qquad}
%   \texttt{\string\mailentry\ac\textit{value1},\textit{value2},...\fc}\\
%   where \texttt{\textit{value1}} is the value of field named
%   \texttt{\textit{name1}}, \texttt{\textit{value2}} is the value of
%   field named \texttt{\textit{name2}}, and so on.  The values can be
%   several paragraphs long.  If the value has a comma with it, better
%   enclose the value between curly brackets, like in
% \begin{verbatim}
%    \mailfields{name,friends,drives}
%    \mailentry{John,{Bart,Robert},yes}
%    \mailentry{Michael,{Jean,Phillip,Maria},no}
% \end{verbatim}
%
%
% \item \DescribeMacro{\mailnewdata} In case of intention of use of
% several databases in the same file, use the command +\mailnewdata+,
% which resets entries.  New uses of +\mailfields+ overhide previous
% field names.
% \end{enumerate}
%
% \section{Example}
%
% \begin{verbatim}
%    \usepackage{ifthen,mailmerge}
%
%    % \ifequal{A}{B}{what if A=B}{what if A<>B}
%    \newcommand{\ifequal}[2]{\ifthenelse{\equal{#1}{#2}}}
%
%    \mailfields{name,friends,drives}
%
%    \mailrepeat{\section*{\field{name}'s profile}
%
%       \field{name} has
%       \ifequal{\field{friends}}{}
%         {no friends}
%         {\field{friends} as friends}.
%       \ifequal{\field{drives}}{yes}{Drives.}{Doesn't drive.}
%
%    (entry \entrynumber\ of \numberofentries)
%
%    % \newpage optional
%    }
%
%    \mailentry{John,{Bart and Robert},yes}
%    \mailentry{Sara,{Jean, Phillip and Maria},no}
%    \mailentry{Edward,,yes}
% \end{verbatim}
%
% \noindent what produces the following output:
%
% \newcommand{\ifequal}[2]{\ifthenelse{\equal{#1}{#2}}}
%
% \mailfields{name,friends,drives}
%
% \mailrepeat{\section*{\field{name}'s profile}
%
%    \field{name} has
%    \ifequal{\field{friends}}{}
%      {no friends}
%      {\field{friends} as friends}.
%    \ifequal{\field{drives}}{yes}{Drives.}{Doesn't drive.}
%
%    (entry \entrynumber\ of \numberofentries)
%
% ^^A \newpage optional
% }
%
% \mailentry{John,{Bart and Robert},yes}
% \mailentry{Sara,{Jean, Phillip and Maria},no}
% \mailentry{Edward,,yes}
%
% \section{Idea of implementation}
%
% \begin{itemize}
% \item Each new data initialization (call od +\mailnewdata+) defines
%   a tag command with values `a', `aa', `aaa', and so on, saved in
%   command +\MAILMcurrtag+.
% \item A +\mailfields+ saves field names to commands +\MAILMfieldI+,
%   +\MAILMfieldII+, +\MAILMfieldIII+, etc (ending with upcase roman
%   numbers), and at the end, saves in the \texttt{.aux} file the
%   number of fields in a command determined by the data tag.
% \item The +\mailrepeat+ command just saves its parameter to a command.
% \item Each \texttt{\string\field\ac\textit{name}\fc} is expanded to
% a command \texttt{\string\MAILMthefield\textit{name}}.
% \item +\numberoffields+ expands to a command whose name is composed
% by \texttt{MAILMnumberfields} plus ``tag''. The same for +\numberofentries+.
% \item Each +\mailentry+ defines the comands
%   \texttt{\string\MAILMthefield\textit{nameN}} to expand to
%   \texttt{\textit{valueN}}, using
%   \texttt{\string\MAILMfield\textit{N-in-roman}} to compose the name
%   of the command and expand an entry of the repetition command.
%   Now, when the +\field+, +\numberoffields+ and +\numberofentries+
%   are expanded, they have ppropriated values.
% \end{itemize}
%
%
% \section{Code}
%
%
% Identidication of the package and use of the package \textsf{ifthen}.
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{mailmerge}[2009/09/23 v1.0 repeat amount of text merging fields]
\RequirePackage{ifthen}
%    \end{macrocode}
%
% \subsection{(Re)initialization}
%
% Reset counters and update tag command +\MAILMcurrtag+.  Inicialize once.
%    \begin{macrocode}
\def\MAILMcurrtag{}
\newtoks\MAILMtok
\newcounter{MAILMcount}% aux counter
\newcounter{MAILMentry}%
\newcommand{\mailnewdata}{%
  \setcounter{MAILMentry}{0}%
  \xdef\MAILMcurrtag{a\MAILMcurrtag}}
\mailnewdata
%    \end{macrocode}
%
% \subsection{Saving the repetition in a command}
%
% \DescribeMacro{\mailrepeat}
%    \begin{macrocode}
\newcommand{\mailrepeat}[1]{\gdef\MAILMrepetition{#1}}
%    \end{macrocode}
%
% \subsection{Restoring data from aux file}
%
% \DescribeMacro{\MAILMsetnumfields}
% \DescribeMacro{\MAILMsetnumentries}
% \DescribeMacro{\numberoffields}
% \DescribeMacro{\numberofentries}
% Commands that extract info from aux file (saved by +\mailfields+ and
% +\mailentry+) and commands that use this information when repeting.
%    \begin{macrocode}
\newcommand{\MAILMsetnumfields}[2]
  {\expandafter\xdef\csname MAILMnumberoffields#1\endcsname{#2}}
\newcommand{\MAILMsetnumentries}[2]
  {\expandafter\xdef\csname MAILMnumberofentries#1\endcsname{#2}}
\newcommand{\numberoffields}
  {\csname MAILMnumberoffields\MAILMcurrtag\endcsname}
\newcommand{\numberofentries}
  {\csname MAILMnumberofentries\MAILMcurrtag\endcsname}
%    \end{macrocode}
%
% \subsection{Saving field names}
%
%    \begin{macrocode}
\newcommand{\mailfields}[1]{%
  \setcounter{MAILMcount}{0}%
%    \end{macrocode}
% \noindent Initiate a loop, where for each entry, the command
% +\MAILMaux+ is set to entry name.
%    \begin{macrocode}
  \@for\MAILMaux:=#1\do{%
%    \end{macrocode}
% \noindent  The next line is to extract white space after comma.
%    \begin{macrocode}
    \edef\MAILMaux{\expandafter\@firstofone\MAILMaux\@empty}%
%    \end{macrocode}
% \noindent Define command
% \texttt{\string\MAILMfield\textit{Roman-number}}.
%    \begin{macrocode}
    \stepcounter{MAILMcount}%
    \expandafter\edef\csname MAILMfield\Roman{MAILMcount}\endcsname
         {\MAILMaux}%
    \edef\numberoffields{\arabic{MAILMcount}}%
  }%
%    \end{macrocode}
% \noindent Write to \texttt{aux} +\MAILMsetnumfields{tag}{num}+
%    \begin{macrocode}
  \immediate\write\@mainaux{\string\MAILMsetnumfields
    {\MAILMcurrtag}{\theMAILMcount}}%
}
%    \end{macrocode}
%
% \subsection{Repeating within an entry}
%
% \DescribeMacro{\field}
% Defining +\field+, that expands to
% \texttt{\string\MAILMthefield\textit{name}}.
%    \begin{macrocode}
\newcommand{\field}[1]{\csname MAILMthefield#1\endcsname}
%    \end{macrocode}
%
% \DescribeMacro{\mailentry}
% \noindent Each entry increments counter (reset in initialization),
% saves entry number to aux, saves each value to the command expanded
% by +\field+ and expand the repetition, stored in +\MAILMrepetition+.
% The implementation is similar to +\mailfields+.
%    \begin{macrocode}
\newcommand{\mailentry}[1]{%
  \stepcounter{MAILMentry}%
  \edef\entrynumber{\theMAILMentry}%
  \immediate\write\@mainaux{\string\MAILMsetnumentries
    {\MAILMcurrtag}{\theMAILMentry}}%
  \setcounter{MAILMcount}{0}%
  \@for\MAILMentryfield:=#1\do{%
     \MAILMtok=\expandafter{\MAILMentryfield}%
     \stepcounter{MAILMcount}%
     \expandafter\long\expandafter\edef
        \csname MAILMthefield%
           \csname MAILMfield\Roman{MAILMcount}\endcsname
        \endcsname {\the\MAILMtok}%
  }%
  \MAILMrepetition
}
%    \end{macrocode}
%
% \Finale \PrintIndex %\PrintChanges
%
%% \CharacterTable
%%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%%   Digits        \0\1\2\3\4\5\6\7\8\9
%%   Exclamation   \!     Double quote  \"     Hash (number) \#
%%   Dollar        \$     Percent       \%     Ampersand     \&
%%   Acute accent  \'     Left paren    \(     Right paren   \)
%%   Asterisk      \*     Plus          \+     Comma         \,
%%   Minus         \-     Point         \.     Solidus       \/
%%   Colon         \:     Semicolon     \;     Less than     \<
%%   Equals        \=     Greater than  \>     Question mark \?
%%   Commercial at \@     Left bracket  \[     Backslash     \\
%%   Right bracket \]     Circumflex    \^     Underscore    \_
%%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%%   Right brace   \}     Tilde         \~}
%
\endinput