Next: \newcounter, Previous: \makeatletter & \makeatother, Up: Definitions [Contents][Index]
\@ifstar
Synopsis:
\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}% }