R devel - Apr 2013 - Documentation error in subsitute

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/

On Wed, Apr 3, 2013 at 10:38 AM, Hadley Wickham <h.wickham at gmail.com>
wrote:
> 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.
It acts differently in the global environment.  Try this:
> f <- function() { delayedAssign("a", "test");
substitute(a) }
> f()
[1] "test"


--
Statistics & Software Consulting
GKX Group, GKX Associates Inc.
tel: 1-877-GKX-GROUP
email: ggrothendieck at gmail.com