1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
|
<!DOCTYPE html>
<html>
<!-- Created by GNU Texinfo 7.0.3, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<!-- This manual documents GNU troff version 1.23.0.
Copyright 1994-2023 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
copy of the license is included in the section entitled "GNU Free
Documentation License". -->
<title>Parameters (The GNU Troff Manual)</title>
<meta name="description" content="Parameters (The GNU Troff Manual)">
<meta name="keywords" content="Parameters (The GNU Troff Manual)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">
<link href="index.html" rel="start" title="Top">
<link href="Request-Index.html" rel="index" title="Request Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Writing-Macros.html" rel="up" title="Writing Macros">
<link href="Copy-Mode.html" rel="next" title="Copy Mode">
<link href="Writing-Macros.html" rel="prev" title="Writing Macros">
<style type="text/css">
<!--
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
div.example {margin-left: 3.2em}
span.r {font-family: initial; font-weight: normal; font-style: normal}
span:hover a.copiable-link {visibility: visible}
strong.def-name {font-family: monospace; font-weight: bold; font-size: larger}
-->
</style>
</head>
<body lang="en">
<div class="subsection-level-extent" id="Parameters">
<div class="nav-panel">
<p>
Next: <a href="Copy-Mode.html" accesskey="n" rel="next">Copy Mode</a>, Previous: <a href="Writing-Macros.html" accesskey="p" rel="prev">Writing Macros</a>, Up: <a href="Writing-Macros.html" accesskey="u" rel="up">Writing Macros</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Request-Index.html" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<h4 class="subsection" id="Parameters-1">5.24.1 Parameters</h4>
<a class="index-entry-id" id="index-parameters"></a>
<p>Macro calls and string interpolations optionally accept a list of
arguments; recall <a class="ref" href="Calling-Macros.html">Calling Macros</a>. At the time such an
interpolation takes place, these <em class="dfn">parameters</em> can be examined using
a register and a variety of escape sequences starting with ‘<samp class="samp">\$</samp>’.
All such escape sequences are interpreted even in copy mode, a fact we
shall motivate and explain below (see <a class="pxref" href="Copy-Mode.html">Copy Mode</a>).
</p>
<dl class="first-deffn">
<dt class="deffn" id="index-_005cn_005b_002e_0024_005d"><span class="category-def">Register: </span><span><strong class="def-name"><code class="t">\n[.$]</code></strong><a class="copiable-link" href='#index-_005cn_005b_002e_0024_005d'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-_002e_0024"></a>
<a class="index-entry-id" id="index-parameter-count-register-_0028_002e_0024_0029"></a>
<p>The count of parameters available to a macro or string is kept in this
read-only register. The <code class="code">shift</code> request can change its value.
</p></dd></dl>
<p>Any individual parameter can be accessed by its position in the list of
arguments to the macro call, numbered from left to right starting at 1,
with one of the following escape sequences.
</p>
<dl class="first-deffn">
<dt class="deffn" id="index-_005c_0024n"><span class="category-def">Escape sequence: </span><span><strong class="def-name"><code class="t">\$</code><span class="r"><i class="slanted">n</i></span><code class="t"></code></strong><a class="copiable-link" href='#index-_005c_0024n'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-_005c_0024"></a>
</dd><dt class="deffnx def-cmd-deffn" id="index-_005c_0024_0028nn"><span class="category-def">Escape sequence: </span><span><strong class="def-name"><code class="t">\$(</code><span class="r"><i class="slanted">nn</i></span><code class="t"></code></strong><a class="copiable-link" href='#index-_005c_0024_0028nn'> ¶</a></span></dt>
<dt class="deffnx def-cmd-deffn" id="index-_005c_0024_005bnnn_005d"><span class="category-def">Escape sequence: </span><span><strong class="def-name"><code class="t">\$[</code><span class="r"><i class="slanted">nnn</i></span><code class="t">]</code></strong><a class="copiable-link" href='#index-_005c_0024_005bnnn_005d'> ¶</a></span></dt>
<dd><p>Interpolate the <var class="var">n</var>th, <var class="var">nn</var>th, or <var class="var">nnn</var>th parameter. The
first form expects only a single digit (1≤<var class="var">n</var>≤9)), the
second two digits (01≤<var class="var">nn</var>≤99)), and the third any
positive integer <var class="var">nnn</var>. Macros and strings accept an unlimited
number of parameters.
</p></dd></dl>
<dl class="first-deffn">
<dt class="deffn" id="index-_002eshift"><span class="category-def">Request: </span><span><strong class="def-name"><code class="t">.shift</code></strong> <var class="def-var-arguments">[<span class="r"><i class="slanted">n</i></span>]</var><a class="copiable-link" href='#index-_002eshift'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-shift"></a>
<p>Shift the parameters <var class="var">n</var> places (1 by default). This is a
“left shift”: what was parameter <var class="var">i</var> becomes parameter
<em class="math"><var class="var">i</var>-<var class="var">n</var></em>. The parameters formerly in positions 1
to <var class="var">n</var> are no longer available. Shifting by a non-positive
amount performs no operation. The register <code class="code">.$</code> is adjusted
accordingly.
</p></dd></dl>
<a class="index-entry-id" id="index-copy-mode_002c-and-macro-parameters"></a>
<a class="index-entry-id" id="index-mode_002c-copy_002c-and-macro-parameters"></a>
<a class="index-entry-id" id="index-macro_002c-parameters-_0028_005c_0024_0029"></a>
<a class="index-entry-id" id="index-parameters_002c-macro-_0028_005c_0024_0029"></a>
<p>In practice, parameter interpolations are usually seen prefixed with an
extra escape character. This is because the <code class="code">\$</code> family of escape
sequences is interpreted even in copy mode.<a class="footnote" id="DOCF100" href="groff.html_fot.html#FOOT100"><sup>100</sup></a>
</p>
<dl class="first-deffn">
<dt class="deffn" id="index-_005c_0024_002a-1"><span class="category-def">Escape sequence: </span><span><strong class="def-name"><code class="t">\$*</code><span class="r"><i class="slanted"></i></span><code class="t"></code></strong><a class="copiable-link" href='#index-_005c_0024_002a-1'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-_005c_0024_002a"></a>
</dd><dt class="deffnx def-cmd-deffn" id="index-_005c_0024_0040-1"><span class="category-def">Escape sequence: </span><span><strong class="def-name"><code class="t">\$@</code><span class="r"><i class="slanted"></i></span><code class="t"></code></strong><a class="copiable-link" href='#index-_005c_0024_0040-1'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-_005c_0024_0040"></a>
</dd><dt class="deffnx def-cmd-deffn" id="index-_005c_0024_005e-1"><span class="category-def">Escape sequence: </span><span><strong class="def-name"><code class="t">\$^</code><span class="r"><i class="slanted"></i></span><code class="t"></code></strong><a class="copiable-link" href='#index-_005c_0024_005e-1'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-_005c_0024_005e"></a>
<p>In some cases it is convenient to interpolate all of the parameters at
once (to pass them to a request, for instance). The <code class="code">\$*</code> escape
concatenates the parameters, separating them with spaces. <code class="code">\$@</code>
is similar, concatenating the parameters, surrounding each with double
quotes and separating them with spaces. If not in compatibility mode,
the interpolation depth of double quotes is preserved (see <a class="pxref" href="Calling-Macros.html">Calling Macros</a>). <code class="code">\$^</code> interpolates all parameters as if they were
arguments to the <code class="code">ds</code> request.
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">.de foo
. tm $1='\\$1'
. tm $2='\\$2'
. tm $*='\\$*'
. tm $@='\\$@'
. tm $^='\\$^'
..
.foo " This is a "test"
error→ $1=' This is a '
error→ $2='test"'
error→ $*=' This is a test"'
error→ $@='" This is a " "test""'
error→ $^='" This is a "test"'
</pre></div></div>
<p><code class="code">\$*</code> is useful when writing a macro that doesn’t need to
distinguish its arguments, or even to not interpret them; examples
include macros that produce diagnostic messages by wrapping the
<code class="code">tm</code> or <code class="code">ab</code> requests. Use <code class="code">\$@</code> when writing a macro
that may need to shift its parameters and/or wrap a macro or request
that finds the count significant. If in doubt, prefer <code class="code">\$@</code> to
<code class="code">\$*</code>. An application of <code class="code">\$^</code> is seen in <samp class="file">trace.tmac</samp>,
which redefines some requests and macros for debugging purposes.
</p></dd></dl>
<dl class="first-deffn">
<dt class="deffn" id="index-_005c_00240-1"><span class="category-def">Escape sequence: </span><span><strong class="def-name"><code class="t">\$0</code><span class="r"><i class="slanted"></i></span><code class="t"></code></strong><a class="copiable-link" href='#index-_005c_00240-1'> ¶</a></span></dt>
<dd><a class="index-entry-id" id="index-_005c_00240"></a>
<a class="index-entry-id" id="index-macro-name-register-_0028_005c_00240_0029"></a>
<a class="index-entry-id" id="index-als-request_002c-and-_005c_00240"></a>
<p>Interpolate the name by which the macro being interpreted was called.
The <code class="code">als</code> request can cause a macro to have more than one name.
Applying string interpolation to a macro does not change this name.
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">.de foo
. tm \\$0
..
.als bar foo
.
.de aaa
. foo
..
.de bbb
. bar
..
.de ccc
\\*[foo]\\
..
.de ddd
\\*[bar]\\
..
.
.aaa
error→ foo
.bbb
error→ bar
.ccc
error→ ccc
.ddd
error→ ddd
</pre></div></div>
</dd></dl>
</div>
<hr>
<div class="nav-panel">
<p>
Next: <a href="Copy-Mode.html">Copy Mode</a>, Previous: <a href="Writing-Macros.html">Writing Macros</a>, Up: <a href="Writing-Macros.html">Writing Macros</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Request-Index.html" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
|
