Package 'remindR'

Insert, extract, and print text "reminders"

Description

remindR is a simple package to insert, extract, and print text "reminders" either in source code comments or as the "comment" attribute of any R object.

Details

The primary intent is to allow addition and retrieval of informal text notes to oneself or collaborators during code development. These could be reminders about argument requirements, changes or additions to make, the structure of the function's returned value, required options settings, etc. – basically anything that one wants to note. Generally such reminders will be ephemeral and brief. They are not intended as detailed development specifications.

It is also possible to use such notes as minimal help "tooltips" for users. To facilitate this, the "remind<-" insertion and remind extraction functions wrap R's comment functionality to use the "comment" attribute of any R object as a list of reminders.

Author(s)

Maintainer: Bert Gunter [email protected]

---

Insert, extract, and print "reminders" for functions and objects

Description

Insert, extract, and print text (i.e. character vector) "reminders" either as the "comment" attribute of objects or as delimited comments within function source code.

Usage

remind(x, ...)

## Default S3 method:
remind(x, ...)

## S3 method for class 'function'
remind(x, begin = "<<", end = ">>", ...)

remind(x) <- value

## S3 method for class 'reminder'
print(x, ...)

Arguments

x	An R object/function for remind; a class "reminder" object for print
...	Additional arguments to methods
begin	Character string delimiting reminder beginning
end	Character string delimiting reminder ending
value	Character vector of text to attach as 'comment' attribute

Details

Extracts text between the 'begin' and 'end' delimiting character strings within source code comments. This is mostly intended to enable easy addition and retrieval of informal text notes during the course of script/function development, aka 'reminders', e.g. to fix something, add a validity check, note additional argument requirements etc. Multiple such separately delimited reminders can be included.

As a slight convenience, the function wraps R's existing comment function to attach and extract reminders as the 'comment' attribute of any R object. These can be used to provide information (provenance, context) on objects and even serve as a kind of minimal informal Help documentation for functions, i.e. a sort of simple manual "tooltip" functionality.

Value

A list of S3 class "reminder".

Note

Because there is no fixed syntax in source code comments, extracting reminders cannot be guaranteed to always work correctly. Some simple checks have been included to warn when they may not be properly extracted, but this may not succeed in all cases.

Also, retrieving reminders from functions depends on whether options(keep.source = TRUE) is in use when they are saved.

See Also

comment

Examples

x <- 1:3
remind(x)
remind(x) <- c("first comment","and a second")
remind(x)
remind(x) <- NULL ## removes reminder
remind(x)
f <- function(x){
   y <- x
   ## Some miscellaneous comments
   ## Now <<This is reminder 1>> and next
   ## This is
   ## yet another <<reminder 2 is this>>
   ## some more stuff
   y
}
f(5)
remind(f)
remind(f)<- "something else"
remind(f)
## "tooltip" type example:
my.summary<- function(x, fun = mean,...)fun(x)
remind(my.summary)<-
"Don't forget to include the na.rm argument if missing values might be present"
remind(my.summary)
rm(f,x,my.summary)

---