Next: , Previous: , Up: Definitions   [Contents][Index]


12.4 \@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}% 
  }

Unofficial LaTeX2e reference manual