5.5 Identifiers

An identifier labels a GNU troff datum such as a register, name (macro, string, or diversion), typeface (font, family, or style), color, special character or character class, hyphenation language code, environment, or stream. Valid identifiers consist of one or more ordinary characters.⁵¹ An ordinary character is any Unicode Basic Latin character that is not a space and not the escape character; recall Input Format. Thus, the identifiers ‘br’, ‘PP’, ‘end-list’, ‘ref*normal-print’, ‘|’, ‘@_’, and ‘!"#$%'()*+,-./’ are all valid. Discretion should be exercised to prevent confusion. Identifiers starting with ‘(’ or ‘[’ require care.

.nr x 9
.nr y 1
.nr (x 2
.nr [y 3
.nr sum1 (\n(x + \n[y])
    error→ a space character is not allowed in an escape
    error→   sequence parameter
A:2+3=\n[sum1]
.nr sum2 (\n((x + \n[[y])
B:2+3=\n[sum2]
.nr sum3 (\n[(x] + \n([y)
C:2+3=\n[sum3]
    ⇒ A:2+3=1 B:2+3=5 C:2+3=5

An identifier with a closing bracket (‘]’) in its name can’t be accessed with bracket-form escape sequences that expect an identifier as a parameter. For example, ‘\[foo]]’ accesses the glyph ‘foo’, followed by ‘]’ in whatever the surrounding context is, whereas ‘\C'foo]'’ formats a glyph named ‘foo]’. Similarly, the identifier ‘(’ can’t be interpolated except with bracket forms.

Beginning a macro, string, or diversion name with the character ‘[’ or ‘]’ forecloses use of the refer preprocessor, which recognizes input lines starting with ‘.[’ and ‘.]’ as bibliographic reference delimiters.

Escape sequence: \A'input'

Interpolate 1 if input is a valid identifier, and 0 otherwise. The delimiter need not be a neutral apostrophe; see Delimiters. Because GNU troff ignores any input character with an invalid code when reading it, invalid identifiers are empty or contain spaces, tabs, newlines, or escape sequences that interpolate something other than a sequence of ordinary characters.

You can employ \A to validate a macro argument before using it to construct another escape sequence or identifier.

.\" usage: .init-coordinate-pair name val1 val2
.\" Create a coordinate pair where name!x=val1 and
.\" name!y=val2.
.de init-coordinate-pair
.  if \A'\\$1' \{\
.    if \B'\\$2' .nr \\$1!x \\$2
.    if \B'\\$3' .nr \\$1!y \\$3
.  \}
..
.init-coordinate-pair center 5 10
.init-coordinate-pair "poi→nt" trash garbage \" ignored
.init-coordinate-pair point waste rubbish \" ignored
The center is at (\n[center!x], \n[center!y]).
    ⇒ The center is at (5, 10).

In this example, we also validated the numeric arguments; the registers ‘point!x’ and ‘point!y’ remain undefined. See Numeric Expressions for the \B escape sequence.

The formatter’s handling of undefined identifiers is context-dependent. There is no way to invoke an undefined request; such syntax is interpreted as a macro call instead. If the identifier is interpreted as a string, macro, or diversion name, the formatter defines it as empty and interpolates nothing.⁵² Similarly, if the identifier is interpreted as a register name, the formatter initializes it to zero and interpolates that value.⁵³ Attempting to use an undefined typeface, special character or character class, color, environment, hyphenation language code, or stream generally provokes an error diagnostic.

Identifiers for requests, macros, strings, and diversions share one name space; special characters and character classes another. No other object types do.

.de xxx
.  nop foo
..
.di xxx
bar
.br
.di
.
.xxx
    ⇒ bar

The foregoing example shows that GNU troff reuses the identifier ‘xxx’, changing it from a macro to a diversion. No warning is emitted, and the previous contents of ‘xxx’ are lost.