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

12.4 \@ifstar



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}

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}}

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.

  {starred version}%
  {unstarred version}% 

Unofficial LaTeX2e reference manual