How to create multi-pass command in a .cls

Question

I have a command that creates some canned text at the top of a file that requires information about the location of an environment I've created. I've got the code for this all put together, and it works just fine at the end of the document, but I'm required to put it at the head of the document.

Specifically, I've got a command

\newcommand\Pages{\expandafter\@printWatermarkedPage\@watermarkedPages,@}
\makeatother

\newcommand{\makeparagraph}{
Pages \Pages of this document has watermarks
}

where a bunch of logic populates the watermarkedPages list (see here for more Iterate over pages and set variable) and I need to print the resulting phrase up at the top. If I simply move the current implementation to the head of the document, I get a "Missing \endcsname inserted." error, which I assume is because the list hasn't been populated yet.

How does one create a command that knows it needs multiple passes to get the information it needs?

Answer 1

I've taken the accepted answer from Iterate over pages and set variable and added the necessary components to allow for using a \label-\ref approach to extracting the watermarked pages.

I've added

\usepackage{atveryend}
\newcommand\printWatermarkedPages{%
  \@ifundefined{r@watermark-pages}{??}{%
    \edef\@thewatermarkedPages{\expandafter\expandafter\expandafter\@firstoffive\csname r@watermark-pages\endcsname}%
    \expandafter\@printWatermarkedPage\@thewatermarkedPages,@%
  }%
}
\AfterLastShipout{
  \immediate\write\@auxout{\string\newlabel{watermark-pages}{{\@watermarkedPages}{}{}{watermark.end}{}}}
}

which does two things:

1. Writes the "watermark labels" to the .aux in the form of the reference/\label at the end of the document with the aid of atveryend's \AfterLastShipout. You might get away without this and just using \AtEndDocument).

2. Creates \printWatermarkedPages which inserts the hyperlinked sequence of watermarked pages (similar to \WatermarkedPages) obtained from the above-mentioned reference.

Here's a complete minimal example:

\documentclass{article}
\usepackage[contents={Watermarked!},pages=some]{background}
\usepackage[colorlinks]{hyperref}
\pagenumbering{arabic}

\newcounter{watermark}

\makeatletter
\newif\ifWatermarkPage\WatermarkPagefalse% true if page should be watermarked
\newif\ifStillWatermarking\StillWatermarkingfalse% true if we want a watermark on the next page
\AddEverypageHook{%
  \ifWatermarkPage%
    \bg@material%
  \else%
    \ifStillWatermarking%
      \global\WatermarkPagefalse%
      \AddWatermarkLabels\bg@material%
    \fi%
  \fi%
  \global\WatermarkPagefalse%
}
% will hold a comma separated list of labels for the watermarked pages
\def\@watermarkedPages{\@gobble}  % gobble will eat an initial comma
% add a watermark and create a label - unless we've already done this for this page
\newcommand\AddWatermarkLabels{%
  \ifWatermarkPage%  already have label, so do nothing
  \else%
    \global\WatermarkPagetrue
    \refstepcounter{watermark}% increment number of watermarked pages
    % NB. Using \label{watermark:\thepage} doesn't write to the aux file 
    % when this is called via \AddEverypageHook, so we do it ourselves:
    \immediate\write\@auxout{\string\newlabel{watermark:\thepage}{{\thewatermark}{\thepage}{}{watermark.\thewatermark}{}}}
    \global\edef\@watermarkedPages{\@watermarkedPages,watermark:\thepage}% add label
  \fi
}
\newenvironment{watermarked}%
    {\global\StillWatermarkingtrue\AddWatermarkLabels}
    {\global\StillWatermarkingfalse\AddWatermarkLabels} % this page still needs a watermark

% The next macros pass the labels in \@watermarkedPages to \pageref taking
% care to add commas between references and an "and" between the last two.
\def\@printWatermarkedPage#1,#2{\pageref{#1}%
  \ifx#2@\let\@nextWatermark\@gobble%
  \else\let\@nextWatermark\@printWatermarkedPages%
  \fi%
  \@nextWatermark#2%
  }
\def\@printWatermarkedPages#1,#2{%
  \ifx#2@ and \let\@nextWatermark\@gobble\else ,\fi%
  \pageref{#1}%
  \@nextWatermark#2%
}
\newcommand\WatermarkedPages{\expandafter\@printWatermarkedPage\@watermarkedPages,@}

\usepackage{atveryend}
\newcommand\printWatermarkedPages{%
  \@ifundefined{r@watermark-pages}{??}{%
    \edef\@thewatermarkedPages{\expandafter\expandafter\expandafter\@firstoffive\csname r@watermark-pages\endcsname}%
    \expandafter\@printWatermarkedPage\@thewatermarkedPages,@%
  }%
}
\AfterLastShipout{
  \immediate\write\@auxout{\string\newlabel{watermark-pages}{{\@watermarkedPages}{}{}{watermark.end}{}}}
}
\makeatother

\begin{document}
Watermarks on pages \printWatermarkedPages.% 2,4,5,6,7


Some text here on page  1.
\newpage

\begin{watermarked}
some text
\end{watermarked}

\begin{watermarked}
more text
\end{watermarked}

More text here.

\newpage
Page with no watermarked stuff.
\newpage

\begin{watermarked}
more text,
\newpage
on several pages
\newpage
\end{watermarked}

More text here. Start a new page.
\newpage

\begin{watermarked}
more text
\end{watermarked}

\newpage
Loop to find pages containing the watermarked environment. Hard coded
here.

The \arabic{watermark} watermarked environments appear on the following
pages \printWatermarkedPages.

\end{document}

You can use \printWatermarkedPages anywhere in the document in the same way you would normally use \ref.