12.4 \@ifstar

Synopsis :

\newcommand{\macmd}{\@ifstar{\macmd@star}{\macmd@nostar}}
\newcommand{\macmd@nostar}[nostar-nbre-args]{nostar-corps}
\newcommand{\macmd@star}[star-nbre-args]{star-corps}

Vous l’avez sans doute remarqué, beaucoup d’environnements ou commandes standards de LaTeX existent sous une variante avec le même nom mais finissant avec le caractère étoile *, un astérisque. Par exemple c’est le cas des environnements table et table*, et des commandes \section et \section*.

Lorsque on définit un environnement, cela est facile puisque \newenvironment et \renewenvironment autorisent que le nom de l’environnement contienne un astérisque. Il vous suffit donc d’écrire \newenvironment{monenv} ou \newenvironment{monenv*} et de continuer la définition comme d’habitude. Pour les commandes, c’est plus compliqué car l’étoile n’étant pas une lettre ne peut pas faire partie du nom de la commande. Comme dans le synopsis ci-dessus, on a donc une commande utilisateur, donnée ci-dessus comme \macmd, qui doit être capable de regarder si elle est ou non suivie d’une étoile. Par exemple, LaTeX n’a pas réellement une commande \section* ; au lieu de cela la commande \section regarde ce qui la suit. Cette première commande n’accepte d’argument, mais au lieu de cela se développe en l’une de deux commandes qui elle accepte des arguments. Dans le synopsis ces commandes sont \macmd@nostar et \macmd@star. Elles peuvent prendre le même nombre d’arguments ou un nombre différent, ou pas d’argument du tout. Comme d’habitude, dans un document LaTeX une commande utilisant l’arobe @ dans son nom doit être comprise au sein d’un bloc \makeatletter ... \makeatother (voir \makeatletter & \makeatother).

Dans cet exemple, on définit \ciel comme une commande avec un argument obligatoire et admettant une variante étoilée \ciel* également avec un argument obligatoire. Ainsi, \ciel{bleu} composera « ciel bleu non étoilé » tandis que \ciel*{nocturne} composera « ciel nocturne étoilé ».

\makeatletter
\newcommand*\ciel@starred[1]{ciel #1 étoilé}
\newcommand*\ciel@unstarred[1]{ciel #1 non étoilé}
\newcommand\ciel{\@ifstar{\ciel@starred}{\ciel@unstarred}}
\makeatother

Voici un autre exemple, où la variante étoilée prend un nombre d’arguments différent de la non étoilée. Avec cette définition, la célèbre réplique de l’agent 007 « Mon nom est \agentsecret*{Bond}, \agentsecret{James}{Bond}. » est équivalente à saisir les commandes « Je m'appelle \textsc{Bond}, \textit{James} textsc{Bond}. »

\makeatletter
\newcommand*\agentsecret@starred[1]{\textsc{#1}}
\newcommand*\agentsecret@unstarred[2]{\textit{#1} \textsc{#2}}
\newcommand\agentsecret{\@ifstar{\agentsecret@starred}{\agentsecret@unstarred}}
\makeatother

Après le nom d’une commande, l’étoile est traitée d’une manière similaire à un argument optionnel. (Ceci est différent des noms d’environnement, où l’étoile fait partie du nom lui-même, et peut donc être à n’importe quelle position). D’un point de vue purement technique il est donc possible de mettre un nombre indéfini d’espaces entre la commande et l’étoile. Ainsi \agentsecret*{Bond} et \agentsecret *{Bond} sont équivalents. Toutefois, la pratique normale est de ne pas insérer de tels espaces.

Il y a deux manières pouvant être plus commodes d’accomplir la même tâche que \@ifstar. Le paquetage suffix permet la construction \newcommand\macommande{variante-non-étoilée} suivie de \WithSuffix\newcommand\macommande*{variante-étoilée}. Et LaTeX3 a le paquetage xparse qui permet ce code.

\NewDocumentCommand\toto{s}{\IfBooleanTF#1
  {variante-étoilée}%
  {variante-non-étoilée}%
  }