Wiki: TeX

Your best resource for TeX is the TeXBook, particularly chapter 20 ("Definitions (also called Macros)") and Appendix D ("Dirty Tricks"). Appendix B provides a list of almost all macros defined at startup.

The reference for plain TeX at tug.org and TeX for the Impatient are also good resources.

TeX-autogolfer is a tool to help in golfing TeX. It's a combo of a simple minifier (remove whitespace, etc.) and a meta-macro system; for example you can write \usegolf{rebind\advance}, and it creates (effectively) \let\A\advance and replaces all of your uses of \advance with \A.

Basics

Differences from Plain TeX

The TeX language on the site is very similar to Knuth's plain TeX, with a few small modifications:

• Output is through text rather than DVI or PDF, using dvi-to-text.
• None of the default fonts support characters with code greater than 127, so we use font called \octet with a full code page.
• Hole arguments are pre-filled by a \argv#1 macro, with arg count given by \argc.

Note that all whitespaces and special characters in hole arguments are tweaked to have the category code of 12 ("other").

Spaces

Space characters can be annoying to manage. Important spacing rules:

• Single newline characters get converted to a space (double newlines are converted to \par), so if a bunch of spaces infiltrate your output, try removing newlines or suppressing the newlines with %.
• If you want a literal space, you sometimes have to do an escaped space \ or a non-breaking space ~ (which works only if ~ has not been re-defined)
• Control sequences remove the space after them, so \f 123 is the same as \f123. This rule exists so \f abc does not have an unwanted space
• While parsing a number literal, TeX keeps reading more tokens until it reaches a non-digit or an expandable control sequence. So \newcount\x\x=5\f will expand \f before assigning 5 to \x because it needs to make sure that \f does not start with a digit. Add a space if you want to assign 5 to \x before expanding \f: \newcount\x\x=5 \f

Math operations

Math can be performed in counters. Define a counter with \newcount, and print the value with \the.

\newcount\x
\x=15  % equivalent to the following line
\x15   % (the equals sign is optional)
\the\x % prints 15 as two tokens, "1" then "5"

Counters are 32-bit signed integers. Operations that overflow cause the program to instantly halt with no output.

\x\y            % x = y
\advance\x5     % x += 5
\advance\x by\y % equivalent to the following line
\advance\x\y    % x += y (the "by" text is optional)
\advance\x-\y   % x += -y
\multiply\x\y   % x *= y
\divide\x\y     % x /= y (floor divide)

There is no modulo operator. Modulo can be calculated (if you must) using the definition x % y = x - x / y * y, where x/y is floor division

% d = x - x % y, x = x % y (requires an extra counter)
\d\x\divide\d\y\multiply\d\y\advance\x-\d

Or modulo can be computed by repeated subtraction, assuming x and y are positive.

% x = x % y (slow)
\loop\ifnum\x>\y\advance\x-\y\repeat

ASCII conversions

Convert a char code to corresponding character with \char: \char97 gives the token a.

Convert a character to char code with a backtick: \number`a gives the two tokens 97, and \newcount\x\x=`a assigns 97 as the value of the counter \x.

Looping over a string

The following code loops over all tokens until ;, replacing all - tokens with (DASH)

\def\f#1{\ifx#1;%
    \let\n\relax%
\else%
    \let\n\f%
    \ifx#1-(DASH)%
    \else #1%
    \fi%
\fi\n}

\f 0-185186-70-;

Improvement: an extra stop token

The following code loops over all tokens until ,;, replacing all - tokens with (DASH)

\def\f#1#2;{\ifx#1,\else
    \ifx#1-(DASH)%
    \else #1%
    \fi%
    \f#2;
\fi}

\f 0-185186-70-,;

Tweak: check for empty argument

The following code loops over all tokens until ;, replacing all - tokens with (DASH). It assumes there are no .s in the input.

\def\f#1#2;{%
    \ifx#1-(DASH)%
    \else #1%
    \fi%
\if.#2.\else%
    \f#2;%
\fi}
\f 0-185186-70-;

Looping over two strings

The following code prints "Equal!" if two input token lists are equal.

\def\streq#1#2;#3#4;{
  \if#1,
    \if#3,
      % strings are equal, done
      Equal!
    \else
      % left string is shorter than right string
    \fi
  \else
    \if#3,
      % right string is shorter than left string
    \else
      %#1 and #3 are both not ','
      \if#1#3
        \streq#2;#4;
      \fi
    \fi
  \fi
}

\streq ABC,;DEF,; % (empty output)

\streq ABC,;ABC,; % outputs "Equal!"

Space-delimited inputs

Since all whitespaces from \argv have the category code of 12, the usual macro can't be used to parse inputs:

\def\parse#1 #2\relax{...}
\parse123 456\relax        % Works

{\catcode32=12\gdef\expandedarg{123 456}}  % Simulate an argument with a space
\parse\expandedarg\relax   % Fails

You may want \catcode32=12 for that particular character, but that can break many things. If you can't avoid using a space in your definition, a classic trick is to use another character with the same category code by default, and then replace it with \lowercase or \uppercase:

\lccode`?=32
\lowercase{\def\parse#1?#2\relax{...}}
\parse\expandedarg\relax

Note that \lowercase and \uppercase will apply to every token in the definition that is not a control sequence, so you have to try both and/or tweak \lccode or \uccode to avoid an unwanted substitution.

Debugging

You may find \tracingmacros=1, \message, \meaning, \show and \showthe indispensable for debugging complex macros.

Golfing

One-byte macro ending

If a macro you define takes an argument longer than one token, you might be tempted to use curly braces. However, \def can allow for a single end character, saving one byte per usage.

\def\f#1{something #1 something}
\f{123}\f{456}
% compare
\def\f#1;{something #1 something}
\f123;\f456;

\let

Commonly-used macros can be aliased with \let

\newcount\a\newcount\b\newcount\c
% compare
\let\N\newcount\N\a\N\b\N\c

At the top of a long solution, you might see a block of \lets like \let\N\newcount\let\I\ifnum\let\A\advance

Tilde is active

Tilde (~) is an active character (\catcode`\~=\active), so you can use it in lieu of one control sequence.

\let\N\newcount\N\a\N\b\N\c
% compare
\let~\newcount~\a~\b~\c

Repeated macro vs loop

Repeating a macro several times is often shorter than a loop.

\newcount~\loop\ifnum10>~\the~,\advance~1\repeat
% compare (uses an extra variable)
\newcount\i\def~{\the\i\advance\i1,}~~~~~~~~~~

Newlines

The conventional way to make a new paragraph is the \par command. Two or more consecutive newlines are converted to a single \par and are the most common way to get a newline.

Form feed (ASCII character 12 = 0x0C) is equivalent to \par, but it has one restriction: It is \outer, so it is disallowed in many contexts, such as the replacement text of \def definitions (unless the definition is declared as \long\def) and inside \loop...\repeat constructs. Form feed can be typed in the code.golf editor by typing "0c" while holding down the Alt key.

A few other commands are loosely equivalent to \par and useful over a double-newline in niche situations. Try playing around with these to get a feel for when they're useful: \vfil, \eject, \char10, \endgraf. In particular, \eject forces a page break, so it flushes the output, so you can terminate by an error such as stack overflow.

\catcode`\^^L=\active \outer\def^^L{\par} % ascii form-feed is "\outer\par"
\let\endgraf=\par
\def\break{\penalty-\@M}
\def\eject{\par\break}

The following prints 0 through 9 on their own lines by two approaches which are the same length. The two approaches are a recursive approach using double-newline and a \loop...\repeat approach using \vfil.

\newcount\i\loop\ifnum10>\i\the\i\vfil\advance\i1\repeat
% compare
\newcount\i\def\f{\ifnum10>\i\the\i\advance\i1

\f\fi}\f

Counters

TeX has a fixed set of 256 counters, accessible in a few different ways. Usually you would use newcount to be able to reference a previously unused by a name:

\newcount\i   \the\i  % 0, newcounts are initially 0
\advance\i 3  \the\i  % 3

If you just need one or two counters, you can instead make use of predefined counters:

\day3 \the\day \the\fam % 3 0

If you use lots of counters, alias \count to an active character and address counters by their index (0-255):

\let~\count
\the~0               % 1, if you use a counter that is already in use by TeX, it might have a non-zero value
\advance~0 3 \the~0  % 4

% this way also allows using counters as small arrays:
\the~~0  % index in \count0

As noted above, the <number> argument common to \count and other commands only gets parsed after the first token that can't form a number and extra spaces may be required. You can often eliminate them by using hexadecimal numbers ("41) or character code (`A), or swapping arguments whenever possible:

\count42 100 \foo     % Both spaces are required.
\count42"64 \foo
\count42`d\foo        % No more space is required in general.
                      % However note that if `\foo` were `\the\count42`,
                      % This still requires one space due to the lookahead.

\ifnum\x<9 \the\x\fi  % A space is required.
\ifnum9>\x\the\x\fi   % No space is required.

Data structures

Map from string to string

The basic way to create entries in a map is to use \csname ... \endcsname to define dynamic macro names

\def\set#1#2{\expandafter\xdef\csname#1\endcsname{#2}}
\def\get#1{\csname#1\endcsname}
% Set entries
\set{1}{1}
\set{2}{4}
\set{3}{9}
% Retrieve entries
1: \get{1} \par  % 1: 1
2: \get{2} \par  % 2: 4
3: \get{3} \par  % 3: 9

An alternative definition is

\let\E\expandafter
\def\set#1#2{\E\E\E\xdef\get{#1}{#2}}
\def\get#1{\csname#1\endcsname}

Note the triple expandafter to avoid repeating the \csname...\endcsname.

Map from number to number

In the special case of the key being a counter number, it's often reasonable to only ever use a single counter to do lookups.

\newcount\x\newcount\y
\let\E\expandafter
\def\set{\E\E\E\xdef\get{\the\y}}
\def\get{\csname\the\x\endcsname}
% Set entries
\x1\y1 \set
\x2\y4 \set
\x3\y9 \set
% Retrieve entries
\x1 1: \get \par % 1: 1
\x2 2: \get \par % 2: 4
\x3 3: \get \par % 3: 9

Small array

For small arrays, you can use the counters themselves to form an array. TeX intends counters 25 to 252 to be used freely (reference the Count registers table). It's safest to only use those counters since other parts of TeX may change the rest of the counters, such as to increment the page number.

\newcount\x\newcount\y
\let~\count
% Set entries
\x1\y1 ~\x\y
\x2\y4 ~\x\y
\x3\y9 ~\x\y
% Retrieve entries
\x1 1: \the~\x \par % 1: 1
\x2 2: \the~\x \par % 2: 4
\x3 3: \the~\x \par % 3: 9

Reference tables

Count registers

\count0 0
\loop\ifnum\count0<256
 |\ \the\count0\ |\ \the\count\count0\ |%
 \vfil
 \advance\count0 1
\repeat

Lengths

\newdimen\x%
\x1in %
\newcount\pt%
\newcount\sp%
\def\div#1,#2;{%
  \def\iterate{
    \ifdim#1>\x\else%
      \advance\x-#1%
      \advance#2 1%
      \expandafter%
      \iterate%
    \fi%
  }%
  \iterate%
}%
\div 1pt,\pt;
\div 1sp,\sp;
(\the\pt pt + \the\sp sp)

Primitive commands with \the usable