guides: Generic Methods to Implement Flexible Guide Line Computations
In diffobj: Diffs for R Objects

Description Usage Arguments Details Value Note Examples

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 signature 'ANY,character'
guidesPrint(obj, obj.as.chr)

guidesStr(obj, obj.as.chr)

## S4 method for signature 'ANY,character'
guidesStr(obj, obj.as.chr)

guidesChr(obj, obj.as.chr)

## S4 method for signature 'ANY,character'
guidesChr(obj, obj.as.chr)

guidesDeparse(obj, obj.as.chr)

## S4 method for signature 'ANY,character'
guidesDeparse(obj, obj.as.chr)

guidesFile(obj, obj.as.chr)

## S4 method for signature 'ANY,character'
guidesFile(obj, obj.as.chr)

`obj`	an R object
`obj.as.chr`	the character representation of `obj` that is used for computing the diffs

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.

integer containing values in seq_along(obj.as.chr)

The mechanism for identifying guides will almost certainly change in the future to allow for better handling of nested guides, so if you do implement custom guideline methods do so with the understanding that they will likely be deprecated in one of the future releases.

## 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)
} )