Style-class: Customize Appearance of Diff

Description

S4 objects that expose the formatting controls for Diff objects. Many predifined formats are defined as classes that extend the base Style class. You may fine tune styles by either extending the pre-defined classes, or modifying an instance thereof.

Arguments

funs

a StyleFuns object that contains all the functions represented above

text

a StyleText object that contains the non-content text used by the diff (e.g. gutter.insert.txt)

wrap

TRUE or FALSE, whether the text should be hard wrapped to fit in the console

pad

TRUE or FALSE, whether text should be right padded

pager

what type of Pager to use

na.sub

what character value to substitute for NA elements; NA elements are generated when lining up side by side diffs by adding padding rows; by default the text styles replace these with a blank character string, and the HTML styles leave them as NA for the HTML formatting functions to deal with

blank

sub what character value to replace blanks with; needed in particular for HTML rendering (uses " ") to prevent lines from collapsing

finalizer

function that accepts at least two parameters and requires no more than two parameters, will receive as the first parameter the full text of the diff as a character vector, and the active Pager as the second argument. This allows final modifications to the character output so that it is displayed correctly by the pager. For example, StyleHtml objects use it to generate HTML headers if the Diff is destined to be displayed in a browser. The Pager object is passed along to provide information about the paging device to the function.

Value

Style S4 object

Pre-defined Classes

Pre-defined classes are used to populate the PaletteOfStyles object, which in turn allows the diff* methods to pick the appropriate Style for each combination of the format, color.mode, and brightness parameters when the style parameter is set to “auto”. The following classes are pre-defined:

StyleRaw: No styles applied
StyleAnsi8NeutralRgb
StyleAnsi8NeutralYb
StyleAnsi256LightRgb
StyleAnsi256LightYb
StyleAnsi256DarkRgb
StyleAnsi256DarkYb
StyleHtmlLightRgb
StyleHtmlLightYb

Each of these classes has an associated constructor function with the same name (see examples). Objects instantiated from these classes may also be used directly as the value for the style parameter to the diff* methods. This will override the automatic selection process that uses PaletteOfStyles. There are predefined classes for most combinations of format/color.mode/brightness, but not all. For example, there are only “light” brightness defined for the “html” format, and that class is re-used for all possible brightness values. PaletteOfStyles substitutes an appropriate class when necessary (e.g. StyleAnsi8NeutralYb for the neutral yellow-blue Ansi256 entry). To get a preview of what a style looks like just instantiate an object; the show method will output a trivial diff to screen with styles applied. Note that for ANSI styles of the dark and light variety the show method colors the terminal background and foregrounds in compatible colors. In normal usage the terminal background and foreground colors are left untouched so you should not expect light styles to look good on dark background and vice versa even if they render correctly when showing the style object.

Style Structure

Most of the customization is done by specifying functions that operate on character vectors and return a modified character vector of the same length. The intended use case is to pass crayon functions such as crayon::red, although you may pass any function of your liking that behaves as described. The visual representation of the diff has many nested components. The functions you specify here will be applied starting with the innermost ones. A schematic of the various component that represent an inserted line follows (note “insert” abbreviated to “ins”, and “gutter” abbreviated to “gtr”):

+- line ---------------------------------------------------+
|+- line.ins ---------------------------------------------+|
||+- gtr ------------------------++- text ---------------+||
|||+- gtr.ins ---++- gtr.pad ---+||+- text.ins ---------+|||
||||             ||             ||||      +- word.ins -+||||
|||| gtr.ins.txt || gtr.pad.txt |||| DIFF | TEXT HERE  |||||
||||             ||             ||||      +------------+||||
|||+-------------++-------------+||+--------------------+|||
||+------------------------------++----------------------+||
|+--------------------------------------------------------+|
+----------------------------------------------------------+

A similar model applies to deleted and matching lines. The boxes represent functions. gutter.insert.txt represents the text to use in the gutter and is not a function. DIFF TEXT HERE is text from the objects being diffed, with the portion that has different words inside the word.insert. gutter.pad and gutter.pad.txt are used to separate the gutter from the text and usually end up resolving to a space. Most of the functions defined here default to identity, but you are given the flexibility to fully format the diff. See StyleFuns and StyleText for a full listing of the adjustable elements. In side-by-side mode there are two “lines” per screen line, each with the structure described here. The structure described here may change in the future.

HTML Styles

If you use a Style that inherits from StyleHtml the diff will be wrapped in HTML tags, styled with CSS, and output to a web browser by the pager. The HTML output will be a full stand-alone HTML page with references to the built-in cascading style sheet. If the pager is disabled or is not PagerBrowser then only the raw HTML for the diff is output. Should you want to capture the HTML output for use elsewhere, you can do so by using as.character on the return value of the diff* methods. If you want the raw HTML without any of the headers and css in

Examples

Run this code

## Create a new style based on existing style by changing
## gutter symbols and guide color; see `?StyleFuns` and
## `?StyleText` for a full list of adjustable elements
my.style <- StyleAnsi8NeutralYb()
my.style   ## `show` method gives you a preview of the style
my.style@text@gutter.insert <- "+++"
my.style@text@gutter.delete <- "---"
my.style@funs@text.guide <- crayon::green
my.style   ## Notice gutters and guide color

## Provide a custom style sheet; here we assume there is a style sheet at
## `HOME/web/mycss.css`
## Not run: 
# my.css <- file.path(path.expand("~"), "web", "mycss.css")
# diffPrint(1:5, 2:6, style=StyleHtmlLightYb(css=my.css))
# ## End(Not run)
## Return only the raw HTML without any of the headers
as.character(
  diffPrint(1:5, 2:6, style=StyleHtmlLightYb(html.output="diff.only"))
)

Run the code above in your browser using DataLab