The mhsetup package^{∗}

Morten Høgholm

2004/10/10

Abstract

The mhsetup package provides tools for a L^{A}TEX programming environment similar to the one described in expl3 on ctan although not as extensive. It is a required part of both the mathtools and empheq packages.

1 The new internal syntax

The L^{A}TEX3 package ldcsetup defines the command \InternalSyntaxOn which makes _and : letters and then automatically restores the category codes at the end of the package. This usually works fine but when you try to load amstext you will experience that TEX goes into an infinite loop. Packages containing code like \@for\@tempa:=\@tempb\do{...} will not work correctly either, thus we provide an alternative version here with the pair of commands

\MHInternalSyntaxOn  \MHInternalSyntaxOn and \MHInternalSyntaxOff. They are to be used only
\MHInternalSyntaxOff as a pair, because \MHInternalSyntaxOn defines \MHInternalSyntaxOff so that

it restores the category codes correctly.

2 Handling optional arguments

The standard behavior of scanning for optional arguments in L^{A}TEX allows any number of spaces preceding the optional argument and that is not always good in math. For that reason amsmath makes sure that commands like \\ disallows spaces before the optional argument but at the same time it fails to provide “safe” environments. What would you expect from the following input?

  \[
    \begin{gathered}
      [v] = 100 \\
      [t] = 200
    \end{gathered}
  \]

L^{A}TEX will see the [v] as an optional argument of gathered and use it. In this case the test inside gathered checks if it’s a t or b and if it’s neither it’ll choose \vcenter internally. So you get no warning, only missing output. Another example, this time from the empheq package used with its overload option: If preceding spaces are allowed, the input

∗This package has version number v1.0b, last revised on 2004/10/10.

    \begin{gather}
      [a] = [b]
    \end{gather}

results in the rather strange error message

    ! Package keyval Error: a undefined.

When using \newcommand etc. for defining commands and environments with optional arguments, the peek ahead is done by \kernel@ifnextchar (since L^{A}TEX release 2003/12/01, else \@ifnextchar) and it is hardwired at defini-

\MHPrecedingSpacesOff tion time by \@xargdef. With the commands \MHPrecedingSpacesOff and

\MHPrecedingSpacesOn \MHPrecedingSpacesOn mhsetup provides an interface to define commands and environments where the optional argument cannot have preceding spaces. You simply wrap them around the definitions:

  \MHPrecedingSpacesOff
  \newenvironment*{test}[1][default]{Start, arg: (#1)}{Ending.}
  \MHPrecedingSpacesOn
  \begin{test}
    [text]
  \end{test}
  \begin{test}[text]
  \end{test}

Start, arg: (default) [text] Ending. Start, arg: (text) Ending.

It is of somewhat limited use in commands (control words in TEX terminology), because TEX discards the spaces. The exception is control symbols where TEX obeys following spaces but there are rather few of them available. All is not lost however. In the aligned environment from amsmath (shown below) a command is used as argument grabber.

  \newenvironment{aligned}{%
    \let\@testopt\alignsafe@testopt
    \aligned@a
  }{%
    \crcr\egroup
    \restorecolumn@
    \egroup
  }
  \newcommand{\aligned@a}[1][c]{\start@aligned{#1}\m@ne}

By applying our trick on the grabber function, we get a space obeying version:

  \MHPrecedingSpacesOff
  \renewcommand*\aligned@a[1][c]{\start@aligned{#1}\m@ne}
  \MHPrecedingSpacesOn

This way a nested aligned environment is still safe from empty first cells.

3 First bits of a new programming environment

1 ⟨∗package⟩

3.1 The new internal syntax

\MHInternalSyntaxOn \MHInternalSyntaxOff Almost copy of \InternalSyntaxOn.
 2 \def\MHInternalSyntaxOn{
 3 \edef\MHInternalSyntaxOff{%
 4 \catcode`\noexpand\~=\the\catcode`\~\relax
 5 \catcode`\noexpand\ =\the\catcode`\ \relax
 6 \catcode`\noexpand\^^I=\the\catcode`\^^I\relax
 7 \catcode`\noexpand\@=\the\catcode`\@\relax
 8 \catcode`\noexpand\:=\the\catcode`\:\relax
 9 \catcode`\noexpand\_=\the\catcode`\_\relax
10 \endlinechar=\the\endlinechar\relax
11 }%
12 \catcode`\~=10\relax
13 \catcode`\ =9\relax
14 \catcode`\^^I=9\relax
15 \makeatletter
16 \catcode`\_=11\relax
17 \catcode`\:=11\relax
18 \endlinechar=` %
19 \relax

20 }

21 \MHInternalSyntaxOn
22 \AtEndOfPackage{\MHInternalSyntaxOff}

3.2 Programming tools

The whole idea is to provide programming tools that are convenient but not yet widely available. I hope this’ll be obsolete soon!

Firstly we setup a few helper functions.

\MH_let:NwN An alias for \let.
23 \let\MH_let:NwN \let

\MH_let:cN This one takes a \csname-\endcsname name and \lets it to a single macro. We’ll use this to setup our conditionals.

24 \def\MH_let:cN #1#2{
25 \expandafter\MH_let:NwN \csname#1\endcsname#2}

\MH_let:cc This one has takes a \csname-\endcsname name and \lets it to a another \csname-\endcsname name. To be used in constructions with weird characters like * or alike in them and can take a \global prefix if wanted (we want that later on).

26 \def\MH_let:cc #1#2{
27 \expandafter\MH_let:NwN\csname#1\expandafter\endcsname
28 \csname#2\endcsname}
\MH_new_boolean:n \MH_set_boolean_F:n \MH_set_boolean_T:n \MH_if_boolean:nTF \MH_if_boolean:nT \MH_if_boolean:nF Sets up conditionals. For instance
     \MH_new_boolean:n {⟨name⟩}

defines the boolean ⟨name⟩ but also the conditional \if_boolean_⟨name ⟩: to be used in the ordinary

\if_boolean_⟨name ⟩:

⟨true code⟩

\else:

⟨false code⟩

\fi:

There is also a more “L^{A}TEX-like” interface available by using the commands

     \MH_if_boolean:nT{⟨name⟩}{⟨arg⟩}

which will execute the argument if the current value of the boolean is ‘true’ while

     \MH_if_boolean:nF{⟨name⟩}{⟨arg⟩}

is the equivalent with ‘false’. Finally we have

\MH_if_boolean:nTF{⟨name⟩}{⟨true code⟩}{⟨false code⟩}.

This is the interface I have used in this package.

Initially \if_boolean_⟨name ⟩: is ‘false’. This can be changed by saying

  TEX: \boolean_⟨name ⟩_true: or
  L^{A}TEX: \MH_set_boolean_T:n{⟨name⟩}

and changed back again by

  TEX: \boolean_⟨name ⟩_false: or
  L^{A}TEX: \MH_set_boolean_F:n{⟨name⟩}

And yes, we’re also using alternative names for \else and \fi now. That way a simple search and replace will be all that is needed for this package to be a certified L^{A}TEX3 package (well, maybe a little more is needed, but not much).

29 \def\MH_new_boolean:n #1{
30 \expandafter\@ifdefinable\csname if_boolean_#1:\endcsname{
31  \@namedef{boolean_#1_true:}
32  {\MH_let:cN{if_boolean_#1:}\iftrue}
33  \@namedef{boolean_#1_false:}
34  {\MH_let:cN{if_boolean_#1:}\iffalse}
35  \@nameuse{boolean_#1_false:}%

36 } 37 }

38 \def\MH_set_boolean_F:n #1{ \@nameuse{boolean_#1_false:} }
39 \def\MH_set_boolean_T:n #1{ \@nameuse{boolean_#1_true:} }
40 \def\MH_if_boolean:nTF #1{
41 \@nameuse{if_boolean_#1:}
42  \expandafter\@firstoftwo
43 \else:
44  \expandafter\@secondoftwo
45 \fi:

46 }

47 \def\MH_if_boolean:nT #1{
48 \@nameuse{if_boolean_#1:}
49  \expandafter\@firstofone

50 \else:
51  \expandafter\@gobble
52 \fi:

53 }

54 \def\MH_if_boolean:nF #1{
55 \@nameuse{if_boolean_#1:}
56  \expandafter\@gobble
57 \else:
58  \expandafter\@firstofone
59 \fi:

60 }

\if:w \if_meaning:NN \else: \fi: \if_num:w \if_dim:w \if_case:w \or: Copies of TEX primitives.
61 \@ifundefined{if:w}{\MH_let:NwN \if:w =\if}{}
62 \@ifundefined{if_meaning:NN}{\MH_let:NwN \if_meaning:NN =\ifx}{}
63 \@ifundefined{else:}{\MH_let:NwN \else:=\else}{}
64 \@ifundefined{fi:}{\MH_let:NwN \fi:=\fi}{}
65 \@ifundefined{if_num:w}{\MH_let:NwN \if_num:w =\ifnum}{}
66 \@ifundefined{if_dim:w}{\MH_let:NwN \if_dim:w =\ifdim}{}
67 \@ifundefined{if_case:w}{\MH_let:NwN \if_case:w =\ifcase}{}
68 \@ifundefined{or:}{\MH_let:NwN \or:=\or}{}

\MH_cs_to_str:N Strip off the backslash of a macro name.

69 \def\MH_cs_to_str:N {\expandafter\@gobble\string}

\MH_protected: \MH_setlength:dn \MH_addtolength:dn We might as well make use of some of the extended features from ε-TEX. We use \dimexpr for some simple calculations as it saves a lot of the scanning that goes on inside calc. The \protected primitive comes in handy when we want to declare a robust command, that cannot be ‘robustified’ with \DeclareRobustCommand. If we don’t have ε-TEX we’ll just let our private macros be aliases for the less effective alternatives.

70 \@ifundefined{eTeXversion}

71 {

72  \MH_let:NwN \MH_protected:\relax
73  \def\MH_setlength:dn{\setlength}
74  \def\MH_addtolength:dn{\addtolength}

75 } 76 {

77  \MH_let:NwN \MH_protected:\protected
78  \def\MH_setlength:dn #1#2{#1=\dimexpr#2\relax\relax}
79  \def\MH_addtolength:dn #1#2{\advance#1 \dimexpr#2\relax\relax}

80 }

\MH_keyval_alias_with_addon:nnnn \MH_keyval_alias:nnn A way to make aliases with keyval. This will come in handy later.

81 \def\MH_keyval_alias_with_addon:nnnn #1#2#3#4{
82 \@namedef{KV@#1@#2}{\@nameuse{KV@#1@#3}#4}
83 \@namedef{KV@#1@#2@default}{\@nameuse{KV@#1@#3@default}#4}}
84 \def\MH_keyval_alias:nnn #1#2#3{
85 \MH_keyval_alias_with_addon:nnnn {#1}{#2}{#3}{}}
\MH_use_choice_i:nnnn \MH_use_choice_ii:nnnn \MH_use_choice_iii:nnnn \MH_use_choice_iv:nnnn I need to be able to pick up individual arguments in a list of four (similar to
\@secondoftwo).
86 \def\MH_use_choice_i:nnnn #1#2#3#4{#1}

 87 \def\MH_use_choice_ii:nnnn #1#2#3#4{#2}
 88 \def\MH_use_choice_iii:nnnn #1#2#3#4{#3}
 89 \def\MH_use_choice_iv:nnnn #1#2#3#4{#4}
\MH_nospace_ifnextchar:Nnn \MH_nospace_nextchar: \MH_nospace_testopt:nn \MH_nospace_protected_testopt:n Scanning for the next character but disallow spaces.
 90 \long\def\MH_nospace_ifnextchar:Nnn #1#2#3{
 91 \MH_let:NwN\reserved@d=~#1
 92 \def\reserved@a{#2}
 93 \def\reserved@b{#3}
 94 \futurelet\@let@token\MH_nospace_nextchar:

95 }

 96 \def\MH_nospace_nextchar:{
 97 \if_meaning:NN \@let@token\reserved@d
 98  \MH_let:NwN \reserved@b\reserved@a
 99 \fi:
100 \reserved@b

101 }

102 \long\def\MH_nospace_testopt:nn #1#2{
103 \MH_nospace_ifnextchar:Nnn[
104  {#1}
105  {#1[{#2}]}

106 }

107 \def\MH_nospace_protected_testopt:n #1{
108 \if_meaning:NN \protect\@typeset@protect
109  \expandafter\MH_nospace_testopt:nn
110 \else:
111  \@x@protect#1
112 \fi:

113 }

\kernel@ifnextchar \MH_kernel_xargdef:nwwn \MH_nospace_xargdef:nwwn \MHPrecedingSpacesOff \MHPrecedingSpacesOn The code for the space sensitive peek ahead.
114 \@ifundefined{kernel@ifnextchar}
115 {\MH_let:NwN \kernel@ifnextchar \@ifnextchar}

116 {}

117 \MH_let:NwN \MH_kernel_xargdef:nwwn \@xargdef
118 \long\def\MH_nospace_xargdef:nwwn #1[#2][#3]#4{
119 \@ifdefinable#1{
120  \expandafter\def\expandafter#1\expandafter{
121  \expandafter
122  \MH_nospace_protected_testopt:n
123  \expandafter

124 #1

125  \csname\string#1\endcsname
126  {#3}}
127  \expandafter\@yargdef
128  \csname\string#1\endcsname
129  \tw@
130  {#2}
131  {#4}}}
132 \providecommand*\MHPrecedingSpacesOff{
133 \MH_let:NwN \@xargdef \MH_nospace_xargdef:nwwn

134 }

135 \providecommand*\MHPrecedingSpacesOn{
136 \MH_let:NwN \@xargdef \MH_kernel_xargdef:nwwn

137 } 138 ⟨/package⟩

7