#' @name sprinkle
#' @export sprinkle
#'
#' @title Define Customizations to a Table
#' @description Customizations to a \code{dust} table are added by "sprinkling"
#' with a little extra pixie dust. Sprinkles are a collection of attributes
#' to be applied over a subset of table cells. They may be added to any
#' part of the table, or to the table as a whole.
# Parameters --------------------------------------------------------
#' @param x A dust object
#' @param rows A numeric vector specifying the rows of the table to sprinkle.
#' See details for more about sprinkling.
#' @param cols A numeric (or character) vector specifying the columns (or
#' column names) to sprinkle. See details for more about sprinkling.
#' @param part A character string denoting which part of the table to modify.
#' @param fixed \code{logical(1)} indicating if the values in \code{rows}
#' and \code{cols} should be read as fixed coordinate pairs. By default,
#' sprinkles are applied at the intersection of \code{rows} and \code{cols},
#' meaning that the arguments do not have to share the same length.
#' When \code{fixed = TRUE}, they must share the same length.
#' @param recycle A \code{character} one that determines how sprinkles are
#' managed when the sprinkle input doesn't match the length of the region
#' to be sprinkled. By default, recycling is turned off. Recycling
#' may be performed across rows first (left to right, top to bottom),
#' or down columns first (top to bottom, left to right).
#' @param ... named arguments, each of length 1, defining the customizations
#' for the given cells. See "Sprinkles" for a listing of these arguments.
#'
# Details -----------------------------------------------------------
#' @details Sprinkling is done over the intersection of rows and columns
#' (unless \code{fixed = TRUE}. If
#' rows but no columns are specified, sprinkling is performed over all columns
#' of the given given rows. The reverse is true for when columns but no rows
#' are specified. If neither columns nor rows are specified, the attribute
#' is applied over all of the cells in the table part denoted in \code{part}.
#'
#' If at least one of \code{border}, \code{border_thickness}, \code{border_units},
#' \code{border_style} or \code{border_color} is specified, the remaining
#' unspecified attributes assume their default values.
#'
#' Other sprinkle pairings are \code{height} and \code{height_units};
#' \code{width} and \code{width_units}; \code{font_size} and \code{font_size_units};
#' \code{bg_pattern} and \code{bg_pattern_by}
#'
#' The sprinkles \code{bg} and \code{bg_pattern} may not be used together.
#'
#' A more detailed demonstration of the use of sprinkles is available in
#' \code{vignette("pixiedust", package = "pixiedust")}
#'
#' Using \code{sprinkle_table}, sprinkles may be applied to the columns of multiple tables. Table
#' parts are required to have the same number of columns, but not necessarily the same number
#' of rows, which is why the \code{rows} argument is not available for the \code{sprinkle_table}.
#' In contrast to \code{sprinkle}, the \code{part} argument in \code{sprinkle_table} will
#' accept multiple parts. If any of the named parts is \code{"table"}, the sprinkle will be
#' applied to the columns of all of the parts.
#'
# Sprinkles ---------------------------------------------------------
#' @section Sprinkles:
#' The following table describes the valid sprinkles that may be defined in the
#' \code{...} dots argument. All sprinkles may be defined for any output type, but
#' only sprinkles recognized by that output type will be applied when printed.
#' A more readable format of this information is available in
#' \code{vignette("sprinkles", package = "pixiedust")}.
#'
#' \tabular{lll}{
#' bg \tab \tab \cr
#' \tab action \tab Modifies the background color of a cell. \cr
#' \tab default \tab \cr
#' \tab accepts \tab dvips color names; rgb(R,G,B); rgba(R,G,B,A); \cr
#' \tab \tab #RRGGBB; #RRGGBBAA. See the "Colors" section \cr
#' \tab \tab for further details. \cr
#' \tab console \tab Not recognized \cr
#' \tab markdown \tab Not recognized \cr
#' \tab html \tab Accepts any of the listed formats; \cr
#' \tab \tab recognizes transparency \cr
#' \tab latex \tab Accepts any of the listed formats, \cr
#' \tab \tab but ignores transparency \cr
#' bg_pattern \tab \tab \cr
#' \tab action \tab Generates a pattern of background colors. \cr
#' \tab \tab Can be used to make striping \cr
#' \tab \tab by rows or by columns. \cr
#' \tab default \tab c("#FFFFFF", "#DDDDDD") \cr
#' \tab accepts \tab A vector of color names: \cr
#' \tab \tab dvips color names; rgb(R,G,B); rgba(R,G,B,A); \cr
#' \tab \tab #RRGGBB; #RRGGBBAA \cr
#' \tab console \tab Not recognized \cr
#' \tab markdown \tab Not recognized \cr
#' \tab html \tab Accepts any of the listed formats; \cr
#' \tab \tab recognizes transparency \cr
#' \tab latex \tab Accepts any of the listed formats, \cr
#' \tab \tab but ignores transparency \cr
#' bg_pattern_by \tab \tab \cr
#' \tab action \tab Determines if a `bg_pattern` is patterned \cr
#' \tab \tab by row or by columns. \cr
#' \tab default \tab "rows" \cr
#' \tab accepts \tab "rows", "columns", "cols" \cr
#' \tab console \tab Not recognized \cr
#' \tab markdown \tab Not recognized \cr
#' \tab html \tab Recognized \cr
#' \tab latex \tab Recognized \cr
#' bold \tab \tab \cr
#' \tab action \tab Renders text within a cell in bold. \cr
#' \tab default \tab FALSE \cr
#' \tab accepts \tab logical(1) \cr
#' \tab console \tab Recognized; rendered as double asterisks on either\cr
#' \tab \tab side of the text \cr
#' \tab markdown \tab Recognized \cr
#' \tab html \tab Recognized \cr
#' \tab latex \tab Recognized \cr
#' border_collapse \tab \tab \cr
#' \tab action \tab Sets the `border-collapse` property in an \cr
#' \tab \tab HTML table. The property sets whether the \cr
#' \tab \tab table borders are collapsed into a \cr
#' \tab \tab single border or detached as in standard HTML. \cr
#' \tab default \tab TRUE \cr
#' \tab accepts \tab logical(1) \cr
#' \tab console \tab Not recognized \cr
#' \tab markdown \tab Not recognized \cr
#' \tab html \tab Recognized \cr
#' \tab latex \tab Not recognized \cr
#' border \tab \tab \cr
#' \tab action \tab Sets a border on the specified side of a cell. \cr
#' \tab default \tab \cr
#' \tab accepts \tab Any combination of "all", "bottom", "left", "top",\cr
#' \tab \tab "right". Using "all" results in all borders \cr
#' \tab \tab being drawn, regardless of what other values are \cr
#' \tab \tab passed with it. \cr
#' \tab console \tab Not recognized \cr
#' \tab markdown \tab Not recognized \cr
#' \tab html \tab Recognized \cr
#' \tab latex \tab Recognized \cr
#' border_color \tab \tab \cr
#' \tab action \tab Sets the color of the borders specified for a cell. \cr
#' \tab default \tab "Black" \cr
#' \tab accepts \tab character(1) \cr
#' \tab \tab dvips color names; rgb(R,G,B); rgba(R,G,B,A); \cr
#' \tab \tab #RRGGBB; #RRGGBBAA. See the "Colors" section \cr
#' \tab \tab for further details. \cr
#' \tab console \tab Not recognized \cr
#' \tab markdown \tab Not recognized \cr
#' \tab html \tab Recognized \cr
#' \tab latex \tab Recognized \cr
#' border_style \tab \tab \cr
#' \tab action \tab Sets the border style for a specified cell \cr
#' \tab default \tab "solid" \cr
#' \tab accepts \tab character(1) \cr
#' \tab \tab "solid", "dashed", "dotted", "double", "groove", \cr
#' \tab \tab "ridge", "inset", "outset", "hidden", "none" \cr
#' \tab console \tab Not recognized \cr
#' \tab markdown \tab Not recognized \cr
#' \tab html \tab Accepts any of the values listed. \cr
#' \tab latex; hhline = FALSE \tab accepts "solid", "dashed", "dotted", \cr
#' \tab \tab "hidden", "none" \cr
#' \tab \tab "dotted" is silently changed to "dashed" \cr
#' \tab \tab "hidden" and "none" are equivalent. \cr
#' \tab latex; hhline = TRUE \tab accepts "solid", "double", "hidden", "none" \cr
#' \tab \tab "hidden" and "none" are equivalent. \cr
#' border_thickness \tab \tab \cr
#' \tab action \tab Sets the thickness of the specified border \cr
#' \tab default \tab 1 \cr
#' \tab accepts \tab numeric(1) \cr
#' \tab console \tab Not recognized \cr
#' \tab markdown \tab Not recognized \cr
#' \tab html \tab Recognized \cr
#' \tab latex \tab Recognized \cr
#' border_units \tab \tab \cr
#' \tab action \tab Sets the unit of measure for the specified border \cr
#' \tab \tab thickness \cr
#' \tab default \tab "pt" \cr
#' \tab accepts \tab "pt", "px" \cr
#' \tab console \tab Not recognized \cr
#' \tab markdown \tab Not recognized \cr
#' \tab html \tab Recognized \cr
#' \tab latex \tab Silently changes "px" to "pt" \cr
#' caption \tab \tab \cr
#' \tab action \tab Adds or alters the `caption` property \cr
#' \tab default \tab \cr
#' \tab accepts \tab character(1) \cr
#' \tab console \tab Recognized \cr
#' \tab markdown \tab Recognized \cr
#' \tab html \tab Recognized \cr
#' \tab latex \tab Recognized \cr
#' discrete \tab \tab \cr
#' \tab action \tab Adds distinct background colors based on \cr
#' \tab \tab discrete values in the selected region. \cr
#' \tab \tab May not be used concurrently with \code{bg}. \cr
#' \tab \tab \code{"font"} is an alias for \code{"font_color"} \cr
#' \tab \tab and \code{"border"} is an alias for \cr
#' \tab \tab all borders. \cr
#' \tab default \tab "bg" \cr
#' \tab accepts \tab "bg", "font", "font_color", "border", \cr
#' \tab \tab "left_border", "top_border", "right_border", \cr
#' \tab \tab "bottom_border" \cr
#' \tab console \tab Not recognized \cr
#' \tab markdown \tab Not recognized \cr
#' \tab html \tab Recognized \cr
#' \tab latex \tab Recognized \cr
#' discrete_color \tab \tab \cr
#' \tab action \tab Sets the color palette from which \code{discrete} \cr
#' \tab \tab selects background colors. If \code{NULL} \cr
#' \tab \tab colors are automatically selected using \cr
#' \tab \tab the \code{scales} package. \cr
#' \tab default \tab \code{getOption("pixie_discrete_pal", NULL)} \cr
#' \tab accepts \tab character \cr
#' \tab console \tab Not recognized \cr
#' \tab markdown \tab Not recognized \cr
#' \tab html \tab Recognized \cr
#' \tab latex \tab Recognized \cr
#' float \tab \tab \cr
#' \tab action \tab Sets the `float` property \cr
#' \tab default \tab TRUE \cr
#' \tab accepts \tab logical(1) \cr
#' \tab console \tab Not recognized \cr
#' \tab markdown \tab Not recognized \cr
#' \tab html \tab Not recognized \cr
#' \tab latex \tab Recognized \cr
#' fn \tab \tab \cr
#' \tab action \tab Applies a function to the value of a cell. \cr
#' \tab \tab The function should be an \cr
#' \tab \tab expression that acts on the variable `value`. \cr
#' \tab \tab For example, \code{quote(format(value, nsmall = 3))} \cr
#' \tab default \tab \cr
#' \tab accepts \tab call \cr
#' \tab console \tab Recognized \cr
#' \tab markdown \tab Recognized \cr
#' \tab html \tab Recognized \cr
#' \tab latex \tab Recognized \cr
#' font_color \tab \tab \cr
#' \tab action \tab Sets the color of the cell text \cr
#' \tab default \tab Black \cr
#' \tab accepts \tab dvips color names; rgb(R,G,B); rgba(R,G,B,A); \cr
#' \tab \tab #RRGGBB; #RRGGBBAA. See the "Colors" section \cr
#' \tab \tab for further details. \cr
#' \tab console \tab Not recognized \cr
#' \tab markdown \tab Not recognized \cr
#' \tab html \tab Recognized; transparency recognized \cr
#' \tab latex \tab Recognized; transparency ignored \cr
#' font_family \tab \tab \cr
#' \tab action \tab Sets the font for the text \cr
#' \tab default \tab Times New Roman \cr
#' \tab accepts \tab character(1) \cr
#' \tab \tab http://www.w3schools.com/cssref/css_websafe_fonts.asp \cr
#' \tab console \tab Not recognized \cr
#' \tab markdown \tab Not recognized \cr
#' \tab html \tab Recognized \cr
#' \tab latex \tab Not recognized \cr
#' font_size \tab \tab \cr
#' \tab action \tab Sets the size of the font in the cell \cr
#' \tab default \tab \cr
#' \tab accepts \tab numeric(1) \cr
#' \tab console \tab Not recognized \cr
#' \tab markdown \tab Not recognized \cr
#' \tab html \tab Recognized \cr
#' \tab latex \tab Recognized \cr
#' font_size_units \tab \tab \cr
#' \tab action \tab Determines the units in which `font_size` \cr
#' \tab \tab is measured \cr
#' \tab default \tab "px" \cr
#' \tab accepts \tab "px", "pt", "\%", "em" \cr
#' \tab console \tab Not recognized \cr
#' \tab markdown \tab Not recognized \cr
#' \tab html \tab Recognized \cr
#' \tab latex \tab Only recognizes "pt" and "em". \cr
#' \tab \tab All others are coerced to "pt" \cr
#' gradient \tab \tab \cr
#' \tab action \tab Adds distinct background colors based on \cr
#' \tab \tab progressively increasing values in the \cr
#' \tab \tab selected region. May not be used concurrently \cr
#' \tab \tab with \code{bg}. \cr
#' \tab \tab \code{"font"} is an alias for \code{"font_color"} \cr
#' \tab \tab and \code{"border"} is an alias for \cr
#' \tab \tab all borders. \cr
#' \tab default \tab "bg" \cr
#' \tab accepts \tab "bg", "font", "font_color", "border", \cr
#' \tab \tab "left_border", "top_border", "right_border", \cr
#' \tab \tab "bottom_border" \cr
#' \tab console \tab Not recognized \cr
#' \tab markdown \tab Not recognized \cr
#' \tab html \tab Recognized \cr
#' \tab latex \tab Recognized \cr
#' gradient_colors \tab \tab \cr
#' \tab action \tab Provides the colors between which to \cr
#' \tab \tab shade gradients. \cr
#' \tab default \tab \code{getOptions("pixie_gradient_pal", NULL)} \cr
#' \tab accepts \tab character \cr
#' \tab console \tab Not recognized \cr
#' \tab markdown \tab Not recognized \cr
#' \tab html \tab Recognized \cr
#' \tab latex \tab Recognized \cr
#' gradient_cut \tab \tab \cr
#' \tab action \tab Determines the breaks points for the \cr
#' \tab \tab gradient shading. When \code{NULL} \cr
#' \tab \tab equally spaced quantiles are used, the \cr
#' \tab \tab number of which are determined by \cr
#' \tab \tab \code{gradient_n}. \cr
#' \tab default \tab NULL \cr
#' \tab accepts \tab numeric \cr
#' \tab console \tab Not recognized \cr
#' \tab markdown \tab Not recognized \cr
#' \tab html \tab Recognized \cr
#' \tab latex \tab Recognized \cr
#' gradient_n \tab \tab \cr
#' \tab action \tab Determines the number of shades to use \cr
#' \tab \tab between the colors in \code{gradient_colors}.\cr
#' \tab default \tab 10 \cr
#' \tab accepts \tab numeric \cr
#' \tab console \tab Not recognized \cr
#' \tab markdown \tab Not recognized \cr
#' \tab html \tab Recognized \cr
#' \tab latex \tab Recognized \cr
#' gradient_na \tab \tab \cr
#' \tab action \tab Sets the color of NA values when gradients \cr
#' \tab \tab are shaded. \cr
#' \tab default \tab grey \cr
#' \tab accepts \tab character(1) \cr
#' \tab console \tab Not recognized \cr
#' \tab markdown \tab Not recognized \cr
#' \tab html \tab Recognized \cr
#' \tab latex \tab Recognized \cr
#' halign \tab \tab \cr
#' \tab action \tab Sets the horizontal alignment of the text in \cr
#' \tab \tab the cell \cr
#' \tab default \tab \cr
#' \tab accepts \tab "left", "center", "right" \cr
#' \tab console \tab Not recognized \cr
#' \tab markdown \tab Recognized; numeric values will auto align to the \cr
#' \tab \tab right if no value given. \cr
#' \tab html \tab Recognized. Does not currently employ auto \cr
#' \tab \tab alignment of numeric values, but this may change. \cr
#' \tab latex \tab Recognized; numeric values will auto align to \cr
#' \tab \tab the right if no value given. \cr
#' height \tab \tab \cr
#' \tab action \tab Sets the height of the cell \cr
#' \tab default \tab \cr
#' \tab accepts \tab numeric(1) \cr
#' \tab console \tab Not recognized \cr
#' \tab markdown \tab Not recognized \cr
#' \tab html \tab Recognized \cr
#' \tab latex \tab Recognized \cr
#' height_units \tab \tab \cr
#' \tab action \tab Determines the units in which `height` is measured \cr
#' \tab default \tab "pt" \cr
#' \tab accepts \tab "px", "pt", "cm", "in", "\%" \cr
#' \tab console \tab Not recognized \cr
#' \tab markdown \tab Not recognized \cr
#' \tab html \tab Recognized \cr
#' \tab latex \tab Recognized; "px" is coerced to "pt" \cr
#' hhline \tab \tab \cr
#' \tab action \tab Toggles the option for cell border drawing with \cr
#' \tab \tab the `hhline` LaTeX package \cr
#' \tab default \tab FALSE \cr
#' \tab accepts \tab logical(1) \cr
#' \tab console \tab Not recognized \cr
#' \tab markdown \tab Not recognized \cr
#' \tab html \tab Not recognized \cr
#' \tab latex \tab Recognized. When `FALSE` double borders are \cr
#' \tab \tab not available. \cr
#' \tab \tab When `TRUE`, colored and dashed borders are not \cr
#' \tab \tab available. This is usually the better option \cr
#' \tab \tab when using colored backgrounds in table cells. \cr
#' italic \tab \tab \cr
#' \tab action \tab Renders the text in the cell in italic \cr
#' \tab default \tab FALSE \cr
#' \tab accepts \tab logical(1) \cr
#' \tab console \tab Recognized; rendered as an underscore on either \cr
#' \tab \tab side of the text. \cr
#' \tab markdown \tab Recognized \cr
#' \tab html \tab Recognized \cr
#' \tab latex \tab Recognized \cr
#' justify \tab \tab \cr
#' \tab action \tab Justifies the entire table on the page. \cr
#' \tab default \tab "center" \cr
#' \tab accepts \tab character(1) \cr
#' \tab console \tab Not recognized \cr
#' \tab markdown \tab Not recognized \cr
#' \tab html \tab Recognized \cr
#' \tab latex \tab Recognizes "center", but both "left" and "right" \cr
#' \tab \tab are rendered as left justified. This may change \cr
#' \tab \tab if a satisfactory solution is found. \cr
#' \tab \tab Usually, tables are best left centered. \cr
#' longtable \tab \tab \cr
#' \tab action \tab Toggles the use of the LaTeX `longtable` style \cr
#' \tab \tab tables, namely allowing long tables to be broken \cr
#' \tab \tab into multiple sections. The table header appears \cr
#' \tab \tab at the top of each section. The table interfoot \cr
#' \tab \tab appears at the bottom of each section, except \cr
#' \tab \tab for the last. \cr
#' \tab \tab The table foot appears at the bottom of the \cr
#' \tab \tab last section. \cr
#' \tab \tab May accept either a logical or a numerical value. \cr
#' \tab \tab If numerical, each section will have the specified \cr
#' \tab \tab number of rows. \cr
#' \tab default \tab FALSE \cr
#' \tab accepts \tab logical(1); numeric(1) \cr
#' \tab console \tab Recognized; when `TRUE`, defaults to 25 rows \cr
#' \tab \tab per section. \cr
#' \tab markdown \tab Recognized; when `TRUE`, defaults to 25 rows \cr
#' \tab \tab per section. \cr
#' \tab html \tab Recognized; when `TRUE`, defaults to 25 rows \cr
#' \tab \tab per section. \cr
#' \tab latex \tab Recognized; when `TRUE`, `longtable`'s own algorithm \cr
#' \tab \tab will determine the number of rows per section. \cr
#' \tab \tab When numeric, breaks are forced at the specified \cr
#' \tab \tab number of rows. \cr
#' merge \tab \tab \cr
#' \tab action \tab Merges cells in the specified range into a \cr
#' \tab \tab single cell. In cases where \cr
#' \tab \tab either `merge_rowval` or `merge_colval` is \cr
#' \tab \tab specified, they will only be \cr
#' \tab \tab honored if `merge = TRUE`. You must opt in to \cr
#' \tab \tab this action. \cr
#' \tab default \tab FALSE \cr
#' \tab accepts \tab logical(1) \cr
#' \tab console \tab Recognized \cr
#' \tab markdown \tab Recognized \cr
#' \tab html \tab Recognized \cr
#' \tab latex \tab Recognized \cr
#' merge_rowval \tab \tab \cr
#' \tab action \tab Specifies the row value of the merged range to \cr
#' \tab \tab print in the table \cr
#' \tab default \tab minimum row value of the merged range \cr
#' \tab accepts \tab numeric(1) \cr
#' \tab console \tab Recognized \cr
#' \tab markdown \tab Recognized \cr
#' \tab html \tab Recognized \cr
#' \tab latex \tab Recognized \cr
#' merge_colval \tab \tab \cr
#' \tab action \tab Specifies the column value of the merged range \cr
#' \tab \tab to print in the table \cr
#' \tab default \tab minimum col value of the merged range \cr
#' \tab accepts \tab numeric(1) \cr
#' \tab console \tab Recognized \cr
#' \tab markdown \tab Recognized \cr
#' \tab html \tab Recognized \cr
#' \tab latex \tab Recognized \cr
#' na_string \tab \tab \cr
#' \tab action \tab Designates the character string to use in place \cr
#' \tab \tab of missing values \cr
#' \tab default \tab NA \cr
#' \tab accepts \tab character(1) \cr
#' \tab console \tab Recognized \cr
#' \tab markdown \tab Recognized \cr
#' \tab html \tab Recognized \cr
#' \tab latex \tab Recognized \cr
#' pad \tab \tab \cr
#' \tab action \tab Designates the padding to place between cell \cr
#' \tab \tab text and boundaries \cr
#' \tab \tab Measured in pixels. \cr
#' \tab default \tab 0 \cr
#' \tab accepts \tab numeric(1) \cr
#' \tab console \tab Not recognized \cr
#' \tab markdown \tab Not recognized \cr
#' \tab html \tab Recognized \cr
#' \tab latex \tab Not recognized \cr
#' replace \tab \tab \cr
#' \tab action \tab Replaces existing cell values with user-specified \cr
#' \tab \tab content. Replacement occurs moving down columns \cr
#' \tab \tab from left to right. \cr
#' \tab default \tab \cr
#' \tab accepts \tab character vector of the same length as the number \cr
#' \tab \tab of cells being replaced. \cr
#' \tab console \tab Recognized \cr
#' \tab markdown \tab Recognized \cr
#' \tab html \tab Recognized \cr
#' \tab latex \tab Recognized \cr
#' rotate_degree \tab \tab \cr
#' \tab action \tab Rotates text in cells by the designated angle \cr
#' \tab \tab in degrees \cr
#' \tab default \tab \cr
#' \tab accepts \tab numeric(1) \cr
#' \tab console \tab Not recognized \cr
#' \tab markdown \tab Not recognized \cr
#' \tab html \tab Recognized \cr
#' \tab latex \tab Recognized \cr
#' round \tab \tab \cr
#' \tab action \tab Applies the `round` function to values in the \cr
#' \tab \tab cell. Skips any character values it encounters. \cr
#' \tab default \tab \code{getOption("digits")} \cr
#' \tab accepts \tab numeric(1) \cr
#' \tab console \tab Recognized \cr
#' \tab markdown \tab Recognized \cr
#' \tab html \tab Recognized \cr
#' \tab latex \tab Recognized \cr
#' sanitize \tab \tab \cr
#' \tab action \tab Sanitizes character values that may cause \cr
#' \tab \tab difficulties for the rendered format. \cr
#' \tab default \tab FALSE \cr
#' \tab accepts \tab logical(1) \cr
#' \tab console \tab Not recognized \cr
#' \tab markdown \tab Not recognized \cr
#' \tab html \tab Not recognized \cr
#' \tab latex \tab Recognized. Sanitization is performed using \cr
#' \tab \tab \code{\link[Hmisc]{latexTranslate}} \cr
#' sanitize_args \tab \tab \cr
#' \tab action \tab Passes additional arguments to \code{\link[Hmisc]{latexTranslate}} \cr
#' \tab default \tab \code{list()} \cr
#' \tab accepts \tab list. See documentation for \code{\link[Hmisc]{latexTranslate}} \cr
#' \tab \tab for details \cr
#' \tab console \tab Not recognized \cr
#' \tab markdown \tab Not recognized \cr
#' \tab html \tab Not recognized \cr
#' \tab latex \tab Recognized \cr
#' tabcolsep \tab \tab \cr
#' \tab action \tab Modifies the LaTeX `tabcolsep` parameter of tables \cr
#' \tab \tab This is similar to `pad` for HTML tables, but only \cr
#' \tab \tab affects the space between columns. Measured in "pt" \cr
#' \tab default \tab 6 \cr
#' \tab accepts \tab numeric(1) \cr
#' \tab console \tab Not recognized \cr
#' \tab markdown \tab Not recognized \cr
#' \tab html \tab Not recognized \cr
#' \tab latex \tab Recognized \cr
#' valign \tab \tab \cr
#' \tab action \tab Designates the vertical alignment of a cell. \cr
#' \tab default \tab \cr
#' \tab accepts \tab "top", "middle", "bottom" \cr
#' \tab console \tab Not recognized \cr
#' \tab markdown \tab Not recognized \cr
#' \tab html \tab Recognized \cr
#' \tab latex \tab Recognized \cr
#' width \tab \tab \cr
#' \tab action \tab Sets the width of the cell \cr
#' \tab default \tab \cr
#' \tab accepts \tab numeric(1) \cr
#' \tab console \tab Not recognized \cr
#' \tab markdown \tab Not recognized \cr
#' \tab html \tab Recognized \cr
#' \tab latex \tab Recognized \cr
#' width_units \tab \tab \cr
#' \tab action \tab Determines the units in which `width` is measured \cr
#' \tab default \tab "pt" \cr
#' \tab accepts \tab "px", "pt", "cm", "in", "\%" \cr
#' \tab console \tab Not recognized \cr
#' \tab markdown \tab Not recognized \cr
#' \tab html \tab Recognized \cr
#' \tab latex \tab Recognized; "px" is coerced to "pt" \cr
#' }
#'
# Longtable details -------------------------------------------------
#' @section Longtable:
#' The \code{longtable} feature is named for the LaTeX package used to break very large
#' tables into multiple pages.
#'
#' When using the \code{longtable=TRUE} option, the default number of rows per table is 25 for
#' console, HTML, and markdown output. For LaTeX output, the number of rows is determined by
#' the LaTeX \code{longtable} package's algorithm. The number of rows per table only considers
#' the content in the body of the table. Consideration for the number of rows in the head and
#' foot are the responsibility of the user.
#'
#' Whenever a table is broken into multiple parts, each part retains the table head. If any
#' \code{interfoot} is provided, it is appended to the bottom of each section, with the
#' exception of the last section. The last section has the \code{foot} appended.
#'
# Colors ------------------------------------------------------------
#' @section Colors:
#' Colors may be declared as any of the color names in \code{colors()},
#' as rgb character strings such as \code{"rgb(rrr,ggg,bbb)"} or as
#' hexadecimal character strings such as \code{"#rrggbb"}.
#'
#' Transparency is also recognized by HTML output, and may be indicated
#' in the rgba format \code{"rgba(rrr,ggg,bbb,aa)"}, where \code{aa} is a
#' number between 0 and 1, inclusive. Alternative, transparency may be
#' given as \code{"#rrggbbAA"}, where \code{AA} is a hexadecimal
#' representation of transparency with "00" being completely transparent
#' and "FF" being completely opaque.
#'
#' LaTeX output does not recognize transparency and will quietly drop the
#' transparency parameter.
#'
#' All colors are internally translated into rgb format and are case insensitive.
#'
# LaTeX Packages ----------------------------------------------------
#' @section Required LaTeX Packages:
#'
#' If you will be using the LaTeX output, some sprinkles will require you
#' to include additional LaTeX packages in your document preamble. In
#' \code{.Rnw} files, additional packages can be included with the
#' \code{\\usepackage\{[package]\}} syntax. In markdown, additional packages
#' are included using \code{header-includes:} in the YAML front matter with
#' a line of the format \code{\\usepackage\{[package]\}} for each package to
#' be used. Sprinkles that require additional packages, and the LaTeX packages
#' required, are listed below:
#'
#' \tabular{ll}{
#' Sprinkle \tab LaTeX Package(s) \cr
#' \code{font_color} \tab \code{\\usepackage[dvipsnames]\{xcolor\}} \cr
#' \code{bg, bg_pattern} \tab \code{\\usepackage[dvipsnames,table]\{xcolor\}} \cr
#' \code{border_style} \tab \code{\\usepackage\{arydshln\}} \cr
#' \tab \code{\\usepackage\{amssymb\}} \cr
#' \tab \code{\\usepackage\{hhline\}} \cr
#' (with vertical dashed lines) \tab \\usepackage\{graphicx\} \cr
#' \tab \code{\\makeatletter} \cr
#' \tab \code{\\newcommand*\\vdashline\{\\rotatebox[origin=c]\{90\}\{\$\\dabar@@\\dabar@@\\dabar@@\$\}\}} \cr
#' \tab \code{\\makeatother} \cr
#' \code{longtable} \tab \code{\\usepackage\{longtable\}} \cr
#' \tab (Must be loaded before \code{arydshln}) \cr
#' \code{merge} \tab \code{\\usepackage\{multirow\}} \cr
#' \code{captions} for non floats \tab \code{\\usepackage\{caption\}}
#' }
#'
#' Note that \code{hhline} is used to make horizontal lines when
#' \code{options(pixiedust_latex_hhline = TRUE)} (the package default is \code{FALSE}),
#' otherwise the \code{cline} command is used.
#'
#' Use of \code{cline} permits colored borders and dashed borders, but
#' borders around cells with background colors are sometimes (often) lost.
#'
#' Use of \code{hhline} preserves borders around cells with background colors
#' and permits double borders, but colored and dashed borders are not available.
#'
#' In order to ensure all features are available, the recommended code block (accounting for
#' the proper order to load packages) is:
#'
#' \code{header-includes:} \cr
#' \code{ - \\usepackage\{amssymb\}} \cr
#' \code{ - \\usepackage\{arydshln\}} \cr
#' \code{ - \\usepackage\{caption\}} \cr
#' \code{ - \\usepackage\{graphicx\}} \cr
#' \code{ - \\usepackage\{hhline\}} \cr
#' \code{ - \\usepackage\{longtable\}} \cr
#' \code{ - \\usepackage\{multirow\}} \cr
#' \code{ - \\usepackage[dvipsnames,table]\{xcolor\}} \cr
#' \code{ - \\makeatletter} \cr
#' \code{ - \\newcommand*\\vdashline\{\\rotatebox[origin=c]\{90\}\{\$\\dabar@@\\dabar@@\\dabar@@\$\}\}} \cr
#' \code{ - \\makeatother}
#'
# Remaining Documentation -------------------------------------------
#' @seealso
#' \code{\link{sprinkle_colnames}} for changing column names in a table.
#'
#' @source
#' Altering the number of rows in a LaTeX longtable \cr
#' http://tex.stackexchange.com/questions/19710/how-can-i-set-the-maximum-number-of-rows-in-a-page-for-longtable
#'
#' Vertical dashed cell borders in LaTeX table \cr
#' http://www.latex-community.org/forum/viewtopic.php?f=45&t=3149
#'
#' Colored Cell border \cr
#' http://tex.stackexchange.com/questions/40666/how-to-change-line-color-in-tabular
#'
#' @author Benjamin Nutter
#'
#' @examples
#' x <- dust(lm(mpg ~ qsec + factor(am), data = mtcars))
#' x %>% sprinkle(cols = 2:4, round = 3) %>%
#' sprinkle(cols = 5, fn = quote(pvalString(value))) %>%
#' sprinkle(rows = 2, bold = TRUE)
#'
#' @rdname sprinkle
#' @export
# sprinkle method ---------------------------------------------------
sprinkle <- function(x, rows = NULL, cols = NULL, ...,
part = c("body", "head", "foot", "interfoot", "table"))
{
UseMethod("sprinkle")
}
# sprinkle.default --------------------------------------------------
#' @rdname sprinkle
#' @export
sprinkle.default <- function(x, rows = NULL, cols = NULL, ...,
part = c("body", "head", "foot", "interfoot", "table"),
fixed = FALSE,
recycle = c("none", "rows", "cols", "columns"))
{
sprinkles <- list(...)
# Argument validations ----------------------------------------------
coll <- checkmate::makeAssertCollection()
checkmate::assertClass(x = x,
classes = "dust",
add = coll)
if (!length(sprinkles)){
coll$push("At least one sprinkle must be declared in ...")
}
else
{
sprinkle_match <-
unlist(sprinkle_groups)[pmatch(names(sprinkles),
unlist(sprinkle_groups))]
unmatched_sprinkle <-
names(sprinkles)[which(is.na(sprinkle_match))]
names(sprinkles) <- sprinkle_match
if (length(unmatched_sprinkle))
{
coll$push(
sprintf("The following arguments could not be matched to an existing sprinkle (check spelling and partial matching): %s",
paste(unmatched_sprinkle, collapse = ", "))
)
sprinkles <- sprinkles[!is.na(names(sprinkles))]
}
}
if (!checkmate::test_named(sprinkles)){
coll$push("Arguments to ... must be named")
}
not_sprinkles <-
sprinkles[!names(sprinkles) %in% unlist(sprinkle_groups)]
if (length(not_sprinkles)){
coll$push(sprintf("The following are not valid sprinkles: %s",
paste0(names(not_sprinkles), collapse = ", ")))
}
indices <- index_to_sprinkle(x = x,
rows = rows,
cols = cols,
fixed = fixed,
part = part,
recycle = recycle,
coll = coll)
recycle <- recycle[1]
for (i in seq_along(sprinkle_groups))
{
if (any(sprinkle_groups[[i]] %in% names(sprinkles)))
{
sprinkle_arg <- c(sprinkles[sprinkle_groups[[i]]], "recycle" = recycle)
sprinkle_arg <- sprinkle_arg[names(sprinkle_arg) %in% sprinkle_groups[[i]]]
sprinkle_arg <- sprinkle_arg[!vapply(sprinkle_arg, is.null, logical(1))]
if (!"fn" %in% names(sprinkle_arg))
{
args_list <-
if (names(sprinkle_groups)[i] == "replace")
{
list(indices = indices,
coll = coll)
}
else
{
list(coll = coll)
}
do.call(what = sprintf("sprinkle_%s_index_assert",
names(sprinkle_groups)[[i]]),
args = c(sprinkle_arg,
args_list))
}
}
}
if ("fn" %in% names(sprinkles))
{
sprinkle_fn_index_assert(fn = sprinkles$fn,
coll = coll)
}
#* Return any errors found.
checkmate::reportAssertions(coll)
# Functional Code ---------------------------------------------------
part <- part[1]
for (i in seq_along(sprinkle_groups))
{
if (any(sprinkle_groups[[i]] %in% names(sprinkles)))
{
sprinkle_arg <- sprinkles[sprinkle_groups[[i]]]
sprinkle_arg <- sprinkle_arg[!vapply(sprinkle_arg, is.null, logical(1))]
if (!"fn" %in% names(sprinkle_arg))
{
x <- do.call(what = sprintf("sprinkle_%s_index",
names(sprinkle_groups)[[i]]),
args = c(sprinkle_arg,
list(x = x,
indices = indices,
part = part)))
}
}
}
if ("fn" %in% names(sprinkles))
{
x <- sprinkle_fn_index(x = x,
indices = indices,
fn = sprinkles$fn,
part = part)
}
x
}
# sprinkle.dust_list ------------------------------------------------
#' @rdname sprinkle
#' @export
sprinkle.dust_list <- function(x, rows = NULL, cols = NULL, ...,
part = c("body", "head", "foot", "interfoot", "table"))
{
structure(
lapply(X = x,
FUN = sprinkle,
rows = rows,
cols = cols,
part = part,
...),
class = "dust_list"
)
}
# Unexported --------------------------------------------------------
sprinkle_groups <-
list(
align = c("halign", "valign", "recycle"),
bg = c("bg", "recycle"),
bg_pattern = c("bg_pattern", "bg_pattern_by"),
bookdown = "bookdown",
border = c("border", "border_color", "border_style",
"border_thickness", "border_units", "recycle"),
border_collapse = "border_collapse",
caption = "caption",
caption_number = "caption_number",
discrete = c("discrete", "discrete_colors"),
fixed_header = c("fixed_header", "include_fixed_header_css",
"fixed_header_class_name",
"scroll_body_height", "scroll_body_height_units",
"scroll_body_background_color",
"fixed_header_height", "fixed_header_height_units",
"fixed_header_text_height", "fixed_header_text_height_units",
"fixed_header_background_color"),
float = "float",
fn = c("fn"),
font = c("bold", "italic", "font_size", "font_size_units",
"font_color", "font_family", "recycle"),
gradient = c("gradient", "gradient_colors", "gradient_cut",
"gradient_n", "gradient_na"),
height = c("height", "height_units", "recycle"),
hhline = "hhline",
justify = "justify",
label = "label",
longtable = "longtable",
merge = c("merge", "merge_rowval", "merge_colval"),
na_string = c("na_string", "recycle"),
pad = c("pad", "recycle"),
replace = "replace",
rotate_degree = c("rotate_degree"),#, "recycle"),
round = c("round"),#, "recycle"),
sanitize = c("sanitize", "sanitize_args"),
tabcolsep = "tabcolsep",
width = c("width", "width_units", "recycle")
)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.