From 531cb88e33a22c636cda87474620cedaff5756ba Mon Sep 17 00:00:00 2001
From: "Elian H. Thiele-Evans" <60372411+ElianHugh@users.noreply.github.com>
Date: Sat, 21 Oct 2023 21:59:40 +1100
Subject: [PATCH] Minor doc changes

- Minor elements refactoring
- extension tests for with_()*
- Minor edit to README
- Minor documentation changes
-
---
 R/elements.R               | 38 ++++++++++++++++++--------------------
 R/misc.R                   |  2 ++
 R/with.R                   |  1 +
 README.md                  | 16 ++++++++--------
 README.qmd                 |  2 +-
 man/as_markdown.Rd         |  3 +++
 man/div.Rd                 |  7 ++++---
 man/page-layout.Rd         |  3 +++
 man/span.Rd                |  7 ++++---
 tests/testthat/test_with.R | 14 ++++++++++++++
 10 files changed, 58 insertions(+), 35 deletions(-)

diff --git a/R/elements.R b/R/elements.R
index 4f66949..35c08ef 100644
--- a/R/elements.R
+++ b/R/elements.R
@@ -1,10 +1,11 @@
 #' Create a quarto div element
 #' @description
 #' Create a div block element with optional attributes to assign to it. Dots
-#' are collapsed into a single character vector with a newline between each element.
+#' are collapsed into a single character vector with a newline between each
+#' element.
 #'
-#' If attr is a vector with a length > 1, attributes will be combined into a
-#' single character vector via [base::paste0].
+#' If attr is a vector with a length > 1, attributes will be combined into
+#' a single character vector via [base::paste0].
 #' @param ... unnamed values that can be coerced to character vectors
 #' @param attr values that can be coerced to character vectors
 #' @examples
@@ -22,15 +23,13 @@
 div <- function(..., attr = NULL) {
     rlang::check_dots_unnamed()
 
-    out <- "\n\n:::{%s}\n\n%s\n\n:::\n"
-    args <- rlang::dots_list(...)
-    attr <- attr %||% "" |>
-        paste0(collapse = " ")
-    content <- args |>
-        paste0(collapse = "\n\n")
+    template_string <- "\n\n:::{%s}\n\n%s\n\n:::\n"
+    dots <- rlang::dots_list(...)
+    attribs <-  paste0(attr %||% "", collapse = " ")
+    content <- paste0(dots, collapse = "\n\n")
 
     structure(
-        sprintf(out, attr, content),
+        sprintf(template_string, attribs, content),
         class = "knit_asis"
     )
 }
@@ -38,10 +37,11 @@ div <- function(..., attr = NULL) {
 #' Create a quarto span element
 #' @description
 #' Create a span element with optional attributes to assign to it. Dots
-#' are collapsed into a single character vector with a space between each element.
+#' are collapsed into a single character vector with a space between
+#' each element.
 #'
-#' If attr is a vector with a length > 1, attributes will be combined into a single
-#'  character vector via [base::paste0].
+#' If attr is a vector with a length > 1, attributes will be combined into
+#' a single character vector via [base::paste0].
 #' @inheritParams div
 #' @examples
 #' span("Hello world!", attr = ".bold")
@@ -51,15 +51,13 @@ div <- function(..., attr = NULL) {
 span <- function(..., attr = NULL) {
     rlang::check_dots_unnamed()
 
-    out <- "[%s]{%s}"
-    args <- rlang::dots_list(...)
-    attr <- attr %||% "" |>
-        paste0(collapse = " ")
-    content <- args |>
-        paste0(collapse = " ")
+    template_string <- "[%s]{%s}"
+    dots <- rlang::dots_list(...)
+    attribs <-  paste0(attr %||% "", collapse = " ")
+    content <- paste0(dots, collapse = " ")
 
     structure(
-        sprintf(out, content, attr),
+        sprintf(template_string, content, attribs),
         class = "knit_asis"
     )
 }
diff --git a/R/misc.R b/R/misc.R
index 6eb5b29..3766b62 100644
--- a/R/misc.R
+++ b/R/misc.R
@@ -5,6 +5,8 @@
 #' the character vector as markdown content, rather than as an R value.
 #' @param x object to convert to character vector
 #' @inheritParams base::paste0
+#' @examples
+#' as_markdown(c("Hello world!"))
 #' @return character vector of length 1
 #' @export
 as_markdown <- function(x, collapse = "") {
diff --git a/R/with.R b/R/with.R
index 2ab4100..e1405c3 100644
--- a/R/with.R
+++ b/R/with.R
@@ -10,6 +10,7 @@
 #' @export
 #' @examples
 #' with_body_column("Hello world!")
+#' @return character vector of length 1
 #' @rdname page-layout
 with_body_column <- function(..., attr = NULL, outset = FALSE, extension = NULL) {
     check_extension_arg(extension, c("left", "right"))
diff --git a/README.md b/README.md
index 759239b..d56a768 100644
--- a/README.md
+++ b/README.md
@@ -18,14 +18,14 @@ function calls. As *quartools* generates quarto-compliant markdown, and
 ## Why quartools?
 
 At work, I ran into an issue where I was generating hundreds of
-parameterised reports that would be similar with subtle differences in
-content. I found myself leaning on R for programmatic markup creation,
-which meant that I could have one master document that I worked on. My
-prototype version (in other words, functions I threw together for work)
-required a lot of constant chunk configuration, and wasn’t particularly
-user-friendly nor elegant. *quartools* is a more streamlined version of
-my prototype, with the added benefit of it requiring little to no setup
-on the end user’s part.
+parameterised reports that would require parts of the report to be
+dynamically populated. I found myself leaning on R for programmatic
+markup creation, which meant that I could have one master document that
+I worked on. My prototype version (in other words, functions I threw
+together for work) required a lot of constant chunk configuration, and
+wasn’t particularly user-friendly nor elegant. *quartools* is a more
+streamlined version of my prototype, with the added benefit of it
+requiring little to no setup on the end user’s part.
 
 ## Installation
 
diff --git a/README.qmd b/README.qmd
index 434d16d..8d1e10e 100644
--- a/README.qmd
+++ b/README.qmd
@@ -16,7 +16,7 @@ _quartools_ allows for the creation of quarto-compliant markdown via R function
 
 ## Why quartools?
 
-At work, I ran into an issue where I was generating hundreds of parameterised reports that would be similar with subtle differences in content. I found myself leaning on R for programmatic markup creation, which meant that I could have one master document that I worked on. My prototype version (in other words, functions I threw together for work) required a lot of constant chunk configuration, and wasn't particularly user-friendly nor elegant. _quartools_ is a more streamlined version of my prototype, with the added benefit of it requiring little to no setup on the end user's part.
+At work, I ran into an issue where I was generating hundreds of parameterised reports that would require parts of the report to be dynamically populated. I found myself leaning on R for programmatic markup creation, which meant that I could have one master document that I worked on. My prototype version (in other words, functions I threw together for work) required a lot of constant chunk configuration, and wasn't particularly user-friendly nor elegant. _quartools_ is a more streamlined version of my prototype, with the added benefit of it requiring little to no setup on the end user's part.
 
 
 ## Installation
diff --git a/man/as_markdown.Rd b/man/as_markdown.Rd
index de49a46..4671d8d 100644
--- a/man/as_markdown.Rd
+++ b/man/as_markdown.Rd
@@ -20,3 +20,6 @@ This is a wrapper around \link[base:paste]{base::paste0} which sets the class of
 character vector to "knit_asis". This means that the \link[knitr:knitr-package]{knitr::knitr} engine will render
 the character vector as markdown content, rather than as an R value.
 }
+\examples{
+as_markdown(c("Hello world!"))
+}
diff --git a/man/div.Rd b/man/div.Rd
index 20eb2fd..9c374f3 100644
--- a/man/div.Rd
+++ b/man/div.Rd
@@ -16,10 +16,11 @@ character vector of length 1
 }
 \description{
 Create a div block element with optional attributes to assign to it. Dots
-are collapsed into a single character vector with a newline between each element.
+are collapsed into a single character vector with a newline between each
+element.
 
-If attr is a vector with a length > 1, attributes will be combined into a
-single character vector via \link[base:paste]{base::paste0}.
+If attr is a vector with a length > 1, attributes will be combined into
+a single character vector via \link[base:paste]{base::paste0}.
 }
 \examples{
 # Create a quarto tip callout
diff --git a/man/page-layout.Rd b/man/page-layout.Rd
index f8ac6f9..cb3b0e8 100644
--- a/man/page-layout.Rd
+++ b/man/page-layout.Rd
@@ -27,6 +27,9 @@ with_margin_column(..., attr = NULL)
 
 \item{extension}{affix class to apply to column class}
 }
+\value{
+character vector of length 1
+}
 \description{
 Create a div block that modifies the current quarto layout column temporarily.
 
diff --git a/man/span.Rd b/man/span.Rd
index 6a509f5..6ae8722 100644
--- a/man/span.Rd
+++ b/man/span.Rd
@@ -16,10 +16,11 @@ character vector of length 1
 }
 \description{
 Create a span element with optional attributes to assign to it. Dots
-are collapsed into a single character vector with a space between each element.
+are collapsed into a single character vector with a space between
+each element.
 
-If attr is a vector with a length > 1, attributes will be combined into a single
-character vector via \link[base:paste]{base::paste0}.
+If attr is a vector with a length > 1, attributes will be combined into
+a single character vector via \link[base:paste]{base::paste0}.
 }
 \examples{
 span("Hello world!", attr = ".bold")
diff --git a/tests/testthat/test_with.R b/tests/testthat/test_with.R
index 220b02b..34377a6 100644
--- a/tests/testthat/test_with.R
+++ b/tests/testthat/test_with.R
@@ -18,3 +18,17 @@ test_that("with_*() output is as expected", {
         expect_true(input[[i]] == expectations[[i]])
     })
 })
+
+test_that("with_*() disallows invalid extensions", {
+    input <- list(
+        quote(with_body_column(extension = "shaded")),
+        quote(with_page_column(extension = "shaded")),
+        quote(with_screen_inset_column(extension = "bad")),
+        quote(with_screen_column(extension = "shaded")),
+        quote(with_margin_column(extension = "shaded"))
+    )
+    lapply(input, function(x) {
+        expect_error(eval(x))
+    })
+})
+