% \iffalse meta-comment
%%% etextools : more e-TeX useful tools for LaTeX package writers
%%% Florent CHERVET
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either
% version 1.3 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
%
% This work consists of the main source file etextools.dtx
% and the derived files
%        etextools.sty, etextools.pdf, etextools.ins,
% and    etextools-examples.tex
%
% Unpacking:
%    (a) If etextools.ins is present:
%           etex etextools.ins
%    (b) Without etextools.ins:
%           etex etextools.dtx
%    (c) If you insist on using LaTeX
%           latex \let\install=y\input{etextools.dtx}
%        (quote the arguments according to the demands of your shell)
%
% Documentation:
%           (pdf)latex etextools.dtx
%           (pdf)latex etextools-examples.tex
%<*ignore>
\begingroup
  \def\x{LaTeX2e}%
\expandafter\endgroup
\ifcase 0\ifx\install y1\fi\expandafter
         \ifx\csname processbatchFile\endcsname\relax\else1\fi
         \ifx\fmtname\x\else 1\fi\relax
\else\csname fi\endcsname
%</ignore>
%<*install>
\input docstrip.tex
\Msg{************************************************************************}
\Msg{* Installation}
\Msg{* Package: etextools 2009/07/14 v2e e-TeX more useful tools for LaTeX package writers}
\Msg{************************************************************************}

\keepsilent
\askforoverwritefalse

\let\MetaPrefix\relax
\preamble

This is a generated file.

Copyright (C) 2009 by Florent Chervet <florent.chervet@free.fr>

This work may be distributed and/or modified under the
conditions of the LaTeX Project Public License, either
version 1.3 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

This work consists of the main source file etextools.dtx
and the derived files
      etextools.sty, etextools.pdf, etextools.ins,
and   etextools-examples.tex

\endpreamble
\let\MetaPrefix\DoubleperCent

\generate{%
  \file{etextools.ins}{\from{etextools.dtx}{install}}%
  \file{etextools.sty}{\from{etextools.dtx}{package}}%
  \file{etextools-examples.tex}{\from{etextools.dtx}{example}}%
}

\obeyspaces
\Msg{************************************************************************}
\Msg{*}
\Msg{* To finish the installation you have to move the following}
\Msg{* file into a directory searched by TeX:}
\Msg{*}
\Msg{*     etextools.sty}
\Msg{*}
\Msg{* To produce the documentation run the file `etextools.dtx'}
\Msg{* through LaTeX.}
\Msg{*}
\Msg{* Happy TeXing!}
\Msg{*}
\Msg{************************************************************************}

\endbatchfile
%</install>
%<*ignore>
\fi
%</ignore>
%<*driver>
\edef\thisfile{\jobname}
\def\thisinfo{The \thispackage\ package -- an \eTeX{} package for \LaTeX{}}
\documentclass[a4paper,oneside]{ltxdockit}
\usepackage[latin9]{inputenc}
\usepackage[american]{babel}
\usepackage{doc,stmaryrd,amsmath,graphics,geometry,fancyhdr,framed,bbding,trace,embedfile}\CodelineNumbered
\embedfile{\thisfile.dtx}
\geometry{totalheight=26cm,marginparwidth=14pt}
\titlepage{%
  title={The \sty{etextools} package},
  subtitle={An \etex package providing useful tools for LaTeX Users \\ and package Writers},
  url={http://www.ctan.org/tex-archive/macros/latex/contrib/etextools/},
  author={Florent CHERVET},
  email={florent.chervet@free.fr},
  revision={2\:$\boldsymbol{\varepsilon}$},
  date={14 July 2009}}
\hypersetup{%
  pdftitle={The etextools package},
  pdfsubject={An e-TeX package for more useful tools for LaTeX package writers},
  pdfauthor={Florent CHERVET},
  colorlinks,linkcolor=reflink,
  pdfkeywords={tex, e-tex, latex, package, programming},
  bookmarksopen=true,bookmarksopenlevel=2}
\begin{document}
   \DocInput{\thisfile.dtx}
\end{document}
%</driver>
% \fi
%
% \makeatletter
% \def\thispackage{\sty{\thisfile}}
% \font\ding=dingbat scaled 800
% \fancyhf{}\fancyhead[L]{The \sty{etextools} package -- an \eTeX\, package for \LaTeX}
% \fancyfoot[L]{\color[gray]{.35}\scriptsize\thispackage\quad\copyright\,\lower.3ex\hbox{\NibRight}\,Florent Chervet}
% \fancyfoot[R]{\oldstylenums{\thepage} / \oldstylenums{\pageref{LastPage}}}
% \pagestyle{fancy}
% \def\CTAN#1{\href{http://www.ctan.org/tex-archive/#1}{\nolinkurl{CTAN:#1}}}
% \definecolor{spot}{rgb}{.7,0.1,0.2}
% \newcommand\fecccolor{\color{fecc}}\definecolor{fecc}{rgb}{.2,.6,.2}
% \newcommand\macrocodecolor{\color{macrocode}}\definecolor{macrocode}{rgb}{0.18,0.00,0.45}
% \newcommand\reflinkcolor{\color{reflink}}\definecolor{reflink}{rgb}{.3,0,0}
% \newcommand\rmklinkcolor{\color{rmklink}}\definecolor{rmklink}{rgb}{.2,.2,.2}
% \newcommand\rmkcolor{\color{rmk}\let\reflinkcolor\rmklinkcolor}\definecolor{rmk}{gray}{.35}
% \newcommand\rmk{\par\nobreak\footnotesize\rmkcolor}
% \definecolor{shadecolor}{rgb}{0.93,0.94,0.81}
% \renewcommand\ltxsyntaxlabelfont{\spotcolor \displayverbfont\bfseries}
% \newcommand\eol{\textcolor[gray]{.5}{$\hookleftarrow$}}
% \newenvironment{codecomment}{\par\vskip\parskip\begin{small}\color[gray]{.2}\parskip=0pt}{\end{small}}
% \g@addto@macro\macro@font{\macrocodecolor\let\AltMacroFont\macro@font}
% \MakeShortVerb{\|}
% \catcode`\§\active\def§{\par\nobreak\vskip-\parskip}
% \renewcommand\partformat{}\let\thepart\partformat\renewcommand\raggedpart{\centering}
% \newcommand\cmdref[1]{\hyperref[#1]{\underline{\sty{\reflinkcolor\textbackslash #1}}}}
% \newcommand\cmdlabel[1]{\label{#1}}
% \def\FE{\setbox8\hbox{$\m@th\bindnasrepma$}%
%           \marginpar{\fecccolor\scalebox{2}{$\copy8\mkern-13.5mu\copy8\mkern-13.5mu\copy8$}}\space}
% \def\smex{\leavevmode\hb@xt@2em{\hfil\spotcolor$\longrightarrow$\hfil}}
% \font\manual=manfnt\def\dbend{\marginpar{\manual\char127}\space}
% \parindent\z@\topsep\z@\partopsep\z@\parskip.3\baselineskip
% \lastlinefit999
% \makeatother
%
% \thispagestyle{plain}\printtitlepage
% \fontfamily{ua1}\selectfont
% \tableofcontents\vfil
%
% \begin{shaded}\parindent0pt\noindent\large
%
% {\bfseries\catcode`\ \active\let =\,\hfil \* A b s t r a c t \*\hfil}\par
%
% The \sty{etextools} package is based on the \sty{etex} and \sty{etoolbox}
% packages and defines more tools for \LaTeX\ Users or package Writers.
% Before using this package, it is highly recommended to read the
% documentation (of this package and...) of the \sty{etoolbox} package.
%
% This package requires the \sty{etex} package from David Carlisle
% and the \sty{etoolbox} package from Philipp Lehman. Both of them
% are available on CTAN under the \sty{/latex/contrib/} directory \footnotemark.
%
% The main contributions of this package are :
% \begin{itemize}
%   \item the \cmdref{expandnext} macro;
%   \item the ability to define fully expandable macros with parameter and/or star version (with a small restriction)
%           -- see \cmdref{FE@testopt}, \cmdref{FE@ifstar};
%   \item a Command-List Parser constructor that fully uses this new feature : command-list parser are fully expandable
%           -- see \cmdref{csvloop} and \cmdref{listloop};
%   \item three macros that are lacking from the \sty{etoolbox} package for removing elements from lists :
%              \cmdref{listdel} and \cmdref{listgdel}, \cmdref{listxdel};
%   \item macros that return the index of an item in a list: \cmdref{getlistindex} and \cmdref{xgetlistindex} and conversely
%         the item at a given position in a list: \cmdref{getlistitem};
%
% \end{itemize}
%
% \end{shaded}
%
% \footnotetext{This documentation is produced with the \sty{ltxdockit}
% classe and package by Philipp Lehman using the |DocStrip| utility.
% \begin{tabbing}
% \qquad\=\smex\=To get the documentation, \= run (twice):\quad\= \sty{pdflatex etextools.dtx} \\
% \>\smex\>To get the package, \> run:\>        \sty{etex etextools.dtx}
% \end{tabbing}}
%
% \vfil\eject
%
% \section{Introduction}
%
% \subsection{Identification}
%
%    \begin{macrocode}
%<*package>
\NeedsTeXFormat{LaTeX2e}[1996/12/01]
\ProvidesPackage{etextools}
   [2009/07/14 v2e e-TeX more useful tools for LaTeX package writers]
\csname ettl@onlyonce\endcsname\let\ettl@onlyonce\endinput
%    \end{macrocode}
%
% \subsection{Requirements}
%
% This package requires both the \sty{etex} package by David Carlisle and
% the \sty{etoolbox} package by Philipp Lehman.
%
%    \begin{macrocode}
\RequirePackage{etex,etoolbox}
%    \end{macrocode}
%
% Furthermore, the space token must have its natural catcode (10) all along this package.
%
%    \begin{macrocode}
\edef\ettl@restore@space@catcode{\catcode`\ =\the\catcode`\ }
\AtEndOfPackage{\ettl@restore@space@catcode
   \let\ettl@restore@space@catcode\ettl@undefined}
\catcode`\ =10
%    \end{macrocode}
%
% \subsection{Acknowledgements -- Thank You !}
%
% Thanks to Philipp Lehman for the \sty{etoolbox} package (and also for this nice class of documentation).
% Much of my work on lists are based on his work and package.
%
% Thank to Heiko Oberdiek who has done so much for the \TeX\ and \LaTeX\ community, and allows me to
% produce a package in one only \sty{.dtx} file.
%
% \subsection{Hint for the reader}
%
% Every command provided in this \sty{etextools} package are fully expandable
% unless explicitly specified. As it (one of) the philosophy of \sty{etoolbox}
% to make the most of its commands fully expandable (and this is very useful for package
% writing and/or document-style programming) the \FE fully expandable commands
% have a special sign in the margin (displayed here for information).
%
% Remain what a control sequence, a control word and a control character are...
%
% \iffalse The commands have been (extensively, more or less) tested.\fi
%
%
% \part*{User commands}
% \addtocontents{toc}{\protect\contentsline{part}{\large User commands}{}{}}
%
% \section{A few (\texorpdfstring{\oldstylenums{7}}{7}) ``helper'' macros}
%
% \begin{ltxsyntax}
%
% \cmditem{ettl@afterelse} \cmdlabel{ettl@afterelse}
% \cmditem*{ettl@afterfi}   \cmdlabel{ettl@afterfi}\hfil\par
%
% Those two commands\FE are the copies of |\bbl@afterelse| and |\bbl@afterfi| from the \sty{babel} package.
% They allow to get out of |\if|...|\fi| conditionals.
%
%    \begin{macrocode}
\long\def\ettl@afterelse#1\else#2\fi{\fi#1}
\long\def\ettl@afterfi#1\fi{\fi#1}
\long\def\ettl@afterfifi#1\fi\fi{\fi\fi#1}
\long\def\ettl@afterelsefi#1\else#2\fi\fi{\fi#1}
%    \end{macrocode}
%
% {\rmk Those commands are used in \cmdref{iffirstchar} and \cmdref{expandnext} }
%
% \cmditem*{@gobblescape}\hfil\par
%
% This sequence\FE of command is very often used, even in \sty{latex.ltx}. So
% it appears to be better to put it in a macro. It's aim is to reverse the
% mechanism of |\csname|...|\endcsname|:
%    \begin{macrocode}
\newcommand*\@gobblescape{\expandafter\@gobble\string}
%    \end{macrocode}
%
% \cmditem{str@gobblescape}{string}\hfil\par
%
% With \FE \eTeX\space |\detokenize| it is now possible to invoke a |\string| on an arbitrary
% sequence of tokens. Unfortunately, |\detokenize| adds a
% space tokens at the very end of the sequence. |\str@gobblescape| acts exactly
% the same way as |\@gobblescape| \ie it removes the first character from a string, but removes
% the trailing spaces as well:
%
%    \begin{macrocode}
\newcommand\str@gobblescape[1]{\expandafter\deblank\expandafter{%
         \expandafter\@gobble\detokenize{#1}}}
%    \end{macrocode}
%
% The \cmdref{deblank} command will be desbribed later.
%
% \end{ltxsyntax}
%
% \section{Expansion control}
%
% NOTA BENE: Pay attention\dbend that the expansion control macros are not \emph{primitives}!
% Therefore:
% \begin{tabbing}
% \qquad\= |\expandafter\controlsequence\noexpandcs{|\prm{csname}|}|\\
% \> |\expandafter\controlsequence\expandonce{|\prm{command}|}|
% \end{tabbing}
% etc. etc. may not lead to the result you expected.
% The |\expandonce| macro from \sty{etoolbox} worth the same warning.
%
% For expansion control, it's better to use primitives, unless you clearly knows what
% you do and what will happen... \textbf{In particular,\dbend you'd very better avoid to use
% expansion control macros at the very beginning of the definition of a command, for if this command
% is preceded (in the user's code) by \sty{\textbackslash expandafter}, you will be lead
% to undesirable result and most probably to an error !}

% \begin{ltxsyntax}
%
% \cmditem{noexpandcs}{csname}
%
% In an \FE expansion context (|\edef|) we often want a control sequence whose name results
% from the expansion of some macros and/or other tokens to be created, but not expanded at that point.
% Roughly:§
% \qquad |\edef{\noexpandcs{<balanced text to be expanded as a cs-name>}}|§
% will expand to: |\"cs-name"| but this (new) control sequence itself will not be expanded.
% A typical use is shown in the following code:§
% \smex |\edef\abc{\noexpandcs{abc@\@gobblescape\controlword}}|§
% \smex if equivalent to:\quad|\def\abc{\abc@controlword}|.
%
%    \begin{macrocode}
\newcommand*\noexpandcs[1]{\expandafter\noexpand\csname #1\endcsname}
%    \end{macrocode}
%
% {\rmk|\noexpandcs| can be abbreviated in |\`#1`| in |\edef| that take place in a group. }
%
% \cmditem{noexpandafter}\hfil\par
%
% |\noexpandafter|\FE only means |\noexpand\expandafter| and is shorter to type.
%
%    \begin{macrocode}
\newcommand\noexpandafter{\noexpand\expandafter}
%    \end{macrocode}
%
% {\rmk This command is used in the definition of \cmdref{DeclareCmdListParser}.}
% \iffalse
% \cmditem{afterexpandafter}
%
% |\afterexpandafter|\FE means to delay the expansion twice :§
% \qquad |\afterexpandafter\a\expandafter\b\c|\quad will replace |\c| by its \prm{replacement text}, then
% expand place |\b| before and replace it by its \prm{replacement text} as well, eventually consuming its
% parameters, and after that, place |\a| before the whole thing; then expansion goes further.
%
%    \begin{macrocode}
% \newcommand\afterexpandafter{\expandafter\expandafter\expandafter}
%    \end{macrocode}
% \fi
%
% \cmditem{expandnext}{cstoken}{first parameter of cstoken} \cmdlabel{expandnext}
%
% We\FE often want a control sequence to be expanded after its first argument. For example, if we want to test if a command
% |\foo| has a blank replacement text we will type :
%
% \qquad |\expandafter\ifblank\expandafter{\foo}|
%
% Now suppose you wish to define a macro |\detokenizecs{|\prm{csname}|}| that expands to the detokenized content
% of |\csname |\prm{csname}|\endcsname|. Without |\expandnext| you will have to say:
% \begin{tabbing}
% \qquad\= |\expandafter\expandafter\expandafter\detokenize| \\
% \>       |\expandafter\expandafter\expandafter{\csname |\prm{csname}|\endcsname}|
% \end{tabbing}
% \textbf{six} \cmd{expandafter}(s). With |\expandnext| you will just have to say:§
% \qquad|\expandnext\expandnext\detokenize{\csname #1\endcsname}|
%
% Now observe the following game :
% \begin{tabbing}
% \qquad\= |\def\foo{foo}| \qquad \= \smex \qquad \=  |\def\Foo{\foo}| \quad \= \eol \\
% \>       |\def\\FOo{\Foo}| \>   \smex \>    |\def\FOO{\FOo}| \> \eol \\
% \>       |\def\FOOL{\FOO}|
% \end{tabbing}
% And {\bfseries guess how many \cmd{expandafter} you will need in order to test ``|\ifblank{foo}|'' directly from |\FOOL| ??? }
%
% |\expandnext| solves this problem : |\FOOL| has 5 degrees of expansion until it expands to ``foo'', so one require exactly 5
% |\expandnext| : the solution is :
%
% \qquad |\expandnext\expandnext\expandnext\expandnext\expandnext\ifblank{\FOOL}|
%
% And now : if you define, say : |\csdef{bloody fool}{\FOO}| you just require 2 more |\expandnext| in order
% to test ``foo'' from  ``|\csname bloody fool\endcsname|'' ! \emph{just test it!}
%
%    \begin{macrocode}
\newcommand\expandnext[2]{%
   \ifx#1\expandnext
      \ettl@afterelse\expandafter\expandafter\expandafter
            \expandafter\@expandnext{#2}{\expandafter\expandafter\expandafter}
   \else\ettl@afterfi\expandafter#1\expandafter{#2}
   \fi}
\long\def\@expandnext#1#2#3{%
   \ifx#1\expandnext
      \expandafter\ettl@afterelse\expandafter\expandafter\expandafter
            \expandafter\@expandnext{#3}{\expandafter#2#2}
   \else
      \expandafter\ettl@afterfi#2#1#2{#3}
   \fi}
%    \end{macrocode}
%
% This code is not very tricky but difficult to explain. The better is to watch at the log if the reader is eager
% to understand the job of each \cmd{expandafter}.
%
% Note that the first argument of |\expandnext| must be a single \prm{cstoken} (for \cmd{expandafter} acts
% only on the first following token).
%
% \end{ltxsyntax}
%
% \section{String manipulation}
%
% \subsection{String trimming}
%
% \begin{ltxsyntax}
%
% \cmditem{deblank}{string} \cmdlabel{deblank}
%
% The macro \FE |\deblank| will remove the extra blank space inserted by |\detokenize| at the
% very end of the \prm{string}. Actually, it removes all trailing spaces (charcode 32, catcode 10)
% from its argument:
%
%    \begin{macrocode}
\newcommand\deblank{}
\begingroup\catcode`\&=3% a & as a math shift
\long\gdef\deblank#1{\@deblank#1 &}
\long\gdef\@deblank#1 #2&{\ifblank{#2}{#1}{#1\@deblank#2 &}}
\endgroup
%    \end{macrocode}
%
% Note, by the way, that the leading spaces are also removed by \TeX's mastication mechanism.
% \goodbreak
%
% \subsection{Expanded string comparison}
%
% \cmditem{xifblank}{string}{true}{false}
%
% |\xifblank| is similar to |\ifblank| except that the \prm{string} is first expanded
% with |\protected@edef|:
%    \begin{macrocode}
\newrobustcmd\xifblank[1]{\begingroup
   \protected@edef\@xifblank{\endgroup
         \noexpand\ifblank{#1}%
   }\@xifblank}
%    \end{macrocode}
%
% \cmditem{xifstrequal}{string1}{string2}{true}{false}
%
% In the same way, |\xifstrequal| is similar to |\ifstrequal| but both \prm{string} arguments
% are expanded with |\protected@edef| before comparison:
%    \begin{macrocode}
\newrobustcmd\xifstrequal[2]{%
   \begingroup\protected@edef\@tempa{#1}\protected@edef\@tempb{#2}%
      \ifx\@tempa\@tempb   \aftergroup\@firstoftwo
      \else                \aftergroup\@secondoftwo
      \fi\endgroup}
%    \end{macrocode}
%
% \subsection{Testing characters}
%
% \cmditem{iffirstchar}{string1}{string2}{true}{false} \cmdlabel{iffirstchar}
% \cmditem*{iffirstchar}{}{string}{true}{false}
%
% |\iffirstchar| will\FE compare the character codes of the \textbf{first} characters of each \prm{string}. The
% comparison is \emph{catcode agnostic} and the macro is fully expandable. Neither \prm{string1} not \prm{string2}
% is expanded before comparison.
%
% There is a ``special'' use of this command when the user want to test if a \prm{string} begins
% with an \emph{escape} character (\,\textbackslash\,) one may say:
% \begin{tabbing}
%\qquad\= |\iffirstchar \@backslashchar{|\prm{string}|}|\qquad\= or even easier:\\
% \>|\iffirstchar {}{|\prm{string}|}|
% \end{tabbing}
% Please note that the tests:
% \begin{tabbing}
% \qquad\qquad\=|\iffirstchar |\=|{|\prm{whatever string1 is}|}{}|\\
% and:\>|\iffirstchar |\>|{}{}|
% \end{tabbing}
%  are \textbf{always expanded into \underline{\prm{false}}}
% (for consistency with the shortcut-test for |\@backslashchar|):
%
%    \begin{macrocode}
\newcommand\iffirstchar[2]{%
   \if \expandafter\@car\string#2\relax\@nil\expandafter\@car#1\string\\\@nil
         \ettl@afterelse\ifblank{#2}\@secondoftwo\@firstoftwo
   \else \expandafter\@secondoftwo
   \fi}
%    \end{macrocode}
%
%
% \cmditem{ifsinglechar}{string1}{string2}{true}{false} \cmdlabel{ifsinglechar}
%
% |\ifsinglechar|\FE will perform the test |\iffirstchar| but will also check that \prm{string2} has only one character.
%
%    \begin{macrocode}
\newcommand\ifsinglechar[2]{%
%    \end{macrocode}
%
% \begin{codecomment}
% Remember that neither \prm{string1} nor \prm{string2} is expanded.§
% First: test if |#2| is a single character:
%    \begin{macrocode}
   \expandnext\expandnext\ifblank{\expandafter\@cdr\string#2 \@nil}
%    \end{macrocode}
% The test returned \prm{true}: therefore test further the character codes of |#2| and |#1|, and
% switch to \prm{true} only in case of equality:
%    \begin{macrocode}
  {\iffirstchar{#1}{#2}}
%    \end{macrocode}
% Otherwise, switch to \prm{false}
%    \begin{macrocode}
   \@secondoftwo}
%    \end{macrocode}
% \end{codecomment}
%
% Now with the macro |\ifsinglechar| it becomes possible to write fully expandable macros with an option, \textbf{provided
% that this macro has at least one non-optional argument}, as far as we don't use |\futurelet| nor any assignation.
% The ``trick'' is the following:
% \begin{tabbing}
% \qquad\= |\def\MacroWithOption#1{\ifsing|\=|lechar|\=|[{#1}| \\
% \>\>|{\MacroHasOption[}| \\
% \>\>|{\MacroNoOption{#1}}}}|\\
% \> |\def\MacroHasOption[#1]#2|... \>\textit{definition} \\
% \> |\def\MacroNoOption#1|...\>\textit{definition}
% \end{tabbing}
%
% Moreover (in the style of |\@testopt|):
% \begin{tabbing}
%  \qquad\= |\def\MacroWithOption#1{\ifsing|\=|lechar|\=|[{#1}|\\
%  \>\>|{\MacroHasOption#1}|\\
%  \>\>|{\MacroHasOption[default]{#1}}}|
% \end{tabbing}
%
% Therefore, the following macro is defined:
%
% \subsection{Fully expandable macros with options}
%
% \cmditem{FE@testopt}{argument to be tested}{commands}{default option} \cmdlabel{FE@testopt}
%
%   |\FE@testopt| mimics the behaviour of |\@testopt| but is Fully Expandable (\sty{FE})\FE and can be used as follow:§
% \qquad |\def\MacroWithOption#1{\FE@testopt{#1}\MacroHasOption{default}}|\par
%
% Remember that |\MacroWithOption| \textbf{must have at least one mandatory argument.}
%
%    \begin{macrocode}
\newcommand\FE@testopt[3]{\ifsinglechar [{#1}{#2#1}{#2[{#3}]{#1}}}
%    \end{macrocode}
%
% \textbf{Limitation :}\dbend if you call such an option command without option and with |{[}| as mandatory
% argument, it will be considered that the command has an option, whose end will be at the next `\,]\,' found in the input string.
%
% {\rmk |\FE@testopt| is used in the definition of \cmdref{DeclareCmdListParser}.}
%
% \cmditem{FE@ifstar}{argument to be tested}{star-commands}{non-star commands} \cmdlabel{FE@ifstar}
%
% Similarly,\FE it becomes possible to mimic the behaviour of |\@ifstar| but in a fully expandable(\sty{FE}) way.
% |\FE@ifstar| can be used as follow :§
% \begin{tabbing}
% \qquad\= |\def\StarOrNotCommand#1{\FE@|\=|ifstar|\=|{#1}|\\
% \>\>|{\StarredCommand}|\\
% \>\>|{\NotStarredCommand}}|
% \end{tabbing}
%
% Remember that |\StarredCommand| and |\NotStarredCommand| \textbf{must have at least one mandatory argument.}
%
%    \begin{macrocode}
\newcommand\FE@ifstar[3]{\ifsinglechar *{#1}{#2}{#3{#1}}}
%    \end{macrocode}
%
% \textbf{Limitation :}\dbend if you call such a command with |{*}| as mandatory argument,
% it will be considered that the command is starred, and the mandatory argument will be found next inside the input string.
%
% \textbf{This ``limitation'' is in fact a benediction:} thank to it we can have
% {\it\catcode`\ \active\let =-Fully Expandable starred macros with option\/}!\nobreak
% {\rmk |\FE@ifstar| is used in the definitions of \cmdref{DeclareCmdListParser}, \cmdref{csvloop}, \cmdref{listloop}
% and \cmdref{csvtolist}.}
% \goodbreak
% \end{ltxsyntax}
%
% \section{List management}
%
% \subsection{The Command-List Parser}
%
% The \sty{etoolbox} package provides a way to define list parsers a fully expandable macros:
% the list parser is able to expand the auxiliary command |\do| on each item of a list.
% \iffalse
% Declaration of a list parser is done via the |\DeclareListParser| macro\footnotemark.
% \footnotetext{besides, \sty{etoolbox} defines the \sty{\textbackslash docsvlist} and the
% \sty{\textbackslash dolistloop} macros: the choice of this name is not very friendly
% and we expected to have a \sty{\textbackslash docsvloop} macro instead...}.
% \fi
%
% Here we provide a |\DeclareCmdListParser| macro that is compatible and slightly different, because the auxiliary
% command is not necessarily |\do|. Such a command-list-parser is fully expandable.
%
% The idea is that if |\csvloop| has been defined as a command-parser then, thank to the fully expandable macro |\FE@testopt|
% we can call for expansion:
% \begin{tabbing}
% \qquad\= |\csvloop*{item,item,...}|\,\= as a shortcut for\,\= |\csvloop*[\do]{item,...}|\\
% or:\>       |\csvloop*[\listadd\mylist]{item,item,...}|\quad
% \end{tabbing}
% for example to convert the csv-list into internal \sty{etoolbox} list.
%
% {\rmk The star-form of \cmdref{csvloop} will be explained below.}
%
% \begin{ltxsyntax}
%
% \cmditem{DeclareCmdListParser}{command}{separator}  \cmdlabel{DeclareCmdListParser}
%
% |\DeclareCmdListParser| acts in the same way as \sty{etoolbox}-|\DeclareListParser| and the command-list-parser
% are sensitive to the category code of the \prm{separator}
% {\catcode`\ =13\let =-\it(which is not necessarily a single character and shall not be a {\tt\&} with a catcode of 3)}.
%
% \begin{codecomment}
% The command-list-parser will be defined only if it is definable:
%
%    \begin{macrocode}
\newrobustcmd*\DeclareCmdListParser[2]{%
  \@ifdefinable#1
    {\expandafter\etextools@defcmdparser\expandafter{#1}{#2}}}
%    \end{macrocode}
%
% Then the job is done by |\etextools@defcmdparser|: we need the `\,\&\,' to have a catcode of 3
% and globally define the macro inside a purposeful group:
%
%    \begin{macrocode}
\begingroup\catcode`\&=3
\gdef\etextools@defcmdparser#1#2{%
   \begingroup
   \def\`##1`{\expandafter\noexpand\csname ##1\endcsname}%
%    \end{macrocode}
% Now the parser definition is made inside an protected-|\edef| in order to expand control sequences names:
%    \begin{macrocode}
   \protected@edef\defineparser{\endgroup
%    \end{macrocode}
% Here we define the entry-point: we first test if the command was starred.
% This is possible because the list-parser has always a mandatory argument (the \prm{list} itself or the \prm{listmacro}) :
%    \begin{macrocode}
   \long\def#1####1{\noexpand\FE@ifstar{####1}
      {\`ettl@lst@star\string#1`}
      {\`ettl@lst@nost\string#1`}}%
%    \end{macrocode}
% Both starred and not-starred versions have an optional argument which is the auxiliary command, whose name is |\do| if not specified.
% It is possible to test the option for the same reason:
%    \begin{macrocode}
   \long\csdef{ettl@lst@star\string#1}####1{\noexpand\FE@testopt{####1}
      {\`ettl@lst@star@pt\string#1`}{\noexpand\do}}%
   \long\csdef{ettl@lst@nost\string#1}####1{\noexpand\FE@testopt{####1}
      {\`ettl@lst@nost@pt\string#1`}{\noexpand\do}}%
%    \end{macrocode}
% Definition of the parser with its arguments :\quad |[optional command]{list or listmacro}|. If the starred version
% was used, then we do not have to expand the (mandatory) \prm{list}:
%    \begin{macrocode}
   \long\csdef{ettl@lst@star@pt\string#1}[####1]####2{%
      \`ettl@lst\string#1`{####2}{####1}}%
%    \end{macrocode}
% On the other hand, if the parser was not starred, the (mandatory) \prm{listmacro} is expanded once:
%    \begin{macrocode}
   \long\csdef{ettl@lst@nost@pt\string#1}[####1]####2{%
      \noexpandafter\`ettl@lst\string#1`\noexpandafter{####2}{####1}}%
%    \end{macrocode}
% ListParser is defined and leads to |\`ettl@lst\string\ListParser`| in all cases; here the \prm{list} is in first position,
% the auxiliary commands come after, so we reverse the order and add a \prm{separator} in case the \prm{list} is empty:
%    \begin{macrocode}
   \long\csdef{ettl@lst\string#1}####1####2{%
         \`ettl@lst@\string#1`{####2}####1\unexpanded{#2}&}%
%    \end{macrocode}
% In the following macro, we extract the first item from the list (before the \prm{separator} |#2|), for treatment:
%    \begin{macrocode}
   \long\csdef{ettl@lst@\string#1}####1####2\unexpanded{#2}####3&{%
%    \end{macrocode}
% Proceed with the first item, if not empty:
%    \begin{macrocode}
      \noexpand\ifblank{####2}
            {}
            {\noexpand\ettl@lst@doitem{####1}{####2}}%
%    \end{macrocode}
% If the remainder of the list is empty then break loop, otherwise restart extracting the next, first item for treatment:
%    \begin{macrocode}
      \noexpand\ifblank{####3}
            {\noexpand\ettl@listbreak}
            {\`ettl@lst@\string#1`{####1}####3}&}%
%    \end{macrocode}
% Now the definitions are ready, execute them:
%    \begin{macrocode}
   }\defineparser}%
%    \end{macrocode}
% |\ettl@lst@doitem| apply the auxiliary command(s) (in |#1|) to the item (|#2|):
% |\ettl@listbreak| breaks the loop, removing the extra \sty{\&}:
%    \begin{macrocode}
   \long\gdef\ettl@lst@doitem#1#2{#1{#2}}%
   \long\gdef\ettl@listbreak#1&{}%
%    \end{macrocode}
% Leave ``catcode-group'':
%    \begin{macrocode}
\endgroup
%    \end{macrocode}
% \end{codecomment}
%
% \subsection{Loops into lists}
%
% Now we have to declare two command-list-parsers : |\listloop| for \sty{etoolbox} lists
% and |\csvloop| for comma-separated lists.
%
% \cmditem{csvloop}[auxiliary commands]{csvlistmacro} \cmdlabel{csvloop}
% \cmditem*{csvloop*}[auxiliary commands]{item,item,item,...}
% \cmditem*{listloop}[auxiliary commands]{listmacro}    \cmdlabel{listloop}
% \cmditem*{listloop*}[auxiliary commands]{expanded list}
%
% |\listloop|\FE acts exactly as \sty{etoolbox}-|\dolistloop| with an optional argument to change
% the default auxiliary command |\do| to apply to each item of the list :
% \begin{tabbing}
% \qquad\=|\listloop\mylist|\;\=\textit{is}\;\= |\listloop[\do]\mylist|\;\=\textit{and is also}\;\= |\dolistloop\mylist|\\
% \>      |\csvloop\csvlist|\> \textit{is}\> |\csvloop[\do]\csvlist|\> \textit{and is also}: \eol \\
% \>\>\> |\expandafter\docsvlist\expandafter{\csvlist}|
% \end{tabbing}
% Definition of |\csvloop| :
%    \begin{macrocode}
\DeclareCmdListParser\csvloop{,}
%    \end{macrocode}
%
% \begin{codecomment}
% Definition of |\listloop| (with a `\,\textbar\,'  of catcode 3 -- cf.\sty{etoolbox}):
%    \begin{macrocode}
\begingroup\catcode`\|=3
   \gdef\do{\DeclareCmdListParser\listloop{|}\undef\do}\aftergroup\do
\endgroup
%    \end{macrocode}
% \end{codecomment}
%
% \subsection{Converting csv lists to \sty{etoolbox}-lists}
%
% \cmditem{csvtolist}{listmacro}{csvlistmacro} \cmdlabel{csvtolist}
% \cmditem*{csvtolist*}{listmacro}{item,item,item...}
%
% |\csvtolist| converts a comma separated list into an internal \sty{etoolbox} list. It is useful to insert more than one item
% at a time in a list. Those macros are not fully expandable because of the redefinition of \prm{listmacro} done by |\listadd|...
%
% It's also the first application of the \cmdref{csvloop} macro just defined:
%
%    \begin{macrocode}
\newcommand\csvtolist{\@ifstar\star@csvtolist\nost@csvtolist}
\def\star@csvtolist#1{\let#1\@empty\csvloop*[{\unexpanded{\listadd#1}}]}
\def\nost@csvtolist#1{\let#1\@empty\csvloop[{\unexpanded{\listadd#1}}]}
%    \end{macrocode}
%
% \cmditem{csvtolistadd}{listmacro}{csvlistmacro} \cmdlabel{csvtolistadd}
% \cmditem*{csvtolistadd*}{listmacro}{item,item,item...}
%
% |\csvtolistadd| acts similarly but does not reset the \prm{listmacro} to |\@empty|:
%
%    \begin{macrocode}
\newcommand\csvtolistadd{\@ifstar\star@csvtolistadd\nost@csvtolistadd}
\def\star@csvtolistadd#1#2{\ifblank{#2}
         {\let#1\@empty}{\csvloop*[{\unexpanded{\listadd#1}}]{#2}}}
\def\nost@csvtolistadd#1#2{\ifblank{#2}
         {\let#1\@empty}{\csvloop[{\unexpanded{\listadd#1}}]{#2}}}
%    \end{macrocode}
%
% \end{ltxsyntax}
%
% \subsection{Removing elements from \sty{etoolbox}-lists}
%
% The \sty{etoolbox} package provides |\listadd|, |\listgadd| and |\listxadd| commands
% to add items to a list. However, no command is designed to remove an element from a
% list.
%
% \begin{ltxsyntax}
%
% \cmditem{listdel}{listmacro}{item}      \cmdlabel{listdel}
% \cmditem*{listgdel}{listmacro}{item}    \cmdlabel{listgdel}
% \cmditem*{listxdel}{listmacro}{item}    \cmdlabel{listxdel}
%
% The |\listdel| command removes the element \prm{item} from the list \prm{listmacro}. Note that the
% \prm{listmacro} is redefined after deletion:
%
%    \begin{macrocode}
\newrobustcmd\listdel[2]{\@listdel\def{#1}{#2}}
%    \end{macrocode}
%
% Commands |\listgdel| and |\listxdel| are similar, except that the assignment (\ie the redefinition
% of the list) is global; for the latter, the \prm{item} is first expanded using |\protected@edef|:
%
%    \begin{macrocode}
\newrobustcmd\listgdel[2]{\@listdel\gdef{#2}{#2}}
\newrobustcmd\listxdel[2]{\begingroup
   \protected@edef\@listxdel{\endgroup
      \unexpanded{\@listdel\gdef#1}{#2}%
   }\@listxdel}
%    \end{macrocode}
%
% \begin{codecomment}
% Now you noticed the job is delayed to a general macro |\@listdel| which is relatively tricky !
% We need first to be placed in an environment where the `\,\textbar\,' delimiter has a category code of 3
% (cf \sty{etoolbox}-lists definitions):
%    \begin{macrocode}
 \begingroup\catcode`\|=3\catcode`\&=3
%    \end{macrocode}
% Inside this ``catcode-group'' the definition of |\@listdel| ought to be global:
%    \begin{macrocode}
 \long\gdef\@listdel#1#2#3{%
%    \end{macrocode}
% \qquad |#1|=|\def| or |\gdef|, |#2|=\prm{listmacro}, |#3|=\prm{item} to remove.\par
% In order to preserve the hash-table from temporary definitions, a group is opened:
%    \begin{macrocode}
   \begingroup
      \def\@tempa##1|#3|##2&{##1|##2\@tempb}%
%    \end{macrocode}
% |\@tempa| is a delimited macro whose aim is to remove the first \prm{item} found in the list
% and it adds |\@tempb| after the result. If the \prm{item} was not in the list, then |##2|
% will be empty. Note that |\@tempa| is the only macro whose definition depends on the \prm{item}
% (and then leads |\@listdel| not to be fully-expandable).
%
% The result of |\@tempa| expansion is then given to |\@tempb| whose purpose is to cancel out
% whatever is found between the two delimiters: \textbar|\@tempb|...\textbar|\@tempb|:
%    \begin{macrocode}
   \def\@tempb|##1|\@tempb##2|\@tempb{%
      \ifblank{##2}{\unexpanded{##1}}
%    \end{macrocode}
% If the \prm{item} \textbf{was not} is the list, then |##2| will be empty, and§
% \qquad |\@tempb|\textbar...\textbar|\@tempb|...\textbar|\@tempb|§
% is replaced by the \emph{original-}list (\ie |##1| -- that we shall not expand), then the loop is broken;
% otherwise the \prm{item} was in the list and |##1| is the \emph{shortened-}list without the \prm{item}. We have to loop
% to remove all the \prm{item{\tt s}} of the list, except in the case where the \emph{shortened-}list
% is empty after having removing \prm{item} (|##1| empty):
%    \begin{macrocode}
      {\ifblank{##1}{}{\@tempx##1&}}}%
%    \end{macrocode}
% Now we just have to (define and) expand |\@tempx| in an |\edef| which is going to redefine
% the \prm{listmacro}. |\@tempx| expands first |\@tempa| and then |\@tempb| on the result of
% the expansion of |\@tempa|. The macro |\@tempx| itself has an argument: it is (at first stage) the
% replacement text of \prm{listmacro}:
%    \begin{macrocode}
   \def\@tempx##1&{\expandafter\@tempb\@tempa|##1|\@tempb|#3|&}%
   \edef\@redef{\endgroup
      \unexpanded{#1#2}{% ie: \def or \gdef   \listmacro
%    \end{macrocode}
% |\@redef| redefines the list using (|\def| or |\gdef|), the replacement text is the result
% of the expansion of |\@tempx| on the \prm{listmacro} which is expanded once (to see  its items...):
%    \begin{macrocode}
      \expandafter\@tempx\unexpanded\expandafter{#2}&}%
%    \end{macrocode}
% Then just expand |\@redef| (fully expandable):
%    \begin{macrocode}
   }\@redef}% end of \@listdel
%    \end{macrocode}
% And ends the ``catcode-group'':
%    \begin{macrocode}
\endgroup
%    \end{macrocode}
% \end{codecomment}
% \end{ltxsyntax}
%
% \subsection{Index of an element in a list}
%
% \begin{ltxsyntax}
%
% \cmditem{getlistindex}{item}{listmacro} \cmdlabel{getlistindex}
% \cmditem*{xgetlistindex}{item}{listmacro} \cmdlabel{xgetlistindex}
% \cmditem*{getlistindex*}{item}{list}
% \cmditem*{xgetlistindex*}{item}{list}
%
% Sometimes it is interesting to know at which offset in a list lies a given item. |\getlistindex| answers to this question.
% |\xgetlistindex| does the same thing but expand the \prm{item} (using |\protected@edef|) prior looking for it in the list.
% The result (\ie the position of \prm{item} in \prm{list}) is stored in |\indexinlist|.
% \begin{itemize}
% \item \ If \prm{item} is not found in the \prm{list} then |\indexinlist| is 0
% \item \ If \prm{item} is found in first position then |\indexinlit| is 1 and so on.
% \end{itemize}
%
% As for the command-list-parser, the star versions are designed in case the list (in the second argument) is already expanded.
% \begin{codecomment}
% We first need to get into a group where delimiter `\,\textbar\,' and `\,\&\,' have catcode 3:
%    \begin{macrocode}
\begingroup\catcode`\|=3\catcode`\&=3
%    \end{macrocode}
% The next two macros expands to the first item in a list or the remainder of the list respectively :
%    \begin{macrocode}
\gdef\ettl@list@first@item#1|#2&{#1}
\gdef\ettl@list@other@item#1|#2&{#2}
%    \end{macrocode}
% |\getlistindex| may be defined, with its star form (no expansion of the list) and normal form (\prm{listmacro} expanded once);
% The search-index is initialised at 1:
%    \begin{macrocode}
\gdef\getlistindex#1{\FE@ifstar{#1}{\ettl@getlistindex{}}
                                   {\ettl@getlistindex\expandnext}}
%   \@ifstar{\ettl@getlistindex{}}{\ettl@getlistindex{\expandnext}}}
%    \end{macrocode}
% |\xgetlistindex| is similar with prior expansion of \prm{item}:
%    \begin{macrocode}
\gdef\xgetlistindex#1{\FE@ifstar{#1}{\ettl@xgetlistindex{}}
                                    {\ettl@xgetlistindex\expandnext}}
\gdef\ettl@xgetlistindex#1#2#3{\begingroup
   \protected@edef\next{\endgroup\unexpanded{\ettl@getlistindex{#1}{#2}}{#3}%
   }\next}
%    \end{macrocode}
% Then the following macro does the job in a loop, which is not fully expandable because the use of |\ifstrequal|:
%    \begin{macrocode}
\gdef\ettl@getlistindex#1#2#3{\begingroup#1\ettl@get@list@idx{#3}{#2}{\numexpr1}}
\gdef\ettl@get@list@idx#1#2#3{% #1=expanded list, #2=item, #3=index
   \ifblank{#1}0% the (remainder of) the list is empty
      {\expandnext\ifstrequal{\ettl@list@first@item#1&}{#2}
         {\endgroup\edef\indexinlist{\number#3\relax}}
         {\expandnext\ettl@get@list@idx{\ettl@list@other@item#1&}{#2}{#3+1}}}}
\endgroup% catcode group
%    \end{macrocode}
% \end{codecomment}
% \end{ltxsyntax}
%
% \subsection{Extract by index from a list}
%
% \begin{ltxsyntax}
%
% \cmditem{getlistitem}{listmacro}{index [numexpr expression]} \cmdlabel{getlistitem}
% \cmditem*{getlistitem*}{list}{index}
%
% Now\FE the reverse operation of ``getting the index'' is ``getting the element'' whose index is known. Note that this macro
% is fully expandable for we don't have to compare the items (just count the loop using |\numexpr| -- no counter). Therefore we use the
% fully expandable version of |\ifstar| : \cmdref{FE@ifstar} to keep the ``fully-expand-ability'' of the star-form as well:
% \begin{itemize}
% \item \ If the \prm{index} is in the range $[1\dots n]$ then the macro expands to \prm{item}$_n$
% \item \ If the \prm{index} is non positive or $>n$ then the macro expands to nothing (|{}|).
%  \end{itemize}
%
%    \begin{macrocode}
\newcommand\getlistitem[1]{\FE@ifstar{#1}\ettl@getlistitem
                                        {\expandnext\ettl@getlistitem}}
\begingroup\catcode`\&=3
\long\gdef\ettl@getlistitem#1#2{%#1=listmacro, #2=index
   \ettl@get@list@item{#1}{\number\numexpr#2}}
\long\gdef\ettl@get@list@item#1#2{%
   \ifblank{#1}{}
      {\ifnum#2=1 \ettl@afterelsefi
            \expandonce{\ettl@list@first@item#1&}
      \else\ifnum#2>0 \ettl@afterfifi
            \expandnext\ettl@getlistitem{\ettl@list@other@item#1&}{#2-1}%
      \fi\fi}}
\endgroup
%    \end{macrocode}
%
% \end{ltxsyntax}
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \section{Example}
%
%    \begin{macrocode}
%<*example>
\documentclass[11pt,french,a4paper,oneside]{scrartcl}
\usepackage[latin1]{inputenc}
\usepackage[T1]{fontenc}
\usepackage[american]{babel}
\usepackage{geometry,doc,ltxdockit,txfonts,fancyhdr}
\usepackage{etextools}
\hypersetup{colorlinks,pdfstartview={FitH}}
\geometry{top=2cm,bottom=2cm,left=2.5cm,right=1cm}
\fancyhf{}
\fancyhead[L]{Examples for the \sty{etextools} package}
\pagestyle{fancy}
\MakeShortVerb{\|}

\makeatletter
\def\smex{\leavevmode\hb@xt@2em{\hfil$\longrightarrow$\hfil}}
\def\strip@meaning{\expandafter\strip@prefix\meaning}
\def\strip@macro{\expandafter\strip@macroprefix\meaning}
\def\get@params#1{\expandafter\@get@params\meaning#1\@nil}
\edef\@get@params{%
   \def\noexpand\@get@params\detokenize{macro:}##1\detokenize{->}##2\noexpand\@nil{##1}%
}\@get@params
\def\make@macro#1{\string\def\string#1\get@params#1\string{\strip@meaning#1\string}}
\newcommand\preline{\@ifstar{\@preline}{\hrulefill\par\@preline}}
\def\@preline#1{\noindent\hskip6pt\texttt{\make@macro#1}\par\vskip1.5ex}

\def\meaningcs#1{\expandafter\meaning\csname#1\endcsname}
\def\Meaningcs#1{\expandafter\strip@meaning\csname #1\endcsname}

\newcommand\test[1]{%
   \csname test#1\endcsname
   \edef\usercmd{\Meaningcs{test#1}}\edef\result{\meaningcs{#1Test}}\noindent
   \begin{tabular}{lp{15cm}}
   \multicolumn{2}{l}{\textcolor{blue}{\llap\smex\tt \usercmd}} \\[1.5ex]
   \cmd{#1Test}= & \tt\bfseries\result
   \end{tabular}\par\nobreak\hrulefill\null\goodbreak}


\begin{document}
\title{etextools examples}
\subtitle{Examples for some macros provided by the \sty{etextools} package}
\author{Florent Chervet}
\date{July 22, 2009}
\maketitle

\tableofcontents


\section{\cmd{expandnext} examples}

\subsection{Test if the replacement text of a macro is blank (empty or spaces)}

\def\xx{something}
\def\testexpandnext{%
   \edef\expandnextTest{\string\xx\ is \expandnext\ifblank{\xx}{}{not} blank}
}
\preline\xx
\test{expandnext}

\def\xx{    }
\preline\xx
\test{expandnext}

\clearpage
\subsection{Detokenize the replacement text of a named-sequence}
\def\detokenizecs#1{\expandnext\expandnext\detokenize{\csname #1\endcsname}}
\def\testexpandnext{%
   \edef\expandnextTest{\detokenizecs{document}}}
\preline\detokenizecs
\test{expandnext}


\section{Testing characters}
\subsection{\cmd{ifsinglechar} versus \cmd{iffirstchar}}
\def\testifsinglechar{%
   \edef\ifsinglecharTest{\ifsinglechar *{*hello*}{ single star }{ something else }}
}\hrulefill\par
\test{ifsinglechar}

\def\testiffirstchar{%
   \edef\iffirstcharTest{\iffirstchar *{*hello*}{ first char is star }{ something else }}
}\hrulefill\par
\test{iffirstchar}

\subsection{Fully Expandable starred macros}
\def\starmacro#1{\FE@ifstar{#1}\starred\notstarred}
\def\starred#1{your "#1" will be processed by the STAR form}
\def\notstarred#1{your "#1" will be processed by the NORMAL form}
\def\testFE@ifstar{%
   \edef\FE@ifstarTest{\starmacro{sample text}}}
\preline\starmacro
\preline*\starred
\preline*\notstarred
\test{FE@ifstar}

\def\testFE@ifstar{%
   \edef\FE@ifstarTest{\starmacro*{sample text}}}
\hrulefill\par
\test{FE@ifstar}

\subsection{Fully Expandable macros with options}
\def\optmacro#1{\FE@testopt{#1}\OPTmacro{Mr.}}
\def\OPTmacro[#1]#2{#1 #2}
\def\testFE@testopt{%
   \edef\FE@testoptTest{\optmacro{Woody Allen}}}
\preline\optmacro
\preline*\OPTmacro
\test{FE@testopt}

\def\testFE@testopt{%
   \edef\FE@testoptTest{\optmacro[Ms.]{Vanessa Paradis}}}
\hrulefill\par
\test{FE@testopt}

\section{Lists management}
\subsection{\cmd{csvloop} and \cmd{csvloop*} examples}
\subsubsection{\cmd{makequotes}}
\def\makequotes#1{"#1"\space}
\def\testcsvloop{%
   \edef\csvloopTest{\csvloop*[\makequotes]{hello,world}}
}
\preline\makequotes
\test{csvloop}
\subsubsection{\cmd{detokenize}}
\def\testcsvloop{%
   \edef\csvloopTest{\csvloop*[\detokenize]{\un,\deux}}
}\hrulefill\par
\test{csvloop}
\subsubsection{\cmd{numexpr}}
\def\mylist{1,2,3,4,5}\def\BySeven#1{$#1\times 7 = \number\numexpr#1*7\relax$\par}
\def\testcsvloop{%
   \edef\csvloopTest{\csvloop[\BySeven]\mylist}}
\preline\mylist
\preline*\BySeven
\test{csvloop}
\subsubsection{protected \cmd{testbf}}
\def\testcsvloop{%
   \protected@edef\csvloopTest{\csvloop*[\textbf]{hello ,my ,friends}}
}\hrulefill\par
\test{csvloop}

\subsection{\cmd{getlistitem}}
\csvtolist*\mylist{one,two,three,four,five,alpha,beta,gamma}
\def\testgetlistitem{%
   \edef\getlistitemTest{\getlistitem\mylist{4}}
}\hrulefill\par
\noindent\hskip6pt|\csvtolist*\mylist{one,two,three,four,five,alpha,beta,gamma}|\par\vskip1.5ex
\test{getlistitem}

\subsection{\cmd{getlistindex} {\mdseries(not expandable)}}
\getlistindex{four}\mylist
\hrulefill\par
\noindent\hskip6pt|\csvtolist*\mylist{one,two,three,four,five,alpha,beta,gamma}|\par\vskip1.5ex
\noindent\hskip6pt\textcolor{blue}{\llap\smex\cmd{getlistindex}{four}\cmd{mylist}}\par\vskip1.5ex
\noindent\hskip6pt\cmd{indexinlist}=\quad{\bfseries\meaning\indexinlist}\par\hrulefill\par

\end{document}
%</example>
%    \end{macrocode}
%
% \begin{thebibliography}{9}
%
% \bibitem{etex}
%   David Carlisle and Peter Breitenlohner
%   \textit{The \sty{etex} package};
%   1998/03/26 v2.0;
%   \CTAN{macros/latex/contrib/etex-pkg/etex.sty}.
%
% \bibitem{etoolbox}
%   Philipp Lehman
%   \textit{The \sty{etoolbox} package};
%   2008/06/28 v1.7;
%   \CTAN{macros/latex/contrib/etoolbox/etoolbox.dtx}.
%
% \end{thebibliography}
%
% \PrintIndex
%
% \label{LastPage}
% \Finale

