The R Project SVN – R – Diff – /trunk/src/library/methods/man/findClass.Rd

 % Part of the R package, https://www.R-project.org
 % Copyright 1995-2015 R Core Team
 % Distributed under GPL 2 or later
 \name{findClass}
-\title{Computations with Classes}
+\title{Find Class Definitions}
 \alias{removeClass}
 \alias{resetClass}
 \alias{isClass}
 \alias{getClasses}
 \alias{findClass}
 \alias{sealClass}
 \description{
-  Functions to find and manipulate class definitions.
+  Functions to find classes:  \code{isClass} tests for a class;
+  \code{findClass} returns the name(s) of packages containing the
+  class; \code{getClasses} returns the names of all the classes in an
+  environment, typically a namespace.  To examine the definition of a class, use \code{\link{getClass}}.
+}
 \usage{
 isClass(Class, formal=TRUE, where)
 getClasses(where, inherits = missing(where))
 findClass(Class, where, unique = "")
+## The remaining functions are retained for compatibility
+## but not generally recommended
 removeClass(Class, where)
 resetClass(Class, classDef, where)
 sealClass(Class, where)
 \arguments{
   \item{Class}{character string name for the class.  The functions will
     usually take a class definition instead of the string.  To restrict
     the class to those defined in a particular package, set the
     \code{\link{packageSlot}} of the character string.}
-  \item{where}{the \code{\link{environment}} in which to modify or
+  \item{where}{the \code{\link{environment}} in which to search for
-    remove the definition.  Defaults to the top-level environment of the
+    the class definition.  Defaults to the top-level environment of the
-    calling function (the global environment for ordinary computations,
+    calling function.  When called from the command line, this has the
-    but the environment or namespace of a package in the source for a
+    effect of using all the package environments in the search list.
-    package).
-    When searching for class definitions, \code{where} defines where to
+    To restrict the search to classes in a particular package, use \code{where =
-    do the search, and the default is to search from the top-level
+      asNamespace(pkg)} with \code{pkg} the package name;  to restrict
+    it to
+    the \emph{exported} classes, use \code{where = "package:pkg"} after the
-    environment or namespace of the caller to this function.
+    package is attached to the search list.
+  }
-  \item{formal}{\code{\link{logical}} indicating if a formal definition
+  \item{formal}{\code{\link{logical}} is a formal definition
-    is required.}
+    required? For S compatibility, and always treated as \code{TRUE}.}
   \item{unique}{if \code{findClass} expects a unique location for the
     class, \code{unique} is a character string explaining the purpose
     of the search (and is used in warning and error messages).  By
     default, multiple locations are possible and the function always
     returns a list.
     returned include all parent environments of \code{where}, or that
     environment only?  Defaults to \code{TRUE} if \code{where} is
     omitted, and to \code{FALSE} otherwise.
+  }
   \item{classDef}{ For \code{resetClass}, the optional class
-    definition (but usually it's better for \code{Class} to be the
-    class definition, and to omit \code{classDef}).
+    definition.
+  }
+}
-\details{
+\section{Functions}{
-  These are the functions that test and manipulate formal class
-  definitions.  Brief documentation is provided below.  See the
-  references for an introduction and for more details.
   \describe{
-    \item{\code{removeClass}:}{
-      Remove the definition of this class, from the environment
-      \code{where} if this argument is supplied; if not,
-      \code{removeClass} will search for a definition, starting in the
-      top-level environment of the call to \code{removeClass}, and
-      remove the (first) definition found.
-    }
     \item{\code{isClass}:}{
-      Is this the name of a formally defined class? (Argument
+      Is this the name of a formally defined class?
-      \code{formal} is for compatibility and is ignored.)
+    }
     \item{\code{getClasses}:}{
       The names of all the classes formally defined on \code{where}.  If
       called with no argument, all the classes visible from the
       calling function (if called from the top-level, all the classes
       in any of the environments on the search list).  The
-      \code{inherits} argument can be used to search a particular
+      \code{where} argument is used to search only in a particular package.
-      environment and all its parents, but usually the default setting
-      is what you want.
+    }
     \item{\code{findClass}:}{
-      The list of environments or positions on the search list in
+      The list of environments in
       which a class definition of \code{Class} is found.  If
-      \code{where} is supplied, this is an environment (or namespace)
+      \code{where} is supplied, a list is still returned, either empty
-      from which the search takes place; otherwise the top-level
+      or containing the environment corresponding to \code{where}.
-      environment of the caller is used.  If \code{unique} is supplied
+      By default when called from the \R session, the global
-      as a character string, \code{findClass} returns a single
-      environment or position.  By default, it always returns a list.
+      environment and all the currently
-      The calling function should select, say, the first element as a
+      attached packages are searched.
-      position or environment for functions such as \code{\link{get}}.
       If \code{unique} is supplied as a character string,
       \code{findClass} will warn if there is more than one definition
       visible (using the string to identify the purpose of the call),
       and will generate an error if no definition can be found.
+      \emph{The remaining functions are retained for
+        back-compatibility and internal use, but not generally recommended.}
+    }
+    \item{\code{removeClass}:}{
+      Remove the definition of this class.  This can't be used if the
+      class is in another package, and would rarely be needed in
+      source code defining classes in a package.
+    }
     \item{\code{resetClass}:}{
-      Reset the internal definition of a class.  Causes the complete
+      Reset the internal definition of a class.  Not legitimate for a
-      definition of the class to be re-computed, from the
+      class definition not in this package and rarely needed otherwise.
-      representation and superclasses specified in the original
-      call to \code{setClass}.
-      This function is called when aspects of the class definition are
-      changed.  You would need to call it explicitly if you changed the
-      definition of a class that this class extends (but doing that in
-      the  middle of a session is living dangerously, since it may
-      invalidate existing objects).
+    }
     \item{\code{sealClass}:}{ Seal the current definition of the specified
-      class, to prevent further changes.  It is possible to seal a class
+      class, to prevent further changes, by setting the corresponding
-      in the call to \code{setClass}, but sometimes further changes have
+      slot in the class definition.  This is rarely used, since
-      to be made (e.g., by calls to \code{setIs}).  If so, call
-      \code{sealClass} after all the relevant changes have been made.
+      classes in loaded packages are sealed by locking their namespace.
+    }
+  }
+}
 \references{
+ Chambers, John M. (2016)
+ \emph{Extending R},
+  Chapman & Hall.
+(Chapters 9 and 10.)
  Chambers, John M. (2008)
  \emph{Software for Data Analysis: Programming with R}
-  Springer.  (For the R version.)
- Chambers, John M. (1998)
- \emph{Programming with Data}
- Springer (For the original S4 version.)
+  Springer. (Chapter 9 has some details not in the later reference.)
+}
 \seealso{
-  \code{\link{setClassUnion}},
+  \code{\link{getClass}},
+  \code{\link{Classes_Details}},
-  \code{\link{Methods}},
+  \code{\link{Methods_Details}},
   \code{\link{makeClassRepresentation}}
+}
 %% should add Examples section
 \keyword{programming}
 \keyword{classes}

The R Project SVN R

(root)/trunk/src/library/methods/man/findClass.Rd – Rev 70554 → 71366