mvbutils-package: How to use the mvbutils package

Description

Package mvbutils is a collection of utilities offering the following main features:

Hierarchical organization of projects (tasks) and sub-tasks, allowing switching within a single R{} session, searching and moving objects through the hierarchy, objects in ancestor tasks always visible from child (sub)tasks, etc. Seecd.
Improved function, text, and object editing facilities, interfacing with whichever text editor you prefer. The R{} command line is not frozen while editing, and you can have multiple edit windows open. Scriptlets that generate general-purpose objects can also be maintained this way. Function documentation can be stored as plain text after the function definition, and will be found byhelp. There is also a complete automatic text-format backup system for functions & text. Seefixr.
Automated package construction, including production of Rd-format from plain text documentation. Packages can be edited & updated while loaded, without needing to quit/rebuild/reinstall. Seemvbutils.packaging.tools.
"Lazy loading" for individual objects, allowing fast and transparent access to collections of biggish objects where only a few objects are used at a time. Seemlazy.
Miscellaneous goodies: local/nested functions (mlocal), display of what-calls-what (foodweb), multiple replacement (multirep), numerous lower-level lower-level utility functions and operators (mvbutils.utils,mvbutils.operators,extract.named,mcut,search.for.regexpr,strip.missing,Hours).

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) may work even if you don't follow this suggestion.

Arguments

Housekeeping info

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.searchis the directory R{} started in (your ROOT task).
.Pathshows the currently-attached part of the task hierarchy.
base.xxxis the original copy of an overwritten system function, e.g.help
fix.listkeeps track of objects being edited viafixr
session.start.timeis the value ofSys.time()whenmvbutilswas loaded
source.listis used bysource.mvbto allow nesting of sources
r.window.handleis used by thehandypackage (Windows only)
partial.namespacesis used to alleviate difficulties with unloadable data files-- seemvbutils.packaging.tools
things whose name starts with ".." are environments used in live-editing packages
maintained.packagesis a list of the above

Redefined functions

On loading, the present version of package mvbutils compulsorily overwrites a few system functions: library, rbind.data.frame, lockEnvironment, loadNamespace. 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 mods are undone when you unload mvbutils. The mods should have [almost] no side-effects, and/but I hope to be able to avoid them altogether in future versions of R{}. Unloading mvbutils undoes the changes. Briefly:

libraryis modified so that its defaultposargument becomes a call tolib.pos(). This means that packages get attached just below ROOT rather than always in position 2 (needed bycd).
lockEnvironmentis modified to allow live-editing of loaded packages-- no change to default behaviour.
loadNamespacehas the default value of its "partial" argument altered, to let you bypass.onLoadfor selected faulty packages-- seemvbutils.packaging.toolsand look forpartial.namespaces. This allows the loading of certain ".RData" files which otherwise crash from "hidden" attempts to load a namespace. It lets you get round some truly horrendous problems arising from "faults" with 3rd-party packages, as well as problems when you stuff up your own packages.
rbind.data.frameis modified to work better (IMO) when the firstdata.framehas zero rows, to cope with a code-breaking change in R{}'s behaviour several versions ago. Specifically, the modified version doesnotdrop zero-row data.frames, and their column attributes are taken account of whenrbind.data.frameing to the other args. This is useful when repeatedly adding rows to an initially-empty data.frame. To see the difference, experiment withrbind( data.frame( x=1, y=factor( "a")), data.frame( x=2, y=factor( "b"))[-1,])$yvsbase.rbind.data.frame(...)with the same arguments.mvbutilsanddebugrely on the non-default behaviour, so the overwriting is not optional.

Optional but recommended replacements are as follows:

helpis modified so that, if systemhelpcan't find help for a function (but not a method, dataset, or package), it will look for adocattribute of the function to display in a pager usingdochelp.
loadhistoryandsavehistoryare modified so that they use the "R_HISTFILE" environment variable if it set. This can be set dynamically during an R{} session usingSys.setenv. Standard R{} behaviour is to respect "R_HISTFILE" iff it is setbeforethe R{} session starts. If "R_HISTFILE" is not set, thencdwill on first use set "R_HISTFILE" to "<>/.RHistory", so that same the history file will be used throughout each and every session.
save.imageis modified to callSaveinstead; this will behave exactly the same for workspaces not usingmvbutilstask-hierarchy feature or thedebugpackage, but otherwise will prevent problems withmtraced functions andmlazyed objects.
difftime,+.POSIXt, and-.POSIXtare modified to behave more consistently and forgivingly. Results won't break code that doesn't make invalid assumptions. [This should probably be done in a different package. I'm also unsure whether my changes are still necessary, following changes in R{} since about 2.9. But no-one has complained yet, so the mods will stay until/unless enough people do...

] print.POSIXct, format.POSIXct, and as.data.frame.POSIXt are modified to honour any matrix/array shape of POSIXct objects. retain their "shape" on printing. Without this mod, R{} forces you to either hide the matrix shape if you want to see the POSIXity, or to discard POSIXity if you want to see the matricity. I'm not sure that a POSIXlt matrix makes sense, so I haven't provided comparable mods for POSIXlt yet. head.default and tail.default are modified to call head/tail.matrix if the argument is a matrix. Although there are already head/tail.matrix methods, by default they won't be invoked for 2D objects that have a non-default S3 class, such as POSIXct objects. This mod fixes the problem. 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 also set the "mvbutils.replacements" option to a character vector comprising some or all of the above names. After mvbutils has loaded, you can undo the modification of an individual function called xxx with assign.to.base( "xxx", base.xxx). Unloading mvbutils will undo all the changes.

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 (as of ~2005) 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 (though there hasn't been ESS feedback in 5 years...}).

cdchanges the search list, so you may need to alter "ess-change-sp-regex" in ESS.
cdalso 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 zero 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 Linux display where readline() always returns the cursor to the start of the line, overwriting any prompt, then try options( cd.extra.CR=TRUE).

Description

Arguments

Housekeeping info

Redefined functions

Display bugs

See Also