====== Commands defined with * options ======


LaTeX commands commonly have "versions" defined with an asterisk
tagged onto their name: for example ''\newcommand'' and ''\newcommand*''
(the former defines a ''\long'' version of the command).

The simple-minded way for a user to write such a command involves use
of the [[ctanpkg>ifthen|ifthen]] package:

<code latex>
\newcommand{\mycommand}[1]{\ifthenelse{\equal{#1}{*}}%
  {\mycommandStar}%
  {\mycommandNoStar{#1}}%
}
\newcommand{\mycommandStar}{starred version}
\newcommand{\mycommandNoStar}[1]{normal version}
</code>
This does the trick, for sufficiently simple commands, but it has
various tiresome failure modes, and it requires ''\mycommandnostar''
to take an argument.

The LaTeX kernel does a lot of this, and has its own command,
''\@ifstar'' (which needs "internal command protection", cf.


<code latex>
\makeatletter
\newcommand{\mycommand}{%
             \@ifstar
                  \mycommandStar%
                  \mycommandNoStar%
\makeatother
}
\newcommand{\mycommandStar}{starred version}
\newcommand{\mycommandNoStar}{normal version}
</code>

(Note that arguments to ''\mycommandStar'' and ''\mycommandNoStar''
are independent --- either can have their own arguments, unconstrained
by the technique we're using, unlike the trick described above.)
The ''\@ifstar'' trick is all very well, is fast and efficient, but
it requires that the definition be 
[[2_programmation:macros:makeatletter_et_makeatother|''\makeatletter'' protected]].

A pleasing alternative is the [[ctanpkg>suffix|suffix]] package.
This elegant piece of code allows you to define variants of your commands:

<code latex>
\newcommand\mycommand{normal version}
\WithSuffix\newcommand\mycommand*{starred version}
</code>
The package needs [[1_generalites:glossaire:qu_est_ce_que_etex|ε-LaTeX]], but any new enough
distribution defines LaTeX as e-LaTeX by default.  Command
arguments may be specified in the normal way, in both command
definitions (after the ''*'' in the ''\WithSuffix''
version).  You can also use the TeX primitive commands, creating a
definition like:

<code latex>
\WithSuffix\gdef\mycommand*{starred version}
</code>

For those of an adventurous disposition, a further option is to use
the [[ctanpkg>xparse|xparse]] package from the [[ctanpkg>l3packages|l3packages]]
distribution.  The package defines a bunch of commands (such as
''\NewDocumentCommand'') which are somewhat analagous to
''\newcommand'' and the like, in LaTeX2e.  The big difference is
the specification of command arguments; for each argument, you have a
set of choices in the command specification.  So, to create a
*-command (in LaTeX2e style), one might write:


<code latex>
\NewDocumentCommand \foo { s m } {%
  % #1 is the star indicator
  % #2 is a mandatory argument
  ...
}
</code>

The "star indicator" (''s'') argument appears as ''#1''
and will take values ''\BooleanTrue'' (if there was a star) or
''\BooleanFalse'' (otherwise); the other (''m'') argument  is a
normal TeX-style mandatory argument, and appears as ''#2''.

While [[ctanpkg>xparse|xparse]] provides pleasing command argument specifications,
it //is// part of the [[1_generalites:histoire:c_est_quoi_latex3|LaTeX 3 experimental harness]].
Simply loading the package to provide ''\DeclareDocumentCommand''
"pulls in" all of the LaTeX3 kernel (a large bunch of packages)
via the [[ctanpkg>expl3|expl3]] package.


-----
//Source:// [[faquk>FAQ-cmdstar|Commands defined with * options]]

{{htmlmetatags>metatag-keywords=(LaTeX,latex,macros,programmation,étoile,commande étoilée)
metatag-og:title=(Commands defined with * options)
metatag-og:site_name=(FAQ LaTeX francophone)
}}