Hi there Petr,
Apologies for only replying to your post now - I hope the code included
below helps you out.
An alternative function documentation approach would be the one I took when
faced with a
similar problem - I wrote some functions to allow me to embed a retrievable
function specification
into the head of any function I wrote. The code is included below.
How to use this code:
Put the function described below (extractFunctionDefinition) in a single
file (I keep it in
FunctionDescription.R) and load this file at the start of every R project
you wish to use it.
--------------------------------------------------------------START
FUNCTION--------------------------------------------------------------------
extractFunctionDefinition<-function(function_name,start_flag="#<-BEGIN-FUNCTION-DESCRIPTION-BLOCK->",
end_flag="#<-END-FUNCTION-DESCRIPTION-BLOCK->")
{
#<-BEGIN-FUNCTION-DESCRIPTION-BLOCK->
# Extracts this function description from a function.
#
# Declared In:
# FunctionDescription.R
#
# Args:
# function_name: The name of the function (as a string)
# start_flag: Flag (as a string) indicating the start of the function
description block
# (default is #<-BEGIN-FUNCTION-DESCRIPTION-BLOCK->)
# end_flag: Flag (as a string) indicating the end of the function
description block
# (default is #<-END-FUNCTION-DESCRIPTION-BLOCK->)
#
# Returns:
# METHOD_OK if a description block exists, METHOD_FAILED otherwise
#<-END-FUNCTION-DESCRIPTION-BLOCK->
#Get function type - this allows us to handle either function name
entered as text
#or the function name entered as a function pointer (ie myfunc and not
"myfunc")
if(is.null(attributes(function_name)))
{
localText<-lapply(attributes(get(function_name)), function(x)
return(gsub("\t","",x)))$source
}else
{
localText<-lapply(attributes(function_name), function(x)
return(gsub("\t","",x)))$source
}
descSP<-which(unlist(lapply(localText, function(x){if(
length(grep(start_flag, x))==0 ){return(FALSE)}else{return(TRUE)}} )))
descEP<-which(unlist(lapply(localText, function(x){if(
length(grep(end_flag, x))==0 ){return(FALSE)}else{return(TRUE)}} )))
if(length(descSP)==0 | length(descEP)==0)
{
cat(paste("Error - function ", function_name," has no function
description included.\r\n",sep=""))
return(invisible(METHOD_FAILED))
}else
{
if(as.character(match.call())[2]=="extractFunctionDefinition"){
##Handle exceptional case where function is describing itself:
descSP<-descSP[2]+1
descEP<-descEP[3]-1
}else{
if(length(descSP)>1){descSP<-descSP[2]+1}else{descSP<-descSP+1}
if(length(descEP)>1){descEP<-descEP[2]-1}else{descEP<-descEP-1}
}
}
#Extract function description:
desc<-localText[descSP:descEP]
cat(paste(desc, collapse="\r\n"),"\r\n")
return(invisible(METHOD_OK))
}
--------------------------------------------------------------END
FUNCTION--------------------------------------------------------------------
--------------------------------------------------------------START DEMO
CODE------------------------------------------------------------
Example Function:
flyingPigs<-function(input1, input2)
{
#<-BEGIN-FUNCTION-DESCRIPTION-BLOCK->
# Demo function demonstrating how to use extractFunctionDefinition()
#
# Declared In:
# <some_file.R>
#
# Args:
# input1: anything really, just to prove a point
# input2: just to demo how I document my input
#
# Returns:
# I always return a list list(EXIT_STATUS,<anything else>)
#<-END-FUNCTION-DESCRIPTION-BLOCK->
return(list(0,input1, input2))
}
extractFunctionDefinition(flyingPigs)
extractFunctionDefinition("flyingPigs")
--------------------------------------------------------------END DEMO
CODE-------------------------------------------------------------
To the rest of the R community: I realise that this is not "how things
should be done" - by the time I'd
realised that I should be writing a package I'd already created a whole slew
of tools! That'll teach me
not to read the manual.
Cormac Long.
[[alternative HTML version deleted]]
______________________________________________
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.
