defmacro.html
5.64 KB
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
196
197
198
199
200
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><title>R: Define a macro</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link rel="stylesheet" type="text/css" href="../../R.css">
</head><body>
<table width="100%" summary="page for defmacro {gtools}"><tr><td>defmacro {gtools}</td><td align="right">R Documentation</td></tr></table>
<h2>Define a macro</h2>
<h3>Description</h3>
<p>
<code>defmacro</code> define a macro that uses R expression replacement
</p>
<p>
<code>strmacro</code> define a macro that uses string replacement
</p>
<h3>Usage</h3>
<pre>
defmacro(..., expr)
strmacro(..., expr, strexpr)
</pre>
<h3>Arguments</h3>
<table summary="R argblock">
<tr valign="top"><td><code>...</code></td>
<td>
macro argument list </td></tr>
<tr valign="top"><td><code>expr</code></td>
<td>
R expression defining the macro body </td></tr>
<tr valign="top"><td><code>strexpr</code></td>
<td>
character string defining the macro body </td></tr>
</table>
<h3>Details</h3>
<p>
<code>defmacro</code> and <code>strmacro</code> create a macro from the expression
given in <code>expr</code>, with formal arguments given by the other
elements of the argument list.
</p>
<p>
A macro is similar to a function definition, the arguments are
handled. In a function, formal arguments are simply variables that
contains the result of evaluating the expressions provided to the
function call. In contrast, macros actually modify the macro body by
<code>replacing</code> each formal argument by the expression
(<code>defmacro</code>) or string (<code>strmacro</code>) provided to the macro
call.
</p>
<p>
For <code>defmacro</code>, the special argument name <code>DOTS</code> will be
replaced by <code>...</code> in the formal argument list of the macro so
that <code>...</code> in the body of the expression can be used to obtain
any additional arguments passed to the macro. For <code>strmacro</code> you
can mimic this behavior providing a <code>DOTS=""</code> argument. This is
illustrated by the last example below.
</p>
<p>
Macros are often useful for creating new functions during code execution.
</p>
<h3>Value</h3>
<p>
A macro function.</p>
<h3>Note</h3>
<p>
Note that because [the defmacro code] works on the parsed expression,
not on a text string, defmacro avoids some of the problems of
traditional string substitution macros such as <code>strmacro</code> and the C
preprocessor macros. For example, in
<pre>
mul <- defmacro(a, b, expr={a*b})
</pre>
a C programmer might expect
<code>mul(i, j + k)</code> to expand (incorrectly) to <code>i*j + k</code>. In fact it
expands correctly, to the equivalent of <code>i*(j + k)</code>.
</p>
<p>
For a discussion of the differences between functions
and macros, please Thomas Lumley's R-News article (reference below).
</p>
<h3>Author(s)</h3>
<p>
Thomas Lumley wrote <code>defmacro</code>. Gregory R. Warnes
<a href="mailto:warnes@bst.rochester.edu">warnes@bst.rochester.edu</a> enhanced it and created
<code>strmacro</code>.
</p>
<h3>References</h3>
<p>
The original <code>defmacro</code> code was directly taken from:
</p>
<p>
Lumley T. "Programmer's Niche: Macros in {R}", R News, 2001, Vol 1,
No. 3, pp 11–13, <a href="http://CRAN.R-project.org/doc/Rnews/">http://CRAN.R-project.org/doc/Rnews/</a>
</p>
<h3>See Also</h3>
<p>
<code><a href="../../base/html/function.html">function</a></code>
<code><a href="../../base/html/substitute.html">substitute</a></code>,
<code><a href="../../base/html/eval.html">eval</a></code>,
<code><a href="../../base/html/parse.html">parse</a></code>,
<code><a href="../../base/html/source.html">source</a></code>,
<code><a href="../../base/html/parse.html">parse</a></code>,
</p>
<h3>Examples</h3>
<pre>
####
# macro for replacing a specified missing value indicator with NA
# within a dataframe
###
setNA <- defmacro(df, var, values,
expr={
df$var[df$var %in% values] <- NA
})
# create example data using 999 as a missing value indicator
d <- data.frame(
Grp=c("Trt", "Ctl", "Ctl", "Trt", "Ctl", "Ctl", "Trt", "Ctl", "Trt", "Ctl"),
V1=c(1, 2, 3, 4, 5, 6, 999, 8, 9, 10),
V2=c(1, 1, 1, 1, 1, 2, 999, 2, 999, 999)
)
d
# Try it out
setNA(d, V1, 999)
setNA(d, V2, 999)
d
###
# Expression macro
###
plot.d <- defmacro( df, var, DOTS, col="red", title="", expr=
plot( df$var ~ df$Grp, type="b", col=col, main=title, ... )
)
plot.d( d, V1)
plot.d( d, V1, col="blue" )
plot.d( d, V1, lwd=4) # use optional 'DOTS' argument
###
# String macro (note the quoted text in the calls below)
#
# This style of macro can be useful when you are reading
# function arguments from a text file
###
plot.s <- strmacro( DF, VAR, COL="'red'", TITLE="''", DOTS="", expr=
plot( DF$VAR ~ DF$Grp, type="b", col=COL, main=TITLE, DOTS)
)
plot.s( "d", "V1")
plot.s( DF="d", VAR="V1", COL='"blue"' )
plot.s( "d", "V1", DOTS='lwd=4') # use optional 'DOTS' argument
#######
# Create a macro that defines new functions
######
plot.sf <- defmacro(type='b', col='black',
title=deparse(substitute(x)), DOTS, expr=
function(x,y) plot( x,y, type=type, col=col, main=title, ...)
)
plot.red <- plot.sf(col='red',title='Red is more Fun!')
plot.blue <- plot.sf(col='blue',title="Blue is Best!", lty=2)
plot.red(1:100,rnorm(100))
plot.blue(1:100,rnorm(100))
</pre>
<hr><div align="center">[Package <em>gtools</em> version 2.4.0 <a href="00Index.html">Index]</a></div>
</body></html>