How Does the LaTeX \@for Loop Work?
At a glance
- 1. Enable at-sign names
In a document, place \makeatletter before \@for and \makeatother after it.
- 2. Give the loop variable
Write a control sequence after \@for, followed by :=.
- 3. List the items
Separate items with commas; braces protect commas that belong inside one item.
- 4. Write the repeated code
Put the code to run for each item inside the braces after \do.
LaTeX’s \@for command repeats a block of code once for each item in a comma-separated list. On each pass, it defines a chosen macro to contain the current item, so the block can use that macro.
The command is part of LaTeX’s internal programming interface. The at sign in its name needs special handling in ordinary document code; the example below shows the required setup.
Basic syntax
The general form is:
\makeatletter
\@for\variable:=item1,item2,item3\do{%
code that uses \variable
}
\makeatother
The parts mean:
\variableis the control sequence that holds the current item. Choose a macro name that does not conflict with another command.:=marks the start of the list.- Commas separate list items.
\do{...}contains the code repeated for every item.
The braces after \do group the repeated code. Use % at line ends when needed to prevent unwanted spaces in typeset output.
Complete working example
This document prints three lines, with \fruit taking a different value each time:
\documentclass{article}
\begin{document}
\makeatletter
\@for\fruit:=apple,pear,plum\do{%
\noindent Item: \fruit\par
}
\makeatother
\end{document}
The first pass sets \fruit to apple and typesets Item: apple. The next passes use pear and plum. In the loop body, \fruit means the current item; after the loop, do not rely on it having a useful value.
Why \makeatletter is needed
In normal LaTeX documents, @ is not treated as a letter when TeX reads command names. As a result, TeX does not read \@for as one command unless the category code of @ is changed first. \makeatletter makes @ a letter, and \makeatother restores the usual setting.
Put these commands around the code that uses \@for. If you are writing a .sty package or .cls class file, LaTeX normally makes @ a letter while that file is read, so the wrappers are generally unnecessary there. Keep the wrappers balanced in a document so later commands are read with the usual rules.
Commas, braces, and spaces
A comma is a separator, so a list such as red,green,blue contains three items. If an item itself includes a comma, enclose that item in braces, as in one,{two, with comma},three. Braces group the comma so it is not treated as a list separator. For complicated data, nested lists, or values that depend on expansion, \@for may not be the best tool; use a purpose-built interface instead.
Avoid accidental spaces around list items. TeX can retain spaces as tokens, and \@for is a low-level macro rather than a general data-processing function. If the loop is producing unexpected spacing or item contents, simplify the list and test one item at a time. Also avoid assuming that empty entries, such as those suggested by consecutive or trailing commas, will be handled like entries in another programming language.
Common mistakes
Forgetting \makeatletter. In a document, writing \@for without changing the category code of @ can lead to an undefined-command error or unexpected parsing.
Using the wrong separator. The list uses commas, not spaces. A list written as apple pear plum is not three comma-separated values.
Omitting the \do block braces. The repeated code belongs in the argument following \do. Keep the braces around the whole block, even if it contains several commands.
Reusing the loop macro inside a nested loop. An inner loop that assigns to the same macro overwrites the outer loop’s current value. Give nested loops different variable macros.
Treating \@for as a public, high-level interface. It is a LaTeX internal command, useful in package and class code and sometimes convenient in a document. For document-level iteration, a package such as pgffor provides the public-facing \foreach command and features designed for that purpose.
References
Spotted an error? Send a correction. Read how we write and check articles in our editorial policy.