Package 'diffobj'

Diff object

subsetting index, must be numeric

integer(1L), the size for the resulting object

unused, for compatibility with generics

a PaletteOfStyles object

numeric, or character corresponding to a valid style format

numeric, or character corresponding to a valid style brightness

pass a numeric or character corresponding to a valid color.mode

a list of Style class or Style objects

TRUE or FALSE, whether to drop dimensions, defaults to FALSE, which is different than generic

passed on to generic

a Diff object

unused, for compatibility with generic

unused, for compatibility with generic

a DiffSummary object

not used, for compatibility with generic

integer(1L), positive, set to zero to allow any context

integer(1L), set to negative to allow any context

the reference object

the object being compared to target

unused, for compatibility of methods with generics

character(1L), one of:

• “unified”: diff mode used by git diff

• “sidebyside”: line up the differences side by side

• “context”: show the target and current hunks in their entirety; this mode takes up a lot of screen space but makes it easier to see what the objects actually look like

• “auto”: default mode; pick one of the above, will favor “sidebyside” unless getOption("width") is less than 80, or in diffPrint and objects are dimensioned and do not fit side by side, or in diffChr, diffDeparse, diffFile and output does not fit in side by side without wrapping

integer(1L) how many lines of context are shown on either side of differences (defaults to 2). Set to -1L to allow as many as there are. Set to “auto” to display as many as 10 lines or as few as 1 depending on whether total screen lines fit within the number of lines specified in line.limit. Alternatively pass the return value of auto_context to fine tune the parameters of the auto context calculation.

character(1L), controls the diff output format, one of:

• “auto”: to select output format based on terminal capabilities; will attempt to use one of the ANSI formats if they appear to be supported, and if not or if you are in the Rstudio console it will attempt to use HTML and browser output if in interactive mode.

• “raw”: plain text

• “ansi8”: color and format diffs using basic ANSI escape sequences

• “ansi256”: like “ansi8”, except using the full range of ANSI formatting options

• “html”: color and format using HTML markup; the resulting string is processed with enc2utf8 when output as a full web page (see docs for html.output under Style).

Defaults to “auto”. See palette.of.styles for details on customization, style for full control of output format. See 'pager' parameter for more discussion of Rstudio behavior.

character, one of “light”, “dark”, “neutral”, useful for adjusting color scheme to light or dark terminals. “neutral” by default. See PaletteOfStyles for details and limitations. Advanced: you may specify brightness as a function of format. For example, if you typically wish to use a “dark” color scheme, except for when in “html” format when you prefer the “light” scheme, you may use c("dark", html="light") as the value for this parameter. This is particularly useful if format is set to “auto” or if you want to specify a default value for this parameter via options. Any names you use should correspond to a format. You must have one unnamed value which will be used as the default for all formats that are not explicitly specified.

character, one of “rgb” or “yb”. Defaults to “yb”. “yb” stands for “Yellow-Blue” for color schemes that rely primarily on those colors to style diffs. Those colors can be easily distinguished by individuals with limited red-green color sensitivity. See PaletteOfStyles for details and limitations. Also offers the same advanced usage as the brightness parameter.

TRUE (default) or FALSE, whether to run a secondary word diff on the in-hunk differences. For atomic vectors setting this to FALSE could make the diff slower (see the unwrap.atomic parameter). For other uses, particularly with diffChr setting this to FALSE can substantially improve performance.

one of “auto” (default), “on”, “off”, a Pager object, or a list; controls whether and how a pager is used to display the diff output. If you require a particular pager behavior you must use a Pager object, or “off” to turn off the pager. All other settings will interact with other parameters such as format, style, as well as with your system capabilities in order to select the pager expected to be most useful.

“auto” and “on” are the same, except that in non-interactive mode “auto” is equivalent to “off”. “off” will always send output to the console. If “on”, whether the output actually gets routed to the pager depends on the pager threshold setting (see Pager). The default behavior is to use the pager associated with the Style object. The Style object is itself is determined by the format or style parameters.

Depending on your system configuration different styles and corresponding pagers will get selected, unless you specify a Pager object directly. On a system with a system pager that supports ANSI CSI SGR colors, the pager will only trigger if the output is taller than one window. If the system pager is not known to support ANSI colors then the output will be sent as HTML to the IDE viewer if available or to the web browser if not. Even though Rstudio now supports ANSI CSI SGR at the console output is still formatted as HTML and sent to the IDE viewer. Partly this is for continuity of behavior, but also because the default Rstudio pager does not support ANSI CSI SGR, at least as of this writing.

If pager is a list, then the same as with “on”, except that the Pager object associated with the selected Style object is re-instantiated with the union of the list elements and the existing settings of that Pager. The list should contain named elements that correspond to the Pager instantiation parameters. The names must be specified in full as partial parameter matching will not be carried out because the pager is re-instantiated with new.

See Pager, Style, and PaletteOfStyles for more details and for instructions on how to modify the default behavior.

TRUE (default), FALSE, or a function that accepts at least two arguments and requires no more than two arguments. Guides are additional context lines that are not strictly part of a hunk, but provide important contextual data (e.g. column headers). If TRUE, the context lines are shown in addition to the normal diff output, typically in a different color to indicate they are not part of the hunk. If a function, the function should accept as the first argument the object being diffed, and the second the character representation of the object. The function should return the indices of the elements of the character representation that should be treated as guides. See guides for more details.

TRUE (default), FALSE, or a function that accepts at least two arguments and requires no more than two arguments. Function should compute for each line in captured output what portion of those lines should be diffed. By default, this is used to remove row meta data differences (e.g. [1,]) so they alone do not show up as differences in the diff. See trim for more details.

TRUE (default) or FALSE, if TRUE will check whether target and/or current point to a file that can be read with readRDS and if so, loads the R object contained in the file and carries out the diff on the object instead of the original argument. Currently there is no mechanism for specifying additional arguments to readRDS

TRUE (default) or FALSE. Relevant primarily for diffPrint, if TRUE, and word.diff is also TRUE, and both target and current are unnamed one-dimension atomics , the vectors are unwrapped and diffed element by element, and then re-wrapped. Since diffPrint is fundamentally a line diff, the re-wrapped lines are lined up in a manner that is as consistent as possible with the unwrapped diff. Lines that contain the location of the word differences will be paired up. Since the vectors may well be wrapped with different periodicities this will result in lines that are paired up that look like they should not be paired up, though the locations of the differences should be. If is entirely possible that setting this parameter to FALSE will result in a slower diff. This happens if two vectors are actually fairly similar, but their line representations are not. For example, in comparing 1:100 to c(100, 1:99), there is really only one difference at the “word” level, but every screen line is different. diffChr will also do the unwrapping if it is given a character vector that contains output that looks like the atomic vectors described above. This is a bug, but as the functionality could be useful when diffing e.g. capture.output data, we now declare it a feature.

integer(1L), number of differences (default 50000L) after which we abandon the O(n^2) diff algorithm in favor of a naive O(n) one. Set to -1L to stick to the original algorithm up to the maximum allowed (~INT_MAX/4).

integer(1L) number of display columns to take up; note that in “sidebyside” mode the effective display width is half this number (set to 0L to use default widths which are getOption("width") for normal styles and 80L for HTML styles. Future versions of diffobj may change this to larger values for two dimensional objects for better diffs (see details).

TRUE or FALSE, whether to consider differences in horizontal whitespace (i.e. spaces and tabs) as differences (defaults to TRUE).

TRUE or FALSE, whether modify input strings that contain tabs and carriage returns in such a way that they display as they would with those characters, but without using those characters (defaults to TRUE). The conversion assumes that tab stops are spaced evenly eight characters apart on the terminal. If this is not the case you may specify the tab stops explicitly with tab.stops.

integer, what tab stops to use when converting hard tabs to spaces. If not integer will be coerced to integer (defaults to 8L). You may specify more than one tab stop. If display width exceeds that addressable by your tab stops the last tab stop will be repeated.

integer(2L) or integer(1L), if length 1 how many lines of output to show, where -1 means no limit. If length 2, the first value indicates the threshold of screen lines to begin truncating output, and the second the number of lines to truncate to, which should be fewer than the threshold. Note that this parameter is implemented on a best-efforts basis and should not be relied on to produce the exact number of lines requested. In particular do not expect it to work well for for values small enough that the banner portion of the diff would have to be trimmed. If you want a specific number of lines use [ or head / tail. One advantage of line.limit over these other options is that you can combine it with context="auto" and auto max.level selection (the latter for diffStr), which allows the diff to dynamically adjust to make best use of the available display lines. [, head, and tail just subset the text of the output.

integer(2L) or integer (1L), how many diff hunks to show. Behaves similarly to line.limit. How many hunks are in a particular diff is a function of how many differences, and also how much context is used since context can cause two hunks to bleed into each other and become one.

numeric(1L) between 0 and 1, proportion of words in a line of target that must be matched in a line of current in the same hunk for those lines to be paired up when displayed (defaults to 0.25), or an AlignThreshold object. Set to 1 to turn off alignment which will cause all lines in a hunk from target to show up first, followed by all lines from current. Note that in order to be aligned lines must meet the threshold and have at least 3 matching alphanumeric characters (see AlignThreshold for details).

“auto”, a Style object, or a list. “auto” by default. If a Style object, will override the the format, brightness, and color.mode parameters. The Style object provides full control of diff output styling. If a list, then the same as “auto”, except that if the auto-selected Style requires instantiation (see PaletteOfStyles), then the list contents will be used as arguments when instantiating the style object. See Style for more details, in particular the examples.

PaletteOfStyles object; advanced usage, contains all the Style objects or “classRepresentation” objects extending Style that are selected by specifying the format, brightness, and color.mode parameters. See PaletteOfStyles for more details.

an environment to use as the evaluation frame for the print/show/str, calls and for diffObj, the evaluation frame for the diffPrint / diffStr calls. Defaults to the return value of par_frame.

TRUE or FALSE whether the function is being run in interactive mode, defaults to the return value of interactive. If in interactive mode, pager will be used if pager is “auto”, and if ANSI styles are not supported and style is “auto”, output will be send to viewer/browser as HTML.

integer(1L) how many ANSI colors are supported by the terminal. This variable is provided for when crayon::num_colors does not properly detect how many ANSI colors are supported by your terminal. Defaults to return value of crayon::num_colors and should be 8 or 256 to allow ANSI colors, or any other number to disallow them. This only impacts output format selection when style and format are both set to “auto”.

character(1L), language, or NULL, used to generate the text to display ahead of the diff section representing the target output. If NULL will use the deparsed target expression, if language, will use the language as it would the target expression, if character(1L), will use the string with no modifications. The language mode is provided because diffStr modifies the expression prior to display (e.g. by wrapping it in a call to str). Note that it is possible in some cases that the substituted value of target actually is character(1L), but if you provide a character(1L) value here it will be assumed you intend to use that value literally.

character(1L) like tar.banner, but for current

TRUE, FALSE, or NULL (default), whether to strip ANSI CSI SGR sequences prior to comparison and for display of diff. If NULL, resolves to TRUE if 'style' resolves to an ANSI formatted diff, and FALSE otherwise. The default behavior is to avoid confusing diffs where the original SGR and the SGR added by the diff are mixed together.

TRUE, FALSE, or NULL (default), whether to assume the standard output device supports ANSI CSI SGR sequences. If TRUE, strings will be manipulated accounting for the SGR sequences. If NULL, resolves to TRUE if 'style' resolves to an ANSI formatted diff, and to 'crayon::has_color()' otherwise. This only controls how the strings are manipulated, not whether SGR is added to format the diff, which is controlled by the 'style' parameter. This parameter is exposed for the rare cases where you might wish to control string manipulation behavior directly.

list additional arguments to pass on to the functions used to create text representation of the objects to diff (e.g. print, str, etc.)

character(1L) or file connection with read capability; if character should point to a CSV file

like target

unused, for compatibility of methods with generics

character(1L), one of:

• “unified”: diff mode used by git diff

• “sidebyside”: line up the differences side by side

• “context”: show the target and current hunks in their entirety; this mode takes up a lot of screen space but makes it easier to see what the objects actually look like

• “auto”: default mode; pick one of the above, will favor “sidebyside” unless getOption("width") is less than 80, or in diffPrint and objects are dimensioned and do not fit side by side, or in diffChr, diffDeparse, diffFile and output does not fit in side by side without wrapping

integer(1L) how many lines of context are shown on either side of differences (defaults to 2). Set to -1L to allow as many as there are. Set to “auto” to display as many as 10 lines or as few as 1 depending on whether total screen lines fit within the number of lines specified in line.limit. Alternatively pass the return value of auto_context to fine tune the parameters of the auto context calculation.

character(1L), controls the diff output format, one of:

• “auto”: to select output format based on terminal capabilities; will attempt to use one of the ANSI formats if they appear to be supported, and if not or if you are in the Rstudio console it will attempt to use HTML and browser output if in interactive mode.

• “raw”: plain text

• “ansi8”: color and format diffs using basic ANSI escape sequences

• “ansi256”: like “ansi8”, except using the full range of ANSI formatting options

• “html”: color and format using HTML markup; the resulting string is processed with enc2utf8 when output as a full web page (see docs for html.output under Style).

Defaults to “auto”. See palette.of.styles for details on customization, style for full control of output format. See 'pager' parameter for more discussion of Rstudio behavior.

character, one of “light”, “dark”, “neutral”, useful for adjusting color scheme to light or dark terminals. “neutral” by default. See PaletteOfStyles for details and limitations. Advanced: you may specify brightness as a function of format. For example, if you typically wish to use a “dark” color scheme, except for when in “html” format when you prefer the “light” scheme, you may use c("dark", html="light") as the value for this parameter. This is particularly useful if format is set to “auto” or if you want to specify a default value for this parameter via options. Any names you use should correspond to a format. You must have one unnamed value which will be used as the default for all formats that are not explicitly specified.

character, one of “rgb” or “yb”. Defaults to “yb”. “yb” stands for “Yellow-Blue” for color schemes that rely primarily on those colors to style diffs. Those colors can be easily distinguished by individuals with limited red-green color sensitivity. See PaletteOfStyles for details and limitations. Also offers the same advanced usage as the brightness parameter.

TRUE (default) or FALSE, whether to run a secondary word diff on the in-hunk differences. For atomic vectors setting this to FALSE could make the diff slower (see the unwrap.atomic parameter). For other uses, particularly with diffChr setting this to FALSE can substantially improve performance.

one of “auto” (default), “on”, “off”, a Pager object, or a list; controls whether and how a pager is used to display the diff output. If you require a particular pager behavior you must use a Pager object, or “off” to turn off the pager. All other settings will interact with other parameters such as format, style, as well as with your system capabilities in order to select the pager expected to be most useful.

“auto” and “on” are the same, except that in non-interactive mode “auto” is equivalent to “off”. “off” will always send output to the console. If “on”, whether the output actually gets routed to the pager depends on the pager threshold setting (see Pager). The default behavior is to use the pager associated with the Style object. The Style object is itself is determined by the format or style parameters.

Depending on your system configuration different styles and corresponding pagers will get selected, unless you specify a Pager object directly. On a system with a system pager that supports ANSI CSI SGR colors, the pager will only trigger if the output is taller than one window. If the system pager is not known to support ANSI colors then the output will be sent as HTML to the IDE viewer if available or to the web browser if not. Even though Rstudio now supports ANSI CSI SGR at the console output is still formatted as HTML and sent to the IDE viewer. Partly this is for continuity of behavior, but also because the default Rstudio pager does not support ANSI CSI SGR, at least as of this writing.

If pager is a list, then the same as with “on”, except that the Pager object associated with the selected Style object is re-instantiated with the union of the list elements and the existing settings of that Pager. The list should contain named elements that correspond to the Pager instantiation parameters. The names must be specified in full as partial parameter matching will not be carried out because the pager is re-instantiated with new.

See Pager, Style, and PaletteOfStyles for more details and for instructions on how to modify the default behavior.

TRUE (default), FALSE, or a function that accepts at least two arguments and requires no more than two arguments. Guides are additional context lines that are not strictly part of a hunk, but provide important contextual data (e.g. column headers). If TRUE, the context lines are shown in addition to the normal diff output, typically in a different color to indicate they are not part of the hunk. If a function, the function should accept as the first argument the object being diffed, and the second the character representation of the object. The function should return the indices of the elements of the character representation that should be treated as guides. See guides for more details.

TRUE (default), FALSE, or a function that accepts at least two arguments and requires no more than two arguments. Function should compute for each line in captured output what portion of those lines should be diffed. By default, this is used to remove row meta data differences (e.g. [1,]) so they alone do not show up as differences in the diff. See trim for more details.

TRUE (default) or FALSE, if TRUE will check whether target and/or current point to a file that can be read with readRDS and if so, loads the R object contained in the file and carries out the diff on the object instead of the original argument. Currently there is no mechanism for specifying additional arguments to readRDS

TRUE (default) or FALSE. Relevant primarily for diffPrint, if TRUE, and word.diff is also TRUE, and both target and current are unnamed one-dimension atomics , the vectors are unwrapped and diffed element by element, and then re-wrapped. Since diffPrint is fundamentally a line diff, the re-wrapped lines are lined up in a manner that is as consistent as possible with the unwrapped diff. Lines that contain the location of the word differences will be paired up. Since the vectors may well be wrapped with different periodicities this will result in lines that are paired up that look like they should not be paired up, though the locations of the differences should be. If is entirely possible that setting this parameter to FALSE will result in a slower diff. This happens if two vectors are actually fairly similar, but their line representations are not. For example, in comparing 1:100 to c(100, 1:99), there is really only one difference at the “word” level, but every screen line is different. diffChr will also do the unwrapping if it is given a character vector that contains output that looks like the atomic vectors described above. This is a bug, but as the functionality could be useful when diffing e.g. capture.output data, we now declare it a feature.

integer(1L), number of differences (default 50000L) after which we abandon the O(n^2) diff algorithm in favor of a naive O(n) one. Set to -1L to stick to the original algorithm up to the maximum allowed (~INT_MAX/4).

integer(1L) number of display columns to take up; note that in “sidebyside” mode the effective display width is half this number (set to 0L to use default widths which are getOption("width") for normal styles and 80L for HTML styles. Future versions of diffobj may change this to larger values for two dimensional objects for better diffs (see details).

TRUE or FALSE, whether to consider differences in horizontal whitespace (i.e. spaces and tabs) as differences (defaults to TRUE).

TRUE or FALSE, whether modify input strings that contain tabs and carriage returns in such a way that they display as they would with those characters, but without using those characters (defaults to TRUE). The conversion assumes that tab stops are spaced evenly eight characters apart on the terminal. If this is not the case you may specify the tab stops explicitly with tab.stops.

integer, what tab stops to use when converting hard tabs to spaces. If not integer will be coerced to integer (defaults to 8L). You may specify more than one tab stop. If display width exceeds that addressable by your tab stops the last tab stop will be repeated.

integer(2L) or integer(1L), if length 1 how many lines of output to show, where -1 means no limit. If length 2, the first value indicates the threshold of screen lines to begin truncating output, and the second the number of lines to truncate to, which should be fewer than the threshold. Note that this parameter is implemented on a best-efforts basis and should not be relied on to produce the exact number of lines requested. In particular do not expect it to work well for for values small enough that the banner portion of the diff would have to be trimmed. If you want a specific number of lines use [ or head / tail. One advantage of line.limit over these other options is that you can combine it with context="auto" and auto max.level selection (the latter for diffStr), which allows the diff to dynamically adjust to make best use of the available display lines. [, head, and tail just subset the text of the output.

integer(2L) or integer (1L), how many diff hunks to show. Behaves similarly to line.limit. How many hunks are in a particular diff is a function of how many differences, and also how much context is used since context can cause two hunks to bleed into each other and become one.

numeric(1L) between 0 and 1, proportion of words in a line of target that must be matched in a line of current in the same hunk for those lines to be paired up when displayed (defaults to 0.25), or an AlignThreshold object. Set to 1 to turn off alignment which will cause all lines in a hunk from target to show up first, followed by all lines from current. Note that in order to be aligned lines must meet the threshold and have at least 3 matching alphanumeric characters (see AlignThreshold for details).

“auto”, a Style object, or a list. “auto” by default. If a Style object, will override the the format, brightness, and color.mode parameters. The Style object provides full control of diff output styling. If a list, then the same as “auto”, except that if the auto-selected Style requires instantiation (see PaletteOfStyles), then the list contents will be used as arguments when instantiating the style object. See Style for more details, in particular the examples.

PaletteOfStyles object; advanced usage, contains all the Style objects or “classRepresentation” objects extending Style that are selected by specifying the format, brightness, and color.mode parameters. See PaletteOfStyles for more details.

an environment to use as the evaluation frame for the print/show/str, calls and for diffObj, the evaluation frame for the diffPrint / diffStr calls. Defaults to the return value of par_frame.

TRUE or FALSE whether the function is being run in interactive mode, defaults to the return value of interactive. If in interactive mode, pager will be used if pager is “auto”, and if ANSI styles are not supported and style is “auto”, output will be send to viewer/browser as HTML.

integer(1L) how many ANSI colors are supported by the terminal. This variable is provided for when crayon::num_colors does not properly detect how many ANSI colors are supported by your terminal. Defaults to return value of crayon::num_colors and should be 8 or 256 to allow ANSI colors, or any other number to disallow them. This only impacts output format selection when style and format are both set to “auto”.

character(1L), language, or NULL, used to generate the text to display ahead of the diff section representing the target output. If NULL will use the deparsed target expression, if language, will use the language as it would the target expression, if character(1L), will use the string with no modifications. The language mode is provided because diffStr modifies the expression prior to display (e.g. by wrapping it in a call to str). Note that it is possible in some cases that the substituted value of target actually is character(1L), but if you provide a character(1L) value here it will be assumed you intend to use that value literally.

character(1L) like tar.banner, but for current

TRUE, FALSE, or NULL (default), whether to strip ANSI CSI SGR sequences prior to comparison and for display of diff. If NULL, resolves to TRUE if 'style' resolves to an ANSI formatted diff, and FALSE otherwise. The default behavior is to avoid confusing diffs where the original SGR and the SGR added by the diff are mixed together.

TRUE, FALSE, or NULL (default), whether to assume the standard output device supports ANSI CSI SGR sequences. If TRUE, strings will be manipulated accounting for the SGR sequences. If NULL, resolves to TRUE if 'style' resolves to an ANSI formatted diff, and to 'crayon::has_color()' otherwise. This only controls how the strings are manipulated, not whether SGR is added to format the diff, which is controlled by the 'style' parameter. This parameter is exposed for the rare cases where you might wish to control string manipulation behavior directly.

list additional arguments to pass on to the functions used to create text representation of the objects to diff (e.g. print, str, etc.)

the reference object

the object being compared to target

unused, for compatibility of methods with generics

character(1L), one of:

• “unified”: diff mode used by git diff

• “sidebyside”: line up the differences side by side

• “context”: show the target and current hunks in their entirety; this mode takes up a lot of screen space but makes it easier to see what the objects actually look like

• “auto”: default mode; pick one of the above, will favor “sidebyside” unless getOption("width") is less than 80, or in diffPrint and objects are dimensioned and do not fit side by side, or in diffChr, diffDeparse, diffFile and output does not fit in side by side without wrapping

integer(1L) how many lines of context are shown on either side of differences (defaults to 2). Set to -1L to allow as many as there are. Set to “auto” to display as many as 10 lines or as few as 1 depending on whether total screen lines fit within the number of lines specified in line.limit. Alternatively pass the return value of auto_context to fine tune the parameters of the auto context calculation.

character(1L), controls the diff output format, one of:

• “auto”: to select output format based on terminal capabilities; will attempt to use one of the ANSI formats if they appear to be supported, and if not or if you are in the Rstudio console it will attempt to use HTML and browser output if in interactive mode.

• “raw”: plain text

• “ansi8”: color and format diffs using basic ANSI escape sequences

• “ansi256”: like “ansi8”, except using the full range of ANSI formatting options

• “html”: color and format using HTML markup; the resulting string is processed with enc2utf8 when output as a full web page (see docs for html.output under Style).

Defaults to “auto”. See palette.of.styles for details on customization, style for full control of output format. See 'pager' parameter for more discussion of Rstudio behavior.

character, one of “light”, “dark”, “neutral”, useful for adjusting color scheme to light or dark terminals. “neutral” by default. See PaletteOfStyles for details and limitations. Advanced: you may specify brightness as a function of format. For example, if you typically wish to use a “dark” color scheme, except for when in “html” format when you prefer the “light” scheme, you may use c("dark", html="light") as the value for this parameter. This is particularly useful if format is set to “auto” or if you want to specify a default value for this parameter via options. Any names you use should correspond to a format. You must have one unnamed value which will be used as the default for all formats that are not explicitly specified.

character, one of “rgb” or “yb”. Defaults to “yb”. “yb” stands for “Yellow-Blue” for color schemes that rely primarily on those colors to style diffs. Those colors can be easily distinguished by individuals with limited red-green color sensitivity. See PaletteOfStyles for details and limitations. Also offers the same advanced usage as the brightness parameter.

TRUE (default) or FALSE, whether to run a secondary word diff on the in-hunk differences. For atomic vectors setting this to FALSE could make the diff slower (see the unwrap.atomic parameter). For other uses, particularly with diffChr setting this to FALSE can substantially improve performance.

one of “auto” (default), “on”, “off”, a Pager object, or a list; controls whether and how a pager is used to display the diff output. If you require a particular pager behavior you must use a Pager object, or “off” to turn off the pager. All other settings will interact with other parameters such as format, style, as well as with your system capabilities in order to select the pager expected to be most useful.

“auto” and “on” are the same, except that in non-interactive mode “auto” is equivalent to “off”. “off” will always send output to the console. If “on”, whether the output actually gets routed to the pager depends on the pager threshold setting (see Pager). The default behavior is to use the pager associated with the Style object. The Style object is itself is determined by the format or style parameters.

Depending on your system configuration different styles and corresponding pagers will get selected, unless you specify a Pager object directly. On a system with a system pager that supports ANSI CSI SGR colors, the pager will only trigger if the output is taller than one window. If the system pager is not known to support ANSI colors then the output will be sent as HTML to the IDE viewer if available or to the web browser if not. Even though Rstudio now supports ANSI CSI SGR at the console output is still formatted as HTML and sent to the IDE viewer. Partly this is for continuity of behavior, but also because the default Rstudio pager does not support ANSI CSI SGR, at least as of this writing.

If pager is a list, then the same as with “on”, except that the Pager object associated with the selected Style object is re-instantiated with the union of the list elements and the existing settings of that Pager. The list should contain named elements that correspond to the Pager instantiation parameters. The names must be specified in full as partial parameter matching will not be carried out because the pager is re-instantiated with new.

See Pager, Style, and PaletteOfStyles for more details and for instructions on how to modify the default behavior.

TRUE (default), FALSE, or a function that accepts at least two arguments and requires no more than two arguments. Guides are additional context lines that are not strictly part of a hunk, but provide important contextual data (e.g. column headers). If TRUE, the context lines are shown in addition to the normal diff output, typically in a different color to indicate they are not part of the hunk. If a function, the function should accept as the first argument the object being diffed, and the second the character representation of the object. The function should return the indices of the elements of the character representation that should be treated as guides. See guides for more details.

TRUE (default), FALSE, or a function that accepts at least two arguments and requires no more than two arguments. Function should compute for each line in captured output what portion of those lines should be diffed. By default, this is used to remove row meta data differences (e.g. [1,]) so they alone do not show up as differences in the diff. See trim for more details.

TRUE (default) or FALSE, if TRUE will check whether target and/or current point to a file that can be read with readRDS and if so, loads the R object contained in the file and carries out the diff on the object instead of the original argument. Currently there is no mechanism for specifying additional arguments to readRDS

TRUE (default) or FALSE. Relevant primarily for diffPrint, if TRUE, and word.diff is also TRUE, and both target and current are unnamed one-dimension atomics , the vectors are unwrapped and diffed element by element, and then re-wrapped. Since diffPrint is fundamentally a line diff, the re-wrapped lines are lined up in a manner that is as consistent as possible with the unwrapped diff. Lines that contain the location of the word differences will be paired up. Since the vectors may well be wrapped with different periodicities this will result in lines that are paired up that look like they should not be paired up, though the locations of the differences should be. If is entirely possible that setting this parameter to FALSE will result in a slower diff. This happens if two vectors are actually fairly similar, but their line representations are not. For example, in comparing 1:100 to c(100, 1:99), there is really only one difference at the “word” level, but every screen line is different. diffChr will also do the unwrapping if it is given a character vector that contains output that looks like the atomic vectors described above. This is a bug, but as the functionality could be useful when diffing e.g. capture.output data, we now declare it a feature.

integer(1L), number of differences (default 50000L) after which we abandon the O(n^2) diff algorithm in favor of a naive O(n) one. Set to -1L to stick to the original algorithm up to the maximum allowed (~INT_MAX/4).

integer(1L) number of display columns to take up; note that in “sidebyside” mode the effective display width is half this number (set to 0L to use default widths which are getOption("width") for normal styles and 80L for HTML styles. Future versions of diffobj may change this to larger values for two dimensional objects for better diffs (see details).

TRUE or FALSE, whether to consider differences in horizontal whitespace (i.e. spaces and tabs) as differences (defaults to TRUE).

TRUE or FALSE, whether modify input strings that contain tabs and carriage returns in such a way that they display as they would with those characters, but without using those characters (defaults to TRUE). The conversion assumes that tab stops are spaced evenly eight characters apart on the terminal. If this is not the case you may specify the tab stops explicitly with tab.stops.

integer, what tab stops to use when converting hard tabs to spaces. If not integer will be coerced to integer (defaults to 8L). You may specify more than one tab stop. If display width exceeds that addressable by your tab stops the last tab stop will be repeated.

integer(2L) or integer(1L), if length 1 how many lines of output to show, where -1 means no limit. If length 2, the first value indicates the threshold of screen lines to begin truncating output, and the second the number of lines to truncate to, which should be fewer than the threshold. Note that this parameter is implemented on a best-efforts basis and should not be relied on to produce the exact number of lines requested. In particular do not expect it to work well for for values small enough that the banner portion of the diff would have to be trimmed. If you want a specific number of lines use [ or head / tail. One advantage of line.limit over these other options is that you can combine it with context="auto" and auto max.level selection (the latter for diffStr), which allows the diff to dynamically adjust to make best use of the available display lines. [, head, and tail just subset the text of the output.

integer(2L) or integer (1L), how many diff hunks to show. Behaves similarly to line.limit. How many hunks are in a particular diff is a function of how many differences, and also how much context is used since context can cause two hunks to bleed into each other and become one.

numeric(1L) between 0 and 1, proportion of words in a line of target that must be matched in a line of current in the same hunk for those lines to be paired up when displayed (defaults to 0.25), or an AlignThreshold object. Set to 1 to turn off alignment which will cause all lines in a hunk from target to show up first, followed by all lines from current. Note that in order to be aligned lines must meet the threshold and have at least 3 matching alphanumeric characters (see AlignThreshold for details).

“auto”, a Style object, or a list. “auto” by default. If a Style object, will override the the format, brightness, and color.mode parameters. The Style object provides full control of diff output styling. If a list, then the same as “auto”, except that if the auto-selected Style requires instantiation (see PaletteOfStyles), then the list contents will be used as arguments when instantiating the style object. See Style for more details, in particular the examples.

PaletteOfStyles object; advanced usage, contains all the Style objects or “classRepresentation” objects extending Style that are selected by specifying the format, brightness, and color.mode parameters. See PaletteOfStyles for more details.

an environment to use as the evaluation frame for the print/show/str, calls and for diffObj, the evaluation frame for the diffPrint / diffStr calls. Defaults to the return value of par_frame.

TRUE or FALSE whether the function is being run in interactive mode, defaults to the return value of interactive. If in interactive mode, pager will be used if pager is “auto”, and if ANSI styles are not supported and style is “auto”, output will be send to viewer/browser as HTML.

integer(1L) how many ANSI colors are supported by the terminal. This variable is provided for when crayon::num_colors does not properly detect how many ANSI colors are supported by your terminal. Defaults to return value of crayon::num_colors and should be 8 or 256 to allow ANSI colors, or any other number to disallow them. This only impacts output format selection when style and format are both set to “auto”.

character(1L), language, or NULL, used to generate the text to display ahead of the diff section representing the target output. If NULL will use the deparsed target expression, if language, will use the language as it would the target expression, if character(1L), will use the string with no modifications. The language mode is provided because diffStr modifies the expression prior to display (e.g. by wrapping it in a call to str). Note that it is possible in some cases that the substituted value of target actually is character(1L), but if you provide a character(1L) value here it will be assumed you intend to use that value literally.

character(1L) like tar.banner, but for current

TRUE, FALSE, or NULL (default), whether to strip ANSI CSI SGR sequences prior to comparison and for display of diff. If NULL, resolves to TRUE if 'style' resolves to an ANSI formatted diff, and FALSE otherwise. The default behavior is to avoid confusing diffs where the original SGR and the SGR added by the diff are mixed together.

TRUE, FALSE, or NULL (default), whether to assume the standard output device supports ANSI CSI SGR sequences. If TRUE, strings will be manipulated accounting for the SGR sequences. If NULL, resolves to TRUE if 'style' resolves to an ANSI formatted diff, and to 'crayon::has_color()' otherwise. This only controls how the strings are manipulated, not whether SGR is added to format the diff, which is controlled by the 'style' parameter. This parameter is exposed for the rare cases where you might wish to control string manipulation behavior directly.

list additional arguments to pass on to the functions used to create text representation of the objects to diff (e.g. print, str, etc.)

character(1L) or file connection with read capability; if character should point to a text file

like target

unused, for compatibility of methods with generics

character(1L), one of:

• “unified”: diff mode used by git diff

• “sidebyside”: line up the differences side by side

• “context”: show the target and current hunks in their entirety; this mode takes up a lot of screen space but makes it easier to see what the objects actually look like

• “auto”: default mode; pick one of the above, will favor “sidebyside” unless getOption("width") is less than 80, or in diffPrint and objects are dimensioned and do not fit side by side, or in diffChr, diffDeparse, diffFile and output does not fit in side by side without wrapping

integer(1L) how many lines of context are shown on either side of differences (defaults to 2). Set to -1L to allow as many as there are. Set to “auto” to display as many as 10 lines or as few as 1 depending on whether total screen lines fit within the number of lines specified in line.limit. Alternatively pass the return value of auto_context to fine tune the parameters of the auto context calculation.

character(1L), controls the diff output format, one of:

• “auto”: to select output format based on terminal capabilities; will attempt to use one of the ANSI formats if they appear to be supported, and if not or if you are in the Rstudio console it will attempt to use HTML and browser output if in interactive mode.

• “raw”: plain text

• “ansi8”: color and format diffs using basic ANSI escape sequences

• “ansi256”: like “ansi8”, except using the full range of ANSI formatting options

• “html”: color and format using HTML markup; the resulting string is processed with enc2utf8 when output as a full web page (see docs for html.output under Style).

Defaults to “auto”. See palette.of.styles for details on customization, style for full control of output format. See 'pager' parameter for more discussion of Rstudio behavior.

character, one of “light”, “dark”, “neutral”, useful for adjusting color scheme to light or dark terminals. “neutral” by default. See PaletteOfStyles for details and limitations. Advanced: you may specify brightness as a function of format. For example, if you typically wish to use a “dark” color scheme, except for when in “html” format when you prefer the “light” scheme, you may use c("dark", html="light") as the value for this parameter. This is particularly useful if format is set to “auto” or if you want to specify a default value for this parameter via options. Any names you use should correspond to a format. You must have one unnamed value which will be used as the default for all formats that are not explicitly specified.

character, one of “rgb” or “yb”. Defaults to “yb”. “yb” stands for “Yellow-Blue” for color schemes that rely primarily on those colors to style diffs. Those colors can be easily distinguished by individuals with limited red-green color sensitivity. See PaletteOfStyles for details and limitations. Also offers the same advanced usage as the brightness parameter.

TRUE (default) or FALSE, whether to run a secondary word diff on the in-hunk differences. For atomic vectors setting this to FALSE could make the diff slower (see the unwrap.atomic parameter). For other uses, particularly with diffChr setting this to FALSE can substantially improve performance.

one of “auto” (default), “on”, “off”, a Pager object, or a list; controls whether and how a pager is used to display the diff output. If you require a particular pager behavior you must use a Pager object, or “off” to turn off the pager. All other settings will interact with other parameters such as format, style, as well as with your system capabilities in order to select the pager expected to be most useful.

“auto” and “on” are the same, except that in non-interactive mode “auto” is equivalent to “off”. “off” will always send output to the console. If “on”, whether the output actually gets routed to the pager depends on the pager threshold setting (see Pager). The default behavior is to use the pager associated with the Style object. The Style object is itself is determined by the format or style parameters.

Depending on your system configuration different styles and corresponding pagers will get selected, unless you specify a Pager object directly. On a system with a system pager that supports ANSI CSI SGR colors, the pager will only trigger if the output is taller than one window. If the system pager is not known to support ANSI colors then the output will be sent as HTML to the IDE viewer if available or to the web browser if not. Even though Rstudio now supports ANSI CSI SGR at the console output is still formatted as HTML and sent to the IDE viewer. Partly this is for continuity of behavior, but also because the default Rstudio pager does not support ANSI CSI SGR, at least as of this writing.

If pager is a list, then the same as with “on”, except that the Pager object associated with the selected Style object is re-instantiated with the union of the list elements and the existing settings of that Pager. The list should contain named elements that correspond to the Pager instantiation parameters. The names must be specified in full as partial parameter matching will not be carried out because the pager is re-instantiated with new.

See Pager, Style, and PaletteOfStyles for more details and for instructions on how to modify the default behavior.

TRUE (default), FALSE, or a function that accepts at least two arguments and requires no more than two arguments. Guides are additional context lines that are not strictly part of a hunk, but provide important contextual data (e.g. column headers). If TRUE, the context lines are shown in addition to the normal diff output, typically in a different color to indicate they are not part of the hunk. If a function, the function should accept as the first argument the object being diffed, and the second the character representation of the object. The function should return the indices of the elements of the character representation that should be treated as guides. See guides for more details.

TRUE (default), FALSE, or a function that accepts at least two arguments and requires no more than two arguments. Function should compute for each line in captured output what portion of those lines should be diffed. By default, this is used to remove row meta data differences (e.g. [1,]) so they alone do not show up as differences in the diff. See trim for more details.

TRUE (default) or FALSE, if TRUE will check whether target and/or current point to a file that can be read with readRDS and if so, loads the R object contained in the file and carries out the diff on the object instead of the original argument. Currently there is no mechanism for specifying additional arguments to readRDS

TRUE (default) or FALSE. Relevant primarily for diffPrint, if TRUE, and word.diff is also TRUE, and both target and current are unnamed one-dimension atomics , the vectors are unwrapped and diffed element by element, and then re-wrapped. Since diffPrint is fundamentally a line diff, the re-wrapped lines are lined up in a manner that is as consistent as possible with the unwrapped diff. Lines that contain the location of the word differences will be paired up. Since the vectors may well be wrapped with different periodicities this will result in lines that are paired up that look like they should not be paired up, though the locations of the differences should be. If is entirely possible that setting this parameter to FALSE will result in a slower diff. This happens if two vectors are actually fairly similar, but their line representations are not. For example, in comparing 1:100 to c(100, 1:99), there is really only one difference at the “word” level, but every screen line is different. diffChr will also do the unwrapping if it is given a character vector that contains output that looks like the atomic vectors described above. This is a bug, but as the functionality could be useful when diffing e.g. capture.output data, we now declare it a feature.

integer(1L), number of differences (default 50000L) after which we abandon the O(n^2) diff algorithm in favor of a naive O(n) one. Set to -1L to stick to the original algorithm up to the maximum allowed (~INT_MAX/4).

integer(1L) number of display columns to take up; note that in “sidebyside” mode the effective display width is half this number (set to 0L to use default widths which are getOption("width") for normal styles and 80L for HTML styles. Future versions of diffobj may change this to larger values for two dimensional objects for better diffs (see details).

TRUE or FALSE, whether to consider differences in horizontal whitespace (i.e. spaces and tabs) as differences (defaults to TRUE).

TRUE or FALSE, whether modify input strings that contain tabs and carriage returns in such a way that they display as they would with those characters, but without using those characters (defaults to TRUE). The conversion assumes that tab stops are spaced evenly eight characters apart on the terminal. If this is not the case you may specify the tab stops explicitly with tab.stops.

integer, what tab stops to use when converting hard tabs to spaces. If not integer will be coerced to integer (defaults to 8L). You may specify more than one tab stop. If display width exceeds that addressable by your tab stops the last tab stop will be repeated.

integer(2L) or integer(1L), if length 1 how many lines of output to show, where -1 means no limit. If length 2, the first value indicates the threshold of screen lines to begin truncating output, and the second the number of lines to truncate to, which should be fewer than the threshold. Note that this parameter is implemented on a best-efforts basis and should not be relied on to produce the exact number of lines requested. In particular do not expect it to work well for for values small enough that the banner portion of the diff would have to be trimmed. If you want a specific number of lines use [ or head / tail. One advantage of line.limit over these other options is that you can combine it with context="auto" and auto max.level selection (the latter for diffStr), which allows the diff to dynamically adjust to make best use of the available display lines. [, head, and tail just subset the text of the output.

integer(2L) or integer (1L), how many diff hunks to show. Behaves similarly to line.limit. How many hunks are in a particular diff is a function of how many differences, and also how much context is used since context can cause two hunks to bleed into each other and become one.

numeric(1L) between 0 and 1, proportion of words in a line of target that must be matched in a line of current in the same hunk for those lines to be paired up when displayed (defaults to 0.25), or an AlignThreshold object. Set to 1 to turn off alignment which will cause all lines in a hunk from target to show up first, followed by all lines from current. Note that in order to be aligned lines must meet the threshold and have at least 3 matching alphanumeric characters (see AlignThreshold for details).

“auto”, a Style object, or a list. “auto” by default. If a Style object, will override the the format, brightness, and color.mode parameters. The Style object provides full control of diff output styling. If a list, then the same as “auto”, except that if the auto-selected Style requires instantiation (see PaletteOfStyles), then the list contents will be used as arguments when instantiating the style object. See Style for more details, in particular the examples.

PaletteOfStyles object; advanced usage, contains all the Style objects or “classRepresentation” objects extending Style that are selected by specifying the format, brightness, and color.mode parameters. See PaletteOfStyles for more details.

an environment to use as the evaluation frame for the print/show/str, calls and for diffObj, the evaluation frame for the diffPrint / diffStr calls. Defaults to the return value of par_frame.

TRUE or FALSE whether the function is being run in interactive mode, defaults to the return value of interactive. If in interactive mode, pager will be used if pager is “auto”, and if ANSI styles are not supported and style is “auto”, output will be send to viewer/browser as HTML.

integer(1L) how many ANSI colors are supported by the terminal. This variable is provided for when crayon::num_colors does not properly detect how many ANSI colors are supported by your terminal. Defaults to return value of crayon::num_colors and should be 8 or 256 to allow ANSI colors, or any other number to disallow them. This only impacts output format selection when style and format are both set to “auto”.

character(1L), language, or NULL, used to generate the text to display ahead of the diff section representing the target output. If NULL will use the deparsed target expression, if language, will use the language as it would the target expression, if character(1L), will use the string with no modifications. The language mode is provided because diffStr modifies the expression prior to display (e.g. by wrapping it in a call to str). Note that it is possible in some cases that the substituted value of target actually is character(1L), but if you provide a character(1L) value here it will be assumed you intend to use that value literally.

character(1L) like tar.banner, but for current

TRUE, FALSE, or NULL (default), whether to strip ANSI CSI SGR sequences prior to comparison and for display of diff. If NULL, resolves to TRUE if 'style' resolves to an ANSI formatted diff, and FALSE otherwise. The default behavior is to avoid confusing diffs where the original SGR and the SGR added by the diff are mixed together.

TRUE, FALSE, or NULL (default), whether to assume the standard output device supports ANSI CSI SGR sequences. If TRUE, strings will be manipulated accounting for the SGR sequences. If NULL, resolves to TRUE if 'style' resolves to an ANSI formatted diff, and to 'crayon::has_color()' otherwise. This only controls how the strings are manipulated, not whether SGR is added to format the diff, which is controlled by the 'style' parameter. This parameter is exposed for the rare cases where you might wish to control string manipulation behavior directly.

list additional arguments to pass on to the functions used to create text representation of the objects to diff (e.g. print, str, etc.)

the reference object

the object being compared to target

unused, for compatibility of methods with generics

the reference object

the object being compared to target

unused, for compatibility of methods with generics

character(1L), one of:

• “unified”: diff mode used by git diff

• “sidebyside”: line up the differences side by side

• “context”: show the target and current hunks in their entirety; this mode takes up a lot of screen space but makes it easier to see what the objects actually look like

• “auto”: default mode; pick one of the above, will favor “sidebyside” unless getOption("width") is less than 80, or in diffPrint and objects are dimensioned and do not fit side by side, or in diffChr, diffDeparse, diffFile and output does not fit in side by side without wrapping

integer(1L) how many lines of context are shown on either side of differences (defaults to 2). Set to -1L to allow as many as there are. Set to “auto” to display as many as 10 lines or as few as 1 depending on whether total screen lines fit within the number of lines specified in line.limit. Alternatively pass the return value of auto_context to fine tune the parameters of the auto context calculation.

character(1L), controls the diff output format, one of:

• “auto”: to select output format based on terminal capabilities; will attempt to use one of the ANSI formats if they appear to be supported, and if not or if you are in the Rstudio console it will attempt to use HTML and browser output if in interactive mode.

• “raw”: plain text

• “ansi8”: color and format diffs using basic ANSI escape sequences

• “ansi256”: like “ansi8”, except using the full range of ANSI formatting options

• “html”: color and format using HTML markup; the resulting string is processed with enc2utf8 when output as a full web page (see docs for html.output under Style).

Defaults to “auto”. See palette.of.styles for details on customization, style for full control of output format. See 'pager' parameter for more discussion of Rstudio behavior.

character, one of “light”, “dark”, “neutral”, useful for adjusting color scheme to light or dark terminals. “neutral” by default. See PaletteOfStyles for details and limitations. Advanced: you may specify brightness as a function of format. For example, if you typically wish to use a “dark” color scheme, except for when in “html” format when you prefer the “light” scheme, you may use c("dark", html="light") as the value for this parameter. This is particularly useful if format is set to “auto” or if you want to specify a default value for this parameter via options. Any names you use should correspond to a format. You must have one unnamed value which will be used as the default for all formats that are not explicitly specified.

character, one of “rgb” or “yb”. Defaults to “yb”. “yb” stands for “Yellow-Blue” for color schemes that rely primarily on those colors to style diffs. Those colors can be easily distinguished by individuals with limited red-green color sensitivity. See PaletteOfStyles for details and limitations. Also offers the same advanced usage as the brightness parameter.

TRUE (default) or FALSE, whether to run a secondary word diff on the in-hunk differences. For atomic vectors setting this to FALSE could make the diff slower (see the unwrap.atomic parameter). For other uses, particularly with diffChr setting this to FALSE can substantially improve performance.

one of “auto” (default), “on”, “off”, a Pager object, or a list; controls whether and how a pager is used to display the diff output. If you require a particular pager behavior you must use a Pager object, or “off” to turn off the pager. All other settings will interact with other parameters such as format, style, as well as with your system capabilities in order to select the pager expected to be most useful.

“auto” and “on” are the same, except that in non-interactive mode “auto” is equivalent to “off”. “off” will always send output to the console. If “on”, whether the output actually gets routed to the pager depends on the pager threshold setting (see Pager). The default behavior is to use the pager associated with the Style object. The Style object is itself is determined by the format or style parameters.

Depending on your system configuration different styles and corresponding pagers will get selected, unless you specify a Pager object directly. On a system with a system pager that supports ANSI CSI SGR colors, the pager will only trigger if the output is taller than one window. If the system pager is not known to support ANSI colors then the output will be sent as HTML to the IDE viewer if available or to the web browser if not. Even though Rstudio now supports ANSI CSI SGR at the console output is still formatted as HTML and sent to the IDE viewer. Partly this is for continuity of behavior, but also because the default Rstudio pager does not support ANSI CSI SGR, at least as of this writing.

If pager is a list, then the same as with “on”, except that the Pager object associated with the selected Style object is re-instantiated with the union of the list elements and the existing settings of that Pager. The list should contain named elements that correspond to the Pager instantiation parameters. The names must be specified in full as partial parameter matching will not be carried out because the pager is re-instantiated with new.

See Pager, Style, and PaletteOfStyles for more details and for instructions on how to modify the default behavior.

TRUE (default), FALSE, or a function that accepts at least two arguments and requires no more than two arguments. Guides are additional context lines that are not strictly part of a hunk, but provide important contextual data (e.g. column headers). If TRUE, the context lines are shown in addition to the normal diff output, typically in a different color to indicate they are not part of the hunk. If a function, the function should accept as the first argument the object being diffed, and the second the character representation of the object. The function should return the indices of the elements of the character representation that should be treated as guides. See guides for more details.

TRUE (default), FALSE, or a function that accepts at least two arguments and requires no more than two arguments. Function should compute for each line in captured output what portion of those lines should be diffed. By default, this is used to remove row meta data differences (e.g. [1,]) so they alone do not show up as differences in the diff. See trim for more details.

TRUE (default) or FALSE, if TRUE will check whether target and/or current point to a file that can be read with readRDS and if so, loads the R object contained in the file and carries out the diff on the object instead of the original argument. Currently there is no mechanism for specifying additional arguments to readRDS

TRUE (default) or FALSE. Relevant primarily for diffPrint, if TRUE, and word.diff is also TRUE, and both target and current are unnamed one-dimension atomics , the vectors are unwrapped and diffed element by element, and then re-wrapped. Since diffPrint is fundamentally a line diff, the re-wrapped lines are lined up in a manner that is as consistent as possible with the unwrapped diff. Lines that contain the location of the word differences will be paired up. Since the vectors may well be wrapped with different periodicities this will result in lines that are paired up that look like they should not be paired up, though the locations of the differences should be. If is entirely possible that setting this parameter to FALSE will result in a slower diff. This happens if two vectors are actually fairly similar, but their line representations are not. For example, in comparing 1:100 to c(100, 1:99), there is really only one difference at the “word” level, but every screen line is different. diffChr will also do the unwrapping if it is given a character vector that contains output that looks like the atomic vectors described above. This is a bug, but as the functionality could be useful when diffing e.g. capture.output data, we now declare it a feature.

integer(1L), number of differences (default 50000L) after which we abandon the O(n^2) diff algorithm in favor of a naive O(n) one. Set to -1L to stick to the original algorithm up to the maximum allowed (~INT_MAX/4).

integer(1L) number of display columns to take up; note that in “sidebyside” mode the effective display width is half this number (set to 0L to use default widths which are getOption("width") for normal styles and 80L for HTML styles. Future versions of diffobj may change this to larger values for two dimensional objects for better diffs (see details).

TRUE or FALSE, whether to consider differences in horizontal whitespace (i.e. spaces and tabs) as differences (defaults to TRUE).

TRUE or FALSE, whether modify input strings that contain tabs and carriage returns in such a way that they display as they would with those characters, but without using those characters (defaults to TRUE). The conversion assumes that tab stops are spaced evenly eight characters apart on the terminal. If this is not the case you may specify the tab stops explicitly with tab.stops.

integer, what tab stops to use when converting hard tabs to spaces. If not integer will be coerced to integer (defaults to 8L). You may specify more than one tab stop. If display width exceeds that addressable by your tab stops the last tab stop will be repeated.

integer(2L) or integer(1L), if length 1 how many lines of output to show, where -1 means no limit. If length 2, the first value indicates the threshold of screen lines to begin truncating output, and the second the number of lines to truncate to, which should be fewer than the threshold. Note that this parameter is implemented on a best-efforts basis and should not be relied on to produce the exact number of lines requested. In particular do not expect it to work well for for values small enough that the banner portion of the diff would have to be trimmed. If you want a specific number of lines use [ or head / tail. One advantage of line.limit over these other options is that you can combine it with context="auto" and auto max.level selection (the latter for diffStr), which allows the diff to dynamically adjust to make best use of the available display lines. [, head, and tail just subset the text of the output.

integer(2L) or integer (1L), how many diff hunks to show. Behaves similarly to line.limit. How many hunks are in a particular diff is a function of how many differences, and also how much context is used since context can cause two hunks to bleed into each other and become one.

numeric(1L) between 0 and 1, proportion of words in a line of target that must be matched in a line of current in the same hunk for those lines to be paired up when displayed (defaults to 0.25), or an AlignThreshold object. Set to 1 to turn off alignment which will cause all lines in a hunk from target to show up first, followed by all lines from current. Note that in order to be aligned lines must meet the threshold and have at least 3 matching alphanumeric characters (see AlignThreshold for details).

“auto”, a Style object, or a list. “auto” by default. If a Style object, will override the the format, brightness, and color.mode parameters. The Style object provides full control of diff output styling. If a list, then the same as “auto”, except that if the auto-selected Style requires instantiation (see PaletteOfStyles), then the list contents will be used as arguments when instantiating the style object. See Style for more details, in particular the examples.

PaletteOfStyles object; advanced usage, contains all the Style objects or “classRepresentation” objects extending Style that are selected by specifying the format, brightness, and color.mode parameters. See PaletteOfStyles for more details.

an environment to use as the evaluation frame for the print/show/str, calls and for diffObj, the evaluation frame for the diffPrint / diffStr calls. Defaults to the return value of par_frame.

TRUE or FALSE whether the function is being run in interactive mode, defaults to the return value of interactive. If in interactive mode, pager will be used if pager is “auto”, and if ANSI styles are not supported and style is “auto”, output will be send to viewer/browser as HTML.

integer(1L) how many ANSI colors are supported by the terminal. This variable is provided for when crayon::num_colors does not properly detect how many ANSI colors are supported by your terminal. Defaults to return value of crayon::num_colors and should be 8 or 256 to allow ANSI colors, or any other number to disallow them. This only impacts output format selection when style and format are both set to “auto”.

character(1L), language, or NULL, used to generate the text to display ahead of the diff section representing the target output. If NULL will use the deparsed target expression, if language, will use the language as it would the target expression, if character(1L), will use the string with no modifications. The language mode is provided because diffStr modifies the expression prior to display (e.g. by wrapping it in a call to str). Note that it is possible in some cases that the substituted value of target actually is character(1L), but if you provide a character(1L) value here it will be assumed you intend to use that value literally.

character(1L) like tar.banner, but for current

TRUE, FALSE, or NULL (default), whether to strip ANSI CSI SGR sequences prior to comparison and for display of diff. If NULL, resolves to TRUE if 'style' resolves to an ANSI formatted diff, and FALSE otherwise. The default behavior is to avoid confusing diffs where the original SGR and the SGR added by the diff are mixed together.

TRUE, FALSE, or NULL (default), whether to assume the standard output device supports ANSI CSI SGR sequences. If TRUE, strings will be manipulated accounting for the SGR sequences. If NULL, resolves to TRUE if 'style' resolves to an ANSI formatted diff, and to 'crayon::has_color()' otherwise. This only controls how the strings are manipulated, not whether SGR is added to format the diff, which is controlled by the 'style' parameter. This parameter is exposed for the rare cases where you might wish to control string manipulation behavior directly.

list additional arguments to pass on to the functions used to create text representation of the objects to diff (e.g. print, str, etc.)

the reference object

the object being compared to target

unused, for compatibility of methods with generics

character(1L), one of:

• “unified”: diff mode used by git diff

• “sidebyside”: line up the differences side by side

• “context”: show the target and current hunks in their entirety; this mode takes up a lot of screen space but makes it easier to see what the objects actually look like

• “auto”: default mode; pick one of the above, will favor “sidebyside” unless getOption("width") is less than 80, or in diffPrint and objects are dimensioned and do not fit side by side, or in diffChr, diffDeparse, diffFile and output does not fit in side by side without wrapping

integer(1L) how many lines of context are shown on either side of differences (defaults to 2). Set to -1L to allow as many as there are. Set to “auto” to display as many as 10 lines or as few as 1 depending on whether total screen lines fit within the number of lines specified in line.limit. Alternatively pass the return value of auto_context to fine tune the parameters of the auto context calculation.

character(1L), controls the diff output format, one of:

• “auto”: to select output format based on terminal capabilities; will attempt to use one of the ANSI formats if they appear to be supported, and if not or if you are in the Rstudio console it will attempt to use HTML and browser output if in interactive mode.

• “raw”: plain text

• “ansi8”: color and format diffs using basic ANSI escape sequences

• “ansi256”: like “ansi8”, except using the full range of ANSI formatting options

• “html”: color and format using HTML markup; the resulting string is processed with enc2utf8 when output as a full web page (see docs for html.output under Style).

Defaults to “auto”. See palette.of.styles for details on customization, style for full control of output format. See 'pager' parameter for more discussion of Rstudio behavior.

character, one of “light”, “dark”, “neutral”, useful for adjusting color scheme to light or dark terminals. “neutral” by default. See PaletteOfStyles for details and limitations. Advanced: you may specify brightness as a function of format. For example, if you typically wish to use a “dark” color scheme, except for when in “html” format when you prefer the “light” scheme, you may use c("dark", html="light") as the value for this parameter. This is particularly useful if format is set to “auto” or if you want to specify a default value for this parameter via options. Any names you use should correspond to a format. You must have one unnamed value which will be used as the default for all formats that are not explicitly specified.

character, one of “rgb” or “yb”. Defaults to “yb”. “yb” stands for “Yellow-Blue” for color schemes that rely primarily on those colors to style diffs. Those colors can be easily distinguished by individuals with limited red-green color sensitivity. See PaletteOfStyles for details and limitations. Also offers the same advanced usage as the brightness parameter.

TRUE (default) or FALSE, whether to run a secondary word diff on the in-hunk differences. For atomic vectors setting this to FALSE could make the diff slower (see the unwrap.atomic parameter). For other uses, particularly with diffChr setting this to FALSE can substantially improve performance.

one of “auto” (default), “on”, “off”, a Pager object, or a list; controls whether and how a pager is used to display the diff output. If you require a particular pager behavior you must use a Pager object, or “off” to turn off the pager. All other settings will interact with other parameters such as format, style, as well as with your system capabilities in order to select the pager expected to be most useful.

“auto” and “on” are the same, except that in non-interactive mode “auto” is equivalent to “off”. “off” will always send output to the console. If “on”, whether the output actually gets routed to the pager depends on the pager threshold setting (see Pager). The default behavior is to use the pager associated with the Style object. The Style object is itself is determined by the format or style parameters.

Depending on your system configuration different styles and corresponding pagers will get selected, unless you specify a Pager object directly. On a system with a system pager that supports ANSI CSI SGR colors, the pager will only trigger if the output is taller than one window. If the system pager is not known to support ANSI colors then the output will be sent as HTML to the IDE viewer if available or to the web browser if not. Even though Rstudio now supports ANSI CSI SGR at the console output is still formatted as HTML and sent to the IDE viewer. Partly this is for continuity of behavior, but also because the default Rstudio pager does not support ANSI CSI SGR, at least as of this writing.

If pager is a list, then the same as with “on”, except that the Pager object associated with the selected Style object is re-instantiated with the union of the list elements and the existing settings of that Pager. The list should contain named elements that correspond to the Pager instantiation parameters. The names must be specified in full as partial parameter matching will not be carried out because the pager is re-instantiated with new.

See Pager, Style, and PaletteOfStyles for more details and for instructions on how to modify the default behavior.

TRUE (default), FALSE, or a function that accepts at least two arguments and requires no more than two arguments. Guides are additional context lines that are not strictly part of a hunk, but provide important contextual data (e.g. column headers). If TRUE, the context lines are shown in addition to the normal diff output, typically in a different color to indicate they are not part of the hunk. If a function, the function should accept as the first argument the object being diffed, and the second the character representation of the object. The function should return the indices of the elements of the character representation that should be treated as guides. See guides for more details.

TRUE (default), FALSE, or a function that accepts at least two arguments and requires no more than two arguments. Function should compute for each line in captured output what portion of those lines should be diffed. By default, this is used to remove row meta data differences (e.g. [1,]) so they alone do not show up as differences in the diff. See trim for more details.

TRUE (default) or FALSE, if TRUE will check whether target and/or current point to a file that can be read with readRDS and if so, loads the R object contained in the file and carries out the diff on the object instead of the original argument. Currently there is no mechanism for specifying additional arguments to readRDS

TRUE (default) or FALSE. Relevant primarily for diffPrint, if TRUE, and word.diff is also TRUE, and both target and current are unnamed one-dimension atomics , the vectors are unwrapped and diffed element by element, and then re-wrapped. Since diffPrint is fundamentally a line diff, the re-wrapped lines are lined up in a manner that is as consistent as possible with the unwrapped diff. Lines that contain the location of the word differences will be paired up. Since the vectors may well be wrapped with different periodicities this will result in lines that are paired up that look like they should not be paired up, though the locations of the differences should be. If is entirely possible that setting this parameter to FALSE will result in a slower diff. This happens if two vectors are actually fairly similar, but their line representations are not. For example, in comparing 1:100 to c(100, 1:99), there is really only one difference at the “word” level, but every screen line is different. diffChr will also do the unwrapping if it is given a character vector that contains output that looks like the atomic vectors described above. This is a bug, but as the functionality could be useful when diffing e.g. capture.output data, we now declare it a feature.

integer(1L), number of differences (default 50000L) after which we abandon the O(n^2) diff algorithm in favor of a naive O(n) one. Set to -1L to stick to the original algorithm up to the maximum allowed (~INT_MAX/4).

integer(1L) number of display columns to take up; note that in “sidebyside” mode the effective display width is half this number (set to 0L to use default widths which are getOption("width") for normal styles and 80L for HTML styles. Future versions of diffobj may change this to larger values for two dimensional objects for better diffs (see details).

TRUE or FALSE, whether to consider differences in horizontal whitespace (i.e. spaces and tabs) as differences (defaults to TRUE).

TRUE or FALSE, whether modify input strings that contain tabs and carriage returns in such a way that they display as they would with those characters, but without using those characters (defaults to TRUE). The conversion assumes that tab stops are spaced evenly eight characters apart on the terminal. If this is not the case you may specify the tab stops explicitly with tab.stops.

integer, what tab stops to use when converting hard tabs to spaces. If not integer will be coerced to integer (defaults to 8L). You may specify more than one tab stop. If display width exceeds that addressable by your tab stops the last tab stop will be repeated.

integer(2L) or integer(1L), if length 1 how many lines of output to show, where -1 means no limit. If length 2, the first value indicates the threshold of screen lines to begin truncating output, and the second the number of lines to truncate to, which should be fewer than the threshold. Note that this parameter is implemented on a best-efforts basis and should not be relied on to produce the exact number of lines requested. In particular do not expect it to work well for for values small enough that the banner portion of the diff would have to be trimmed. If you want a specific number of lines use [ or head / tail. One advantage of line.limit over these other options is that you can combine it with context="auto" and auto max.level selection (the latter for diffStr), which allows the diff to dynamically adjust to make best use of the available display lines. [, head, and tail just subset the text of the output.

integer(2L) or integer (1L), how many diff hunks to show. Behaves similarly to line.limit. How many hunks are in a particular diff is a function of how many differences, and also how much context is used since context can cause two hunks to bleed into each other and become one.

numeric(1L) between 0 and 1, proportion of words in a line of target that must be matched in a line of current in the same hunk for those lines to be paired up when displayed (defaults to 0.25), or an AlignThreshold object. Set to 1 to turn off alignment which will cause all lines in a hunk from target to show up first, followed by all lines from current. Note that in order to be aligned lines must meet the threshold and have at least 3 matching alphanumeric characters (see AlignThreshold for details).

“auto”, a Style object, or a list. “auto” by default. If a Style object, will override the the format, brightness, and color.mode parameters. The Style object provides full control of diff output styling. If a list, then the same as “auto”, except that if the auto-selected Style requires instantiation (see PaletteOfStyles), then the list contents will be used as arguments when instantiating the style object. See Style for more details, in particular the examples.

PaletteOfStyles object; advanced usage, contains all the Style objects or “classRepresentation” objects extending Style that are selected by specifying the format, brightness, and color.mode parameters. See PaletteOfStyles for more details.

an environment to use as the evaluation frame for the print/show/str, calls and for diffObj, the evaluation frame for the diffPrint / diffStr calls. Defaults to the return value of par_frame.

TRUE or FALSE whether the function is being run in interactive mode, defaults to the return value of interactive. If in interactive mode, pager will be used if pager is “auto”, and if ANSI styles are not supported and style is “auto”, output will be send to viewer/browser as HTML.

integer(1L) how many ANSI colors are supported by the terminal. This variable is provided for when crayon::num_colors does not properly detect how many ANSI colors are supported by your terminal. Defaults to return value of crayon::num_colors and should be 8 or 256 to allow ANSI colors, or any other number to disallow them. This only impacts output format selection when style and format are both set to “auto”.

character(1L), language, or NULL, used to generate the text to display ahead of the diff section representing the target output. If NULL will use the deparsed target expression, if language, will use the language as it would the target expression, if character(1L), will use the string with no modifications. The language mode is provided because diffStr modifies the expression prior to display (e.g. by wrapping it in a call to str). Note that it is possible in some cases that the substituted value of target actually is character(1L), but if you provide a character(1L) value here it will be assumed you intend to use that value literally.

character(1L) like tar.banner, but for current

TRUE, FALSE, or NULL (default), whether to strip ANSI CSI SGR sequences prior to comparison and for display of diff. If NULL, resolves to TRUE if 'style' resolves to an ANSI formatted diff, and FALSE otherwise. The default behavior is to avoid confusing diffs where the original SGR and the SGR added by the diff are mixed together.

TRUE, FALSE, or NULL (default), whether to assume the standard output device supports ANSI CSI SGR sequences. If TRUE, strings will be manipulated accounting for the SGR sequences. If NULL, resolves to TRUE if 'style' resolves to an ANSI formatted diff, and to 'crayon::has_color()' otherwise. This only controls how the strings are manipulated, not whether SGR is added to format the diff, which is controlled by the 'style' parameter. This parameter is exposed for the rare cases where you might wish to control string manipulation behavior directly.

list additional arguments to pass on to the functions used to create text representation of the objects to diff (e.g. print, str, etc.)

a PaletteOfStyles object

object to finalize

arguments to pass on to methods

character text representation of x, typically generated with the as.character method for x

character javascript code to append to HTML representation

character(1L) name off diffobj option to retrieve, without the “diffobj.” prefix

an R object

the character representation of obj that is used for computing the diffs

function to test for diff presence with, typically Rdiff

a function

character(1L) a message to use as the readline prompt

whether to return the result of fun invisibly

character

unused for compatibility with internal use

a function that accepts at least one parameter and does not require a parameter other than the first parameter. This function will be called with a file path passed as the first argument. The referenced file will contain the text of the diff. By default this is a temporary file that will be deleted as soon as the pager function completes evaluation. PagerSystem and PagerSystemLess use file.show by default, and PagerBrowser uses view_or_browse for HTML output. For asynchronous pagers such as view_or_browse it is important to make the pager function blocking by setting the make.blocking parameter to TRUE, or to specify a pager file path explicitly with file.path.

character(1L) an extension to append to file path passed to pager, without the period. For example, PagerBrowser uses “html” to cause browseURL to launch the web browser. This parameter will be overridden if file.path is used.

integer(1L) number of lines of output that triggers the use of the pager; negative values lead to using console_lines + 1, and zero leads to always using the pager irrespective of how many lines the output has.

TRUE or FALSE, whether the pager supports ANSI CSI SGR sequences.

character(1L), if not NA the diff will be written to this location, ignoring the value of file.ext. If NA_character_ (default), a temporary file is used and removed after the pager function completes evaluation. If not NA, the file is preserved. Beware that the file will be overwritten if it already exists.

TRUE, FALSE, or NA. Whether to wrap pager with make_blocking prior to calling it. This suspends R code execution until there is user input so that temporary diff files are not deleted before the pager has a chance to read them. This typically defaults to FALSE, except for PagerBrowser where it defaults to NA, which resolves to is.na(file.path) (i.e. it is TRUE if the diff is being written to a temporary file, and FALSE otherwise).

additional arguments to pass on to new that are passed on to parent classes.

character(1L), only for PagerSystemLess, what flags to set with the LESS system environment variable. By default the “R” flag is set to ensure ANSI escape sequences are interpreted if it appears your terminal supports ANSI escape sequences. If you want to leave the output on the screen after you exit the pager you can use “RX”. You should only provide the flag letters (e.g. “"RX"”, not "-RX"). The system variable is only modified for the duration of the evaluation and is reset / unset afterwards. Note: you must specify this slot via the constructor as in the example. If you set the slot directly it will not have any effect.

character or object coercible to character for Rdiff_chr, any R object with Rdiff_obj, or a file pointing to an RDS object

character same as from

TRUE or FALSE, whether to display output to screen

TRUE or FALSE, whether to exclude the lines that show the actual differences or only the actual edit script commands

passed to tools::Rdiff

character

character

integer(1L), number of differences (default 50000L) after which we abandon the O(n^2) diff algorithm in favor of a naive O(n) one. Set to -1L to stick to the original algorithm up to the maximum allowed (~INT_MAX/4).

TRUE (default) or FALSE whether to warn if we hit max.diffs.

TRUE (default) or FALSE, whether to also return the indices in a and b the diff values are taken from. Set to FALSE for a small performance gain.

a DiffSummary object

a PaletteOfStyles object

a Style S4 object

a StyleFuns object that contains all the functions represented above

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

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

TRUE or FALSE, whether text should be right padded

what type of Pager to use

function to use to count characters; intended mostly for internal use (used only for gutters as of version 0.2.0).

TRUE or FALSE, whether text should be hard wrapped at disp.width

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

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

how many columns the text representation of the objects to diff is allowed to take up before it is hard wrapped (assuming wrap is TRUE). See param disp.width for diffPrint.

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.

(StyleHtml objects only) one of:

• “page”: Include all HTML/CSS/JS required to create a stand-alone web page with the diff; in this mode the diff string will be re-encoded with enc2utf8 and the HTML page encoding will be declared as UTF-8.

• “diff.w.style”: The CSS and HTML, but without any of the outer tags that would make it a proper HTML page (i.e. no <html>/<head> tags or the like) and without the JS; note that technically this is illegal HTML since we have <style> tags floating outside of <head> tags, but it seems to work in most browsers.

• “diff.only”: Like “diff.w.style”, but without the CSS

• “auto”: Pick one of the above based on Pager, will chose “page” if the pager is of type PagerBrowser (as in that case the output is destined to be displayed in a browser like device), or “diff.only” if it is not.

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

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

(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.

function used primarily by HTML styles to generate an outermost DIV that allows for CSS targeting of its contents (see cont_f for a function generator appropriate for use here)

function

function

function

function

function formats guide lines (see guides)

function

function

function

function

function formats guide lines (see guides)

function

function

function

function

function

function

function to format each hunk header with

function to format entire banner

function to format insertion banner

function to format deletion banner

function format meta information lines

function to format the separator used to visually distinguish the A and B hunks in “context” mode

character(1L) text to use as visual cue to indicate whether a diff line is an insertion, defaults to “> ”

character(1L) if a diff line is wrapped, the visual cue shifts to this character to indicate wrapping occured

character(1L) see gutter.insert above

character(1L) see gutter.insert.ctd above

character(1L) see gutter.insert above

character(1L) see gutter.insert.ctd above

character(1L) see gutter.insert above

character(1L) see gutter.insert.ctd above

character(1L) see gutter.insert above

character(1L) see gutter.insert.ctd above

character(1L) separator between gutter characters and the rest of a line in a diff

character(1L) separator between columns in side by side mode

at Diff object

numeric(1L) between 0 and 1, how much distortion to allow when creating the summary map, where 0 is none and 1 is as much as needed to fit under max.lines, defaults to 0.1

integer(1L) how many lines to allow for the summary map, defaults to 50

integer(1L) how many columns wide the output should be, defaults to getOption("width")

unused, for compatibility with generic

a PaletteOfStyles object

unused, for compatibility with generic

character(1L) a name of an HTML tag

character the CSS class(es)

named character inline styles, where the name is the CSS property and the value the value.

the object

character the printed representation of the object

character(1L) a location containing a file to display