Re: [R] Building packages in R - 'private' functions
On Wed, 2006-06-07 at 01:14 -0400, Dan Rabosky wrote:
Hello.
I am creating an R package that I'd like to submit to CRAN (OS Windows
XP). How do I distinguish among 'public' functions, e.g., those that are
intended to be called by users of the package and for which I am providing
documentation examples, and 'private' functions, which are used
internally by the 'public' functions, but for which I do not wish to
provide documentation? The private functions are all coded in R (nothing
in C or Fortran) and are essential to the operation of several public
functions.
Hi Dan,
The answer is in the Writing R Extensions manual.
You could do either:
1) Put the code for your private functions in a file names
internal.R. You then provide a simple file named
package-name-internal.Rd which lists in individual \alias{}
markup the names of the private functions, eg;
\name{mypackage-internal}
\alias{foo1}
\alias{foo2}
\alias{foo3}
\alias{foo4}
\title{Internal mypackage Functions}
\description{
Internal mypackage functions
}
\details{
These are not to be called by the user.
}
\keyword{ internal }
But even here, you aren't documenting the internal functions,
just working round the package checks.
2) Place your package in a namespace, which is documented fully
in Writing R Extensions.
Not sure what the best advice is - I'd guess that for all but the
simplest packages, namespaces are the preferred way, but the internal.R
way works just fine also.
By the way, in future, questions of this nature are best asked on the
R-Devel list, not here.
HTH,
Gavin
__
R-help@stat.math.ethz.ch mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide! http://www.R-project.org/posting-guide.html
Re: [R] Building packages in R - 'private' functions
Dan Rabosky wrote: Hello. I am creating an R package that I'd like to submit to CRAN (OS Windows XP). How do I distinguish among 'public' functions, e.g., those that are intended to be called by users of the package and for which I am providing documentation examples, and 'private' functions, which are used internally by the 'public' functions, but for which I do not wish to provide documentation? The private functions are all coded in R (nothing in C or Fortran) and are essential to the operation of several public functions. I have been unable to find any documentation on this in the 'writing r extensions' manual', on previous posts to R-help, or through any other source. One possibility is to include the source code for the 'private' functions within the public functions. However, since multiple public functions utilize the same core set of 'private' functions, this seems unwieldy and redundant at best. If I simply include the source for the 'private' functions in the R directory (without corresponding *.Rd and *.html documentation in /man), then check the package with R CMD check', it does appear to process the private functions (and successfully builds with R CMD build). However, I do receive a warning for including undocumented code objects. Is this the recommended approach and/or is there a better way to do this? One potential problem with this approach is that - should an error occur within a private function, it may be very difficult for the user to decipher the nature of the problem. Any suggestions will be greatly appreciated. ~Dan Rabosky Dan Rabosky Department of Ecology and Evolutionary Biology 237 Corson Hall Cornell University Ithaca, NY14853-2701 USA [EMAIL PROTECTED] web: http://www.birds.cornell.edu/evb/Graduates_Dan.htm __ R-help@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide! http://www.R-project.org/posting-guide.html it's in the 'extensions' manual, including an example I believe: 1. create a file `NAMESPACE' in the package top level dir (beside `R' and `man') containing the single line exportPattern(^[^\\.]) 2. name all private functions with a leading `.' (more precisely: all functions starting with a `.' are private in this setting). of course, you can modify the pattern to suit another naming convention. joerg __ R-help@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide! http://www.R-project.org/posting-guide.html
Re: [R] Building packages in R - 'private' functions
1. If you have time to change internal functions naming, you can rename internal functions by putting a leading '.'. Even without namespace, I have noticed there is no check for corresponding docs for such functions. 2. If you don't want to rename all internal functions, the best way is writing an 'internals.Rd' file with an alias for each internal function (documented in 'writing R extensions'). 3.Finally, you can add a NAMESPACE (see writing R extensions). However, if you use S3/S4 classes, this can be much more tedious to do. I think the no. 2 to be the fastest/safer way. Antonio. 2006/6/7, Dan Rabosky [EMAIL PROTECTED]: Hello. I am creating an R package that I'd like to submit to CRAN (OS Windows XP). How do I distinguish among 'public' functions, e.g., those that are intended to be called by users of the package and for which I am providing documentation examples, and 'private' functions, which are used internally by the 'public' functions, but for which I do not wish to provide documentation? The private functions are all coded in R (nothing in C or Fortran) and are essential to the operation of several public functions. I have been unable to find any documentation on this in the 'writing r extensions' manual', on previous posts to R-help, or through any other source. One possibility is to include the source code for the 'private' functions within the public functions. However, since multiple public functions utilize the same core set of 'private' functions, this seems unwieldy and redundant at best. If I simply include the source for the 'private' functions in the R directory (without corresponding *.Rd and *.html documentation in /man), then check the package with R CMD check', it does appear to process the private functions (and successfully builds with R CMD build). However, I do receive a warning for including undocumented code objects. Is this the recommended approach and/or is there a better way to do this? One potential problem with this approach is that - should an error occur within a private function, it may be very difficult for the user to decipher the nature of the problem. Any suggestions will be greatly appreciated. ~Dan Rabosky Dan Rabosky Department of Ecology and Evolutionary Biology 237 Corson Hall Cornell University Ithaca, NY14853-2701 USA [EMAIL PROTECTED] web: http://www.birds.cornell.edu/evb/Graduates_Dan.htm __ R-help@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide! http://www.R-project.org/posting-guide.html [[alternative HTML version deleted]] __ R-help@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide! http://www.R-project.org/posting-guide.html
Re: [R] Building packages in R - 'private' functions
Antonio, Fabio Di Narzo [EMAIL PROTECTED] writes: 1. If you have time to change internal functions naming, you can rename internal functions by putting a leading '.'. Even without namespace, I have noticed there is no check for corresponding docs for such functions. 2. If you don't want to rename all internal functions, the best way is writing an 'internals.Rd' file with an alias for each internal function (documented in 'writing R extensions'). 3.Finally, you can add a NAMESPACE (see writing R extensions). However, if you use S3/S4 classes, this can be much more tedious to do. I think the no. 2 to be the fastest/safer way. I think adding a NAMESPACE file is the best solution and I don't think that the process needs to be particularly tedious. Having a naming convention for private functions is fine and you can still do that with a NAMESPACE. Non-exported functions do not get checked for documentation, so there is no need for an internals.Rd (of course, it doesn't hurt to give yourself some documentation for when you return to the project 3 months later :-) Besides hiding your private functions, a NAMESPACE protects you from users or other packages redefining functions that you rely on. As an extreme example, if a user redefined length(), many packages without namespaces would break. + seth __ R-help@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide! http://www.R-project.org/posting-guide.html
