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.
StyleFuns
object that contains all the functions
represented aboveStyleText
object that contains the non-content
text used by the diff (e.g. gutter.insert.txt
)Pager
to use" "
) to prevent lines from
collapsingPager
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.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
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.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.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
tags use html.ouput="diff.only"
when you
instantiate the Style
object (see examples), or disable the
Pager
. Another option is html.output="diff.w.style"
which will add
tags with the CSS, but without wrapping those
in
tags. This last option results in illegal HTML with a
block inside the
block, but appears to work and
is useful if you want to embed HTML someplace but do not have access to the
headers. For compatibility with RStudio server sessions the styles are always included
directly within style
tags rather than in an external style sheet. Unlike with ANSI styles, you should not modify the styling functions in the
@funs
slot of the Style
object. Instead, provide your own
styles. See diffobj_css()
for the predefined styles. The styles are
structured so that they are applied to any element within a container of a
particular class. To provide your own custom CSS style sheet you may:
css
slot of a StyleHtml
object,
and pass that object as the value for the style
parameter for the
diff*
methods (see example)
PaletteOfStyles
StyleHtml
object you may want to modify
the slot @funs@container
. This slot contains a function that is
applied to the entire diff output. For example, StyleHtmlLightRgb
uses @funs@container <- cont_f("light", "rgb")
. cont_f
returns
a function that accepts a character vector as an argument and returns
that value wrapped in a DIV
block with class
"diffobj_container light rgb". This allows the CSS style sheet to
target the Diff
elements with the correct styles.## 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