refactor: move optional arguments of plotting functions behind the ellipsis

R/cycles.R

@@ -31,6 +31,7 @@
 #' a specific cycle.
 #'
 #' @param graph The input graph.
+#' @inheritParams rlang::args_dots_empty
 #' @param mode Character constant specifying how to handle directed graphs.
 #'   `out` follows edge directions, `in` follows edges in the reverse direction,
 #'   and `all` ignores edge directions. Ignored in undirected graphs.

R/par.R

@@ -295,8 +295,35 @@ get_all_options <- function() {
 }
 
 #' @rdname igraph_options
+#' @inheritParams rlang::args_dots_empty
 #' @export
-igraph_opt <- function(x, default = NULL) {
+igraph_opt <- function(
+  x,
+  ...,
+  default = NULL
+) {
+  # BEGIN GENERATED ARG_HANDLE: igraph_opt, do not edit, see tools/generate-migrations.R
+  if (...length() > 0L) {
+    .arg_handle <- migrate_recover_args(
+      list(...),
+      current = list(default = default),
+      recover_new = c("default"),
+      recover_old = c("default"),
+      match_names = c("default"),
+      match_to = c("default"),
+      defaults = list(default = NULL),
+      head_args = c("x"),
+      fn_name = "igraph_opt"
+    )
+    list2env(.arg_handle$values, environment())
+    lifecycle::deprecate_soft(
+      "3.0.0",
+      what = I(.arg_handle$what),
+      details = .arg_handle$details
+    )
+  }
+  # END GENERATED ARG_HANDLE
+
   if (missing(default)) {
     get_config(paste0("igraph::", x), .igraph.pars[[x]])
   } else {

R/plot.common.R

@@ -707,6 +707,7 @@ i.postprocess.layout <- function(maybe_layout) {
 #' plotting a graph with multiple edges, so that all edges are visible.
 #'
 #' @param graph The input graph.
+#' @inheritParams rlang::args_dots_empty
 #' @param start The curvature at the two extreme edges. All edges will have a
 #'   curvature between `-start` and `start`, spaced equally.
 #' @return A numeric vector, its length is the number of edges in the graph.
@@ -730,7 +731,33 @@ i.postprocess.layout <- function(maybe_layout) {
 #' set.seed(42)
 #' plot(g)
 #'
-curve_multiple <- function(graph, start = 0.5) {
+curve_multiple <- function(
+  graph,
+  ...,
+  start = 0.5
+) {
+  # BEGIN GENERATED ARG_HANDLE: curve_multiple, do not edit, see tools/generate-migrations.R
+  if (...length() > 0L) {
+    .arg_handle <- migrate_recover_args(
+      list(...),
+      current = list(start = start),
+      recover_new = c("start"),
+      recover_old = c("start"),
+      match_names = c("start"),
+      match_to = c("start"),
+      defaults = list(start = 0.5),
+      head_args = c("graph"),
+      fn_name = "curve_multiple"
+    )
+    list2env(.arg_handle$values, environment())
+    lifecycle::deprecate_soft(
+      "3.0.0",
+      what = I(.arg_handle$what),
+      details = .arg_handle$details
+    )
+  }
+  # END GENERATED ARG_HANDLE
+
   el <- apply(as_edgelist(graph, names = FALSE), 1, paste, collapse = ":")
   ave(rep(NA, length(el)), el, FUN = function(x) {
     if (length(x) == 1) {

R/plot.shapes.R

@@ -369,13 +369,41 @@ shape_noplot <- function(coords, v = NULL, params) {
 }
 
 #' @rdname shapes
+#' @inheritParams rlang::args_dots_empty
 #' @export
 add_shape <- function(
   shape,
+  ...,
   clip = shape_noclip,
   plot = shape_noplot,
   parameters = list()
 ) {
+  # BEGIN GENERATED ARG_HANDLE: add_shape, do not edit, see tools/generate-migrations.R
+  if (...length() > 0L) {
+    .arg_handle <- migrate_recover_args(
+      list(...),
+      current = list(clip = clip, plot = plot, parameters = parameters),
+      recover_new = c("clip", "plot", "parameters"),
+      recover_old = c("clip", "plot", "parameters"),
+      match_names = c("clip", "plot", "parameters"),
+      match_to = c("clip", "plot", "parameters"),
+      defaults = list(
+        clip = shape_noclip,
+        plot = shape_noplot,
+        parameters = list()
+      ),
+      head_args = c("shape"),
+      fn_name = "add_shape"
+    )
+    list2env(.arg_handle$values, environment())
+    lifecycle::deprecate_soft(
+      "3.0.0",
+      what = I(.arg_handle$what),
+      details = .arg_handle$details
+    )
+  }
+  # END GENERATED ARG_HANDLE
+
   if (!is.character(shape) || length(shape) != 1) {
     cli::cli_abort(c(
       "{.arg shape} must be a character of length 1.",

R/tkplot.R

@@ -527,8 +527,35 @@ tkplot <- function(graph, canvas.width = 450, canvas.height = 450, ...) {
 ###################################################################
 
 #' @rdname tkplot
+#' @inheritParams rlang::args_dots_empty
 #' @export
-tk_close <- function(tkp.id, window.close = TRUE) {
+tk_close <- function(
+  tkp.id,
+  ...,
+  window.close = TRUE
+) {
+  # BEGIN GENERATED ARG_HANDLE: tk_close, do not edit, see tools/generate-migrations.R
+  if (...length() > 0L) {
+    .arg_handle <- migrate_recover_args(
+      list(...),
+      current = list(window.close = window.close),
+      recover_new = c("window.close"),
+      recover_old = c("window.close"),
+      match_names = c("window.close"),
+      match_to = c("window.close"),
+      defaults = list(window.close = TRUE),
+      head_args = c("tkp.id"),
+      fn_name = "tk_close"
+    )
+    list2env(.arg_handle$values, environment())
+    lifecycle::deprecate_soft(
+      "3.0.0",
+      what = I(.arg_handle$what),
+      details = .arg_handle$details
+    )
+  }
+  # END GENERATED ARG_HANDLE
+
   # nocov start
   if (window.close) {
     cmd <- paste(sep = "", "tkp.", tkp.id, "$top")
@@ -555,8 +582,36 @@ tk_off <- function() {
 }
 
 #' @rdname tkplot
+#' @inheritParams rlang::args_dots_empty
 #' @export
-tk_fit <- function(tkp.id, width = NULL, height = NULL) {
+tk_fit <- function(
+  tkp.id,
+  ...,
+  width = NULL,
+  height = NULL
+) {
+  # BEGIN GENERATED ARG_HANDLE: tk_fit, do not edit, see tools/generate-migrations.R
+  if (...length() > 0L) {
+    .arg_handle <- migrate_recover_args(
+      list(...),
+      current = list(width = width, height = height),
+      recover_new = c("width", "height"),
+      recover_old = c("width", "height"),
+      match_names = c("width", "height"),
+      match_to = c("width", "height"),
+      defaults = list(width = NULL, height = NULL),
+      head_args = c("tkp.id"),
+      fn_name = "tk_fit"
+    )
+    list2env(.arg_handle$values, environment())
+    lifecycle::deprecate_soft(
+      "3.0.0",
+      what = I(.arg_handle$what),
+      details = .arg_handle$details
+    )
+  }
+  # END GENERATED ARG_HANDLE
+
   # nocov start
   tkp <- .tkplot.get(tkp.id)
   if (is.null(width)) {
@@ -646,8 +701,35 @@ tk_postscript <- function(tkp.id) {
 }
 
 #' @rdname tkplot
+#' @inheritParams rlang::args_dots_empty
 #' @export
-tk_coords <- function(tkp.id, norm = FALSE) {
+tk_coords <- function(
+  tkp.id,
+  ...,
+  norm = FALSE
+) {
+  # BEGIN GENERATED ARG_HANDLE: tk_coords, do not edit, see tools/generate-migrations.R
+  if (...length() > 0L) {
+    .arg_handle <- migrate_recover_args(
+      list(...),
+      current = list(norm = norm),
+      recover_new = c("norm"),
+      recover_old = c("norm"),
+      match_names = c("norm"),
+      match_to = c("norm"),
+      defaults = list(norm = FALSE),
+      head_args = c("tkp.id"),
+      fn_name = "tk_coords"
+    )
+    list2env(.arg_handle$values, environment())
+    lifecycle::deprecate_soft(
+      "3.0.0",
+      what = I(.arg_handle$what),
+      details = .arg_handle$details
+    )
+  }
+  # END GENERATED ARG_HANDLE
+
   # nocov start
   coords <- .tkplot.get(tkp.id, "coords")
   coords[, 2] <- max(coords[, 2]) - coords[, 2]
@@ -675,8 +757,36 @@ tk_set_coords <- function(tkp.id, coords) {
 }
 
 #' @rdname tkplot
+#' @inheritParams rlang::args_dots_empty
 #' @export
-tk_rotate <- function(tkp.id, degree = NULL, rad = NULL) {
+tk_rotate <- function(
+  tkp.id,
+  ...,
+  degree = NULL,
+  rad = NULL
+) {
+  # BEGIN GENERATED ARG_HANDLE: tk_rotate, do not edit, see tools/generate-migrations.R
+  if (...length() > 0L) {
+    .arg_handle <- migrate_recover_args(
+      list(...),
+      current = list(degree = degree, rad = rad),
+      recover_new = c("degree", "rad"),
+      recover_old = c("degree", "rad"),
+      match_names = c("degree", "rad"),
+      match_to = c("degree", "rad"),
+      defaults = list(degree = NULL, rad = NULL),
+      head_args = c("tkp.id"),
+      fn_name = "tk_rotate"
+    )
+    list2env(.arg_handle$values, environment())
+    lifecycle::deprecate_soft(
+      "3.0.0",
+      what = I(.arg_handle$what),
+      details = .arg_handle$details
+    )
+  }
+  # END GENERATED ARG_HANDLE
+
   # nocov start
   coords <- .tkplot.get(tkp.id, "coords")
 

tests/testthat/test-par.R

@@ -56,3 +56,23 @@ test_that("with_igraph_opt works", {
   expect_true(igraph_opt("sparsematrices"))
   expect_true(inherits(res, "matrix"))
 })
+
+# ---- ellipsis migration: argument coverage ----------------------------
+
+test_that("igraph_opt() falls back to `default` for unset options", {
+  # An unset option falls back to the given default.
+  expect_identical(igraph_opt("no.such.option", default = 42), 42)
+
+  # A set option wins over the default.
+  local_igraph_options(annotate.plot = TRUE)
+  expect_true(igraph_opt("annotate.plot", default = FALSE))
+})
+
+test_that("igraph_opt() recovers a positional `default` with a deprecation", {
+  rlang::local_options(lifecycle_verbosity = "warning")
+
+  lifecycle::expect_deprecated(
+    res <- igraph_opt("no.such.option", 42)
+  )
+  expect_identical(res, igraph_opt("no.such.option", default = 42))
+})