Make title, subtitle, caption and tag as labs()'s named arguments

R/labels.r

@@ -28,11 +28,21 @@ update_labels <- function(p, labels) {
 #' the first argument, the `name`). I recommend doing that if you're
 #' changing other scale options.
 #'
-#' @param label The text for the axis, plot title or caption below the plot.
-#' @param subtitle the text for the subtitle for the plot which will be
-#'        displayed below the title. Leave `NULL` for no subtitle.
-#' @param ... A list of new name-value pairs. The name should either be
-#'   an aesthetic, or one of "title", "subtitle", "caption", or "tag".
+#' If a plot already has a title, subtitle, caption, etc., and you want to
+#' remove it, you can do so by setting the respective argument to `NULL`. For
+#' example, if plot `p` has a subtitle, then `p + labs(subtitle = NULL)` will
+#' remove the subtitle from the plot.
+#'
+#' @param label The title of the respective axis (for `xlab()` or `ylab()`) or
+#'        of the plot (for `ggtitle()``).
+#' @param title The text for the title.
+#' @param subtitle The text for the subtitle for the plot which will be
+#'        displayed below the title.
+#' @param caption The text for the caption which will be displayed in the
+#'        bottom-right of the plot by default.
+#' @param tag The text for the tag label which will be displayed at the
+#'        top-left of the plot by default.
+#' @param ... A list of new name-value pairs. The name should be an aesthetic.
 #' @export
 #' @examples
 #' p <- ggplot(mtcars, aes(mpg, wt, colour = cyl)) + geom_point()
@@ -51,10 +61,17 @@ update_labels <- function(p, labels) {
 #' # The plot tag appears at the top-left, and is typically used
 #' # for labelling a subplot with a letter.
 #' p + labs(title = "title", tag = "A")
-labs <- function(...) {
-  args <- list(...)
-  if (is.list(args[[1]])) args <- args[[1]]
+#'
+#' # If you want to remove a label, set it to NULL.
+#' p + labs(title = "title") + labs(title = NULL)
+labs <- function(..., title = waiver(), subtitle = waiver(), caption = waiver(), tag = waiver()) {
+  args <- list(..., title = title, subtitle = subtitle, caption = caption, tag = tag)
+  if (length(args) > 0 && is.list(args[[1]]) && !is.waive(args[[1]])) args <- args[[1]]
   args <- rename_aes(args)
+
+  is_waive <- vapply(args, is.waive, logical(1))
+  args <- args[!is_waive]
+
   structure(args, class = "labels")
 }
 
@@ -72,6 +89,6 @@ ylab <- function(label) {
 
 #' @rdname labs
 #' @export
-ggtitle <- function(label, subtitle = NULL) {
+ggtitle <- function(label, subtitle = waiver()) {
   labs(title = label, subtitle = subtitle)
 }

tests/testthat/test-labels.r

@@ -25,6 +25,24 @@ test_that("setting guide labels works", {
     expect_identical(labs(colour = "my label")$colour, "my label")
     # American spelling
     expect_identical(labs(color = "my label")$colour, "my label")
+
+    # No extra elements exists
+    expect_equivalent(labs(title = "my title"), list(title = "my title"))     # formal argument
+    expect_equivalent(labs(colour = "my label"), list(colour = "my label"))   # dot
+    expect_equivalent(labs(foo = "bar"), list(foo = "bar"))                   # non-existent param
+
+    # labs() can take a list as the first argument
+    expect_identical(labs(list(title = "my title", tag = "A)"))$tag, "A)")
+
+    # NULL is preserved
+    expect_equivalent(labs(title = NULL), list(title = NULL))
+
+    # ggtitle works in the same way as labs()
+    expect_identical(ggtitle("my title")$title, "my title")
+    expect_identical(ggtitle("my title",
+                             subtitle = "my subtitle")$subtitle, "my subtitle")
+    expect_equivalent(ggtitle("my title", subtitle = NULL),
+                      list(title = "my title", subtitle = NULL))
 })