tidy

coolbutuseless · May 5, 2024 · c40eaaf · c40eaaf
1 parent 8a6a59c
commit c40eaaf
Show file tree

Hide file tree

Showing 52 changed files with 357 additions and 330 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,7 +1,7 @@
 Package: emphatic
 Type: Package
 Title: Highlight R Output
-Version: 0.1.6.9011
+Version: 0.1.6.9012
 Author: mikefc
 Maintainer: mikefc <[email protected]>
 Description: User-defined colour highlighting of data.frames and other R output. 

diff --git a/NEWS.md b/NEWS.md
@@ -1,5 +1,5 @@
 
-# emphatic 0.1.6.9011  2024-05-04
+# emphatic 0.1.6.9012  2024-05-05
 
 * Removed `hl_mat()` and associated vignettes.
     * function is not exported for now as the selection process is too 
@@ -16,6 +16,7 @@
 * latex rendering now has better whitespace at start of line
 * SVG anim support
 * Excel export
+* Refactor options for hl_grep and hl_diff
 
 # emphatic 0.1.6  2024-04-27
 

diff --git a/R/hl-diff.R b/R/hl-diff.R
@@ -41,7 +41,11 @@ hl_diff <- function(x, y,
   #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   # Default colours
   #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  fill_default_dark  <- list(sub = 'dodgerblue' , ins = 'darkgreen', del = 'firebrick' )
+  fill_default_dark  <- list(
+    sub = getOption("HL_SUB_COL", 'dodgerblue') ,
+    ins = getOption("HL_INS_COL", 'darkgreen' ) ,
+    del = getOption("HL_DEL_COL", 'firebrick' )
+  )
 
   #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   # Work hard to ensure we have a full complement of colours for both

diff --git a/R/hl-grep.R b/R/hl-grep.R
@@ -37,7 +37,7 @@ hl_grep <- function(x,
   # Choose colours
   #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   if (is.null(fill)) {
-    fill <- "#0F19F0"
+    fill <- getOption("HL_GREP_COL", "#0F19F0")
   }
   if (is.null(text)) {
     text <- calc_contrasting_text(

diff --git a/R/options.R b/R/options.R
@@ -60,7 +60,7 @@ find_args <- function () {
 #'        Note: RStudio only supports 8 bit ANSI output (24bit ANSI is
 #'        rendered invisibly in Rstudio).  For 24bit colour output, try R in the terminal
 #'        e.g. 'iTerm' on OSX.
-#' @param text_mode How to handle textif no text colour has been
+#' @param text_mode How to handle text if no text colour has been
 #'        explicitly specified by the user.
 #'        \describe{
 #'        \item{contrast}{(default) automatically select a contrasting colour for enhanced readability.}

diff --git a/R/zzz.R b/R/zzz.R
@@ -67,11 +67,19 @@ get_env_dbl <- function(nm, unset) {
 #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 .onLoad <- function(libname, pkgname) {
 
-  options(HL_NA            = Sys.getenv ("HL_NA"           , unset =       'NA'))
-  options(HL_FULL_COLOUR   = get_env_lgl("HL_FULL_COLOUR"  , unset =      FALSE))
-  options(HL_TEXT_MODE     = Sys.getenv ("HL_TEXT_MODE"    , unset = 'contrast'))
-  options(HL_TEXT_CONTRAST = get_env_dbl("HL_TEXT_CONTRAST", unset =          1))
-  options(HL_UNDERLINE     = get_env_lgl("HL_UNDERLINE"    , unset =       TRUE))
+  options(HL_NA            = Sys.getenv ("HL_NA"           , unset =          'NA'))
+  options(HL_TEXT_MODE     = Sys.getenv ("HL_TEXT_MODE"    , unset =    'contrast'))
+  options(HL_TEXT_CONTRAST = get_env_dbl("HL_TEXT_CONTRAST", unset =             1))
+  options(HL_GREP_COL      = Sys.getenv("HL_GREP_COL"      , unset =     "#0F19F0"))
+  options(HL_SUB_COL       = Sys.getenv("HL_SUB_COL"       , unset =  "dodgerblue"))
+  options(HL_INS_COL       = Sys.getenv("HL_INS_COL"       , unset =   "darkgreen"))
+  options(HL_DEL_COL       = Sys.getenv("HL_DEL_COL"       , unset =   "firebrick"))
+
+  # Is this the Rstudio 256 colour console?
+  rstudio_256 <- Sys.getenv("RSTUDIO_CONSOLE_COLOR", 0) == 256
+
+  # Assume anything not Rstudio is 24-bit colour
+  options(HL_FULL_COLOUR   = get_env_lgl("HL_FULL_COLOUR"  , unset = !rstudio_256))
 
   #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   # Enable knit_print compatibility without requiring 'knitr' in 'Imports'

diff --git a/README.Rmd b/README.Rmd
@@ -8,13 +8,15 @@ output: github_document
 knitr::opts_chunk$set(
   collapse = TRUE,
   comment = "#>",
-  fig.path = "man/figures/README-",
+  fig.path = "data-raw/figures/README-",
   out.width = "100%"
 )
 
 library(dplyr)
 library(ggplot2)
 library(emphatic)
+
+set.seed(1)
 ```
 
 
@@ -31,7 +33,7 @@ if (FALSE) {
 
 
 ```{r echo = FALSE, eval = FALSE}
-img <- image_read("man/figures/white.png")
+img <- image_read("data-raw/figures/white.png")
 
 
 hexSticker::sticker(subplot  = img,
@@ -48,9 +50,9 @@ hexSticker::sticker(subplot  = img,
                     h_size   = 1.2,
                     h_fill   = "#ffffff",
                     h_color  = "#223344",
-                    filename = "man/figures/logo.png")
+                    filename = "data-raw/figures/logo.png")
 
-image_read("man/figures/logo.png")
+image_read("data-raw/figures/logo.png")
 ```
 
 
@@ -62,24 +64,30 @@ image_read("man/figures/logo.png")
 [![R-CMD-check](https://github.com/coolbutuseless/emphatic/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/coolbutuseless/emphatic/actions/workflows/R-CMD-check.yaml)
 <!-- badges: end -->
 
-`{emphatic}` uses ANSI colouring in the terminal to add user-controlled highlighting to data.frames and other R output.
+`{emphatic}` allows for user-defined highlighting of data.frames.
+
+This highlighting works 
+
+* in the console
+* rendered to HTML (e.g. in Rmarkdown documents)
+* rendered to latex
+* rendered to [typst](https://typst.app) (e.g. in Quarto documents)
+* rendered to SVG and animated SVG
 
-<!-- <img src="man/figures/examples.gif"/> -->
+<img src="data-raw/figures/examples.gif"/>
 
 #### What's in the box
 
-* `hl()` for user-controlled highlighting of data.frames
+* `hl()` for user-defined highlighting of data.frames
 * `hl_diff()` for highlighting differences between two objects 
 * `hl_grep()` highlight regular expression matches in an object or string
-* Conversion of the "emphatic" object to formats for rendering Rmarkdown/Quarto
-  documents, and saving to file:
+* Output from `hl_*()` functions will automatically be rendered in Rmarkdown
+  and Quarto documents with output formats of html, PDF and typst.
+* The highlighted output can be explicitly converted to other formats using:
     * `as_html()`
     * `as_svg()` and animated `as_svg_anim()`
     * `as_typst()`
     * `write_xlsx()` - Excel document
-
-
-<span style="font-size:smaller">`hl_` prefix can be read as `highlight`</span>
 
 #### Installation
 
@@ -92,16 +100,16 @@ remotes::install_github('coolbutuseless/emphatic', ref = 'main')
 
 
 
-## `hl()` - user-controlled highlighting of data.frames 
+## User-controlled highlighting of data.frames with `hl()`
 
 * specify rows and columns you want to highlight
-* specify a colour
+* specify a palette
     * a single colour
     * a vector of colours
     * a `ggplot2` "Scale" object e.g. `scale_colour_continuous()`
 
 
-#### `hl()` simple example of highlighting a data.frame
+#### Simple highlighting a data.frame
 
 By default, colouring will be applied to all rows and columns.
 
@@ -116,23 +124,23 @@ mtcars |>
   head(15) |>
   hl(c('red', 'white', 'blue')) |>
   as_svg(650, 350) |>
-  cat(file = "man/figures/example1.svg")
+  cat(file = "data-raw/figures/example1.svg")
 ```
 
-<img src="man/figures/example1.svg" width="100%">
+<img src="data-raw/figures/example1.svg" width="100%">
 
 
-#### `hl()` complex example of highlighting a data.frame
+#### Complex example of highlighting a data.frame
 
 
 A more complex example showing how to highlight the `mtcars` dataset where:
 
-* colour each row to indicate the miles-per-gallon rating
-* do not colour the `gear` or `carb` columns
-* highlight the car with the minimum horsepower (`hp`) in `hotpink`
+* Determine the colours using `scale_colour_viridis_c()` applied to `mpg`
+* Apply the scale's colouring to all columns from `mpg` to `disp`
+* highlight the row for the car with the minimum horsepower (`hp`) in `hotpink`
 
-Note also that `hl()` calls are cumulative, and you can build up the 
-highlighting you need step by step
+`hl()` calls are cumulative - you can build up the 
+highlighting you need step-by-step
 
 ```{r eval = FALSE}
 mtcars |>
@@ -158,14 +166,14 @@ mtcars |>
   ) |>
   hl('hotpink', rows = hp == min(hp), cols = hp:carb) |>
   as_svg(650, 380) |>
-  cat(file = "man/figures/example2.svg")
+  cat(file = "data-raw/figures/example2.svg")
 ```
 
-<img src="man/figures/example2.svg" width="100%">
+<img src="data-raw/figures/example2.svg" width="100%">
 
 
 
-## `hl_diff()` highlight difference between two objects
+## Highlight difference between two objects with `hl_diff()`
 
 The Levenshtein edit distance is calculated between the string representation
 of two objects and these edits are then coloured 🟢 = insert, 🔴 = delete, 
@@ -183,10 +191,10 @@ x <- "Paris in the the spring?"
 y <- "Not Paris in the spring!"
 hl_diff(x, y) |>
   as_svg(600, 80) |>
-  cat(file = "man/figures/example-strdiff-3.svg")
+  cat(file = "data-raw/figures/example-strdiff-3.svg")
 ```
 
-<img src="man/figures/example-strdiff-3.svg" width="100%">
+<img src="data-raw/figures/example-strdiff-3.svg" width="100%">
 
 Levenshtein's edit distance naturally applies to strings, but `hl_diff()` can 
 visualise the difference between arbitrary objects by first converting them
@@ -203,12 +211,12 @@ hl_diff(mean, median, coerce = 'print', sep = " ")
 ```{r echo=FALSE}
 hl_diff(mean, median, coerce = 'print', sep = " ") |>
   as_svg(600, 200) |>
-  cat(file = "man/figures/example-strdiff-4.svg")
+  cat(file = "data-raw/figures/example-strdiff-4.svg")
 ```
 
-<img src="man/figures/example-strdiff-4.svg" width="100%">
+<img src="data-raw/figures/example-strdiff-4.svg" width="100%">
 
-## `hl_grep()` highlight regular expression matches in objects
+## Highlight regular expression matches in objects with `hl_grep()` 
 
 `hl_grep()` highlights the regular expression matches within a string or
 objects coerced into a string representation.
@@ -217,26 +225,29 @@ objects coerced into a string representation.
 
 
 ```{r eval = FALSE} 
-gettysburg <- c(
-  "Four score and seven years ago our fathers brought forth on",
-  "this continent, a new nation, conceived in Liberty, and dedicated to the", 
-  "proposition that all men are created equal."
-)
-hl_grep(gettysburg, "men.*equal")
+txt <- "Among the few possessions he left to his heirs was a set of 
+Encyclopedia Britannica in storage at the Lindbergh Palace Hotel under the 
+names Ari and Uzi Tenenbaum. No-one spoke at the funeral, and Father 
+Petersen's leg had not yet mended, but it was agreed among them that Royal 
+would have found the event to be most satisfactory.
+[Chas, now wearing a black Adidas tracksuit, nods to his sons]"
+
+hl_grep(txt, "event.*satisfactory", coerce = 'character')
 ```
 
 ```{r echo = FALSE}
-gettysburg <- c(
-  "Four score and seven years ago our fathers brought forth on",
-  "this continent, a new nation, conceived in Liberty, and dedicated to the", 
-  "proposition that all men are created equal."
-)
-hl_grep(gettysburg, "men.*equal") |>
-  as_svg(600, 80) |>
-  cat(file = "man/figures/example-hlgrep-1.svg")
+txt <- "Among the few possessions he left to his heirs was a set of 
+Encyclopedia Britannica in storage at the Lindbergh Palace Hotel under the 
+names Ari and Uzi Tenenbaum. No-one spoke at the funeral, and Father 
+Petersen's leg had not yet mended, but it was agreed among them that Royal 
+would have found the event to be most satisfactory.
+[Chas, now wearing a black Adidas tracksuit, nods to his sons]"
+hl_grep(txt, "event.*satisfactory", coerce = 'character')|>
+  as_svg(600, 200) |>
+  cat(file = "data-raw/figures/example-hlgrep-1.svg")
 ```
 
-<img src="man/figures/example-hlgrep-1.svg" width="100%">
+<img src="data-raw/figures/example-hlgrep-1.svg" width="100%">
 
 #### Highlight regular expression matches within an object
 
@@ -253,10 +264,10 @@ hl_grep(mode, 'switch')
 ```{r echo = FALSE}
 hl_grep(mode, 'switch') |>
   as_svg(600, 250) |>
-  cat(file = "man/figures/example-hlgrep-2.svg")
+  cat(file = "data-raw/figures/example-hlgrep-2.svg")
 ```
 
-<img src="man/figures/example-hlgrep-2.svg" width="100%">
+<img src="data-raw/figures/example-hlgrep-2.svg" width="100%">
 
 
 # Animated SVG
@@ -270,7 +281,7 @@ objs <- list(
   hl_grep("goodbye", "good boy")
 ) 
 
-svg <- as_svg_anim(objs, width = 600, height = 300, duration = 3, 
+svg <- as_svg_anim(objs, width = 600, height = 300, duration = 2, 
                    playback = 'infinite')
 ```
 
@@ -281,15 +292,15 @@ objs <- list(
   hl_diff("goodbye", "good boy")
 ) 
 
-svg <- as_svg_anim(objs, width = 600, height = 100, duration = 1.5, 
+svg <- as_svg_anim(objs, width = 600, height = 100, duration = 2, 
                    playback = 'infinite', browsable = FALSE)
 
-writeLines(svg, "man/figures/example-svg-anim.svg")
+writeLines(svg, "data-raw/figures/example-svg-anim.svg")
 # svg
 ```
 
 
-<img src="man/figures/example-svg-anim.svg" width="100%">
+<img src="data-raw/figures/example-svg-anim.svg">
 
 
 
@@ -300,19 +311,25 @@ writeLines(svg, "man/figures/example-svg-anim.svg")
 * `hl_opts()` create a named list of default options accepted by the functions 
   in this package
 * `hl_adjust()` to adjust options after creation.
-* Set the following options to control global behaviour within a session.
-    * `HL_NA`
-    * `HL_FULL_COLOUR`
-    * `HL_TEXT_MODE`
-    * `HL_TEXT_CONTRAST`
-* The above R options are initialised using `Sys.getenv()` during package start,
-  and otherwise use a default value.
+* These options are initialised at package start time using `Sys.getenv()`.
   Set these values as environment variables in your `.Rprofile` to save 
   your preferred settings across different sessions.  e.g.
-    * `Sys.setenv(HL_NA = FALSE)` prior to loading package
+    * `Sys.setenv(HL_NA = "<none>")` prior to loading package or in `.Rprofile`
     * `options(HL_NA = FALSE)` at any time
 
 
+| Option  |  Description |
+|:-----------|:------------------|
+| `HL_NA`            | String to use for NA values. Default "NA"  |
+| `HL_FULL_COLOUR`   | Should full colour ANSI codes be used when outputting to the  console?  Default: FALSE on Rstudio, but TRUE on all other R consoles  |
+| `HL_TEXT_MODE`     | How to handle text if no text colour has been explicitly specified by the user  |
+|  | `"contrast"` (default) automatically select a colour which contrasts with the background |
+|  | `"asis"` do not change the colour from the console's default |
+|  | `"remove"` remove all text without a user-defined colour  |
+| `HL_TEXT_CONTRAST` | When `text_mode = "contrast"` this numeric value (in range [0, 1]) adjusts the visibility of the text. Default: 1 (high contrast)  |
+| `HL_GREP_COL`      |The fill colour to use with `hl_grep()` if no colour is specified. Default: "#0F19F0"|
+| `HL_SUB_COL`, `HL_INS_COL`, `HL_DEL_COL`     |  the default colours to use with `hl_diff()` for substitution, insertion and deletion (respectively). Defaults: `dodgerblue` (substitute), `darkgreen` (insert) and `firebrick` (delete)  |
+
 
 ## Vignettes
 
@@ -327,3 +344,18 @@ vignettes and more examples.
     * [Specifying colours](https://coolbutuseless.github.io/package/emphatic/articles/specify-colours.html)
 * Worked Examples
     * [Space Shuttle O-ring dataset - Challenger Disaster](https://coolbutuseless.github.io/package/emphatic/articles/challenger.html)
+
+
+```{r echo = FALSE}
+knitr::knit_exit()
+```
+
+
+
+
+
+
+
+
+
+