findClass              package:methods              R Documentation

Computations with Classes

Description:

     Functions to find and manipulate class definitions.

Usage:

     removeClass(Class, where)

     isClass(Class, formal=TRUE, where)

     getClasses(where, inherits = missing(where))

     findClass(Class, where, unique = "")

     resetClass(Class, classDef, where)

     sealClass(Class, where)

Arguments:

   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 'packageSlot' of the character string.

   where: The environment in which to modify or remove the definition. 
          Defaults to the top-level environment of the calling function
          (the global environment for ordinary computations, but the
          environment or name space of a package in the source for a
          package).

          When searching for class definitions, 'where' defines where
          to do the search, and the default is to search from the
          top-level environment or name space of the caller to this
          function. 

  unique: if 'findClass' expects a unique location for the class,
          '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. 

inherits: in a call to 'getClasses', should the value returned include
          all parent environments of 'where', or that environment only?
           Defaults to 'TRUE' if 'where' is omitted, and to 'FALSE'
          otherwise. 

  formal: Should a formal definition be required? 

classDef: For 'removeClass', the optional class definition (but usually
          it's better for 'Class' to be the class definition, and to
          omit 'classDef'). 

Details:

     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.


     'removeClass': Remove the definition of this class, from the
          environment 'where' if this argument is supplied; if not,
          'removeClass' will search for a definition, starting in the
          top-level environment of the call to 'removeClass', and
          remove the (first) definition found.

     'isClass': Is this the name of a formally defined class? (Argument
          'formal' is for compatibility and is ignored.)

     'getClasses': The names of all the classes formally defined on
          '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 'inherits' argument can be used to search a particular
          environment and all its parents, but usually the default
          setting is what you want.

     'findClass': The list of environments or positions on the search
          list in which a class definition of 'Class' is found.  If
          'where' is supplied, this is an environment (or name space)
          from which the search takes place; otherwise the top-level
          environment of the caller is used.  If 'unique' is supplied
          as a character string, 'findClass' returns a single
          environment or position.  By default, it always returns a
          list. The calling function should select, say, the first
          element as a position or environment for functions such as
          'get'.

          If 'unique' is supplied as a character string, '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.

     'resetClass': Reset the internal definition of a class.  Causes
          the complete definition of the class to be re-computed, from
          the representation and superclasses specified in the original
          call to '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).

     'sealClass': Seal the current definition of the specified class,
          to prevent further changes.  It is possible to seal a class
          in the call to 'setClass', but sometimes further changes have
          to be made (e.g., by calls to 'setIs').  If so, call
          'sealClass' after all the relevant changes have been made.


References:

     Chambers, John M. (2008) _Software for Data Analysis: Programming
     with R_ Springer.  (For the R version.)

     Chambers, John M. (1998) _Programming with Data_ Springer (For the
     original S4 version.)

See Also:

     'setClassUnion', 'Methods', 'makeClassRepresentation'

