| Line 7... |
Line 7... |
| 7 |
\alias{validObject}
|
7 |
\alias{validObject}
|
| 8 |
\alias{getValidity}
|
8 |
\alias{getValidity}
|
| 9 |
\alias{setValidity}
|
9 |
\alias{setValidity}
|
| 10 |
\title{ Test the Validity of an Object }
|
10 |
\title{ Test the Validity of an Object }
|
| 11 |
\description{
|
11 |
\description{
|
| - |
|
12 |
\code{validObject()} tests the validity of \code{object} related to
|
| - |
|
13 |
its class definition; specifically, it checks that all slots
|
| - |
|
14 |
specified in the class definition are present and that the object in
|
| 12 |
The validity of \code{object} related to its class definition is
|
15 |
the slot is from the required class or a subclass of that class.
|
| - |
|
16 |
|
| 13 |
tested. If the object is valid, \code{TRUE} is returned; otherwise,
|
17 |
If the object is valid, \code{TRUE} is returned; otherwise, an error
|
| 14 |
either a vector of strings describing validity failures is returned,
|
18 |
is generated, reporting all the validity failures encountered.
|
| 15 |
or an error is generated (according to whether \code{test} is
|
19 |
If argument \code{test} is
|
| 16 |
\code{TRUE}). Optionally, all slots in the object can also be validated.
|
20 |
\code{TRUE}, the errors are returned as a character vector rather
|
| - |
|
21 |
than generating an error.
|
| - |
|
22 |
|
| - |
|
23 |
|
| - |
|
24 |
When an object from a class is initialized, the default method for
|
| - |
|
25 |
\code{\link{initialize}()} calls \code{validObject}.
|
| 17 |
|
26 |
|
| 18 |
The function \code{setValidity} sets the validity method of a class
|
27 |
A class definition may have a validity method, set by a call to
|
| 19 |
(but more normally, this method will be supplied as the
|
28 |
the function \code{setValidity}, in the package or environment that
|
| 20 |
\code{validity} argument to \code{\link{setClass}}). The method
|
29 |
defines the class (or via the \code{validity} argument to \code{\link{setClass}}). The method
|
| 21 |
should be a function of one object that returns \code{TRUE} or a
|
30 |
should be a function of one object that returns \code{TRUE} or a character-string
|
| 22 |
description of the non-validity.
|
31 |
description of the non-validity.
|
| - |
|
32 |
If such a method exists, it will be called from \code{validObject}
|
| - |
|
33 |
and any strings from failure will be included in the result or the
|
| - |
|
34 |
error message.
|
| - |
|
35 |
Any validity methods defined for superclasses (from the \code{contains=}
|
| - |
|
36 |
argument to \code{\link{setClass}}, will also be called.
|
| - |
|
37 |
|
| - |
|
38 |
|
| 23 |
}
|
39 |
}
|
| 24 |
\usage{
|
40 |
\usage{
|
| 25 |
validObject(object, test = FALSE, complete = FALSE)
|
41 |
validObject(object, test = FALSE, complete = FALSE)
|
| 26 |
|
42 |
|
| 27 |
setValidity(Class, method, where = topenv(parent.frame()) )
|
43 |
setValidity(Class, method, where = topenv(parent.frame()) )
|
| Line 33... |
Line 49... |
| 33 |
object's class has a formal definition.}
|
49 |
object's class has a formal definition.}
|
| 34 |
\item{test}{logical; if \code{TRUE} and validity fails, the
|
50 |
\item{test}{logical; if \code{TRUE} and validity fails, the
|
| 35 |
function returns a vector of strings describing the problems. If
|
51 |
function returns a vector of strings describing the problems. If
|
| 36 |
\code{test} is \code{FALSE} (the default) validity failure generates
|
52 |
\code{test} is \code{FALSE} (the default) validity failure generates
|
| 37 |
an error.}
|
53 |
an error.}
|
| 38 |
\item{complete}{logical; if \code{TRUE}, validity methods will be
|
54 |
\item{complete}{logical; if \code{TRUE}, \code{validObject} is
|
| 39 |
applied recursively to any of the slots that have such methods.}
|
55 |
called recursively for each of the slots. The default is \code{FALSE}.}
|
| 40 |
\item{Class}{the name or class definition of the class whose validity
|
56 |
\item{Class}{the name or class definition of the class whose validity
|
| 41 |
method is to be set.}
|
57 |
method is to be set.}
|
| 42 |
\item{ClassDef}{a class definition object, as from
|
58 |
\item{ClassDef}{a class definition object, as from
|
| 43 |
\code{\link{getClassDef}}.}
|
59 |
\code{\link{getClassDef}}.}
|
| 44 |
\item{method}{a validity method; that is, either \code{NULL} or a
|
60 |
\item{method}{a validity method; that is, either \code{NULL} or a
|
| Line 46... |
Line 62... |
| 46 |
\code{validObject}, the function should return \code{TRUE} if the
|
62 |
\code{validObject}, the function should return \code{TRUE} if the
|
| 47 |
object is valid, and one or more descriptive strings if any problems
|
63 |
object is valid, and one or more descriptive strings if any problems
|
| 48 |
are found. Unlike \code{validObject}, it should never generate an
|
64 |
are found. Unlike \code{validObject}, it should never generate an
|
| 49 |
error.
|
65 |
error.
|
| 50 |
}
|
66 |
}
|
| - |
|
67 |
\item{where}{an environment to store the modified class
|
| - |
|
68 |
definition. Should be omitted, specifically for calls from a package that defines the class.
|
| 51 |
\item{where}{the modified class definition will be stored in this
|
69 |
The definition will be stored in the
|
| - |
|
70 |
namespace of the package.}
|
| - |
|
71 |
|
| - |
|
72 |
}
|
| - |
|
73 |
\section{Validity methods}{
|
| - |
|
74 |
A validity method must be a function of one argument; formally, that
|
| - |
|
75 |
argument should be named \code{object}.
|
| - |
|
76 |
If the argument has a different name, \code{setValidity} makes the
|
| - |
|
77 |
substitution but in obscure cases that might fail, so it's wiser to
|
| - |
|
78 |
name the
|
| - |
|
79 |
argument \code{object}.
|
| - |
|
80 |
|
| - |
|
81 |
A good method checks all the possible errors and returns a character
|
| - |
|
82 |
vector citing all the exceptions found, rather than returning after
|
| 52 |
environment.}
|
83 |
the first one.
|
| - |
|
84 |
\code{validObject} will accumulate these errors in its error message
|
| - |
|
85 |
or its return value.
|
| 53 |
|
86 |
|
| 54 |
Note that validity methods do not have to check validity of
|
87 |
Note that validity methods do not have to check validity of
|
| 55 |
superclasses: the logic of \code{validObject} ensures these tests are
|
88 |
superclasses: \code{validObject} calls such methods explicitly.
|
| 56 |
done once only. As a consequence, if one validity method wants to use
|
- |
|
| 57 |
another, it should extract and call the method from the other
|
- |
|
| 58 |
definition of the other class by calling \code{getValidity()}: it
|
- |
|
| 59 |
should \emph{not} call \code{validObject}.
|
- |
|
| 60 |
}
|
89 |
}
|
| 61 |
\details{
|
90 |
\details{
|
| 62 |
Validity testing takes place \sQuote{bottom up}: Optionally, if
|
91 |
Validity testing takes place \sQuote{bottom up}, checking the slots,
|
| - |
|
92 |
then the superclasses, then the object's own validity method, if
|
| - |
|
93 |
there is one.
|
| - |
|
94 |
|
| - |
|
95 |
For each slot and superclass, the existence of the specified class is
|
| - |
|
96 |
checked.
|
| - |
|
97 |
For each slot, the object in the slot is tested for inheritance from
|
| - |
|
98 |
the corresponding class.
|
| 63 |
\code{complete=TRUE}, the validity of the object's slots, if any, is
|
99 |
If \code{complete} is {TRUE}, \code{validObject} is called
|
| - |
|
100 |
recursively for the object in the slot.
|
| - |
|
101 |
|
| 64 |
tested. Then, in all cases, for each of the classes that this class
|
102 |
Then, for each of the classes that this class
|
| 65 |
extends (the \sQuote{superclasses}), the explicit validity method of
|
103 |
extends (the \sQuote{superclasses}), the explicit validity method of
|
| 66 |
that class is called, if one exists. Finally, the validity method of
|
104 |
that class is called, if one exists. Finally, the validity method of
|
| 67 |
\code{object}'s class is called, if there is one.
|
105 |
\code{object}'s class is called, if there is one.
|
| 68 |
|
106 |
|
| 69 |
Testing generally stops at the first stage of finding an error, except
|
- |
|
| 70 |
that all the slots will be examined even if a slot has failed its
|
- |
|
| 71 |
validity test.
|
- |
|
| 72 |
|
- |
|
| 73 |
The standard validity test (with \code{complete=FALSE}) is applied
|
- |
|
| 74 |
when an object is created via \code{\link{new}} with any optional
|
- |
|
| 75 |
arguments (without the extra arguments the result is just the class
|
- |
|
| 76 |
prototype object).
|
- |
|
| 77 |
|
- |
|
| 78 |
An attempt is made to fix up the definition of a validity method if
|
- |
|
| 79 |
its argument is not \code{object}.
|
- |
|
| 80 |
}
|
107 |
}
|
| 81 |
\value{
|
108 |
\value{
|
| 82 |
\code{validObject} returns \code{TRUE} if the object is valid.
|
109 |
\code{validObject} returns \code{TRUE} if the object is valid.
|
| 83 |
Otherwise a vector of strings describing problems found, except that
|
110 |
Otherwise a vector of strings describing problems found, except that
|
| 84 |
if \code{test} is \code{FALSE}, validity failure generates an error,
|
111 |
if \code{test} is \code{FALSE}, validity failure generates an error,
|
| 85 |
with the corresponding strings in the error message.
|
112 |
with the corresponding strings in the error message.
|
| 86 |
}
|
113 |
}
|
| 87 |
\references{
|
114 |
\references{
|
| 88 |
Chambers, John M. (2008)
|
115 |
Chambers, John M. (2016)
|
| 89 |
\emph{Software for Data Analysis: Programming with R}
|
116 |
\emph{Extending R},
|
| 90 |
Springer. (For the R version.)
|
117 |
Chapman & Hall.
|
| 91 |
|
- |
|
| 92 |
Chambers, John M. (1998)
|
118 |
(Chapters 9 and 10.)
|
| 93 |
\emph{Programming with Data}
|
- |
|
| 94 |
Springer (For the original S4 version.)
|
- |
|
| 95 |
}
|
119 |
}
|
| 96 |
\seealso{\code{\link{setClass}};
|
120 |
\seealso{\code{\link{setClass}};
|
| 97 |
class \code{\linkS4class{classRepresentation}}.
|
121 |
class \code{\linkS4class{classRepresentation}}.
|
| 98 |
}
|
122 |
}
|
| 99 |
\examples{
|
123 |
\examples{
|
The R Project SVN
R