RClassUtils             package:methods             R Documentation

_U_t_i_l_i_t_i_e_s _f_o_r _M_a_n_a_g_i_n_g _C_l_a_s_s _D_e_f_i_n_i_t_i_o_n_s

_D_e_s_c_r_i_p_t_i_o_n:

     These are various functions to support the definition and use of
     formal classes.  Most of them are rarely suitable to be called
     directly.

_U_s_a_g_e:

     testVirtual(properties, extends, prototype)

     makePrototypeFromClassDef(properties, prototype, extends)

     newEmptyObject()

     completeClassDefinition(Class, ClassDef)

     getProperties(ClassDef)

     getSlots(x, complete = TRUE)

     getExtends(ClassDef)

     getAccess(ClassDef)

     getAllSuperClasses(ClassDef)

     superClassDepth(ClassDef, soFar)

     getPrototype(ClassDef)

     getVirtual(ClassDef)

     isVirtualClass(Class)

     getSubclasses(ClassDef)

     getClassName(ClassDef)

     assignClassDef(Class, def, where=.GlobalEnv)

     newBasic(Class, ...)

     makeExtends(Class, to, coerce, test, replace, by, package, slots,
                      classDef1, classDef2)

     reconcilePropertiesAndPrototype(name, properties, prototype, superClasses)

     tryNew(Class)

     trySilent(expr)

     empty.dump()

     showClass(Class, complete=TRUE, propertiesAreCalled="Properties")

     showExtends(ext, printTo = stdout())

     getFromClassMetaData(name)

     assignToClassMetaData(name, value)

     removeFromClassMetaData(name)

     possibleExtends(class1, class2)

     completeExtends(ClassDef)

     classMetaName(name)

     methodsPackageMetaName(prefix, name)

     metaNameUndo(strings, prefix = "M", searchForm = FALSE)

     requireMethods(functions, signature, message)

     checkSlotAssignment(obj, name, value)

     defaultPrototype()

     isClassDef(object)

     validSlotNames(names)

     getDataPart(object)
     setDataPart(object, value)

_S_u_m_m_a_r_y _o_f _F_u_n_c_t_i_o_n_s:

     `_t_e_s_t_V_i_r_t_u_a_l': 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 "VIRTUAL".  

          Otherwise, a class is virtual only if it has no slots,
          extends no non-virtual classes, and has a `NULL' Prototype.


     `_m_a_k_e_P_r_o_t_o_t_y_p_e_F_r_o_m_C_l_a_s_s_D_e_f': 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, if there is one, is used
          instead (but it must be coercible to the class of the slot).

          If there are no slots but a non-null prototype was specified,
          this is returned.

          If there is a single non-virtual superclass (a class in the
          extends list), then its prototype is used.

          If all three of the above fail, the prototype is `NULL'.


     `_n_e_w_E_m_p_t_y_O_b_j_e_c_t': Utility function to create an empty object into
          which slots can be set.

          Currently just creates an empty list with class `"NULL"'.

          Later version should create a special object reference that
          marks an object currently with no slots and no data.


     `_c_o_m_p_l_e_t_e_C_l_a_s_s_D_e_f_i_n_i_t_i_o_n': Completes the definition of `Class',
          relative to the current session.

          The completed definition is stored in the session's class
          metadata, to be retrieved the next time that getClass is
          called on this class, and is returned as the value of the
          call.

          If `ClassDef' is omitted, the initial definition is obtained
          from the first package having a meta-object for this class.


     `_g_e_t_F_r_o_m_C_l_a_s_s_D_e_f': Extracts one of the intrinsically defined class
          definition properties (".Properties", etc.)  Strictly a
          utility function.


     `_g_e_t_P_r_o_p_e_r_t_i_e_s': Extracts the class's Properties information from
          the class representation (only, not from the name of the
          class).


     `_g_e_t_S_l_o_t_s': Returns a named character vector.  The names are the
          names of the slots, the values are the classes of the
          corresponding slots.  If `complete' is `TRUE', all slots from
          all superclasses will be included.  The argument `x' can
          either be the name of a class or an object having that class.


     `_g_e_t_E_x_t_e_n_d_s': Extracts the class's Extends information from the
          class representation (only, not from the name of the class)

          Contrast with the `possibleExtends' and `is' functions, both
          of which use indirect information as well.


     `_g_e_t_A_l_l_S_u_p_e_r_C_l_a_s_s_e_s', `_s_u_p_e_r_C_l_a_s_s_D_e_p_t_h': Get the names of all the
          classes that this class definition extends.

          `getAllSuperClasses' is 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
          `label' and `depth', the latter for the number of generations
          back each class is in the inheritance tree.  The argument
          `soFar' is used to avoid loops in the network of class
          relationships.


     `_g_e_t_P_r_o_t_o_t_y_p_e': extract the class's Prototype information from the
          class representation (only, not from the name of the class)


     `_g_e_t_A_c_c_e_s_s': extract the class's Access information from the class
          representation (only, not from the name of the class)


     `_g_e_t_V_i_r_t_u_a_l': extract the class's Virtual information from the
          class representation (only, not from the name of the class)


     `_i_s_V_i_r_t_u_a_l_C_l_a_s_s': 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.


     `_g_e_t_S_u_b_c_l_a_s_s_e_s': extract the class's Subclasses information from
          the class representation (only, not from the name of the
          class)


     `_g_e_t_C_l_a_s_s_N_a_m_e': The internal property in the class definition for
          the class name.


     `_a_s_s_i_g_n_C_l_a_s_s_D_e_f': assign the definition of the class to the
          specially named object


     `_n_e_w_B_a_s_i_c': the implementation of the function `new' for basic
          classes that don't have a formal definition.  

          Any of these could have a formal definition, except for
          `Class="NULL"' (disallowed because `NULL' can't have
          attributes).  For all cases except `"NULL"', the class of the
          result will be set to `Class'.

          See `new' for the interpretation of the arguments.


     `_m_a_k_e_E_x_t_e_n_d_s': convert the argument to a list defining the
          extension mechanism.


     `_r_e_c_o_n_c_i_l_e_P_r_o_p_e_r_t_i_e_s_A_n_d_P_r_o_t_o_t_y_p_e': 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, `classi' of the slot if that succeeds, and
          `NULL' otherwise.

          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).


     `_t_r_y_N_e_w': 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 `NULL'. 

          This is inefficient and also not a good idea when actually
          generating objects, but is useful in the initial definition
          of classes.


     `_s_h_o_w_C_l_a_s_s': Print the information about a class definition.  

          If `complete' is `TRUE', include the indirect information
          about extensions.


     `_s_h_o_w_E_x_t_e_n_d_s': Print the elements of the list of extensions.  

          (Used also by `promptClass' to get the list of what and how
          for the extensions.)


     `_p_o_s_s_i_b_l_e_E_x_t_e_n_d_s': Find the information that says whether class1
          extends class2, directly or indirectly.

          This can be either a logical value or an object of class
          `SClassExtension-class' containing various functions to test
          and/or coerce the relationship.


     `_c_o_m_p_l_e_t_e_E_x_t_e_n_d_s': complete the extends information in the class
          definition, by following transitive chains.

          Elements in the immediate extends list may be added and
          current elements may be replaced, either by replacing a
          conditional relation with an unconditional one, or by adding
          indirect relations.


     `_c_l_a_s_s_M_e_t_a_N_a_m_e': a name for the object storing this class's
          definition


     `_m_e_t_h_o_d_s_P_a_c_k_a_g_e_M_e_t_a_N_a_m_e': a name mangling device to hide metadata
          defining method and class information.

     _m_e_t_a_N_a_m_e_U_n_d_o As its name implies, this function undoes the
          name-mangling used to produce meta-data object names, and
          returns a object of class `ObjectsWithPackage-class'.


     `_r_e_q_u_i_r_e_M_e_t_h_o_d_s': Require a subclass to implement methods for the
          generic functions, for this signature.

          For each generic, `setMethod' will be called to define a
          method that throws an error, with the supplied message.

          The `requireMethods' function 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.


     `_c_h_e_c_k_S_l_o_t_A_s_s_i_g_n_m_e_n_t': 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 accesor
          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 `checkSlotAssignment'.


     `_d_e_f_a_u_l_t_P_r_o_t_o_t_y_p_e': The prototype for a class which will have
          slots, is not a virtual  class, and does not extend one of
          the basic classes.  In future releases, this will likely be a
          non-vector R object type, but none of the current types (as
          of release 1.4) is suitable.


     `_S_e_s_s_i_o_n_C_l_a_s_s_M_e_t_a_D_a_t_a': Contains the name of the special table in
          which class information is cached during the session.


     `._I_n_i_t_B_a_s_i_c_C_l_a_s_s_e_s', `._I_n_i_t_M_e_t_h_o_d_s_L_i_s_t_C_l_a_s_s', `._s_e_t_C_o_e_r_c_e_G_e_n_e_r_i_c': These
          functions perform part of the initialization of classes and
          methods, and are called (only!) from `.First.lib'.


     `_i_s_C_l_a_s_s_D_e_f': Is `object' a representation of a class?


     `_v_a_l_i_d_S_l_o_t_N_a_m_e_s': Returns `names' unless one of the names is
          reserved, in which case there is an error.  (As of writing,
          `"class"' is the only reserved slot name.)

     `_g_e_t_D_a_t_a_P_a_r_t', `_s_e_t_D_a_t_a_P_a_r_t': Utilities called from the base C
          code to implement `object@.Data'.


