mvbutils-package {mvbutils} | R Documentation |
Package mvbutils is a collection of utilities offering the following main features:
cd
.
fixr
.
mlazy
.
help
(i.e. semi-literate programming). Automatic conversion to Rd format is available if certain rules are followed. See flatdoc
.
maintain.packages
.
source
calls, and for interspersing R code and data in the same file. See source.mvb
.
mlocal
and do.in.envir
.
foodweb
.
There are also numerous lower-level utility functions and operators: see ?"mvbutils-utils"
and ?"mvbutils-operators"
.
To get the full features of the mvbutils package (in particular, the project organization), you need to start R in the same directory every time (your "ROOT task"), and then switch to whichever project from inside R; see cd
. Various options
always need to be set to make fixr
and the debug package work the way you want, so one advantage of the start-in-the-same directory-approach is that you can keep all your project-independent options()
, library loads, etc., in a single .First
function, called automatically when you start R. However, most features (including support for the debug package) will probably work even if you don't follow this suggestion.
On loading, the mvbutils package creates a new environment in the search path, called mvb.session.info
, which stores some housekeeping information. mvb.session.info
is never written to disk, and disappears when the R session finishes. [For Splus users: mvb.session.info
is similar to frame 0.] You should never change anything in mvb.session.info
by hand, but it is sometimes useful to look at some of the variables there:
.First.top.search
is the directory R started in (your ROOT task).
.Path
shows the currently-attached part of the task hierarchy.
base.xxx
is the original copy of an overwritten system function, e.g. help
fix.list
keeps track of functions being edited via fixr
session.start.time
is the value of Sys.time()
when mvbutils
was loaded
source.list
is used by source.mvb
to allow nesting of sources
r.window.handle
is used by the handy package (Windows only)
On loading, the present version of package mvbutils compulsorily overwrites a few system functions: library
, rbind.data.frame
, lockEnvironment
. By default, it also overwrites help
, savehistory
, loadhistory
, save.image
, difftime
, +.POSIXt
, and -.POSIXt
. (The original version of routine xxx
can always be obtained via base.xxx
if you really need it.) The modifications should have [almost] no side-effects, and/but I hope to be able to avoid them altogether in future versions of R. Briefly:
library
is modified so that its default pos
argument becomes a call to lib.pos()
. This means that packages get attached just below ROOT rather than always in position 2 (needed by cd
).
lockEnvironment
gets an X-rated hack to allow editing of "live" packages (see maintain.packages
)– no change to default behaviour.
rbind.data.frame
is modified to work better (IMO) when the first data.frame
has zero rows, to cope with a code-breaking change in R's behaviour several versions ago. Specifically, the modified version does not drop zero-row data.frames, and their column attributes are taken account of when rbind
ing to the other args. In other words, rbind( data.frame( x=1, y="a"), data.frame( x=2, y="b"))[-1,]$y
now has the same levels as rbind( data.frame( x=1, y="a")[-1,], data.frame( x=2, y="b"))$y
. Experiment with base.rbind.data.frame
instead, if you want to see the difference.
help
is modified so that, if system help
can't find help for a simple object (not a method or package), it will look for the doc
attribute of that object (if any) and display it in a pager using dochelp
.
savehistory
and loadhistory
are modified so that they use the R_HISTFILE
environment variable if it set. This can be set dynamically during an R session using Sys.setenv
. Standard R behaviour is to respect R_HISTFILE
iff it is set before the R session starts. Note that, by default, cd
will on first use set R_HISTFILE
to what it thinks is the ROOT task, so that same the history file will be used throughout the session; see cd
if you want to change this.
save.image
is modified to call Save
instead; this will behave exactly the same for workspaces not using mvbutils
task-hierarchy feature or the debug package, but otherwise will prevent problems with mtrace
d functions and mlazy
ed functions.
difftime
, +.POSIXt
, and -.POSIXt
are modified to behave more consistently and forgivingly. Results won't break code that doesn't make invalid assumptions.
If you are certain that you don't want the optional replacements, set options(mvbutils.replacements=FALSE)
before loading mvbutils
. However, this will prevent cd
, fixr
, and the flat-documentation help from working properly. You can undo the modification of an individual function called xxx
with assign.to.base( "xxx", base.xxx)
.
ESS.and.'mvbutils'
For ESS users: I'm not an Emacs user and so haven't tried ESS with the mvbutils package myself, but a read-through of the ESS documentation suggests that a couple of ESS variables may need changing to get the two working optimally. Please check the ESS documentation for further details on these points. I will update this helpfile when/if I receive more feedback on what works.
cd
changes the search list, so you may need to alter "ess-change-sp-regex" in ESS.
cd
also changes the prompt, so you may need to alter "inferior-ess-prompt". Prompts have the form WORD1/WORD2/.../WORDn> where WORDx is a letter followed by one or more letters, underscores, periods, or digits.
move
can add/remove objects in workspaces other than the top one, so if ESS relies on stored internal summaries of "what's where", these may need updating.
Display bugs: if you have a buggy Unix display where readline()
always returns the cursor to the start of the line, overwriting any prompt, then try options( cd.extra.CR=TRUE)
.
Version 2.2.0 is partly a maintenance fix, and partly a premature release of a major new feature: the easy package-building and maintenance routines. The documentation for the latter is incomplete, and the routines haven't been thoroughly tested except on my own half-dozen packages. (If anyone is brave enough to try the package-related material, I'd appreciate feedback!) The reason for rushing this version out is to deal with a fatal non-back-compatible change deep inside R 2.8; it also sorts out a number of other mostly minor bugs that have hatched or been unearthed since the last CRAN release. I will release a properly-documented version as soon as I can, hopefully with an R-news article to describe the package-maintenance routines.
Mark Bravington
cd
, fixr
, mlazy
, flatdoc
, dochelp
, maintain.packages
, source.mvb
, mlocal
, do.in.envir
, foodweb
, mvbutils-operators
, mvbutils-utils
, package debug