[Rd] S4 object type available for testing

[John Chambers]

The default prototype object for an S4 class up to now has been a 
zero-length list (nothing else worked).  This is wrong in principle, 
because it makes the objects look like vectors to low-level C code, and 
they should not.  It may also be the cause of some inefficiency.

A new low-level type has been added for these classes.  It's currently 
available in the r-devel version, but not turned on by default.  If you 
have code that makes use of S4 objects, or C-level code that tries to 
handle all internal types, please try to test out the new feature.

To turn the feature on, set environment variable R_S4_Type to anything 
non-empty, for example in bash

$ export R_S4_Type=TRUE

before starting up R.  You can also turn the new type on and off in R by 
calling methods:::.useS4Prototype(TRUE) or FALSE.  (This is a temporary 
situation, eventually the type will be made the default.)

Note the following points.

1.  The type affects the prototype object for the class.  Therefore what 
matters is whether it's turned on when the call to setClass() takes 
place.  It has NO effect on objects generated from an existing class.  
And turning the type off has no effect until a new setClass() call.

2.  Classes that contain any of the basic R object types ("character", 
"function", etc.) are unaffected by the change.  Their prototype objects 
will still have the inherited basic type, as they should.

3. To see what the current prototype is, use defaultPrototype().  If the 
new type is on you should see:

 > defaultPrototype()
<S4 Type Object>

4. Not directly related, but some changes have been made to make 
automatic printing of S4 objects correspond more closely to a call to 
show(), as per the green book.

John