Re: [R] NAMESPACE vs internal.Rd
G'day Christophe, On Wed, 16 Jul 2008 18:22:49 +0200 [EMAIL PROTECTED] wrote: Thanks for your answer. My pleasure. I guess writing a regular expression that says export everything that does not start with a dot but do not export foo and bar would be not trivial to write (at least not for me). The NAMESPACE created by package.skeleton contain a single line : exportPattern(^[[:alpha:]]+) I guess that it is what you just say... Not really. :) The regular expression ^[[:alpha:]]+ matches, as far as I know, all objects that have one or more alphabetic character at the beginning. The Writing R Extensions manual suggests the directive exportPattern(^[^\\.]) exports all variables that do not start with a period. As far as I can tell, both these instructions have more or less the same effect (assuming that there are no objects with non-standard names in your package; and I am not enough of an R language lawyer to know what would happen in such a case). I was commenting on your classification as: - some fonction will be accessible (regular function) - some function will be hidden (function starting with .) - some function will be forbiden (function not in namespace) Say, you have accessible functions called fubar, rabuf, main and something.incredible.useful, some hidden functions whose name start with a . and forbidden functions (i.e. not exported) with names foo and bar. (Though, as I commented earlier, it is practically impossible to implement forbidden functions, users can always access them if they want using :::.) Both of the directives above would export fubar, rabuf, main, something.incredible.useful, foo and bar. So my challenge was to come up with a regular expression for exportPattern that says export everything that does not start with a dot but do not export foo and bar, i.e. a regular expression that would only export the accessible functions. HTC. Cheers, Berwin __ R-help@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide http://www.R-project.org/posting-guide.html and provide commented, minimal, self-contained, reproducible code.
[R] NAMESPACE vs internal.Rd
Hi the list, When we use package.skeleton, it create some file in the man directorie. - If we use package.skeleton with namespace=FALSE, it create a file toto-internal.Rd - If we use package.skeleton with namespace=TRUE, it does not create the file toto-internal.Rd Why is that ? Christophe __ R-help@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide http://www.R-project.org/posting-guide.html and provide commented, minimal, self-contained, reproducible code.
Re: [R] NAMESPACE vs internal.Rd
G'day Christophe, On Wed, 16 Jul 2008 15:10:05 +0200 [EMAIL PROTECTED] wrote: Hi the list, When we use package.skeleton, it create some file in the man directorie. - If we use package.skeleton with namespace=FALSE, it create a file toto-internal.Rd - If we use package.skeleton with namespace=TRUE, it does not create the file toto-internal.Rd Why is that ? My understanding from my reading of Writing R Extension is : 1) All functions/objects of a package that a user can call/see have to be documented in order for the package passing R CMD check without warnings/errors. 2) Users can see all functions/objects in packages without a namespace, hence everything has to be documented. For functions that you do not want users to call directly, since they are help functions for the main functions of your package, you can just create entries in internal.Rd (or toto-internal.Rd) without writing a complete help page for these functions. R CMD check will accept this as documentation. 3) In packages with a namespace, you decide which function/objects the user can see by exporting them. Everything not exported is supposed to be internal to the package and should not be accessed directly by users (though they can via :::). Functions/objects that are not exported do not need to be documented, hence no need for the toto-internal.Rd stub. HTH (and HTIC). Cheers, Berwin === Full address = Berwin A TurlachTel.: +65 6516 4416 (secr) Dept of Statistics and Applied Probability+65 6516 6650 (self) Faculty of Science FAX : +65 6872 3919 National University of Singapore 6 Science Drive 2, Blk S16, Level 7 e-mail: [EMAIL PROTECTED] Singapore 117546http://www.stat.nus.edu.sg/~statba __ R-help@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide http://www.R-project.org/posting-guide.html and provide commented, minimal, self-contained, reproducible code.
Re: [R] NAMESPACE vs internal.Rd
Thanks, Berwin, So the main idea is - With NAMESPACE, you do not document the not-for-user because they don't have to be documented - Witout NAMESPACE, you document the not-for-user with a toto-internal.Rd that say not for user That's clear. Is it stupid to consider to use both technique at the same time ? - some fonction will be accessible (regular function) - some function will be hidden (function starting with .) - some function will be forbiden (function not in namespace) I am just asking as a beginner that try to understand how pacakge works, I do not say that it is a good way to do... Christophe G'day Christophe, On Wed, 16 Jul 2008 15:10:05 +0200 [EMAIL PROTECTED] wrote: Hi the list, When we use package.skeleton, it create some file in the man directorie. - If we use package.skeleton with namespace=FALSE, it create a file toto-internal.Rd - If we use package.skeleton with namespace=TRUE, it does not create the file toto-internal.Rd Why is that ? My understanding from my reading of Writing R Extension is : 1) All functions/objects of a package that a user can call/see have to be documented in order for the package passing R CMD check without warnings/errors. 2) Users can see all functions/objects in packages without a namespace, hence everything has to be documented. For functions that you do not want users to call directly, since they are help functions for the main functions of your package, you can just create entries in internal.Rd (or toto-internal.Rd) without writing a complete help page for these functions. R CMD check will accept this as documentation. 3) In packages with a namespace, you decide which function/objects the user can see by exporting them. Everything not exported is supposed to be internal to the package and should not be accessed directly by users (though they can via :::). Functions/objects that are not exported do not need to be documented, hence no need for the toto-internal.Rd stub. HTH (and HTIC). Cheers, Berwin === Full address = Berwin A TurlachTel.: +65 6516 4416 (secr) Dept of Statistics and Applied Probability+65 6516 6650 (self) Faculty of Science FAX : +65 6872 3919 National University of Singapore 6 Science Drive 2, Blk S16, Level 7 e-mail: [EMAIL PROTECTED] Singapore 117546http://www.stat.nus.edu.sg/~statba __ R-help@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide http://www.R-project.org/posting-guide.html and provide commented, minimal, self-contained, reproducible code.
Re: [R] NAMESPACE vs internal.Rd
G'day Christophe, On Wed, 16 Jul 2008 16:11:15 +0200 [EMAIL PROTECTED] wrote: So the main idea is - With NAMESPACE, you do not document the not-for-user because they don't have to be documented - Witout NAMESPACE, you document the not-for-user with a toto-internal.Rd that say not for user That's clear. Is it stupid to consider to use both technique at the same time ? As far as I know, R will not complain if you write documentation for objects that you do not have to document. R CMD check will complain if an object accessible to a user of the package is not documented. A quick perusal of the packages installed on my machine shows that there are several packages that have a namesspace and a -internal file, e.g. the MASS package (from the VR bundle) and the sm package. But both these packages existed before the namespace mechanism was introduced. So the MASS-internal.Rd and sm-internal.Rd may be remainders from the time before namespaces were introduced. You would have to ask the maintainer(s) of such packages why they use a namespace and a -internal.Rd file. I can see no reason but a historical one that the -internal.Rd file stems from the time before namespaces and was not deleted after their introduction (I know that I wouldn't delete such a file if it weren't necessary). - some fonction will be accessible (regular function) - some function will be hidden (function starting with .) - some function will be forbiden (function not in namespace) We are actually talking objects (everything in R is an object) which could be anything, a function, a data frame or ... But if you want to keep the discussion restricted to functions then I would want to point out that functions that start with a . are only hidden from the ls() function and that this has nothing to do with a namespace. According to my understanding, if your package has a namespace, then everything that you do not export explicitly is not visible to users of your package. The Writing R Extensions manual has an example for an exportPattern() directive that exports all variables that do not start with a period, but that would export everything else. I guess writing a regular expression that says export everything that does not start with a dot but do not export foo and bar would be not trivial to write (at least not for me). And your distinction between hidden and forbidden functions is spurious because either function could be accessed via the ::: operator if the user knows that it is in the package (though not exported). Thus, if you use a namespace, then all the objects that you export are visible to the users of the package; all other objects are not visible (but can be accessed via :::). Objects that are not visible do not need to be documented (for R CMD check to succeed), but it is no error to document them. Objects that are visible to the users of the package have to be documented. HTH (and HTIC). Cheers, Berwin === Full address = Berwin A TurlachTel.: +65 6516 4416 (secr) Dept of Statistics and Applied Probability+65 6516 6650 (self) Faculty of Science FAX : +65 6872 3919 National University of Singapore 6 Science Drive 2, Blk S16, Level 7 e-mail: [EMAIL PROTECTED] Singapore 117546http://www.stat.nus.edu.sg/~statba __ R-help@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide http://www.R-project.org/posting-guide.html and provide commented, minimal, self-contained, reproducible code.
Re: [R] NAMESPACE vs internal.Rd
Thanks for your answer. I guess writing a regular expression that says export everything that does not start with a dot but do not export foo and bar would be not trivial to write (at least not for me). The NAMESPACE created by package.skeleton contain a single line : exportPattern(^[[:alpha:]]+) I guess that it is what you just say... Christophe __ R-help@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide http://www.R-project.org/posting-guide.html and provide commented, minimal, self-contained, reproducible code.
