Rename classModule to exposeClass; recommend it from setRcppClass.Rd

Author: johnmchambers

ChangeLog

@@ -1,3 +1,12 @@
+2013-10-06  John M Chambers  <jmc@r-project.org>
+
+	* NAMESPACE: change classModule to expose Class
+	* R/classModule.R: delete
+	* man/classModule.Rd: delete
+	* R/exposeClass.R: add
+	* man/exposeClass.Rd: add
+	* man/setRcppClass.Rd: update, clarify, recommend exposeClass()
+
 2013-10-03  John M Chambers  <jmc@r-project.org>
 
 	* R/classModule.R: new function to write module file for class

NAMESPACE

@@ -20,8 +20,8 @@ export(Module,
        setRcppClass,
        loadRcppClass,
        loadModule,
-       classModule,
        cppFunction,
+       exposeClass,
        evalCpp,
        sourceCpp,
        compileAttributes,

R/classModule.R R/exposeClass.RR/classModule.R renamed to R/exposeClass.R

@@ -53,7 +53,7 @@
     paste0(ns, "::",mName)
 }
 
-classModule <- function(class, constructors, fields, methods,
+exposeClass <- function(class, constructors, fields, methods,
                         file = paste0(CppClass, "Module.cpp"),
                         header = character(),
                         module = paste0("class_",class), CppClass = class,

man/classModule.Rd man/exposeClass.Rdman/classModule.Rd renamed to man/exposeClass.Rd

@@ -1,13 +1,13 @@
-\name{classModule}
-\alias{classModule}
+\name{exposeClass}
+\alias{exposeClass}
 \title{
 Create an Rcpp Module to Expose a C++ Class in R
 }
 \description{
 The arguments specify a C++ class and some combination of
 constructors, fields and methods to be shared with \R by creating a
 corresponding reference class in \R.
-The information needed in the call to \code{classModule()} is the
+The information needed in the call to \code{exposeClass()} is the
 simplest possible in order to create a C++ module for the class; for
 example, fields and methods in this class need only be identified by
 their name.
@@ -20,7 +20,7 @@ class.
 }
 
 \usage{
-classModule(class, constructors = , fields = , methods = , file = ,
+exposeClass(class, constructors = , fields = , methods = , file = ,
     header = , module = , CppClass = class, readOnly = , rename = ,
     Rfile = TRUE)
 }
@@ -97,16 +97,16 @@ information in the C++ class supplied.  This file is intended to be
 part of the C++ source for an \R package.  The file only needs to
 modified when the information changes, either because the class has
 changed or because you want to expose different information to \R.  In
-that case you can either recall \code{classModule()} or edit the C++
+that case you can either recall \code{exposeClass()} or edit the C++
 file created.
 
 The Rcpp Module mechanism has a number of other optional techniques,
-not covered by \code{classModule()}.  These should be entered into the
+not covered by \code{exposeClass()}.  These should be entered into the
 C++ file created.  See the \dQuote{rcpp-modules} vignette with the
 package for current possibilities.
 
 For fields and methods specified directly in the C++ class,
-the fields and method arguments to \code{classModule()} are character vectors naming the
+the fields and method arguments to \code{exposeClass()} are character vectors naming the
 corresponding members of the class.  For module construction, the
 data types of directly specified fields and of the arguments for the methods are not
 needed.
@@ -128,7 +128,7 @@ An indirect mechanism is used, generating free functions in C++ to
 expose the inherited members in \R.
 
 This mechanism requires data type information in the call to
-\code{classModule()}.
+\code{exposeClass()}.
 This is provided by naming the corresponding element of the
 \code{fields} or \code{methods} argument with the name of the member.
 The actual element of the \code{fields} argument is then the single
@@ -158,7 +158,7 @@ in the package.
 \examples{
 \dontrun{
 ### Given the following C++ class, defined in file PopBD.h,
-### the call to classModule() shown below will write a file
+### the call to exposeClass() shown below will write a file
 ### src/PopBDModule.cpp containing a corresponding module definition.
 ###   class PopBD {
 ###     public:
@@ -178,7 +178,7 @@ in the package.
 ### The call below exposes the lineage and size fields, read-only,
 ### and the evolve() method.
 
-classModule("PopBD",
+exposeClass("PopBD",
       constructors =
         list("", c("NumericVector", "NumericVector")),
       fields = c("lineage", "size"),
@@ -191,7 +191,7 @@ classModule("PopBD",
 ### constructors as the previous class.
 ### To expose the table() method, and the inherited evolve() method and size field:
 
-classModule("PopCount",
+exposeClass("PopCount",
       constructors =
         list("", c("NumericVector", "NumericVector")),
       fields = c(size = "std::vector<long>"),

man/setRcppClass.Rd

@@ -6,11 +6,13 @@
 Create a Class Extending a C++ Class
 }
 \description{
-A class is defined that includes the fields and methods of a C++ class
-defined, usually in this package.  For most applications, it is
-recommended to call
-\code{\link{classModule}()} to write files in the package with a call to \code{setRcppClass()} and the
-C++ module code required.  See Details.
+These routines create a class definition in \R for an exposed C++
+class, setting up and executing a load action to incorporate the C++
+pointer information.
+Neither function should normally need to be called directly; for most applications,
+a call to
+\code{\link{exposeClass}()} will create both C++ and \R code files to
+expose the C++ class.
 }
 \usage{
 setRcppClass(Class, CppClass = , module = , fields = list(), contains = ,
@@ -33,12 +35,14 @@ The Rcpp module in which the class is defined.  The module does not
 have to be loaded separately; \code{setRcppClass()} will arrange to
 load the module. By default, \code{"class_"} followed by the C++ class
 name.
+
+If \code{\link{exposeClass}()} has been called, the necessary module
+code will have been written in the \code{src} directory of the package.
 }
   \item{fields, contains, methods}{
 Additional fields, superclasses and method definitions in \R{} that
 extend the C++ class.  These arguments are passed on to
 \code{\link{setRefClass}()}.
-See Details for recommendations.
 }
   \item{saveAs}{
 Save a generator object for the class in the package's namespace under
@@ -67,21 +71,12 @@ Arguments, if any, to pass on to \code{\link{setRefClass}()}.
 }
 \details{
 The call to these functions normally appears in the source code for a
-package.
-It generates a load action that loads the specified module and
-extracts the C++ class definition specified.
+package; in particular, a call is written in an \R source file when
+\code{\link{exposeClass}()} is called.
 
-\R{} code can define new fields and methods for the class, typically
-as prototypes for possible future C++ implementation.
+\R{} code for this class or (preferably) a subclass can define new fields and methods for the class.
 Methods for the \R{} class can refer to methods and fields defined in
-C++ for the C++ class.
-These will be mapped into the C++ equivalents by \R{} code generated
-by \code{setRcppClass}.
-The C++ code may not deal as well as \R{} with incompatible
-argument types and lengths.
-Segmentation faults are a definite possibility.
-If that's a problem, you should define methods in \R{} that check for
-legal data types and values.
+C++ for the C++ class, if those have been exposed.
 
 The fields  and methods defined can
 include overriding C++ fields or methods.
@@ -93,7 +88,14 @@ Otherwise, the C++ code will continue to use the old C++ definition.
 
 }
 \value{
-A generator for the new class.
+At load time, a generator for the new class is created and stored
+according to the \code{saveAs} argument, typically under the name of
+the class.
+
+The value returned at installation time is a dummy.  Future revisions
+of the function may allow us to return a valid generator at install
+time.  We recommend using the standard style of assigning the value
+to the name of the class, as one would do with \code{\link{setRefClass}}.
 }
 \author{
 John Chambers