[Rd] Documentation error in subsitute

[Hadley Wickham]

Hi all,

The documentation for substitute currently reads:

Substitution takes place by examining each component of the parse
tree as follows: If it is not a bound symbol in ‘env’, it is
unchanged.  If it is a promise object, i.e., a formal argument to
a function or explicitly created using ‘delayedAssign()’, the
expression slot of the promise replaces the symbol.  If it is an
ordinary variable, its value is substituted, unless ‘env’ is
‘.GlobalEnv’ in which case the symbol is left unchanged.

Since the clause referring to the globalenv() is attached to the
discussion of ordinary variables, I thought that it implied that

delayedAssign("a", "test")
substitute(a)

would return "test"  (but actually it returns quote(a))

I'd suggest rewording this paragraph to:

Substitution takes place by examining each component of the parse
tree as follows: If it is not a bound symbol in ‘env’, it is
unchanged.  If it is a promise object, i.e., a formal argument to
a function or explicitly created using ‘delayedAssign()’, the
expression slot of the promise replaces the symbol.  If it is an
ordinary variable, its value is substituted.  There's one important
exception to these rules: If 'env' is the ‘.GlobalEnv’, then no
substitution occurs.

Hadley


--
Chief Scientist, RStudio
http://had.co.nz/