Utilities for Managing Class Definitions
These are various functions to support the definition and use of formal classes. Most of them are rarely suitable to be called directly.
Others are somewhat experimental and/or partially implemented only. Do
setClass for normal code development.
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
classLabel(Class) .classEnv(Class, default = .requirePackage("methods"), mustFind = TRUE) testVirtual(properties, extends, prototype, where) makePrototypeFromClassDef(slots, ClassDef, extends, where) newEmptyObject() completeClassDefinition(Class, ClassDef, where, doExtends) getAllSuperClasses(ClassDef, simpleOnly = TRUE) superClassDepth(ClassDef, soFar, simpleOnly = TRUE) isVirtualClass(Class, where) newBasic(Class, ...) makeExtends(Class, to, coerce, test, replace, by, package, slots, classDef1, classDef2) reconcilePropertiesAndPrototype(name, properties, prototype, superClasses, where) tryNew(Class, where) empty.dump() showClass(Class, complete=TRUE, propertiesAreCalled="Slots") showExtends(ext, printTo = stdout()) possibleExtends(class1, class2, ClassDef1 = getClassDef(class1), ClassDef2 = getClassDef(class2, where = .classEnv(ClassDef1))) completeExtends(ClassDef, class2, extensionDef, where) classMetaName(name) methodsPackageMetaName(prefix, name, package = "") metaNameUndo(strings, prefix, searchForm = FALSE) requireMethods(functions, signature, message, where) checkAtAssignment(cl, name, valueClass) checkSlotAssignment(obj, name, value) defaultPrototype() isClassDef(object) validSlotNames(names) getDataPart(object) setDataPart(object, value, check = TRUE)
Summary of Functions
Test for a Virtual Class. Figures out, as well as possible, whether the class with these properties, extension, and prototype is a virtual class. Can be forced to be virtual by extending
Otherwise, a class is virtual only if it has no slots, extends no non-virtual classes, and has a
Makes the prototype implied by the class definition.
The following three rules are applied in this order.
If the class has slots, then the prototype for each slot is used by default, but a corresponding element in the explicitly supplied prototype in
ClassDef, if there is one, is used instead (but it must be coercible to the class of the slot). This includes the data part (
".Data"slot) if there is one.
If there are no slots but a non-null prototype was specified, this is returned.
If there is a non-virtual superclass (a class in the extends list), then its prototype is used. The data part is extracted if needed (it is allowed to have two superclasses with a data part; the first is used and a warning issued on any others).
If all three of the above fail, the prototype is
Utility function to create an empty object into which slots can be set.
Currently just creates an empty list with class
Later version should create a special object reference that marks an object currently with no slots and no data.
Completes the definition of
Class, relative to the class definitions visible from environment
TRUE, complete the super- and sub-class information.
This function is called when a class is defined or re-defined.
Extracts one of the intrinsically defined class definition properties (".Properties", etc.) Strictly a utility function.
Returns a named character vector. The names are the names of the slots, the values are the classes of the corresponding slots. The argument
xcan either be the name of a class or the class definition object.
Get the names of all the classes that this class definition extends.
getAllSuperClassesis a utility function used to complete a class definition. It returns all the superclasses reachable from this class, in breadth-first order (which is the order used for matching methods); that is, the first direct superclass followed by all its superclasses, then the next, etc. (The order is relevant only in the case that some of the superclasses have multiple inheritance.)
superClassDepth, which is called from
getAllSuperClasses, returns the same information, but as a list with components
depth, the latter for the number of generations back each class is in the inheritance tree. The argument
soFaris used to avoid loops in the network of class relationships.
Is the named class a virtual class?
A class is virtual if explicitly declared to be, and also if the class is not formally defined.
assign the definition of the class to the specially named object
the implementation of the function
newfor basic classes that don't have a formal definition.
Any of these could have a formal definition, except for
NULLcan't have attributes). For all cases except
"NULL", the class of the result will be set to
newfor the interpretation of the arguments.
convert the argument to a list defining the extension mechanism.
makes a list or a structure look like a prototype for the given class.
Specifically, returns a structure with attributes corresponding to the slot names in properties and values taken from prototype if they exist there, from
new(classi)for the class,
classiof the slot if that succeeds, and
The prototype may imply slots not in the properties list, since properties does not include inherited slots (these are left unresolved until the class is used in a session).
Tries to generate a new element from this class, but if the attempt fails (as, e.g., when the class is undefined or virtual) just returns
This is inefficient and also not a good idea when actually generating objects, but is useful in the initial definition of classes.
Print the information about a class definition.
TRUE, include the indirect information about extensions.
It is the utility called from
show(getClass(.)), and the user should typically use
getClass(.)for looking at class definitions.
Print the elements of the list of extensions; for
printTo = FALSE, returns a list with components
how; this is used e.g., by
Find the information that says whether class1 extends class2, directly or indirectly.
This can be either a logical value or an object of class
SClassExtensioncontaining various functions to test and/or coerce the relationship.
Returns an informative character string identifying the class and, if appropriate, the package from which the class came.
Returns the environment, typically a namespace, in which the
Classhas been defined.
Classshould typically be the result of
class()(and hence contain a
complete the extends information in the class definition, by following transitive chains.
extensionDefare included, this class relation is to be added. Otherwise just use the current
subclassesslots are completed with any indirect relations visible.
a name for the object storing this class's definition
a name mangling device to hide metadata defining method and class information.
As its name implies, this function undoes the name-mangling used to produce meta-data object names, and returns a object of class
Require a subclass to implement methods for the generic functions, for this signature.
For each generic,
setMethodwill be called to define a method that throws an error, with the supplied message.
requireMethodsfunction allows virtual classes to require actual classes that extend them to implement methods for certain functions, in effect creating an API for the virtual class.
Otherwise, default methods for the corresponding function would be called, resulting in less helpful error messages or (worse still) silently incorrect results.
Check that the value provided is allowed for this slot, by consulting the definition of the class. Called from the C code that assigns slots.
For privileged slots (those that can only be set by accessor functions defined along with the class itself), the class designer may choose to improve efficiency by validating the value to be assigned in the accessor function and then calling
slot<-with the argument
check=FALSE, to prevent the call to
The prototype for a class which will have slots, is not a virtual class, and does not extend one of the basic classes. Both its
classand its (R internal) type,
These functions perform part of the initialization of classes and methods, and are called (only!) from
objecta representation of a class?
namesunless one of the names is reserved, in which case there is an error. (As of writing,
"class"is the only reserved slot name.)
Utilities called to implement
object@.Data. Calls to
setDataPartare also used to merge the data part of a superclass prototype.
1 2 3 4 5 6 7 8 9 10 11 12 13 14
typeof(defaultPrototype()) #-> "S4" ## .classEnv() meth.ns <- asNamespace("methods") if(get4 <- !any("package:stats4" == search())) require("stats4") stopifnot(TRUE , identical(.classEnv("data.frame"), meth.ns) , identical(.classEnv(class(new("data.frame"))), meth.ns) , identical(.classEnv( "mle" ), meth.ns) # <- *not* 'stats4' , identical(.classEnv(class(new("mle"))), asNamespace("stats4")) , identical(.classEnv(getClass ("mle") ), asNamespace("stats4")) ) if(get4) detach("package:stats4")
Want to suggest features or report bugs for rdrr.io? Use the GitHub issue tracker.