Next: \newcounter, Previous: \makeatletter & \makeatother, Up: Definitions [Contents][Index]
\@ifstarSynopsis:
\newcommand{\mycmd}{\@ifstar{\mycmd@star}{\mycmd@nostar}}
\newcommand{\mycmd@nostar}[nostar-num-args]{nostar-body}
\newcommand{\mycmd@star}[star-num-args]{star-body}
Many standard LaTeX environments or commands have a variant with the
same name but ending with a star character *, an asterisk.
Examples are the table and table* environments and the
\section and \section* commands.
When defining environments, following this pattern is straightforward
because \newenvironment and \renewenvironment allow the
environment name to contain a star. For commands the situation is more
complex. As in the synopsis above, there will be a user-called command,
given above as \mycmd, which peeks ahead to see if it is followed
by a star. For instance, LaTeX does not really have a
\section* command; instead, the \section command peeks
ahead. This command does not accept arguments but instead expands to
one of two commands that do accept arguments. In the synopsis these two
are \mycmd@nostar and \mycmd@star. They could take the
same number of arguments or a different number, or no arguments at all.
As always, in a LaTeX document a command using at-sign @
must be enclosed inside a \makeatletter ... \makeatother block
(see \makeatletter & \makeatother).
This example of \@ifstar defines the command \ciel and a
variant \ciel*. Both have one required argument. A call to
\ciel{night} will return "starry night sky" while
\ciel*{blue} will return "starry not blue sky".
\newcommand*{\ciel@unstarred}[1]{starry #1 sky}
\newcommand*{\ciel@starred}[1]{starry not #1 sky}
\newcommand*{\ciel}{\@ifstar{\ciel@starred}{\ciel@unstarred}}
In the next example, the starred variant takes a different number of
arguments than the unstarred one. With this definition, Agent 007’s
``My name is \agentsecret*{Bond},
\agentsecret{James}{Bond}.'' is equivalent to entering the commands
``My name is \textsc{Bond}, \textit{James} textsc{Bond}.''
\newcommand*{\agentsecret@unstarred}[2]{\textit{#1} \textsc{#2}}
\newcommand*{\agentsecret@starred}[1]{\textsc{#1}}
\newcommand*{\agentsecret}{%
\@ifstar{\agentsecret@starred}{\agentsecret@unstarred}}
There are two sometimes more convenient ways to accomplish the work of
\@ifstar. The suffix package allows the construct
\newcommand\mycommand{unstarred version} followed by
\WithSuffix\newcommand\mycommand*{starred version}. And
LaTeX3 has the xparse package that allows this code.
\NewDocumentCommand\foo{s}{\IfBooleanTF#1
{starred version}%
{unstarred version}%
}