PaletteOfStyles-class: Class for Tracking Default Styles by Style Type
In diffobj: Diffs for R Objects

Description An Array of Styles Dimensions Methods Structural Details Examples

Provides a mechanism for specifying a style based on the style properties along dimensions of format, brightness, and color. This allows a user to request a style that meets a certain description (e.g. a “light” scheme in “ansi256” format), without having to provide a specific Style object.

A PaletteOfStyles object is an “array” containing either “classRepresentation” objects that extend StyleHtml or are instances of objects that inherit from StyleHtml. The diff* methods then pick an object/class from this array based on the values of the format, brightness, and color.mode parameters.

For the most part the distinction between actual Style objects vs “classRepresentation” ones is academic, except that with the latter you can control the instantiation by providing a parameter list as the style argument to the diff* methods. This is not an option with already instantiated objects. See examples.

There are three general orthogonal dimensions of styles that can be used when rendering diffs: the type of format, the “brightness” of the output, and whether the colors used are distinguishable if you assume reds and greens are not distinguishable. Defaults for the intersections each of these dimensions are encoded as a three dimensional list. This list is just an atomic vector of type “list” with a length 3 dim attribute.

The array/list dimensions are:

format: the format type, one of “raw”, “ansi8”, “ansi256”, or “html”
brightness: whether the colors are bright or not, which allows user to chose a scheme that is compatible with their console, one of: “light”, “dark”, “normal”
color.mode: “rgb” for full color or “yb” for dichromats (yb stands for Yellow Blue).

Each of these dimensions can be specified directly via the corresponding parameters to the diff* methods.

PaletteOfStyles objects have The following methods implemented:

[, [<-, [[
show
summary
dimnames

The array/list is stored in the data slot of PaletteOfStyles objects. Subsetting methods are provided so you may operate directly on the S4 object as you would on a regular array.

The array/list must be fully populated with objects that are or inherit Style, or are “classRepresentation” objects (i.e. those of the type returned by getClassDef) that extend Style. By default the array is populated only with “classRepresentation” objects as that allows the list form of the style parameter to the diff* methods. If there is a particular combination of coordinates that does not have a corresponding defined style a reasonable substitution must be provided. For example, this package only defines “light” HTML styles, so it simply uses that style for all the possible brightness values.

There is no explicit check that the objects in the list comply with the descriptions implied by their coordinates, although the default object provided by the package does comply for the most part. One check that is carried out is that any element that has a “html” value in the format dimension extends StyleHtml.

While the list may only have the three dimensions described, you can add values to the dimensions provided the values described above are the first ones in each of their corresponding dimensions. For example, if you wanted to allow for styles that would render in grid graphics, you could generate a default list with a “"grid"” value appended to the values of the format dimension.

## Not run: 
## Look at all "ansi256" styles (assumes compatible terminal)
PaletteOfStyles()["ansi256",,]

## End(Not run)
## Generate the default style object palette, and replace
## the ansi256 / light / rgb style with our modified one
## which for illustrative purposes is the raw style
my.pal <- PaletteOfStyles()
my.style <- StyleRaw()   # See `?Style` for custom styles
my.style@funs@word.delete <- function(x) sprintf("--%s--", x)
my.pal["ansi256", "light", "rgb"] <- list(my.style) # note `list()`
## Output has no format now for format/color.mode/brightness
## we modified ...
## `pager="off"` for CRAN compliance; you may omit in normal use
diffPrint(
   1:3, 2:5, format="ansi256", color.mode="rgb", brightness="light",
   palette.of.styles=my.pal, pager="off", disp.width=80
)
## If so desired, set our new style palette as the default
## one; could also pass directly as argument to `diff*` funs
## Not run: 
options(diffobj.palette=defs)

## End(Not run)