Minor doc changes

- Minor elements refactoring
- extension tests for with_()*
- Minor edit to README
- Minor documentation changes
-

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,26 +23,25 @@
 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"
     )
 }
 
 #' 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"
     )
 }

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 = "") {

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"))

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
 

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

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))
+    })
+})
+