Guides are context lines that would normally be omitted from the diff because they are too far from any differences, but provide particularly useful contextual information. Column headers are a common example. Modifying guide finding is an advanced feature intended for package developers that want special treatment for the display output of their objects.
guidesPrint(obj, obj.as.chr)# S4 method for ANY,character
guidesPrint(obj, obj.as.chr)
guidesStr(obj, obj.as.chr)
# S4 method for ANY,character
guidesStr(obj, obj.as.chr)
guidesChr(obj, obj.as.chr)
# S4 method for ANY,character
guidesChr(obj, obj.as.chr)
guidesDeparse(obj, obj.as.chr)
# S4 method for ANY,character
guidesDeparse(obj, obj.as.chr)
guidesFile(obj, obj.as.chr)
# S4 method for ANY,character
guidesFile(obj, obj.as.chr)
an R object
the character representation of obj that is used
for computing the diffs
integer containing values in seq_along(obj.as.chr)
Diff detects these important context lines by looking for patterns in
the text of the diff, and then displays these lines in addition to the
normal diff output. Guides are marked by a tilde in the gutter, and
are typically styled differently than normal context lines, by default in
grey. Guides may be far from the diff hunk they are juxtaposed to. We
eschew the device of putting the guides in the hunk header as git diff
does because often the column alignment of the guide line is meaningful.
Guides are detected by the guides* methods documented here.
Each of the diff* methods (e.g. diffPrint) has a
corresponding guides* method (e.g.
guidesPrint), with the exception of diffCsv
since that method uses diffPrint internally. The guides*
methods expect an R object as the first parameter and the captured display
representation of the object in a character vector as the second. The
function should then identify which elements in the character representation
should be treated as guides, and should return the numeric indices for them.
The original object is passed as the first argument so that the generic can dispatch on it, and so the methods may adjust their guide finding behavior to data that is easily retrievable from the object, but less so from the character representation thereof.
The default method for guidesPrint has special handling for 2D
objects (e.g. data frames, matrices), arrays, time series, tables, lists, and
S4 objects that use the default show method. Guide finding is on a
best efforts basis and may fail if your objects contain “pathological”
display representations. Since the diff will still work with failed
guides finding we consider this an acceptable compromise. Guide
finding is more likely to fail with nested recursive structures. A known
issue is that list-like S3 objects without print methods [reset the tag
buffers](https://bugs.r-project.org/bugzilla/show_bug.cgi?id=17610) so the
guides become less useful for them.
guidesStr highlights top level objects. The default methods for the
other guide* generics do not do anything and exist only as a mechanism
for providing custom guide line methods.
If you dislike the default handling you can also define your own methods for
matrices, arrays, etc., or alternatively you can pass a guide finding
function directly via the guides parameter to the diff*
methods.
If you have classed objects with special patterns you can define your own
methods for them (see examples), though if your objects are S3 you will need
to use setOldClass as the guides* generics are S4.
# NOT RUN {
## Roundabout way of suppressing guides for matrices
setMethod("guidesPrint", c("matrix", "character"),
function(obj, obj.as.chr) integer(0L)
)
## Special guides for "zulu" S3 objects that match lines
## starting in "zulu###" where ### is a nuber
setOldClass("zulu")
setMethod("guidesPrint", c("zulu", "character"),
function(obj, obj.as.chr) {
if(length(obj) > 20) grep("^zulu[0-9]*", obj.as.chr)
else integer(0L)
} )
# }
Run the code above in your browser using DataLab