%<begin text>
%<*version>
Character Map:
ISO-8859-1 (Latin1, Western)

File Identifier:
forarray

Package: 
§+F§<<File Identifier>>§-F§

Description: 
Using array structures in §ESC§LaTeX

Abstract: 
The package <<Package>> provides functionality for processing lists and array structures in §ESC§LaTeX. Arrays can contain characters as well as §ESC§TeX§ESC§ and §ESC§LaTeX§ESC§ commands, nesting of arrays is possible, and arrays are processed within the same brace level as their surrounding environment. Array levels can be delimited by characters or control sequences defined by the user. Practical uses of this package include data management, construction of lists and tables, and calculations based on the contents of lists and arrays.

Version: 
1.01

Date: 
2008/06/20

Licence: 
§ESC§LaTeX§ESC§ Project Public License (LPPL), version 1.3c

Licence Site:
<+L>§ESC§href{<-L>http://www.latex-project.org/lppl.txt<+L>}{§+P§www.latex-project.org/lppl.txt§-P§}<-L>

Copyright:
The package <<Package>> is <+L>§ESC§textcopyright§ESC§<-L><+T>(c)<-T> <<Copyright Years>> by <<Author>>, and distributed under the terms of the <<Licence>>.

Copyright Years: 
2008

Author: 
Christian Schröppel

Maintainance Status:
maintained

Current Maintainer: 
Christian Schröppel

Address:
<+L>§ESC§href{mailto:christian@schroeppel.com}§CR§{<-L>§+F§christian@schroeppel.com§-F§<+L>}<-L>

Master File: 
§+F§<<File Identifier>>.dtm§-F§

Documentation Style File:
§+F§<<File Identifier>>.dts§-F§

Installation Script:
§+F§<<File Identifier>>§-F§

Derived Files: 
§+F§<<File Identifier>>.dtx§-F§, <<Style File>>, <<Documentation File>>, <<Test File>>, and <<Test Result File>>

DTX File:
§+F§<<File Identifier>>.dtx§-F§

Version File:
§+F§<<File Identifier>>.ver§-F§

README File:
§+F§README.txt§-F§

Style File:
§+F§<<File Identifier>>.sty§-F§

Documentation File:
§+F§<<File Identifier>>.pdf§-F§

Test File:
§+F§<<File Identifier>>-test.tex§-F§

Test Result File:
§+F§<<File Identifier>>-test.pdf§-F§

Style File Directory:
<+L>§ESC§argsymb{<-L>§<§your local texmf directory§>§<+L>}<-L>§+P§/tex/latex/<<File Identifier>>§-P§

Content:
The package <<Package>> consists of the master file <<Master File>>, the file <<README File>>, and the derived files <<Derived Files>>.

Documentation:
The file <<Documentation File>> contains the documentation for the package <<Package>>.§PAR§ The file <<README File>> contains some basic information about the package.§PAR§ The file <<Test File>> can be used to obtain a test page for the package. You can run this file with your §ESC§LaTeX§ESC§ installation and compare the result with the file <<Test Result File>> to check if everything works well.

Installation:
In order to use the package, you need to save the file <<Style File>> to a directory where your §ESC§LaTeX§ESC§ installation will find it. This will often be <<Style File Directory>>. Please consult the manuals for your §ESC§LaTeX§ESC§ system for further information. In many cases, it will be possible to use a package manager provided with your §ESC§LaTeX§ESC§ system to install the package.

DTM File:
You can obtain the files <<Derived Files>>, as well as <<README File>> by placing the files <<Master File>>, <<Documentation Style File>> and the Bourne shell script <<Installation Script>> in a single directory and typing in §VERB§<<File Identifier>>§VERB§ at the command prompt (after §VERB§cd§VERB§ <+L>§ESC§argsymb{<-L>§<§your empty directory§>§<+L>}<-L>). <<No Warranty>>

Copyright Notice:
The package <<Package>> is <+L>§ESC§textcopyright§ESC§<-L><+T>(c)<-T> <<Copyright Years>> by <<Author>>. It may be distributed and/or modified under the conditions of the <<Licence>>. This licence allows you to distribute unmodified copies of the package, as long as you include all components of the package in your distribution. It also allows modification of the package under certain conditions. Please read the licence if you intend to modify any of the contents of this package.§PAR§ If any later version of the LPPL replaces this version, the package may be distributed and/or modified under the conditions of the current version of the LPPL at that time. The latest version of the LPPL is available at <<Licence Site>>.§PAR§ The Author of the package is <<Author>>. You can contact the author at <<Address>>.§PAR§ This package has the LPPL maintenance status <+Q><<Maintainance Status>><-Q>. The Current Maintainer is <<Current Maintainer>>.§PAR§ <<Content>>§PAR§ <<No Warranty>>

No Warranty:
The installation script <<Installation Script>> and the documentation style file <<Documentation Style File>> are not part of the package <<Package>>. Please note, however, that the provisions in the section <+Q>No warranty<-Q> of the <<Licence>>, exempting the author and other parties from liability with regard to the work, apply to the contents of the package as well as to these files.

%</version>
%<*preamble>

The file <<DTX File>> was generated with the shell script <<Installation Script>> from the master file <<Master File>>.

COPYRIGHT NOTICE:

This file is part of the package <<Package>>.

<<Copyright Notice>>

%</preamble>
%<*postamble>
%</postamble>
%<end text>
%<*tex>
%<*manual>
\DOCstart
\DefineTab{\ \ \ }
\MakeShortVerb{\|}
\def\RemarkCountToken{This is a \argsymb{count} token, so you must prefix it by \cmdarg\the, \cmdarg\number, \cmdarg\romannumeral\ or another appropriate command if you want to print out its content.}
\def\RemarkCommandCharacters{You can use any characters that \TeX\ accepts as part of a \cmdarg\csname\ \textellipsis\ \cmdarg\endcsname\ construct.}
\def\UsageFigureRef#1{Figure \vref{Usage of #1} illustrates the usage of \expandafter\cmdarg\csname #1\endcsname.}
\def\UsageFigureCaption#1{\caption{Usage of \expandafter\cmdarg\csname #1\endcsname\label{Usage of #1}}}
\parindent0pt
 \title{<<Description>>: The package <<Package>>\\ [.5ex]\Large Version <<Version>> (<<Date>>)}
\author{<<Author>>\footnote{Please send any comments or suggestions to \protect<<Address>>.}}
\maketitle
\abstract{<<Abstract>>\par <<Copyright>>}
\tableofcontents
\parskip 1ex plus .25ex minus .15ex

\section{Introduction}

\TeX\ as well as \LaTeX\ do not provide any native functionality for processing arrays. Command structures such as |\loop| \textellipsis\ |\repeat| cannot be easily nested, and processing list or array items that contain arbitrary \TeX\ code, including braces that should be preserved during the execution, is difficult to implement.

The package <<Package>> provides the commands |\ForEach| and |\ForArray|, as well as some additional commands, that simplify processing of array structures in \LaTeX.

It offers the following features:
 
\begin{itemize}
\item Array data may contain arbitrary \LaTeX\ code.\footnote{There are some restrictions, however: Category code changes of characters take effect only after a \cmdarg\ForEach\ or \cmdarg\ForArray\ command has been processed, and they do not take effect immediately while processing a \cmdarg\ForEachD\ command.}
\item Array delimiters are chosen by the user, which is especially useful if you intend to process data provided in a format that you cannot or do not want to change.
\item Arrays are being processed at the same brace level as their environment, so that any variables or commands defined while processing an array keep their values or definitions without using |\global|.
\item While processing the array, braces supplied with the content of the array are being preserved. 
\end{itemize}

When processing arrays, the macros provided by the package <<Package>> create functions that are used for processing each array level ``on the fly''. This approach is essential for being able to nest arrays within each other. However, it creates a certain processing overhead. This will usually not matter much if you use the <<Package>> package commands within a \LaTeX\ document. Package writers, when defining commands that repeatedly process large amounts of data, should keep in mind that solutions tailor-made for specific data can avoid this overhead.

The name <<Package>> indicates that this package offers functionality similar to the structures |for|\nolinebreak\ \textellipsis\ |next| or |for|\nolinebreak\ \textellipsis\ |each| that can be found in most programming languages.

\section{Files}

<<Content>> 
 
<<Documentation>>

<<DTM File>>

\section{Usage}

The package <<Package>> provides commands for the following tasks:

\begin{description}
\item[Processing lists] Use |\ForEach| or one of the other commands described in section \vref{Lists}.
\item[Processing arrays] Use |\ForArray|, described in section \vref{Arrays}.
\item[Defining variables] Use |\DefineArrayVar| or one of the other commands described in section \vref{Variables}.
\end{description}

<<Installation>>

As with most other packages, simply include the package in your file with the command |\usepackage{forarray}|. Currently, you cannot supply any options to the package <<Package>>.

\subsection{Processing lists}\label{Lists} 

\subsubsection{The command \cmdarg\ForEach}

The command \DMacro\ForEach\ can be used to process the items of a list. It has the following syntax:

\cmdsyntax{\cmdarg\ForEach}{\argsymbB{separator}\argsymbB{function}\argsymbB{list}}

\begin{description}
\item[\argsymb{separator}] This can be any character or control sequence. Often, a comma or a semicolon will be used as the separator.
\item[\argsymb{function}] This is the function that will be executed for every item in the list. You can use the token \DMacro\thislevelitem\ to reference the contents of the item that is being processed.\footnote{\cmdarg\thislevelitem\ is a \cmdarg\long\ macro that expands to the token list of the item. If you intend to compare its contents with the contents of other macros, please make sure that these macros are also defined as \cmdarg\long\ macros, e.g. by using \cmdarg\newcommand.} The variable \DMacro\thislevelcount\ contains the number of the position of the item within the list. \RemarkCountToken
\item[\argsymb{list}] This argument contains the items of your list. Space characters of category code 10 will be ignored if they immediately precede or follow a separator.
\end{description}

\UsageFigureRef{ForEach}

\begin{figure}[hbt]
\begin{NoHyper}
\begin{WBoth}
\begin{itemize}
\ForEach
{,}
{\item This is item No.\ %
\the\thislevelcount.\\
It contains: ``\thislevelitem''.}
{A \textbf{bold} word, 
\textit{Some more words, written 
in italics},
\multiply\thislevelcount\thislevelcount
the number \the\thislevelcount,
Some more text}
\end{itemize}
\end{WBoth}
\end{NoHyper}
\MakeExampleBox
\UsageFigureCaption{ForEach}
\ShowExampleBox
\end{figure}

\subsubsection{The command \cmdarg\ForEachX}

The command \DMacro\ForEachX\ processes the list of items in the same way as the command \cmdarg\ForEach. However, it expands its third argument, a token containing the actual list, before processing it. It has the following syntax:

\cmdsyntax{\cmdarg\ForEachX}{\argsymbB{separator}\argsymbB{function}\argsymbB{list token}}

\begin{description}
\item[\argsymb{separator}] Same as in |\ForEach|.
\item[\argsymb{function}] Same as in |\ForEach|.
\item[\argsymb{list token}] This is a control sequence or an active character that expands to the list that is to be processed by |\ForEachX|. 
\end{description}

\subsubsection{The command \cmdarg\ForEachSublevel}

The command \DMacro\ForEachSublevel\ processes the the contents of a item of a surrounding list processing command. It is based on the command |\ForEachX|, but operates on the expansion of the token |\thislevelitem| taken from the surrounding list. It has the following syntax:

\cmdsyntax{\cmdarg\ForEachSublevel}{\argsymbB{separator}\argsymbB{function}}

\begin{description}
\item[\argsymb{separator}] Same as in |\ForEach|.
\item[\argsymb{function}] Same as in |\ForEach|.
\end{description}

With the command |\ForEachSublevel|, lists can be easily nested, as shown in Figure \vref{Nested}.

\begin{figure}[hbt]
\begin{NoHyper}
\begin{WBoth}
\begin{enumerate}
\ForEach
{;}
{
\item This is item No.\ %
\the\thislevelcount.
\begin{enumerate}
\ForEachSublevel
{,}
{\item \thislevelitem.}
\end{enumerate}
}
{This is a nested item,
Another nested item;
{This item is, well, nested},
A final item}
\end{enumerate}
\end{WBoth}
\end{NoHyper}
\MakeExampleBox
\caption{Nested Lists\label{Nested}}
\ShowExampleBox
\end{figure}

\subsubsection{The command \cmdarg\ForEachD}

The command \DMacro\ForEachD\ processes the list of items in the same way as the command |\ForEach|. However, it does not the contents of the list as its third argument, but parses the characters supplied after the second argument. These characters have to be delimited by the separator, followed by the control sequence |\endforeach|.\footnote{The token \cmdarg\endforeach\ is never actually expanded.} It has the following syntax:

\cmdsyntax{\cmdarg\ForEachD}{\argsymbB{separator}\argsymbB{function}\argsymb{list}\argsymb{separator}\cmdarg\endforeach}

\begin{description}
\item[\argsymb{separator}] Same as in |\ForEach|.
\item[\argsymb{function}] Same as in |\ForEach|.
\item[\argsymb{list}] Same as in |\ForEach|. The \argsymb{list} must be supplied \emph{without} surrounding braces. 
\end{description}

The command |\ForEachD| allows to change the category codes of characters during the execution of the list. However, if the commands changing the category codes are supplied as part of the list, these changes only take effect after the current item has been processed. Figure \vref{Category Codes} illustrates how category codes can be changed during the execution of |\ForEachD|.

\begin{figure}[hbt]
\begin{NoHyper}
\begin{WBoth}
\ForEachD
{;}
{\thislevelitem\par\bigskip}
* Huh? What is this?;
\catcode`\*\active * I still have no clue!;
\newcommand{*}{\textbf{star}} 
Now I see \textellipsis\ This is a *!;
I remember, this is a *.;\endforeach
\end{WBoth}
\end{NoHyper}
\MakeExampleBox
\caption{Changing category codes within a list\label{Category Codes}}
\ShowExampleBox
\end{figure}

\subsubsection{The command \cmdarg\ExitForEach}
 
The command \DMacro\ExitForEach\ stops the execution of the list after the current item has been processed. It does not take any arguments. \UsageFigureRef{ExitForEach}

\begin{figure}[hbt]
\begin{NoHyper}
\begin{WBoth}
\newcommand{\LeaveThisPlace}
{Leave this place!}
\ForEach
{;}
{-- This item says: 
``\thislevelitem''\par\medskip
\ifx\thislevelitem\LeaveThisPlace
\ExitForEach Ooops, I have to quit.\par
\else
Continuing to the next item 
\textellipsis\par\bigskip
\fi}
{Please continue.;Please continue.;
Leave this place!;Where has he gone?}
\end{WBoth}
\end{NoHyper}
\MakeExampleBox
\UsageFigureCaption{ExitForEach}
\ShowExampleBox
\end{figure}

\subsection{Processing arrays}\label{Arrays} 

\subsubsection{The command \cmdarg\ForArray}

The command \DMacro\ForArray\ processes the contents of an array. The first arguments supplied to this command specify the separators for each level of the array, a grouping marker for each array level, a token or active character that can be for executing a sublevel of the array, and the functions that the command |\ForArray| executes for each item of the array at the respective levels. The command |\ForArray| has the following syntax:

\cmdsyntax{\cmdarg\ForArray}{\argsymbB{separator list}\argbrackets{\argsymbO{marker list separator}\argsymb{marker list}}\argsymbB{sublevel token}\argsymbB{function list separator}\argsymbB{function list}\argsymbB{array}}

\begin{description}
\item[\argsymb{separator list}] This is a list of characters or control sequences that are used to separate the respective level of the array. For example, if you have an array with a semicolon as first level separator and a comma as second level separator, you would use \argbraces{{\tt;,}} as the \argsymbB{separator list}.
\item[\argsymb{marker list separator}] Optional argument. This is a control sequence or active character that separates the markers in the \argsymb{marker list}. It can only be used if a \argsymb{marker list} is supplied as well. If the \argsymb{marker list} is supplied without a \argsymb{marker list separator}, each character or control sequence of the marker list is taken as separate marker.
\item[\argsymb{marker list}] Optional argument. This is a list of characters or control sequences that are used as markers for the respective level of the array. You can use the token \DMacro\thislevelmarker\ to reference the marker of the respective level.
\item[\argsymb{sublevel token}] This is a control sequence or an active character that expands to the function that processes the level of the array below the level that is being processed at the respective time. If you intend to process the lower levels of your array, you have to include this token in the \argsymb{function list} as part of the functions for the higher levels of your array. The \argsymb{sublevel token} expands to the content of the item if used in the function applied to the lowest level of the array.\footnote{The \argsymb{sublevel token} actually expands to \cmdarg\fa@array@level, which in turn expands to \cmdarg\fa@array@\argsymb{array level}. The token \cmdarg\fa@array@\argsymb{array level} either expands to the function that processes the level of the array below the current level or, if used at the lowest level of the array, to \cmdarg\thislevelitem, the reference to the current item. Using \cmdarg\thislevelitem\ avoids this overhead.}
\item[\argsymb{function list separator}] This is a control sequence or active character that separates the functions in the \argsymb{function list}.
\item[\argsymb{function list}] This is a list of functions for the respective levels of the array, separated by the \argsymb{function list separator}. The variables \cmdarg\thislevelitem\ and \cmdarg\thislevelcount\ can be used in the same way as with the \cmdarg\ForEach\ command. In addition, the variable \DMacro\thislevelnr\ can be used. It contains the number of level within the array. \RemarkCountToken
\item[\argsymb{array}] This argument contains the items of your array. Space characters of category code 10 will be ignored if they immediately follow a separator.
\end{description}

\UsageFigureRef{ForArray}

\begin{figure}[hbt]
\UsageFigureCaption{ForArray}

\begin{NoHyper}
\begin{WBoth}
\ForArray{;,}{*}{|}
{[*]\par|(*)}
{A,B;C,D}
\end{WBoth}
\end{NoHyper}
\MakeExampleBox
\subfloat[Basic usage]{\ShowExampleBox}

\begin{NoHyper}
\begin{WBoth}
\ForArray{;,}{*}{|}
{\framebox{*}\par\smallskip|
\framebox{\parbox[t]{3em}
{\centering*}}\ }
{A,B;%
\ForArray{;,}{*}{|}
{\centering*\par|(*)}
{a,b;c,d},D}
\end{WBoth}
\end{NoHyper}
\MakeExampleBox
\subfloat[Nested arrays]{\ShowExampleBox}
\end{figure} 

\subsubsection{The command \cmdarg\ExitForEachLevels}
The command \DMacro\ExitForEachLevels\ stops the execution of the array at the levels indicated in its arguments have been processed. It takes effect after the current item has been processed. Its syntax is as follows:

\cmdsyntax{\cmdarg\ExitForEachLevels}{\argsymbB{Start level}\argsymbB{Number of levels}}

\begin{description}
\item[\argsymb{Start level}] This is the number of the lowest level that is exited after the command \cmdarg\ExitForEachLevels\ is being read. The number is relative to the current level, i.e. a value of 1 indicates that the current level is the lowest level that is being exited, a value of 2 indicates that the level above the current level is the lowest level that is being exited.
\item[\argsymb{Number of levels}] This is the number of levels that are being exited. The levels are being exited in consecutive order, beginning with the lowest level, which is being supplied as \argsymb{Start level}.
\end{description}

During the processing of an array item, you can supply multiple \cmdarg\ExitForEachLevels\ commands. \cmdarg\ForArray\ will exit from all levels indicated in the \cmdarg\ExitForEachLevels\ commands that have been supplied. The command \mbox{\cmdarg\ExitForEachLevels\argbraces{{\tt1}}\argbraces{{\tt1}}} has the same effect as the command \cmdarg\ForEachExit.

\subsection{Defining variables}\label{Variables} 

\subsubsection{The command \cmdarg\DefineArrayVar}

The command \DMacro\DefineArrayVar\ defines a group of variables that are being named as \argsymb{array name}\argsymb{variable name separator}\argsymb{variable name}. Its syntax is as follows:
 
\cmdsyntax{\cmdarg\DefineArrayVar}{\argsymbB{array name}\\\argsymbB{variable name separator}\\\argsymbB{variable list separator}\\\argsymbB{variable list}\\\argsymbB{variable content list separator}\\\argsymbB{variable content list}}

\begin{description}
\item[\argsymb{array name}] The names of all variables that are being defined by \cmdarg\DefineArrayVar\ start with the sequence of characters supplied as \argsymb{array name}. \RemarkCommandCharacters
\item[\argsymb{variable name separator}] This character or sequence of characters separates the \argsymb{array name} and the \argsymb{variable name}. \RemarkCommandCharacters
\item[\argsymb{variable list separator}] The \argsymb{variable list separator} separates the variable names supplied with the \argsymb{variable list}. It is a single control sequence or character. 
\item[\argsymb{variable list}] The \argsymb{variable list} contains the \argsymb{variable name}s that are used to construct the names of the variables in the array. \RemarkCommandCharacters
\item[\argsymb{variable content list separator}] The \argsymb{variable content list separator} separates the contents of the variables supplied with the \argsymb{variable content list}. It is a single control sequence or character.
\item[\argsymb{variable content list}] The \argsymb{variable content list} contains the contents of the variables in the array. 
\end{description}

If you supply less items in the \argsymb{variable content list} than in the \argsymb{variable list}, the content of the remaining variables will be set to the token \cmdarg\relax. If you supply more items in the \argsymb{variable content list} than in the \argsymb{variable list}, the remaining content items will be ignored. \UsageFigureRef{DefineArrayVar}

\begin{figure}[hbt]
\UsageFigureCaption{DefineArrayVar}

\begin{NoHyper}
\begin{WBoth}
\makeatletter
\fontfamily{upl}\selectfont

\DefineArrayVar{Capital}{@}
{,}{Brazil,Japan,South Korea,Viet Nam}
{,}{Bras\'{i}lia,T\={o}ky\={o},
S\u{o}ul,H\^{a} N\^{o}i}

\DefineArrayVar{Name}{@}
{,}{Brazil,Japan,South Korea,Viet Nam}
{,}{Brazil,Japan,the Republic of Korea,
Vi\d\ecircumflex t Nam}

\newcommand{\CapitalCity}[1]
{The capital city of
\csname Name@#1\endcsname\ is
\csname Capital@#1\endcsname.}

\ForEach{,}
{\CapitalCity{\thislevelitem}
\par\medskip}
{Brazil,Japan,South Korea,Viet Nam}
\end{WBoth}
\end{NoHyper}
\MakeExampleBox
\ShowExampleBox
\end{figure} 

\subsubsection{The command \cmdarg\DefineArrayVars}

The command \DMacro\DefineArrayVars\ defines a set of grouped variables that are being named as \argsymb{array name}\argsymb{variable name separator}\argsymb{variable name}. The \argsymb{array name} is taken from a list of names supplied by the user. The syntax of \cmdarg\DefineArrayVars\ is as follows:
 
\cmdsyntax{\cmdarg\DefineArrayVars}{\argsymbB{variable list separator}\\\argsymbB{array definitions separator}\\\argsymbB{array name/content separator}\\\argsymbB{content list separator}\\\argsymbB{variable name separator}\\\argsymbB{variable list}\\\argsymbB{content definition list}}
 
A precise explanation of the functions of the respective arguments would probably be rather lengthy and somewhat confusing. Therefore, the command \cmdarg\DefineArrayVar\ will be explained with the help of an example. Figure \vref{Usage of DefineArrayVars} shows that the result already produced with the use of \cmdarg\DefineArrayVar\ (see Figure \vref{Usage of DefineArrayVar}) can be obtained in a shorter and more structured way by using \cmdarg\DefineArrayVars.

\begin{figure}[hbt]
\UsageFigureCaption{DefineArrayVars}

\begin{NoHyper}
\begin{WBoth}
\makeatletter
\fontfamily{upl}\selectfont

\DefineArrayVars{,}{/}{:}{;}{@}
{Brazil,Japan,South Korea,Viet Nam}
{Capital:
Bras\'{i}lia;T\={o}ky\={o};
S\u{o}ul;H\^{a} N\^{o}i/
Name:
Brazil;Japan;the Republic of Korea;
Vi\d\ecircumflex t Nam}

\newcommand{\CapitalCity}[1]
{The capital city of
\csname Name@#1\endcsname\ is
\csname Capital@#1\endcsname.}

\ForEach{,}
{\CapitalCity{\thislevelitem}
\par\medskip}
{Brazil,Japan,South Korea,Viet Nam}
\end{WBoth}
\end{NoHyper}
\MakeExampleBox
\ShowExampleBox
\end{figure} 

In the example, the \emph{first argument} of \cmdarg\DefineArrayVars\ is a comma. It separates the names of the sequences of character and/or tokens that are being used to construct the second part of the names of the array variables. 

The \emph{second argument} of \cmdarg\DefineArrayVars\ is a slash. It is used to delimit the arrays that you intend to define. In this case, only one slash is needed: It separates the array of ``Capital'' variables from the array of ``Name'' variables. 

The \emph{third argument} separates the array name from the list of contents. In this case, a colon is being used. 

The \emph{fourth argument}, which, in this example, is a semicolon, separates the items of the list of content definitions. 

The \emph{fifth argument} is the string of characters that is being used to separate the array name from the variable name. Here, an \textit{at} sign is being used, and the resulting names of the variables are \cmdarg\Capital@Brazil, \cmdarg\Capital@Japan, \textellipsis\ \verb*|\Name@Viet Nam|.\footnote{Be aware that you cannot directly access control sequences whose names contain non-letter characters without changing the category codes of the respective characters.}

The \emph{sixth argument} and the \emph{seventh argument} contain the list of variable names and the list of array names and contents, respectively. Both have to be structured accordings to the specifications supplied with the preceding arguments.

\subsubsection{The command \cmdarg\DefineArrayDefault}

The command \DMacro\DefineArrayDefault\ can be used to access the contents of a group of variables that have been defined with \cmdarg\DefineArrayVar\ or \cmdarg\DefineArrayVars. It defines a new control sequence whose expansion depends on the value of another variable. If, for a particular content of the second variable, no specific expansion has been defined, the variable expands to a default content. The syntax of \cmdarg\DefineArrayDefault\ is as follows:

\cmdsyntax{\cmdarg\DefineArrayDefault}{\argsymbB{array list separator}\\\argsymbB{variable name separator}\\\argsymbB{index variable}\\\argsymbB{default variable}\\\argsymbB{array list}}

\begin{description}
\item[\argsymb{array list separator}] The \argsymb{variable list separator} separates the array names supplied with the \argsymb{array list}. It is a single control sequence or character.
\item[\argsymb{variable name separator}] Same as in \cmdarg\DefineArrayVar.
\item[\argsymb{index variable}] The variable that expands to one of the names of the variables supplied with the \argsymb{variable list} of \cmdarg\DefineArrayVar\ or \cmdarg\DefineArrayVars. If this variable does not expand to one of these names, the name of the default index variable is being used, resulting in an expansion to the default content.
\item[\argsymb{default variable}] The name of the default variable.
\item[\argsymb{array list}] This in a list of array names, for which the index variable and the default variable are being defined.
\end{description}

\UsageFigureRef{DefineArrayDefault}

\begin{figure}[hbt]
\UsageFigureCaption{DefineArrayDefault}

\begin{NoHyper}
\begin{WBoth}
\makeatletter
\fontfamily{upl}\selectfont

\DefineArrayVars{,}{/}{:}{;}{@}
{Brazil,Japan,South Korea,Viet Nam,Unknown}
{Capital:
Bras\'{i}lia;T\={o}ky\={o};
S\u{o}ul;H\^{a} N\^{o}i;unknown/
Name:
Brazil;Japan;the Republic of Korea;
Vi\d\ecircumflex t Nam;this country}

\DefineArrayDefault{,}{@}{\country}%
{Unknown}{Capital,Name}

\newcommand{\WhatIsTheCapitalCity}
{-- You've asked for the capital city of 
\textit{\country}.\par\medskip
The capital city of \Name\ is 
\textbf{\Capital}.\par\bigskip}

\newcommand{\country}{Brazil}
\WhatIsTheCapitalCity
\renewcommand{\country}{South Korea}
\WhatIsTheCapitalCity
\renewcommand{\country}{a strange country}
\WhatIsTheCapitalCity
\end{WBoth}
\end{NoHyper}
\MakeExampleBox
\ShowExampleBox
\end{figure} 

\subsubsection{The command \cmdarg\DefineArrayVarTo}

The command \DMacro\DefineArrayVarTo\ assigns the same content to a group of variables. It has the following syntax:
 
\cmdsyntax{\cmdarg\DefineArrayVarTo}{\argsymbB{variable list separator}\argsymbB{variable name separator}\argsymbB{array name}\argsymbB{content}\argsymbB{variable list}}

\begin{description}
\item[\argsymb{variable list separator}] Same as in \cmdarg\DefineArrayVar.
\item[\argsymb{variable name separator}] Same as in \cmdarg\DefineArrayVar.
\item[\argsymb{array name}] Same as in \cmdarg\DefineArrayVar.
\item[\argsymb{content}] The content that is being assigned to the variables.
\item[\argsymb{variable list}] Same as in \cmdarg\DefineArrayVar.
\end{description}

\subsubsection{The command \cmdarg\CommandForEach}

The command \DMacro\CommandForEach\ executes the same control sequence (or token list) for each item in a list. The items can consist of one or more characters or tokens. The command \cmdarg\CommandForEach\ has the following syntax:
 
\cmdsyntax{\cmdarg\CommandForEach}{\argsymbB{variable list separator}\argsymbB{command}\argsymbB{variable list}}

\begin{description}
\item[\argsymb{list separator}] Same as in \cmdarg\ForEach.
\item[\argsymb{command}] This is the control sequence or token list that uses the respective item taken from the list as its argument.
\item[\argsymb{list}] Same as in \cmdarg\ForEach.
\end{description}

\subsubsection{The command \cmdarg\FunctionForEach}

The command \DMacro\FunctionForEach\ works in nearly the same way and has the same syntax as the command \cmdarg\CommandForEach. The difference between the two commands is that \cmdarg\FunctionForEach\ encloses the respective list item in braces and supplies it as a single argument to the function. This command has the same syntax as \cmdarg\CommandForEach.

\subsection{Additional features}

The style file for this package contains some features which are not described in the documentation. In particular, some of the commands of the package can be used with optional arguments that are not included in the documentation. These features are still under development, and their usage may change in the future.

%</manual>
%
% \section{The implementation\label{Implementation}}
%
% \subsection{Initial commands}
%
%    \begin{macrocode}
%<*sty>
\ProvidesPackage{forarray}
	[<<Date>> Version <<Version>> -- <<Description>>]
\makeatletter
\def\fe@checkifdefined#1{%
\ifx#1\empty
\else
	\expandafter\ifx\csname #1\endcsname\relax
	\else
		\PackageError{forarray}
			{
			Command #1 is already defined.\MessageBreak
			This command is being used by the package "forarray" %
			and must not be defined when the package is loaded
			}
			{No further immediate help available.}
		\csname fi\endcsname\csname fi\endcsname\@gobblefour
	\fi
	\expandafter\fe@checkifdefined
\fi}
\fe@checkifdefined
	{CommandForEach}{DefineArrayDefault}{DefineArrayVar}
	{DefineArrayVars}{DefineArrayVarTo}{endforeach}
	{ExitForEach}{ExitForEachLevels}{ForArray}{ForEach}
	{ForEachD}{ForEachSublevel}{ForEachX}{FunctionForEach}
	{thislevelcount}{thislevelitem}{thislevelmarker}
	{thislevelnr}{}
\edef\fe@aux@endlinecharrestore{\the\endlinechar}
\endlinechar\m@ne
\newtoks\fe@toks
\newcount\fe@level
\newcount\fe@cnt@i
\newcount\fe@cnt@ii
\newcount\thislevelcount
\newcount\thislevelnr
\fe@level\z@
\chardef\fa@arraylevel\z@
\chardef\fe@toplevel\z@
\chardef\fe@count@abs@\@ne
\chardef\fe@relmax\z@
\chardef\fe@relmax@abs@\z@
\let\fe@item@abs@\empty
\let\fe@first@abs@\empty
\let\fe@last@abs@\empty
\let\fe@empty@abs@\empty
\let\fe@position@abs@\empty
\let\fe@levelrn\empty
%    \end{macrocode}
%
% \subsection{Macros for processing lists}
%
% \subsubsection{User commands}
%
% \begin{macro}{\ForEachD}
% The macro \cmdarg\ForEachD\ directly calls \cmdarg\ForEachD@. It does not take the list as an argument, so that catcodes can be changed during the execution.
%    \begin{macrocode}
\def\ForEachD{\@ifnextchar(\ForEachD@Arg\ForEachD@NoArg}
\def\ForEachD@Arg(#1){\ForEachD@{#1\relax}}
\def\ForEachD@NoArg{\ForEachD@\fe@relmax}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\ForEach}
% The macro \cmdarg\ForEach\ absorbs the list immediately as its third mandatory argument.
%    \begin{macrocode}
\def\ForEach{\@ifnextchar(\ForEach@Arg\ForEach@NoArg}
\def\ForEach@Arg(#1){\ForEach@{#1\relax}}
\def\ForEach@NoArg{\ForEach@\fe@relmax}
\long\def\ForEach@#1#2#3#4{\ForEachD@{#1}{#2}{#3}#4#2\endforeach}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\ForEachX}
% The macro \cmdarg\ForEachX\ expands its third mandatory argument, which contains the list.
%    \begin{macrocode}
\def\ForEachX{\@ifnextchar(\ForEachX@Arg\ForEachX@NoArg}
\def\ForEachX@Arg(#1){\ForEachX@{#1\relax}}
\def\ForEachX@NoArg{\ForEachX@\fe@relmax}
\long\def\ForEachX@#1#2#3#4
	{
	\def\fe@i{\ForEachD@{#1}{#2}{#3}}
	\expandafter\fe@i#4#2\endforeach
	}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\ForEachSublevel}
% The macro \cmdarg\ForEachSublevel\ expands the current item of a surrounding list or array.
%    \begin{macrocode}
\def\ForEachSublevel
	{\@ifnextchar(\ForEachSublevel@Arg\ForEachSublevel@NoArg}
\def\ForEachSublevel@Arg(#1){\ForEachSublevel@{#1\relax}}
\def\ForEachSublevel@NoArg{\ForEachSublevel@\fe@relmax}
\long\def\ForEachSublevel@#1#2#3
	{
	\def\fe@i{\ForEachD@{#1}{#2}{#3}}
	\expandafter\fe@i\thislevelitem#2\endforeach
	}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\ExitForEach}
% The macro \cmdarg\ExitForEach\ redefines the kernel macro \cmdarg\fe@next@\argsymb{current level} in order to stop the execution of the current list. The rest of the list is being supplied as an argument to \cmdarg\fe@next@\argsymb{current level}, which just gobbles it. 
%    \begin{macrocode}
\def\ExitForEach
	{
	\expandafter\let
	\csname fe@next@\romannumeral\fe@level\endcsname
	\fe@ExitForEach@base
	}
\def\fe@ExitForEach@base#1\endforeach{}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\ForEachD@}
% The macro \cmdarg\ForEachD@\ defines several tokens used for processing a list or a level of an array. If it enters a level higher than any previous one, it calls \cmdarg\fe@newlevel, which defines the macros that are being used for processing lists as well as arrays for that level, i.e. the ``kernel'' macros.
%    \begin{macrocode}
\long\def\ForEachD@#1#2#3
	{
	\let\fe@upperlevelrn\fe@levelrn
	\advance\fe@level\@ne\relax
	\expandafter\def\expandafter\fe@levelrn\expandafter
		{\romannumeral\fe@level}
	\ifnum\fe@level>\fe@toplevel
		\expandafter
		\ifx\csname fe@count@abs@\fe@levelrn\endcsname\relax
			\expandafter\newcount
				\csname fe@count@abs@\fe@levelrn\endcsname
		\fi
		\fe@define@position
	\fi
	\csname fe@count@abs@\fe@levelrn\endcsname\z@
	\expandafter\chardef
		\csname fe@first@abs@\fe@levelrn\endcsname\@ne
	\expandafter\chardef
		\csname fe@last@abs@\fe@levelrn\endcsname\z@
	\expandafter\chardef
		\csname fe@relmax@abs@\fe@levelrn\endcsname#1\relax
	\expandafter\fe@define
		\csname fe@relmax@abs@\fe@levelrn\endcsname\fe@levelvars
	\expandafter\long\expandafter\def
		\csname fe@function@\fe@levelrn\endcsname##1{#3}
	\def\fe@emptytest{#2}
	\ifx\fe@emptytest\empty
		\fe@definelevel\empty{}
	\else
		\fe@definelevel#2{\expandafter#2}
	\fi
	\expandafter\expandafter\expandafter\fe@fnsl@
		\expandafter\expandafter
		\csname fe@nextcommandcode@\fe@levelrn\endcsname
		\csname fe@check@\fe@levelrn\endcsname
	}
\def\fe@levelvars{count,item,first,last,position}
\def\fe@definelevel#1#2
	{
	\ifnum\fe@level>\fe@toplevel
		\fe@newlevel#1
		\chardef\fe@toplevel\fe@level
	\fi
	\expandafter\let\csname fe@separator@\fe@levelrn\endcsname#1
	\expandafter\expandafter\expandafter\long
		\expandafter\expandafter\expandafter\def
		\expandafter\expandafter
		\csname fe@getitem@\fe@levelrn\endcsname
		\expandafter##\expandafter1#2\expandafter
		{\csname fe@setitem@\fe@levelrn\endcsname{##1}}
	}
%    \end{macrocode}
% \end{macro}
%
% \subsubsection{Defining the kernel macros}
%
% The following macros define the kernel macros \cmdarg\fe@check@\argsymb{current level}, \cmdarg\fe@setitem@\argsymb{current level} and \cmdarg\fe@process@\argsymb{current level}. \cmdarg\fe@check@\argsymb{current level} checks the next list item and supplies it to \cmdarg\fe@setitem@\argsymb{current level}, which defines the token that is being processed in turn by \cmdarg\fe@process@\argsymb{current level}, which uses the function supplied by \cmdarg\ForEachD@.
% \begin{macro}{\fe@newlevel}
% The macro \cmdarg\fe@newlevel\ sets up the tokens that are being used to define the kernel for the new level.
%    \begin{macrocode}
\def\fe@newlevel#1
	{
	\fe@DefLevelVar{fe}{\fe@levelrn}
		{
		process,next,item@abs,count@abs,first@abs,
		last@abs,position@abs,function,check,getitem,
		nextcommandcode,aftergroup,
		aftergroup@,firsttoken,space,separator,setitem
		}
	\fe@CollectLevelVar{base}
		{check,getitem,next,nextcommandcode}
	\fe@CollectLevelVar{i}
		{firsttoken,aftergroup,aftergroup@,space,separator}
	\fe@CollectLevelVar{ii}
		{count@abs,first@abs}
	\fe@CollectLevelVar{iii}
		{process,function,item@abs,last@abs,setitem}
	\expandafter\expandafter\expandafter\fe@newlevel@i
		\expandafter\fe@level@base\fe@level@i
	\expandafter\fe@newlevel@ii\fe@level@ii
	\expandafter\expandafter\expandafter\fe@newlevel@iii
		\expandafter\fe@level@base\fe@level@iii
	}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\fe@newlevel@i}
% The macro \cmdarg\fe@newlevel@i\ defines two auxilliary macros for the kernel macros and then assembles the first tokens of the macro \cmdarg\fe@def@check, which defines the kernel macro \cmdarg\fe@check@\argsymb{current level}.
%    \begin{macrocode}
\long\def\fe@newlevel@i#1#2#3#4#5#6#7#8#9
	{
	\def#6{\fe@fnsl#4#8#7}
	\def#7{
		\ifx#9#4
			\ifnum#8=\z@
				\fe@braces@ii#2#5{}
			\else
				\fe@braces@ii#2#5{ }
			\fi
		\else
			\ifnum#8=\z@
				\fe@braces@i#2#5{}
			\else
				\fe@braces@i#2#5{ }
			\fi
		\fi
		\fe@item@check@next
		}
	\def\fe@i##1
		{
		\fe@def@check
			{
			\long\def#5{##1}
				\ifcat\noexpand#4\bgroup
					\ifx#9\empty
						\expandafter\def\expandafter#3\expandafter
							{
							\expandafter#2\expandafter
								{\expandafter{#5}}
							}
					\else
						\let#3#6
					\fi
				\else
					\expandafter\def\expandafter#3
						\expandafter{\expandafter#2#5}
				\fi
			}
			{#1##1}#2#3#4
		}
	}
\long\def\fe@braces@i#1#2#3
	{
	\expandafter\def\expandafter\fe@item@check@next\expandafter
		{\expandafter#1\expandafter{#2}#3}
	}
\long\def\fe@braces@ii#1#2#3
	{
	\expandafter\def\expandafter\fe@item@check@next\expandafter
		{\expandafter#1\expandafter{\expandafter{#2}}#3}
	}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\fe@newlevel@ii}
% The macro \cmdarg\fe@newlevel@ii\ actually calls the macro \cmdarg\fe@def@check, which defines the kernel macro \cmdarg\fe@check@\argsymb{current level}.
%    \begin{macrocode}
\long\def\fe@newlevel@ii#1#2{\fe@i{##1}#1#2}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\fe@newlevel@iii}
% The macro \cmdarg\fe@newlevel@iii\ calls the macros \cmdarg\fe@def@setitem\ and \cmdarg\fe@def@process, which define the kernel macros \cmdarg\fe@setitem@\argsymb{current level} and \cmdarg\fe@process@\argsymb{current level}.
%    \begin{macrocode}
\long\def\fe@newlevel@iii#1#2#3#4#5#6#7#8#9
	{
	\fe@def@setitem#9#7#5
	\fe@def@process#5#3#1#6#4#7#8
	}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\fe@def@check}
% The macro \cmdarg\fe@def@check\ defines the kernel macro \cmdarg\fe@check@\argsymb{current level}.
%    \begin{macrocode}
\long\def\fe@def@check#1#2#3#4#5#6#7
	{
	\long\def#2
		{
		\ifx#5\endforeach
			\let#4\fe@endlevel
		\else
			\advance#6\@ne
			\thislevelcount#6
			\ifnum#6=\tw@
				\chardef#7\z@
			\fi
			#1
		\fi
		#4
		}
	}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\fe@def@setitem}
% The macro \cmdarg\fe@def@setitem\ defines the kernel macro \cmdarg\fe@setitem@\argsymb{current level}.
%    \begin{macrocode}
\long\def\fe@def@setitem#1#2#3
	{
	\long\def#1##1
		{
		\long\def#2{##1}
		\let\thislevelitem#2
		#3
		}
	}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\fe@def@process}
% The macro \cmdarg\fe@def@process\ defines the kernel macro \cmdarg\fe@process@\argsymb{current level}.
%    \begin{macrocode}
\long\def\fe@def@process#1#2#3#4#5#6#7
	{
	\long\def#1
		{
		\ifx#5\endforeach
			\chardef#7\@ne
		\fi
		\def#2{\fe@fnsl@#5#3}
		#4#6
		#2
		}
	}
%    \end{macrocode}
% \end{macro}
%
% \subsubsection{Auxilliary macros}
%
% \begin{macro}{\fe@endlevel}
% The macro \cmdarg\fe@endlevel\ is being called after a list or array level has been processed, i.e. when \cmdarg\fe@check@\argsymb{current level} identifies an \cmdarg\endforeach\ token. It resets the pointers \cmdarg\thislevelitem\ and \cmdarg\thislevelcount. It also resets the expansions of some variables, most notably the pointers to the kernel macros, so that they refer to the contents associated with the previous level.
%    \begin{macrocode}
\def\fe@endlevel
	{
	\chardef\fe@count@total\thislevelcount
	\advance\fe@level\m@ne
	\expandafter\def\expandafter\fe@levelrn\expandafter
		{\romannumeral\fe@level}
	\expandafter\fe@define
		\csname fe@relmax@abs@\fe@levelrn\endcsname\fe@levelvars
	\expandafter\thislevelcount
		\csname fe@count@abs@\fe@levelrn\endcsname
	\expandafter\let\expandafter\thislevelitem
		\csname fe@item@abs@\fe@levelrn\endcsname
	}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\fe@fnsl}
% The macro \cmdarg\fe@fnsl\ discards any implicit or explicit space tokens that intervene before a nonspace is scanned, and provides information about the next token and the presence of spaces before this token. It is a modified version of the macro \cmdarg\futurenonspacelet\ from \textit{The TeXBook}.\footnote{\frenchspacing See D. Knuth, \textit{The TeXBook}, Reading: Addison-Wesley, 20\textsuperscript{th} printing, rev., p. 376.}
%    \begin{macrocode}
\begingroup\def\\{\global\let\fe@fnsl@stoken= }\\ \endgroup
\def\fe@fnsl#1#2#3
	{
	\def\fe@fnsl@cs{#1}
	\def\fe@fnsl@space{#2}
	\def\fe@fnsl@next@ii{#3}
	\expandafter\chardef\fe@fnsl@space\z@
	\fe@fnsl@stepone
	}
\def\fe@fnsl@stepone
	{\expandafter\futurelet\fe@fnsl@cs\fe@fnsl@steptwo}
\def\fe@fnsl@steptwo
	{
	\expandafter\ifx\fe@fnsl@cs\fe@fnsl@stoken
		\let\fe@fnsl@next@i=\fe@fnsl@stepthree
	\else
		\let\fe@fnsl@next@i\fe@fnsl@next@ii
	\fi
	\fe@fnsl@next@i
	}
\def\fe@fnsl@stepthree
	{
	\expandafter\chardef\fe@fnsl@space\@ne
	\afterassignment\fe@fnsl@stepone\let\fe@fnsl@next@i= %
	}
\def\fe@fnsl@#1#2
	{
	\def\fe@fnsl@cs{#1}
	\def\fe@fnsl@next@ii{#2}
	\fe@fnsl@stepone@
	}
\def\fe@fnsl@stepone@
	{\expandafter\futurelet\fe@fnsl@cs\fe@fnsl@steptwo@}
\def\fe@fnsl@steptwo@
	{
	\expandafter\ifx\fe@fnsl@cs\fe@fnsl@stoken
		\let\fe@fnsl@next@i=\fe@fnsl@stepthree@
	\else
		\let\fe@fnsl@next@i\fe@fnsl@next@ii
	\fi
	\fe@fnsl@next@i
	}
\def\fe@fnsl@stepthree@
	{
	\afterassignment\fe@fnsl@stepone@\let\fe@fnsl@next@i= %
	}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\endforeach}
% The token \cmdarg\endforeach\ is used as a list delimiter. If executed, it expands to an error message.
%    \begin{macrocode}
\def\endforeach
	{
	\PackageError{forarray}
		{Tried to expand an \string\endforeach token. %
		Something is wrong.\MessageBreak
		The level of the current list is: %
			\the\fe@level\MessageBreak
		The content of the current item is: %
			\expandafter\strip@prefix\meaning\thislevelitem
			\MessageBreak
		The position of the item is:
			\the\thislevelcount}
		{No further immediate help available. Sorry.}
	}
%    \end{macrocode}
% \end{macro}
% The following auxilliary macros redefine several variables when entering or exiting a nesting level.
% \begin{macro}{\fe@@define@process}
% The macro \cmdarg\fe@@define@process\ processes a list of variables supplied by \cmdarg\fe@@define.
%    \begin{macrocode}
\def\fe@@define@process#1,
	{
	\def\fe@@define@Item{#1}
	\ifx\fe@@define@Item\empty
		\let\fe@@define@process@next\relax
	\else
		\def\fe@@define@process@next
			{
			\expandafter\expandafter\expandafter\def
			\expandafter\expandafter
			\csname
				\fe@VarMacro @\fe@@define@Item @rel@
				\romannumeral\fe@cnt@ii
			\endcsname
			\expandafter
				{
				\csname
					\fe@VarMacro @\fe@@define@Item @abs@
					\romannumeral\fe@cnt@i
				\endcsname
				}
			\fe@@define@process
			}
	\fi
	\fe@@define@process@next
	}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\fe@@define}
% The macro \cmdarg\fe@@define\ processes a list of variables supplied by \cmdarg\fe@define, iterating through the current nesting levels.
%    \begin{macrocode}
\def\fe@@define
	{
	\ifnum\fe@cnt@i>\m@ne
		\ifnum\fe@cnt@ii>\fe@define@max
			\let\fe@@define@next\relax
		\else
			\def\fe@@define@next{
				\expandafter\fe@@define@process\fe@Vars,{},
				\advance\fe@cnt@ii\@ne
				\advance\fe@cnt@i\m@ne
				\fe@@define
				}
		\fi
	\else
		\let\fe@@define@next\relax
	\fi
	\fe@@define@next
	}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\fe@define}
% The macro \cmdarg\fe@define\ supplies the names of variables that are being redefined when entering or exiting a nesting level.
%    \begin{macrocode}
\def\fe@define#1
	{
	\chardef\fe@define@max#1\relax
	\ifnum\fe@define@max>\z@
		\expandafter\fe@define@
	\else
		\expandafter\@gobble
	\fi
	}
\def\fe@define@#1
	{
	\def\fe@VarMacro{fe}
	\let\fe@Vars#1
	\fe@cnt@i\fe@level
	\fe@cnt@ii\@ne
	\fe@@define
	}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\fe@ProcessList}
% The macro \cmdarg\fe@ProcessList\ processes a list of variables supplied by \cmdarg\fe@DefLevelVar.
%    \begin{macrocode}
\def\fe@ProcessList#1,
	{
	\def\fe@ProcessList@check{#1}
	\ifx\fe@ProcessList@check\empty
		\let\fe@ProcessList@next\relax
	\else
		\def\fe@ProcessList@next
			{
			\fe@ProcessList@act{#1}
			\fe@ProcessList
			}
	\fi
	\fe@ProcessList@next
	}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\fe@DefLevelVar}
% The macro \cmdarg\fe@DefLevelVar\ redefines the expansion of the pointers \mbox{$\langle$\texttt{fe}$\vert$\texttt{fa}$\rangle$|@|\argsymb{pointer name}|@level|}.
%    \begin{macrocode}
\def\fe@DefLevelVar#1#2#3
	{
	\def\fe@ProcessList@act##1
		{
		\expandafter\expandafter\expandafter\def
		\expandafter\expandafter
		\csname #1@##1@level\endcsname
		\expandafter
		{\csname #1@##1@#2\endcsname}
		}
	\fe@ProcessList#3,{},
	}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\fe@define@position}
% The macro \cmdarg\fe@define@position\ defines a variable that contains the absolute position of the current item in a list, an array, or a system of nested lists and/or arrays. At this point, it is not being used by the package <<Package>>.
%    \begin{macrocode}
\def\fe@define@position
	{
	\ifnum\fe@level=\@ne
		\expandafter\expandafter\expandafter
			\def\expandafter\expandafter
			\csname fe@position@abs@\fe@levelrn\endcsname
			\expandafter
			{
			\csname fe@position@abs@\fe@upperlevelrn\endcsname
			\number\thislevelcount
			}
	\else
		\expandafter\expandafter\expandafter
			\def\expandafter\expandafter
			\csname fe@position@abs@\fe@levelrn\endcsname
			\expandafter
			{
			\csname fe@position@abs@\fe@upperlevelrn\endcsname
			-\number\thislevelcount
			}
	\fi
	}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\fe@AddToTokensX}
% The macro \cmdarg\fe@AddToTokensX\ adds the contents of a variable to a token list.
%    \begin{macrocode}
\def\fe@AddToTokensX#1#2
	{
	\expandafter\expandafter\expandafter#1
	\expandafter\expandafter\expandafter
	{\expandafter\the\expandafter#1#2}
	}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\fe@CollectLevelVar@}
% The macro \cmdarg\fe@CollectLevelVar@\ takes a list of variable names and assembles a corresponding list of pointer variables \mbox{$\langle$\texttt{fe}$\vert$\texttt{fa}$\rangle$@\argsymb{pointer name}@level}.
%    \begin{macrocode}
\def\fe@CollectLevelVar@#1#2#3
	{
	\expandafter\def\csname #1@level@#2\endcsname{}
	\def\fe@ProcessList@act##1{
		\expandafter\fe@AddToTokensX\expandafter
		\fe@toks\csname #1@##1@level\endcsname
		}
	\fe@toks{}
	\fe@ProcessList#3,{},
	\expandafter\expandafter\expandafter\def
		\expandafter\expandafter
		\csname #1@level@#2\endcsname\expandafter{\the\fe@toks}
	}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\fe@CollectLevelVar}
% The macro \cmdarg\fe@CollectLevelVar\ calls \cmdarg\fe@CollectLevelVar@.
%    \begin{macrocode}
\def\fe@CollectLevelVar{\fe@CollectLevelVar@{fe}}
%    \end{macrocode}
% \end{macro}
%
% \subsection{Macros for processing arrays}
%
% \subsubsection{User commands}
%
% This section contains the macros \cmdarg\ForArray\ and \cmdarg\ExitForEachLevels, as well as some macros associated with \cmdarg\ForArray\ that directly read information from the token stream following the call to \cmdarg\ForArray.
%
% \begin{macro}{\ForArray}
% When being called, the macro \cmdarg\ForArray\ checks whether a limit for the creation of pointers to levels relative to the current list or array level has been supplied, and whether an optional argument containing a separator for the list of separators is present.
%    \begin{macrocode}
\def\ForArray
	{
	\fe@aux@advancechardef\fa@arraylevel\@ne
	\expandafter\def\expandafter\fa@arraylevelrn\expandafter
		{\romannumeral\fa@arraylevel}
	\@ifnextchar(\fa@FA@WRelMax\fa@FA@WoRelMax
	}
\def\fa@FA@WRelMax(#1)
	{
	\expandafter\chardef
		\csname fa@relmax@\fa@arraylevelrn\endcsname#1\relax
	\ForArray@
	}
\def\fa@FA@WoRelMax
	{
	\expandafter\chardef
		\csname fa@relmax@\fa@arraylevelrn\endcsname\fe@relmax
	\ForArray@
	}
\def\ForArray@
	{\@ifnextchar[\fa@FA@WSepListSep\fa@FA@WoSepListSep}
\def\fa@FA@WSepListSep[#1]{\fa@FA@SepList#1}
\def\fa@FA@WoSepListSep{\fa@FA@SepList{}}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\fa@FA@SepList}
% The macro \cmdarg\fa@FA@SepList\ reads the list of separators and defines some variables used for processing the array.
%    \begin{macrocode}
\def\fe@aux@advancechardef#1#2
	{
	\count@#1
	\advance\count@#2
	\chardef#1\count@
	}
\def\fa@FA@SepList#1#2
	{
	\fe@DefLevelVar{fa}{\fa@arraylevelrn}
		{
		separatorcount,oldcatcode,baselevel,level,olddef,
		array,restore,next,separator,orientation,nextlevel,
		oldnextlevel,oldlowernextlevel
		}
	\expandafter\chardef
		\csname fa@level@\fa@arraylevelrn\endcsname\z@
	\ForEach
		{#1}
		{
			\expandafter\expandafter\expandafter\def
				\expandafter\expandafter
				\csname
					fa@separator@\fa@arraylevelrn @
					\romannumeral\thislevelcount
				\endcsname
				\expandafter
				{\thislevelitem}
		}
		{#2}
	\expandafter\chardef\fa@separatorcount@level\fe@count@total
	\fa@FA@MarkerList
	}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\fa@FA@MarkerList}
% The macro \cmdarg\fa@FA@MarkerList\ checks for an optional argument containing a list of markers, possibly with an additional optional argument that contains a separator for this list.
%    \begin{macrocode}
\def\fa@FA@MarkerList
	{\@ifnextchar[\fa@FA@WMarkerList\fa@FA@SublevelToken}
\def\fa@FA@WMarkerList[
	{\@ifnextchar[\fa@FA@WMarkerListSep\fa@FA@WoMarkerListSep}
\def\fa@FA@WMarkerListSep[#1]#2]{\fa@FA@MarkerList@{#1}{#2}}
\def\fa@FA@WoMarkerListSep#1]{\fa@FA@MarkerList@{}{#1}}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\fa@FA@MarkerList@}
% The macro \cmdarg\fa@FA@MarkerList@\ reads the list of markers.
%    \begin{macrocode}
\def\fa@FA@MarkerList@#1#2
	{
	\ForEach
		{#1}
		{
			\expandafter\expandafter\expandafter\def
				\expandafter\expandafter
				\csname
					fa@orientation@\fa@arraylevelrn @
					\romannumeral\thislevelcount
				\endcsname
				\expandafter
				{\thislevelitem}
		}
		{#2}
	\fa@FA@SublevelToken
	}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\fa@FA@SublevelToken}
% The macro \cmdarg\fa@FA@SublevelToken\ reads the token that is used to access sublevels and calls \cmdarg\fa@SublevelToken.
%    \begin{macrocode}
\def\fa@FA@SublevelToken#1
	{
	\expandafter\fa@SublevelToken\fa@array@level#1
	\fa@FA@Process
	}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\fa@FA@Process}
% The macro \cmdarg\fa@FA@Process\ reads the functions applied to the respective levels of the array and processes the content of the array.
%    \begin{macrocode}
\long\def\fa@FA@Process#1#2#3
	{
	\ForEach
		{#1}
		{
			\expandafter\expandafter\expandafter\def
				\expandafter\expandafter
				\csname
					fa@function@\fa@arraylevelrn @
					\romannumeral\thislevelcount
				\endcsname
				\expandafter
				{\thislevelitem}
		}
		{#2}
	\long\def\thislevelitem{#3}
	\fe@cnt@i\fe@level
	\advance\fe@cnt@i\@ne
	\expandafter\chardef\fa@baselevel@level\fe@cnt@i
	\expandafter\def\fa@array@level
		{
		\ifnum\fa@level@level=\fa@separatorcount@level\relax
			\expandafter\def\fa@next@level{\thislevelitem}
		\else
			\expandafter\let\fa@next@level\fa@next@level@

		\fi
		\fa@next@level
		}
	\fa@array@level
	\fa@restore@level
	\fe@aux@advancechardef\fa@arraylevel\m@ne
	\expandafter\def\expandafter\fa@arraylevelrn\expandafter
		{\romannumeral\fa@arraylevel}
	}
\def\fa@next@level@
	{
	\fa@SetLevelVars\tw@
	\expandafter\expandafter\expandafter\def
		\expandafter\expandafter\expandafter\fa@i
		\expandafter\expandafter\expandafter
		{
		\csname
		fa@separator@\fa@arraylevelrn @
		\romannumeral\fa@level@level
		\endcsname
		}
	\expandafter\expandafter\expandafter\expandafter
		\expandafter\expandafter\expandafter
		\ForEachSublevel@
		\expandafter\expandafter\expandafter\expandafter
		\expandafter\expandafter
		\csname
			fa@relmax@\fa@arraylevelrn
		\endcsname
		\expandafter
		\fa@i
		\expandafter
		{
		\csname
			fa@function@\fa@arraylevelrn @
			\romannumeral\fa@level@level
		\endcsname
		}
	\fa@SetLevelVars\@ne
	}
\def\fa@SetLevelVars#1
	{
	\fe@cnt@i\fe@level
	\advance\fe@cnt@i-\fa@baselevel@level
	\advance\fe@cnt@i#1
	\expandafter\chardef\fa@level@level\fe@cnt@i
	\thislevelnr\fa@level@level
	\expandafter\let\expandafter\thislevelmarker
		\csname
			fa@orientation@\fa@arraylevelrn @
			\romannumeral\fa@level@level
		\endcsname
	}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\ExitForEachLevels}
% The macro \cmdarg\ExitForEachLevels\ redefines the kernel macros \cmdarg\fe@next@\argsymb{start level} \textellipsis\ \cmdarg\fe@next@\argsymb{start level plus number of levels} of the current position of the array that is being processed. It essentially works in the same way as \cmdarg\ExitForEach.
%    \begin{macrocode}
\def\ExitForEachLevels#1#2
	{
	\fe@cnt@i\fe@level
	\fe@cnt@ii\z@
	\advance\fe@cnt@i\@ne
	\advance\fe@cnt@i-#1\relax
	\def\fe@exitforeach
		{
		\ifnum\fe@cnt@ii<#2\relax
			\def\fe@exitforeach@next
				{
				\expandafter\let
					\csname fe@next@\romannumeral\fe@level\endcsname
					\fe@ExitForEach@base
				\advance\fe@cnt@i\m@ne
				\advance\fe@cnt@ii\@ne
				}
		\else
			\let\fe@exitforeach@next\relax
		\fi
		\fe@exitforeach@next
		}
	\fe@exitforeach
	}
%    \end{macrocode}
% \end{macro}
%
% \subsubsection{Auxilliary macros}
%
% \begin{macro}{\fa@SublevelToken}
% The macro \cmdarg\fa@SublevelToken\ assigns a pointer to the control sequence or active character that is being used to access sublevels. It also defines how the expansion of this token is being reset after exiting a level of an array or nested list. The code at the end of this macro is taken from the \pname{inputenc} package.\footnote{\frenchspacing See A. Jeffrey and F. Mittelbach, inputenc.sty, v1.1b, May 5\textsuperscript{th}, 2006.}
%    \begin{macrocode}
\def\fa@SublevelToken#1#2
	{
	\expandafter\if\noexpand#2\relax
		\expandafter\let\fa@olddef@level#2
		\def#2{#1}
		\expandafter\def\fa@restore@level
			{\expandafter\let#2\fa@olddef@level}
	\else
		\chardef\fa@oldcatcode@level\catcode`#2\relax
		\ifnum\fa@oldcatcode@level=\active
			\expandafter\let\fa@olddef@level#2
		\else
			\catcode`#2\active
		\fi
		\expandafter\def\fa@restore@level
			{
			\ifnum\fa@oldcatcode@level=\active
				\expandafter\expandafter\expandafter
				\fa@SublevelToken
				\expandafter\expandafter\expandafter
				{\fa@olddef@level}{#2}
			\else
				\catcode`#2\fa@oldcatcode@level
			\fi
			}
			\bgroup
				\uccode`\~`#2\relax
				\uppercase{
			\egroup
					\def~{#1}
					}
	\fi
	}
%    \end{macrocode}
% \end{macro}
%
% \subsection{Macros for defining variables}
%
% \begin{macro}{\DefineArrayVar}
% The macro \cmdarg\DefineArrayVar\ first collects the items from the content list in an array of numbered variables and then assigns the content of these variables to the new variables.
%    \begin{macrocode}
\def\DefineArrayVar#1#2#3#4#5#6
	{
	\ForEach{#5}
		{
		\expandafter\expandafter\expandafter
			\def\expandafter\expandafter
			\csname
				fe@item@nr@\number\thislevelcount
			\endcsname
			\expandafter{\thislevelitem}
		}
		{#6}
	\ForEach{#3}
		{
		\expandafter\ifx
			\csname
				fe@item@nr@\number\thislevelcount
			\endcsname
			\relax
			\fe@DefineArrayVar@Warning{#4}{#5}
			\ExitForEach
		\else
			\expandafter\expandafter\expandafter\def
			\expandafter\expandafter\expandafter
			\fa@ArrayVarContent
			\expandafter\expandafter\expandafter
				{
				\csname
					fe@item@nr@\number\thislevelcount
				\endcsname
				}
			\expandafter\ifx
				\csname
					fe@item@nr@\number\thislevelcount
				\endcsname
				\empty
				\typeout
					{Content of	\expandafter\string
					\csname #1#2\thislevelitem\endcsname\space
					is set to nothing.}
			\else
				\typeout
					{Content of	\expandafter\string
					\csname #1#2\thislevelitem\endcsname\space
					is set to %
					\expandafter\strip@prefix
					\meaning\fa@ArrayVarContent.}
			\fi
			\expandafter\expandafter\expandafter\def
				\expandafter\expandafter
				\csname #1#2\thislevelitem\endcsname\expandafter
				{\fa@ArrayVarContent}
		\fi
		}
		{#4}
	}
\def\fe@DefineArrayVar@Warning#1#2
	{
	\PackageWarning
		{fornext}
		{
		No more items available while %
			defining pointers!\MessageBreak
		Pointers: #1\MessageBreak
		Items:\space\space\space #2
		}
	}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\DefineArrayVars}
% The macro \cmdarg\DefineArrayVars\ first defines a function that passes information read from its parameters to \cmdarg\DefineArrayVar, and then calls this function within a \cmdarg\ForEach\ loop.
%    \begin{macrocode}
\def\DefineArrayVars#1#2#3#4#5#6#7
	{
	\typeout{}\typeout{Defining Array Variables...}
	\def\fe@DefineArrayVar@##1#3##2#3##3#2
		{
		\typeout{-- Initializing new variable array: ##1}
		\DefineArrayVar
			{##1}{#5}{#1}{##3}{#4}{##2}
		}
	\ForEach
		{#2}
		{\expandafter\fe@DefineArrayVar@\thislevelitem#3#6#2}
		{#7}
	}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\DefineArrayDefault}
% The macro \cmdarg\DefineArrayDefault\ assigns an |\ifx| \textellipsis\ |else| \textellipsis\ |\fi| structure to the pointers supplied with its last argument.
%    \begin{macrocode}
\def\DefineArrayDefault#1#2#3#4#5
	{
	\ForEach
		{#1}
		{
		\expandafter\edef\csname\thislevelitem\endcsname
			{
			\noexpand\expandafter\noexpand\ifx
			\noexpand\csname
				\thislevelitem #2\noexpand#3
			\noexpand\endcsname
			\noexpand\relax
				\noexpand\csname
					\thislevelitem #2#4
				\noexpand\endcsname
			\noexpand\else
				\noexpand\csname
					\thislevelitem #2\noexpand#3
				\noexpand\endcsname
			\noexpand\fi
			}
		}
		{#5}
	}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\DefineArrayVarTo}
% The macro \cmdarg\DefineArrayVarTo\ assigns the same value to the variables supplied with its last argument.
%    \begin{macrocode}
\def\DefineArrayVarTo#1#2#3#4#5
	{
	\ForEach
		{#1}
		{\expandafter\expandafter\expandafter\def\expandafter
			\csname #3#2\thislevelitem\endcsname{#4}}
		{#5}
	}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\CommandForEach}
% The macro \cmdarg\CommandForEach\ places the items of the list immediately after the token list that is being supplied as the command.
%    \begin{macrocode}
\def\CommandForEach#1#2#3
	{\ForEach#1{\expandafter#2\thislevelitem}{#3}}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\FunctionForEach}
% The macro \cmdarg\FunctionForEach\ expands the items of the list inside braces and immediately places the token group after the token list that is being supplied as the function.
%    \begin{macrocode}
\def\FunctionForEach#1#2#3
	{\ForEach#1{\expandafter#2\expandafter{\thislevelitem}}{#3}}
%    \end{macrocode}
% \end{macro}
%
% \subsection{Final commands}
%
%    \begin{macrocode}
\endlinechar\fe@aux@endlinecharrestore\relax
\makeatother
%</sty>
%    \end{macrocode}
%
% \section{Test page}
%
% The file |forarray-test.tex| contains the following code that generates a test page for the package <<Package>>.
%
%    \begin{macrocode}
%<*test>
\documentclass[10pt,a4paper]{article}
\usepackage[latin1]{inputenc}
\usepackage[T1]{fontenc}
\usepackage[margin=2cm]{geometry}
\usepackage[dvips, pdfborder={0 0 0}, pdfstartview={FitH}, 
	pdfpagelayout={OneColumn}, bookmarks=false, pdfnewwindow, 
	unicode=true]{hyperref}
\urlstyle{same}
\usepackage{examplep}
\usepackage{forarray}
\author
	{
	<<Author>>%
	\footnote%
		{
		Please send any comments or suggestions to %
		\protect<<Address>>.%
		}
	}
\title
	{
	Test page for the %
		{\fontfamily{cmss}\selectfont <<File Identifier>>} % 
		package\\ [.5ex]\Large Version <<Version>> (<<Date>>)
	}
\def\ShowExample{
	\PexaShowBoth{
		yalign=b,
		allowbreak=yes,
		srcstyle=leftnumcol,
		}
	}
\arrayrulewidth=0pt
\begin{document}
\errorcontextlines=20\relax
\maketitle
\thispagestyle{empty}
\small
\section{Test of \texttt{ForEach} (Simple List)}
\begin{WBoth}
\begin{itemize}
\ForEach{,}
	{\item Item No.\ %
		\the\thislevelcount\ is:
		``\thislevelitem''\\{\footnotesize
		\meaning\thislevelitem}}
	{
	{Hello, World!},  Sec{ond},
	   {Thi}rd,{\bf Last}   item%
	}
\end{itemize}
\end{WBoth}
\ShowExample
\section{Test of \texttt{ForEach} (Nested)}
\begin{WBoth}
\begin{itemize}
\ForEach{;}
	{\item[\the\thislevelcount)]
		\raggedright\thislevelitem
	\begin{itemize}
	\ForEachX{,}
		{\item Item No.\ %
		\the\thislevelcount\ %
		is: \thislevelitem}
		{\thislevelitem}
	\end{itemize}}
	{$\alpha$,$\beta$,$\gamma$;
	{\Large A Large Item},
	Transparency \it test,
	Ends \rm here.}
\end{itemize}
\end{WBoth}
\ShowExample
\section{Test of \texttt{ForArray}}
\makeatletter
\begin{WBoth}
\parindent=0pt
\def\MyArray{\ForArray(3){;,}{*}{|}}
\MyArray
	{*\par\vskip 3ex|\parbox{8em}{*}}
	{
	A,B,C;
	\textit{A nested array:}\par
	\MyArray{[*]\par|(*)}{1,2;3,4},b,c;
	$\alpha$,$\beta$,$\gamma$
	}
\end{WBoth}
\ShowExample
\end{document}
%</test>
%    \end{macrocode}
%
% \section{Copyright Notice}
%
% <<Copyright Notice>>
%
%</tex>
%<begin text>
%<*readme>
Note: This file should be viewed with character map <<Character Map>>.


<<Description>>: The package <<Package>>


Version <<Version>> (<<Date>>)

<N><<Abstract>>

<N><<Copyright>>

<N><<Content>>

<N><<Installation>> 
 
<N><<Documentation>>

<N><<DTM File>>
%</readme>
%<end text>
