Style-class: Customize Appearance of Diff

Description

S4 objects that expose the formatting controls for Diff objects. Many predefined 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)

summary

a StyleSummary object that contains formatting functions and other meta data for rendering summaries

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 the object to render (either a Diff or a DiffSummary object), and the text representation of that object 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 object themselves are passed along to provide information about the paging device and other contextual data to the function.

escape.html.entities

(StyleHtml objects only) TRUE (default) or FALSE, whether to escape HTML entities in the input

scale

(StyleHtml objects only) TRUE (default) or FALSE, whether to scale HTML output to fit to the viewport

css

(StyleHtml objects only) path to file containing CSS styles to style HTML output with

(StyleHtml objects only) path to file containing Javascript used for scaling output to viewports.

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. If you wish to tweak an auto-selected style rather than explicitly specify one, pass a parameter list instead of a Style objects as the style parameter to the diff* methods (see examples). 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 those classes are re-used for all possible brightness values, and the 8 color ANSI neutral classes are used for the 256 color neutral selections as well. 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 getOption("viewer") if your IDE supports it (e.g. Rstudio), or directly to the browser otherwise, assuming that the default Pager or a correctly configured pager that inherits from PagerBrowser is in effect. Otherwise, the raw HTML will be output to your terminal. By default HTML output sent to the viewer/browser is a full stand-alone webpage with CSS styles to format and color the diff, and JS code to handle scaling. The CSS and JS is read from the default files and injected into the HTML to simplify packaging of the output. You can customize the CSS and JS by using the css and js arguments respectively, but read the rest of this documentation section if you plan on doing so. 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, CSS, and JS use html.ouput="diff.only" when you instantiate the StyleHtml object (see examples), or disable the Pager. Another option is html.output="diff.w.style" which will add

Modifying Style Parameters Directly

Often you will want to specify some of the style parameters (e.g. scale) while still relying on the default style selection to pick the specific style. You can do so by passing a list to the style parameter of the diff* methods. See examples.

New Classes

You can in theory create entirely new classes that extent Style. For example you could generate a class that renders the diff in grid graphics. Note however that we have not tested such extensions and it is possible there is some embedded code that will misbehave with such a new class.

Examples

Run this code

## Not run: 
# ## 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`
# my.css <- file.path(path.expand("~"), "web", "mycss.css")
# diffPrint(1:5, 2:6, style=StyleHtmlLightYb(css=my.css))
# 
# ## Turn of scaling; notice how we pass a list to `style`
# ## and we do not need to specify a specific style
# diffPrint(letters, letters[-5], format="html", style=list(scale=FALSE))
# 
# ## Alternatively we can do the same by specifying a style, but we must
# ## give an exact html style instead of relying on preferences to pick
# ## one for us
# my.style <- StyleHtmlLightYb(scale=FALSE)
# diffPrint(letters, letters[-5], style=my.style)
# ## End(Not run)
## Return only the raw HTML without any of the headers
as.character(
  diffPrint(1:5, 2:6, format="html", style=list(html.output="diff.only"))
)

Run the code above in your browser using DataLab