path: root/macros/latex/contrib/collcell/collcell.dtx

% \iffalse meta-comment
%
% Copyright (C) 2009-2011 by Martin Scharrer <martin@scharrer-online.de>
% ----------------------------------------------------------------------
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
% of this license or (at your option) any later version.
% 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 2008/05/04 or later.
%
% This work has the LPPL maintenance status `maintained'.
%
% The Current Maintainer of this work is Martin Scharrer.
%
% This work consists of the files collcell.dtx, collcell.ins
% and the derived file collcell.sty.
%
% \fi
%%^^A $Id: collcell.dtx 2188 2011-02-27 14:22:06Z martin $
%
% \iffalse
%<package>\ProvidesPackage{collcell}
%<*driver>
\ProvidesFile{collcell.dtx}
%</driver>
  [2011/02/27 v0.5 Collect the content of a tabular cell]
%<*driver>
\documentclass{ydoc}
\GetFileInfo{\jobname.dtx}
\usepackage[robustcr]{collcell}[\filedate]
\usepackage{tikz-timing}
\lstset{language=[latex]tex,basicstyle=\ttfamily}

\EnableCrossrefs
%\CodelineIndex
\RecordChanges
%\OnlyDescription
\begin{document}
  \DocInput{\jobname.dtx}
  \PrintChanges
  %\newpage\PrintIndex
\end{document}
%</driver>
% \fi
%
% \CheckSum{334}
%
% \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         \~}
%
%
% \changes{v0.0}{2009/08/13}{Created package}
% \changes{v0.1}{2011/02/04}{First released version}
% \changes{v0.1a}{2011/02/05}{Fixed unwanted spaces. Fixed misspelled macros in example.}
% \changes{v0.5}{2011/02/27}{Fixed several bugs and limitations. (Complete list to be inserted)}
%
%
% \DoNotIndex{\newcommand,\newenvironment,\def,\edef,\xdef,\DeclareRobustCommand}
%
% \GetFileInfo{\jobname.dtx}
% \ifpdf
% \hypersetup{%
%   pdfauthor   = {Martin Scharrer <martin@scharrer-online.de>},
%   pdftitle    = {The collcell package},
%   pdfsubject  = {Documentation of LaTeX package collcell},
%   pdfkeywords = {collcell, LaTeX, TeX}
% }%
% \fi
% \clearpage
% \null
% \vspace*{-2em}
% \begin{center}
%   {\LARGE The \textsf{collcell} Package\\[\medskipamount]}
%   {\large Martin Scharrer \\[\medskipamount]\normalsize 
%   \url{martin@scharrer-online.de}\\[.8ex]
%   \url{http://www.ctan.org/pkg/collcell/}\\[\medskipamount]}
%   {\large Version \fileversion\ -- \filedate}\\
% \end{center}
% \vspace{1.2em}%
%
% \begin{abstract}
% This package provides macros which collect the cell content of a tabular
% and provide it to a macro as argument. It was inspired by the |\collect@body|
% macro defined by the \pkg{amsmath} or the \pkg{environ} package, which can be used
% to collect the body of an environment. Special care is taken to remove all aligning
% macros inserted by tabular from the cell content. The macros also work in the last
% column of a tabular. They do not support verbatim material inside the cells, except of a
% special almost-verbatim version of \verb+\verb+.
%
% This package is relatively new and might still not work in all possible situations which can arise
% in a tabular. The implementation might change in future versions. Please do not hesitate to contact the
% author about any issue and suggestions.
% \end{abstract}
%
% \section{Usage}
% This package provides the macros \Macro\collectcell and \Macro\endcollectcell
% which are supposed to be used with the |>{ }| and |<{ }| tabular column declarations of
% the \pkg{array} package. This can be done either in the argument of tabular or using
% \Macro\newcolumntype.
%
% The following code defines a `|E|' column which passes the contents of its cell
% to \Macro\usermacro as an argument. The macro can the process the content as usual.
%
% \par\bigskip
% \noindent
% |% Preamble:|\\
% |\usepackage{array}|\\
% |\usepackage{collcell}|\\
% |% Preamble or document:|\\
% |\newcolumntype{E}{>{\collectcell\usermacro}c<{\endcollectcell}}|\\
% ||\\
% |% Document:|\\
% |\begin{tabular}{lE}|\\
% |   A & Example \\ % Same as \usermacro{Example} |\\ 
% |   B & Text    \\ % Same as \usermacro{Text}    |\\
% |\end{tabular}|\\
% \par\medskip
%
% For example \Macro\usermacro could be \Macro\fbox and wrap the cell content in a frame box.
% More complicated macros are also supported as long they take one argument. This package
% was originally programmed to be used with the \Macro\tikztiming macro of the \pkg{tikz-timing} package.
% This macro takes some complex user input and draws a timing diagram from it
%
% Note that if such a cell contains a tabular environment by itself, the environment must be wrapped
% in braces `|{ }|' to ensure proper operation.
%
% \subsection{Options}
% The following options are supported:
% \begin{description}
%   \item[verb] \null
%   \item[noverb] (Default |noverb|) Enables or disables the definition of a special almost-verbatim version of \verb+\verb+.
%     At the moment the one defined by the \pkg{tabularx} package is used, which is therefore loaded when this feature is enabled.
%     Future versions of \pkg{collcell} might provide this macro in a different way, so the visual result might be different.
%     The \pkg{tabularx} should be loaded explicitly if it is used.
%     This version of \verb+\verb+ will read the content first normally, i.e. non-verbatim, and then print the included tokens in a verbatim format.
%     The content must include a balanced number of |{ }| and must not be end with |\|. Macros inside the content will be followed by a space.
%     See the manual of \pkg{tabularx} (page 8 in the version from 1999/01/07) for a more detailed description.
%   \item[robustcr]
%   \item[norobustcr] (Default |robustcr|) This options enable or disable the redefinition of |\\| to a robust version, i.e. this macro
%     will be prefixed with eTeX's |\protected| to ensure that it isn't expanded by the underlying |\halign|. If this feature disabled the
%     last cell of a tabular must not be empty or only hold empty macros (like |\empty|).
% \end{description}
%
% \subsection{Limitations}
%
% \DescribeMacro\ccunskip
% The macro |\unskip| should not be included inside the cell directly, but only inside a |{ }| group or a macro.
% Otherwise it will be taken as part of the internal cell code and ignored. Leading spaces will however be removed.
% This macro can be used as a replacement of |\unskip| inside the cells.
%
% \DescribeMacro\cci
% The content of every cell is expanded by TeX itself until the first non-expandable token (macro, character, \ldots) is found. This happens to check if a |\noalign| follows
% with e.g.\ is used inside |\hrule| and other rule drawing macros. There is nothing what \pkg{collcell} could do about this.
% If this expansion is unwanted the non-expandable token \Macro\cci should be placed at the beginning of the cell. This macro will be ignored (discarded) by \pkg{collcell} and
% will not be provided to the user macro (|cci| = collect cell; ignore).
%
% \section{Tests and Examples}
%
% \begin{example}
% \caption{Framebox, texttiming, expanded tokens, sub-tabular}
% \begin{examplecode}
%     \makeatletter
%     \newcommand*\Meaning[1]
%        {\def\CODE{#1}\texttt{\expandafter\strip@prefix\meaning\CODE}}%
%     \newcolumntype{F}{>{\collectcell\fbox}l<{\endcollectcell}}%
%     \newcolumntype{M}{>{\collectcell\Meaning}l<{\endcollectcell}}%
%     \newcolumntype{T}{>{\collectcell\texttiming}l<{\endcollectcell}}%
%     \begin{tabular}{@{}F@{}|@{}M@{}|@{}T@{}}
%        A & B                       & HLDZ 2{HZLZ} \\
%        A & \empty\relax Z5D{TEST}Z & Z5D{TEST}Z  \\
%        A & \cci\empty Z5D{TEST}Z & Z5D{TEST}Z  \\
%        {\begin{tabular}{cFc} a & b & c \end{tabular}} &
%         \relax\begin{quote}AA\end{quote}   & $5+5${C} \\
%        A & B   \ccunskip B                 & 3{ttz} \\
%     \end{tabular}%
% \end{examplecode}
% \end{example}
%
% \makeatletter
% \newcommand*\Meaning[1]{\def\CODE{#1}\texttt{\expandafter\strip@prefix\meaning\CODE}}%
% \newcolumntype{M}{>{\collectcell\Meaning}l<{\endcollectcell}}%
% \newcolumntype{F}{>{\collectcell\fbox}l<{\endcollectcell}}%
% \makeatother
%
% \begin{example}
% \caption{Multicolumn, expanded row macro}
% \begin{examplecode}
%     \def\abc{ \empty A & \empty B & \empty C }
%     \begin{tabular}{MMM}
%       \multicolumn{2}{M}{\empty Multi} & \empty single \\
%       \abc \\
%     \end{tabular}
% \end{examplecode}
% \end{example}
%
% \begin{example}
% \caption{Empty cells, missing `\texttt{\textbackslash\textbackslash}' at end}
% \begin{examplecode}
%     \begin{tabular}{|F|F|F|}
%        \\
%        A & \\
%        A & B \\
%        A & B & \\
%        A & B & C \\
%        & \\
%        & B \\
%        & B & \\
%        & B & C \\
%        & & \\
%        & & C \\
%        A & B & C
%     \end{tabular}
% \end{examplecode}
% \end{example}
%
% \StopEventually{}
% \clearpage
% \iffalse
%<*package>
% \fi
% \section{Implementation}
%
%    \begin{macrocode}
\RequirePackage{array}
\def\collcell@beforeuser{\ignorespaces}
\def\collcell@afteruser{\unskip}

\newif\if@collcell@verb
\newif\if@collcell@robustcr
\@collcell@robustcrtrue
%    \end{macrocode}
%
% \subsection{Options}
%    \begin{macrocode}
\DeclareOption{verb}{\@collcell@verbtrue}
\DeclareOption{noverb}{\@collcell@verbfalse}
\DeclareOption{robustcr}{\@collcell@robustcrtrue}%
\DeclareOption{norobustcr}{\@collcell@robustcrfalse}%
\ProcessOptions\relax
\if@collcell@verb
  \RequirePackage{tabularx}
  \def\collcell@beforeuser{%
    \let\collcell@savedverb\verb
    \let\verb\TX@verb
    \let\TX@vwarn\collcell@vwarn
    \ignorespaces
  }%
  \def\collcell@afteruser{\unskip\let\verb\collcell@savedverb}%
  \def\collcell@vwarn{%
    \PackageWarning{collcell}{\noexpand\verb may be unreliable inside a collected cell}%
  }%
\fi
\if@collcell@robustcr
  \RequirePackage{etoolbox}
  \robustify\@arraycr
\fi
%    \end{macrocode}
%
% \subsection{Collect cell content}
%    \begin{macrocode}
\let\collect@cell@toks\@temptokena
\newcount\collect@cell@count
%    \end{macrocode}
%
% \begin{macro}{\collectcell}[2]{user macro(s)}{ignored tokens, possible empty}
%    \begin{macrocode}
\newenvironment{collectcell}{}{}
\def\collectcell#1#2\ignorespaces{%
  \begingroup
  \collect@cell@count\z@
  \collect@cell@toks{}%
  \let\collect@cell@spaces\empty
  \def\collect@cell@end{%
    \expandafter\endgroup
    \expandafter\collcell@beforeuser
    \expandafter\ccell@swap\expandafter{\the\collect@cell@toks}{#1}%
    \collcell@afteruser
  }%
  \collect@cell@look#2%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\ccell@swap}
% Swaps the two arguments. The second one (user macro(s)) is added without braces.
%    \begin{macrocode}
\def\ccell@swap#1#2{#2{#1}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\endcollectcell}
% Holds unique signature which will expand to nothing.
%    \begin{macrocode}
\def\endcollectcell{\@gobble{endcollectcell}}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\collect@cell@look}
% Looks ahead to the next token and call the next macro to handle it.
%    \begin{macrocode}
\def\collect@cell@look{%
  \futurelet\collect@cell@lettoken\collect@cell@look@
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\collect@cell@eatspace}
% Eats a following space and call the 'look' macro again.
%    \begin{macrocode}
\@firstofone{\def\collect@cell@eatspace} {\collect@cell@look}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\collect@cell@look@}
% Handles special tokens which should not be read as argument.
% All other are handled by \Macro\collect@cell@arg.
%    \begin{macrocode}
\def\collect@cell@look@{%
  \cc@case
    \@sptoken{%
      \edef\collect@cell@spaces{\collect@cell@spaces\space}%
      \collect@cell@eatspace
    }%
    \bgroup{\collect@cell@group}%
    \default{\collect@cell@arg}%
  \endcc@case
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\collect@cell@group}
% Tests if the previous discovered |begin-group character {| token was a |\bgroup| or a |{|.
% In the first case the command sequence is simply added but in the second case the surrounding 
% braces must be added again.
% The use of |\unexpanded| allows |#| in the cells, e.g. for in-cell macro definitions.
%    \begin{macrocode}
\def\collect@cell@group#1{%
  \begingroup
  \edef\@tempa{\unexpanded{#1}}%
  \def\@tempb{\bgroup}%
  \ifx\@tempa\@tempb
    \endgroup
    \collect@cell@addarg{#1}%
  \else
    \endgroup
    \collect@cell@addarg{{#1}}%
  \fi
  \collect@cell@look
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\collect@cell@addarg}
% Adds the given argument to the token list.
%    \begin{macrocode}
\def\collect@cell@addarg#1{%
  \expandafter\expandafter\expandafter\collect@cell@toks
  \expandafter\expandafter\expandafter
  {\expandafter\the\expandafter\collect@cell@toks\collect@cell@spaces#1}%
  \let\collect@cell@spaces\empty
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\collect@cell@addcc}
% This macro is called when another |\collectcell| is found in the preamble
% (at the moment also inside the cell). The argument of it is placed into the
% token register and all following tokens are placed in an own token list which content
% is then added with surrounding braces in the outer token list once the |\endcollectcell|
% is found. TeX scoping mechanism is used for this so only one token register is required.
%    \begin{macrocode}
\def\collect@cell@addcc#1{%
  \collect@cell@addarg{#1}%
  \begingroup
  \collect@cell@toks{}%
  \collect@cell@look
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\collect@cell@checkcsname}
% For support of |\end{tabularx}| without trailing |\\|.
%    \begin{macrocode}
\def\collect@cell@checkcsname#1\endcsname{%
  \begingroup
  \expandafter\ccell@swap\expandafter
    {\expandafter,\@currenvir,endtabular,endtabular*,array,tabularx,}%
    {\in@{,#1,}}%
  \ifin@
    \endgroup
    \expandafter\@firstoftwo
  \else
    \endgroup
    \expandafter\@secondoftwo
  \fi
    {\collect@cell@cr\\\csname#1\endcsname}%
    {\collect@cell@addarg{\csname#1\endcsname}\collect@cell@look}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\collect@cell@checkend}[1]{The argument of an \string\end~macro}
% Reads the argument of |\end| and checks if it is identical to the current environment (|tabular|, |array|, |tabularx|, ...).
% If so the collecting of token is ended, otherwise the |\end| and its argument are added to the 
%    \begin{macrocode}
\def\collect@cell@checkend#1{%
  \begingroup
  \def\@tempa{#1}%
  \ifx\@tempa\@currenvir
    \endgroup
    \expandafter\@firstoftwo
  \else
    \endgroup
    \expandafter\@secondoftwo
  \fi
    {\collect@cell@cr\\\end{#1}}%
    {\collect@cell@addarg{\end{#1}}\collect@cell@look}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\cc@iftoken}
% Compares the |\collect@cell@lettoken| with the token given as argument.
%    \begin{macrocode}
\def\cc@iftoken#1{%
  \ifx#1\collect@cell@lettoken
    \expandafter\@firstoftwo
  \else
    \expandafter\@secondoftwo
  \fi
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\cc@case}
% Case statement over |\collect@cell@lettoken|.
%    \begin{macrocode}
\def\cc@case{%
  \begingroup
  \let\default= \collect@cell@lettoken
  \cc@@case
}
\def\cc@@case#1{%
  \ifx#1\collect@cell@lettoken
    \expandafter\cc@@truecase
  \else
    \expandafter\cc@@falsecase
  \fi
}
\def\cc@@truecase#1#2\endcc@case{\endgroup#1}
\def\cc@@falsecase#1{\cc@@case}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\collcell@unskip}
% Wrapper around |\unskip| to protect it from the eyes of the token scanner.
% It is protected to avoid trouble if the user wrongly uses it at the beginning of the cell.
% The macro is first defined using |\newcommand| to warn the user about name collisions.
%    \begin{macrocode}
\newcommand*\ccunskip{}
\protected\def\ccunskip{\unskip}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\cci}
% Protected empty macro usable to stop the expansion of tokens at the beginning of the
% cell. It is ignored (gobbled) by the token scanner.
% The macro is first defined using |\newcommand| to warn the user about name collisions.
%    \begin{macrocode}
\newcommand*\cci{}
\protected\def\cci{}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\collect@cell@cr}
% Redefines the table line/row end macro |\cr| so that 
% token collection is restarted after the real |\cr| is expanded
% and the end material defined by `<{}` is inserted.
%
% This redefinition must be done around some \emph{dirty tricks}
% otherwise the |\cr| will be wrongly taken as end of the
% row.
%
% Because the redefinition is done just at the end of a cell inside the group
% opened by |collcell| it will only be locally.
%    \begin{macrocode}
\def\collect@cell@cr{%
  \iffalse{\fi
  \let\collcell@realcr\cr
  \def\cr{%
    \expandafter
    \collect@cell@look
    \collcell@realcr
  }%
  \iffalse}\fi
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\collect@cell@arg}
% Handles the arguments.
% The first token of the argument is still in the |lettoken| macro which is compared
% against a list of possible end tokens.
% Then either the cell end is handled or the argument is added to the token register
% and the rest of the cell is processed.
%    \begin{macrocode}
\def\collect@cell@arg#1{%
  \cc@case
    \\{\collect@cell@cr#1}%
    \end{\collect@cell@checkend}%
    \csname{\collect@cell@checkcsname}%
    \unskip{%
      \let\collect@cell@spaces\empty
      %\collect@cell@addarg{#1}% do not include the \unskip
      \collect@cell@look%
    }%
    \@sharp{%
      \expandafter\collect@cell@addarg\expandafter{#1}%
      \collect@cell@look
    }%
    \collectcell{%
      \advance\collect@cell@count by \@ne
      \collect@cell@addcc%
    }%
    \endcollectcell{%
      \ifnum\collect@cell@count=\z@
        \expandafter\collect@cell@end
      \else
        \expandafter\endgroup
        \expandafter\collect@cell@addarg\expandafter
        {\expandafter{\the\collect@cell@toks}}%
        \advance\collect@cell@count by \m@ne%
        \expandafter\collect@cell@look
      \fi
    }%
    \cci{%
      \collect@cell@look
    }%
    \default{%
      \expandafter\ccell@swap\expandafter
        {\csname endtabular*\endcsname\endtabular\endarray}{\in@{#1}}%
      \ifin@
          \expandafter\@firstoftwo
      \else
          \expandafter\@secondoftwo
      \fi
      {\collect@cell@cr\\#1}%
      {%
        \collect@cell@addarg{#1}%
        \collect@cell@look
      }%
    }%
 \endcc@case
}
%    \end{macrocode}
% \end{macro}
%
%
% \Finale
% \iffalse
%</package>
% \fi