R/easyreportingG.R

In easyreporting: Helps creating report for improving Reproducible computational Research

#' initReportFilename
#'
#' @param object an easyreporting class object 
#' @param filenamepath the name of the report with or without the path
#' @param mainTitle the title of the report
#' @param author the name of the report author
#' @param documentType type of report final document. (html is default)
#'
#' @return an easyreporting class object 
#' @keywords internal
setGeneric (
    name="initReportFilename",
    def=function(object, filenamepath=NULL, title=NULL,
                author=NULL, optionList=NULL)
    {
        standardGeneric("initReportFilename")
    }
)
#' mkdSetGlobalOpts
#'
#' @param object an easyreporting class object
#' @param optionList a list of options
#'
#' @return an easyreporting class object
#' @keywords internal
setGeneric (
    name="mkdSetGlobalOpts",
    def=function(object, optionList=list()){standardGeneric("mkdSetGlobalOpts")}
)
#' mkdTitle
#' @description Inserts an rmarkdown title inside the report, useful for create
#' distinct sections inside the final resport.
#' @param object an easyreporting class object
#' @param title a string within the title.
#' @param level a numeric from 1 to 6 (default is 1).
#'
#' @return none
#' @export
#' @examples
#' rd <- easyreporting(filenamePath="./project_report",
#'                         title="example_report", author=c("It's me"))
#'
#' mkdTitle(rd, "First Level Title")
#' mkdTitle(rd, "Sub-Title", level=2)
#'
setGeneric (
    name="mkdTitle",
    def=function(object, title, level=1){standardGeneric("mkdTitle")}
)
#' getReportFilename
#' 
#' @description returns the filename with its path of the report generated by 
#' easyreporting
#'
#' @param object an easyreporting class object
#'
#' @return a string of report file name with path
#' @export
#'
#' @examples
#' rd <- easyreporting(filenamePath="./project_report",
#'                         title="example_report", author=c("It's me"))
#' (rep <- getReportFilename(rd))
setGeneric (
    name="getReportFilename",
    def=function(object){standardGeneric("getReportFilename")}
)
#' mkdGeneralMsg
#' @description It appends a general message to the report, useful for 
#' describing a code chunk or a part of the report.
#' Useful for adding natural language comments.
#' @param object an easyreporting class object
#' @param message the message to append to the report
#'
#' @return none
#' @export
#'
#' @examples
#' rd <- easyreporting(filenamePath="./project_report",
#'                         title="example_report", author=c("It's me"))
#' mkdGeneralMsg(rd, message="Writing a paragraph to describe my code chunk")
setGeneric (
    name="mkdGeneralMsg",
    def=function(object, message){standardGeneric("mkdGeneralMsg")}
)

#' mkdGeneralTitledMsg
#' @description It appends a a titled section followed by a general message to 
#' the report. Useful for adding natural language comments.
#' @param object an easyreporting class object
#' @param title the title of the report section.
#' @param level the level (1 to 6) of the title (default is 1)
#' @param message the message to append to the report
#'
#' @return none
#' @export
#'
#' @examples
#' rd <- easyreporting(filenamePath="./project_report",
#'                         title="example_report", author=c("It's me"))
#' mkdGeneralTitledMsg(rd, title="Generic SubTitle for this message", level=2,
#'             message="Writing a paragraph to describe my code chunk")
setGeneric (
    name="mkdGeneralTitledMsg",
    def=function(object, title=NULL, level=1, message)
        {standardGeneric("mkdGeneralTitledMsg")}
)

#' setOptionsList
#' @description set an optionList to the class, it automatically sets the 
#' options for the rmarkdown file. Are useful for the 
#' interpretation/execution of the code chunks.
#' 
#'
#' @param object an easyreporting class object
#' @param cacheFlag boolean for caching chunk data (default TRUE)
#' @param evalFlag boolean for evaluating the code chunk in the compiled version
#' (default TRUE)
#' @param echoFlag boolean for showing the code chunk (default TRUE)
#' @param warningFlag boolean for showing the chunk warnings (default FALSE)
#' @param showMessages boolean for showing the chunk warnings in compiled
#' @param includeFlag boolean for including the code chunk in the compiled
#' version (default TRUE)
#'
#' @return none
#' @export
#'
#' @examples
#' rd <- easyreporting(filenamePath="./project_report",
#'                         title="example_report", author=c("It's me"))
#'
#' ## setting default option
#' setOptionsList(rd)
#'
#' ## modifying only some options
#' rd <- setOptionsList(rd, warningFlag=TRUE, 
#'         showMessages=TRUE, includeFlag=TRUE)
#' 
setGeneric (
    name="setOptionsList",
    def=function(object, cacheFlag=TRUE, evalFlag=TRUE, echoFlag=TRUE, 
                warningFlag=FALSE, showMessages=FALSE, includeFlag=TRUE)
    {standardGeneric("setOptionsList")}
)
#' getOptionsList
#'
#' @description returns the optionList from the easyreporting class 
#' (see the makeOptionList function for more details).
#' @param object an easyreporting class object
#'
#' @return a list of options
#' @export
#'
#' @examples
#' rd <- easyreporting(filenamePath="./project_report", title="example_report",
#'                         author=c("It's me"))
#' optList <- getOptionsList(rd)
#'
setGeneric (
    name="getOptionsList",
    def=function(object){standardGeneric("getOptionsList")}
)
#' compile
#' @description prints the sessionInfo and compiles the produced rmarkdown file
#' into an HTML report.
#' @param object an easyreporting class object
#'
#' @return none
#' @export
#' 
#' @examples
#' rd <- easyreporting(filenamePath="./project_report", title="example_report",
#'                         author=c("It's me"))
#' compile(rd)
setGeneric (
    name="compile",
    def=function(object){standardGeneric("compile")}
)
#' mkdVariableAssignment
#'
#' @description it includes a variable assignment in the report.
#' NB: a call to the "mkdCodeChunkSt" has to be done before using it.
#'
#' @param object an easyreporting class object
#'
#' @param variable.name a string indicating the name of the variabe to store in
#' the report. (This can be changed here, but further uses of the variable needs
#' to take into account the variable name change).
#' @param variable.object.name the name of the already existing variable. (This
#' cannot be canged.)
#' @param show a boolean indicating if to show the message before writing it
#' into the rmardown file.
#'
#' @return none
#' @export
#'
#' @examples
#' rd <- easyreporting(filenamePath="./project_report",
#'                         title="example_report", author=c("It's me"))
#' ## leaving the default options to the code chunk
#' mkdCodeChunkSt(rd)
#' ## adding a variable assignement
#' variable <- 1
#' mkdVariableAssignment(rd, "variable", "variable", show=TRUE)
#' mkdCodeChunkEnd(rd)
setGeneric (
    name="mkdVariableAssignment",
    def=function(object, variable.name, variable.object.name, show)
    {
        standardGeneric("mkdVariableAssignment")
    }
)

#' mkdCodeChunkSt
#' @description it creates a code chunk start. A list of options and files to
#' source  for the chunk can optionally be passed to the function.
#' @param object an easyreporting class object
#' @param optionList a list of options
#' @param sourceFilesList a list of files that can be sourced inside the code
#' chunk.
#' @param isComplete a flag determining if the chunk is already a complete chunk
#'
#' @return none
#' @export
#'
#'
#' @examples
#' rd <- easyreporting(filenamePath="./project_report",
#'                         title="example_report", author=c("It's me"))
#' ## no options
#' mkdCodeChunkSt(rd)
#' ## just leaving empty
#' mkdCodeChunkEnd(rd)
#'
#' ## setting options
#' optList <- makeOptionsList(includeFlag=TRUE)
#' mkdCodeChunkSt(rd, optionList=optList)
#' ## just leaving empty
#' mkdCodeChunkEnd(rd)
#'
setGeneric (
    name="mkdCodeChunkSt",
    def=function(object, optionList=getOptionsList(object),
                 sourceFilesList=NULL, isComplete=FALSE)
    {standardGeneric("mkdCodeChunkSt")}
)
#' mkdSourceFiles
#' @description includes a list of source files inside the rmarkdown
#' @param object an easyreporting class object
#' @param ... a list of files to source
#'
#' @return none
#'
#' @keywords internal
setGeneric (
    name="mkdSourceFiles",
    def=function(object, ...){standardGeneric("mkdSourceFiles")}
)

#' mkdCodeChunkEnd
#' @description it creates a code chunk end. Always use it after a
#' mkdCodeChunkSt()
#' @param object an easyreporting class object
#' @return none
#'
#' @export
#'
#' @examples
#'  rd <- easyreporting(filenamePath="./project_report",
#'                         title="example_report", author=c("It's me"))
#' mkdCodeChunkSt(rd)
#' ## just leaving empty
#' mkdCodeChunkEnd(rd)
setGeneric (
    name="mkdCodeChunkEnd",
    def=function(object){standardGeneric("mkdCodeChunkEnd")}
)
#' mkdCodeChunkComplete
#' @description it creates a complete code chunk.
#' @param object an easyreporting class object
#' @param message a string containing a function call or the entire code chunk
#' to trace.
#' @param optionList a list of options.
#' @param sourceFilesList a list of files to source.
#'
#' @return none
#' @export
#'
#' @examples
#'  rd <- easyreporting(filenamePath="./project_report",
#'                         title="example_report", author=c("It's me"))
#' mkdCodeChunkComplete(rd, message="a <- 1\nb <- 2\nc <- a+b\n print(c)")
setGeneric (
    name="mkdCodeChunkComplete",
    def=function(object, message,
                optionList=getOptionsList(object),
                sourceFilesList=NULL){standardGeneric("mkdCodeChunkComplete")}
)
#' mkdCodeChunkCommented
#' @description it creates a complete code chunk, adding a natural language
#' comment before of it.
#' @param object an easyreporting class object
#' @param commentMsg a string with the natural language comment for the chunk.
#' @param codeMsg a string within the code.
#' @param optionList a list of options (default is the class options).
#' @param sourceFilesList a optional list of files to source inside the chunk.
#'
#' @return none
#' @export
#'
#' @examples
#' rd <- easyreporting(filenamePath="./project_report",
#'                         title="example_report", author=c("It's me"))
#' optList <- makeOptionsList(includeFlag=TRUE, cacheFlag=TRUE)
#' mkdCodeChunkCommented(rd,
#'                 commentMsg="This is the comment of the following code chunk",
#'                 codeMsg="a <- 1\nb <- 2\n(c <- a+b)\n", optionList=optList,
#'                 sourceFilesList=NULL)
#'
setGeneric (
    name="mkdCodeChunkCommented",
    def=function(object, commentMsg=NULL, codeMsg,
                optionList=getOptionsList(object),
                sourceFilesList=NULL){standardGeneric("mkdCodeChunkCommented")}
)
#' mkdCodeChunkCommented
#' @description it creates a complete code chunk, adding a natural language
#' comment before of it.
#' @param object an easyreporting class object
#' @param title the title to assign to the code chunk section
#' @param level the level of the title (default is 1)
#' @param commentMsg a string with the natural language comment for the chunk.
#' @param codeMsg a string within the code.
#' @param optionList a list of options (default is the class options).
#' @param sourceFilesList a optional list of files to source inside the chunk.
#'
#' @return none
#' @export
#'
#' @examples
#' rd <- easyreporting(filenamePath="./project_report",
#'                         title="example_report", author=c("It's me"))
#' optList <- makeOptionsList(includeFlag=TRUE, cacheFlag=TRUE)
#' mkdCodeChunkCommented(rd,
#'                 commentMsg="This is the comment of the following code chunk",
#'                 codeMsg="a <- 1\nb <- 2\n(c <- a+b)\n", optionList=optList,
#'                 sourceFilesList=NULL)
#'
setGeneric (
    name="mkdCodeChunkTitledCommented",
    def=function(object, title=NULL, level=1, commentMsg=NULL, codeMsg,
                optionList=getOptionsList(object),
                sourceFilesList=NULL){
                standardGeneric("mkdCodeChunkTitledCommented")}
)