refactor: move optional arguments of interface 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/interface.R

@@ -335,6 +335,7 @@ ecount <- gsize
 #'
 #' @param graph The input graph.
 #' @param v The vertex of which the adjacent vertices are queried.
+#' @inheritParams rlang::args_dots_empty
 #' @param mode Whether to query outgoing (\sQuote{out}), incoming
 #'   (\sQuote{in}) edges, or both types (\sQuote{all}). This is
 #'   ignored for undirected graphs.
@@ -348,7 +349,34 @@ ecount <- gsize
 #' n1 <- neighbors(g, 1)
 #' n34 <- neighbors(g, 34)
 #' intersection(n1, n34)
-neighbors <- function(graph, v, mode = c("out", "in", "all", "total")) {
+neighbors <- function(
+  graph,
+  v,
+  ...,
+  mode = c("out", "in", "all", "total")
+) {
+  # BEGIN GENERATED ARG_HANDLE: neighbors, do not edit, see tools/generate-migrations.R
+  if (...length() > 0L) {
+    .arg_handle <- migrate_recover_args(
+      list(...),
+      current = list(mode = mode),
+      recover_new = c("mode"),
+      recover_old = c("mode"),
+      match_names = c("mode"),
+      match_to = c("mode"),
+      defaults = list(mode = c("out", "in", "all", "total")),
+      head_args = c("graph", "v"),
+      fn_name = "neighbors"
+    )
+    list2env(.arg_handle$values, environment())
+    lifecycle::deprecate_soft(
+      "3.0.0",
+      what = I(.arg_handle$what),
+      details = .arg_handle$details
+    )
+  }
+  # END GENERATED ARG_HANDLE
+
   ensure_igraph(graph)
   mode <- igraph_match_arg(mode)
 
@@ -369,6 +397,7 @@ neighbors <- function(graph, v, mode = c("out", "in", "all", "total")) {
 #' @param graph The input graph.
 #' @param v The vertex of which the incident edges are queried.
 #' @inheritParams neighbors
+#' @inheritParams rlang::args_dots_empty
 #' @return An edge sequence containing the incident edges of
 #'   the input vertex.
 #'
@@ -379,7 +408,34 @@ neighbors <- function(graph, v, mode = c("out", "in", "all", "total")) {
 #' g <- make_graph("Zachary")
 #' incident(g, 1)
 #' incident(g, 34)
-incident <- function(graph, v, mode = c("all", "out", "in", "total")) {
+incident <- function(
+  graph,
+  v,
+  ...,
+  mode = c("all", "out", "in", "total")
+) {
+  # BEGIN GENERATED ARG_HANDLE: incident, do not edit, see tools/generate-migrations.R
+  if (...length() > 0L) {
+    .arg_handle <- migrate_recover_args(
+      list(...),
+      current = list(mode = mode),
+      recover_new = c("mode"),
+      recover_old = c("mode"),
+      match_names = c("mode"),
+      match_to = c("mode"),
+      defaults = list(mode = c("all", "out", "in", "total")),
+      head_args = c("graph", "v"),
+      fn_name = "incident"
+    )
+    list2env(.arg_handle$values, environment())
+    lifecycle::deprecate_soft(
+      "3.0.0",
+      what = I(.arg_handle$what),
+      details = .arg_handle$details
+    )
+  }
+  # END GENERATED ARG_HANDLE
+
   # For undirected graphs, mode doesn't matter, use "all"
   if (!is_directed(graph)) {
     mode <- "all"
@@ -418,6 +474,7 @@ is_directed <- function(graph) {
 #'
 #' @param graph The input graph
 #' @param es The sequence of edges to query
+#' @inheritParams rlang::args_dots_empty
 #' @param names Whether to return vertex names or
 #'   numeric vertex IDs. By default vertex names are used.
 #' @return A two column matrix of vertex names or vertex IDs.
@@ -430,7 +487,34 @@ is_directed <- function(graph) {
 #' @examples
 #' g <- make_ring(5)
 #' ends(g, E(g))
-ends <- function(graph, es, names = TRUE) {
+ends <- function(
+  graph,
+  es,
+  ...,
+  names = TRUE
+) {
+  # BEGIN GENERATED ARG_HANDLE: ends, do not edit, see tools/generate-migrations.R
+  if (...length() > 0L) {
+    .arg_handle <- migrate_recover_args(
+      list(...),
+      current = list(names = names),
+      recover_new = c("names"),
+      recover_old = c("names"),
+      match_names = c("names"),
+      match_to = c("names"),
+      defaults = list(names = TRUE),
+      head_args = c("graph", "es"),
+      fn_name = "ends"
+    )
+    list2env(.arg_handle$values, environment())
+    lifecycle::deprecate_soft(
+      "3.0.0",
+      what = I(.arg_handle$what),
+      details = .arg_handle$details
+    )
+  }
+  # END GENERATED ARG_HANDLE
+
   ensure_igraph(graph)
 
   res <- matrix(NA_integer_, ncol = length(es), nrow = 2)
@@ -515,6 +599,7 @@ el_to_vec <- function(x, call = rlang::caller_env()) {
 #'   or vector of vertex IDs or symbolic vertex names.
 #'   For a vector, the values are interpreted pairwise, i.e. the first and second are used for
 #'   the first edge, the third and fourth for the second, etc.
+#' @inheritParams rlang::args_dots_empty
 #' @param directed Logical, whether to consider edge directions in
 #'   directed graphs. This argument is ignored for undirected graphs.
 #' @param error Logical, whether to report an error if an edge is not
@@ -543,7 +628,35 @@ el_to_vec <- function(x, call = rlang::caller_env()) {
 #' eis
 #' E(g)[eis]
 #'
-get_edge_ids <- function(graph, vp, directed = TRUE, error = FALSE) {
+get_edge_ids <- function(
+  graph,
+  vp,
+  ...,
+  directed = TRUE,
+  error = FALSE
+) {
+  # BEGIN GENERATED ARG_HANDLE: get_edge_ids, do not edit, see tools/generate-migrations.R
+  if (...length() > 0L) {
+    .arg_handle <- migrate_recover_args(
+      list(...),
+      current = list(directed = directed, error = error),
+      recover_new = c("directed", "error"),
+      recover_old = c("directed", "error"),
+      match_names = c("directed", "error"),
+      match_to = c("directed", "error"),
+      defaults = list(directed = TRUE, error = FALSE),
+      head_args = c("graph", "vp"),
+      fn_name = "get_edge_ids"
+    )
+    list2env(.arg_handle$values, environment())
+    lifecycle::deprecate_soft(
+      "3.0.0",
+      what = I(.arg_handle$what),
+      details = .arg_handle$details
+    )
+  }
+  # END GENERATED ARG_HANDLE
+
   ensure_igraph(graph)
 
   vp <- el_to_vec(vp, call = rlang::caller_env())
@@ -622,14 +735,42 @@ gorder <- vcount
 #' @param graph Input graph.
 #' @param v The vertices to query.
 #' @inheritParams neighbors
+#' @inheritParams rlang::args_dots_empty
 #' @return A list of vertex sequences.
 #'
 #' @family structural queries
 #' @export
 #' @examples
 #' g <- make_graph("Zachary")
 #' adjacent_vertices(g, c(1, 34))
-adjacent_vertices <- function(graph, v, mode = c("out", "in", "all", "total")) {
+adjacent_vertices <- function(
+  graph,
+  v,
+  ...,
+  mode = c("out", "in", "all", "total")
+) {
+  # BEGIN GENERATED ARG_HANDLE: adjacent_vertices, do not edit, see tools/generate-migrations.R
+  if (...length() > 0L) {
+    .arg_handle <- migrate_recover_args(
+      list(...),
+      current = list(mode = mode),
+      recover_new = c("mode"),
+      recover_old = c("mode"),
+      match_names = c("mode"),
+      match_to = c("mode"),
+      defaults = list(mode = c("out", "in", "all", "total")),
+      head_args = c("graph", "v"),
+      fn_name = "adjacent_vertices"
+    )
+    list2env(.arg_handle$values, environment())
+    lifecycle::deprecate_soft(
+      "3.0.0",
+      what = I(.arg_handle$what),
+      details = .arg_handle$details
+    )
+  }
+  # END GENERATED ARG_HANDLE
+
   ensure_igraph(graph)
 
   vv <- as_igraph_vs(graph, v) - 1
@@ -659,14 +800,42 @@ adjacent_vertices <- function(graph, v, mode = c("out", "in", "all", "total")) {
 #' @param graph Input graph.
 #' @param v The vertices to query
 #' @inheritParams neighbors
+#' @inheritParams rlang::args_dots_empty
 #' @return A list of edge sequences.
 #'
 #' @family structural queries
 #' @export
 #' @examples
 #' g <- make_graph("Zachary")
 #' incident_edges(g, c(1, 34))
-incident_edges <- function(graph, v, mode = c("out", "in", "all", "total")) {
+incident_edges <- function(
+  graph,
+  v,
+  ...,
+  mode = c("out", "in", "all", "total")
+) {
+  # BEGIN GENERATED ARG_HANDLE: incident_edges, do not edit, see tools/generate-migrations.R
+  if (...length() > 0L) {
+    .arg_handle <- migrate_recover_args(
+      list(...),
+      current = list(mode = mode),
+      recover_new = c("mode"),
+      recover_old = c("mode"),
+      match_names = c("mode"),
+      match_to = c("mode"),
+      defaults = list(mode = c("out", "in", "all", "total")),
+      head_args = c("graph", "v"),
+      fn_name = "incident_edges"
+    )
+    list2env(.arg_handle$values, environment())
+    lifecycle::deprecate_soft(
+      "3.0.0",
+      what = I(.arg_handle$what),
+      details = .arg_handle$details
+    )
+  }
+  # END GENERATED ARG_HANDLE
+
   ensure_igraph(graph)
 
   vv <- as_igraph_vs(graph, v) - 1

R/iterators.R

@@ -75,10 +75,38 @@ get_es_graph_id <- get_vs_graph_id <- function(seq) {
 #' the attributes of the two graphs are allowed to be different.
 #'
 #' @param g1,g2 The two graphs
+#' @inheritParams rlang::args_dots_empty
 #' @param attrs Whether to compare the attributes of the graphs
 #' @return Logical scalar
 #' @export
-identical_graphs <- function(g1, g2, attrs = TRUE) {
+identical_graphs <- function(
+  g1,
+  g2,
+  ...,
+  attrs = TRUE
+) {
+  # BEGIN GENERATED ARG_HANDLE: identical_graphs, do not edit, see tools/generate-migrations.R
+  if (...length() > 0L) {
+    .arg_handle <- migrate_recover_args(
+      list(...),
+      current = list(attrs = attrs),
+      recover_new = c("attrs"),
+      recover_old = c("attrs"),
+      match_names = c("attrs"),
+      match_to = c("attrs"),
+      defaults = list(attrs = TRUE),
+      head_args = c("g1", "g2"),
+      fn_name = "identical_graphs"
+    )
+    list2env(.arg_handle$values, environment())
+    lifecycle::deprecate_soft(
+      "3.0.0",
+      what = I(.arg_handle$what),
+      details = .arg_handle$details
+    )
+  }
+  # END GENERATED ARG_HANDLE
+
   stopifnot(is_igraph(g1), is_igraph(g2))
   .Call(Rx_igraph_identical_graphs, g1, g2, as.logical(attrs))
 }
@@ -321,6 +349,7 @@ unsafe_create_es <- function(graph, idx, es = NULL) {
 #' edges in the sequence. See [$.igraph.es()] for details.
 #'
 #' @param graph The graph.
+#' @inheritParams rlang::args_dots_empty
 #' @param P A list of vertices to select edges via pairs of vertices.
 #'   The first and second vertices select the first edge, the third
 #'   and fourth the second, etc.
@@ -343,7 +372,35 @@ unsafe_create_es <- function(graph, idx, es = NULL) {
 #' g2 <- make_ring(10) %>%
 #'   set_vertex_attr("name", value = letters[1:10])
 #' E(g2)
-E <- function(graph, P = NULL, path = NULL, directed = TRUE) {
+E <- function(
+  graph,
+  ...,
+  P = NULL,
+  path = NULL,
+  directed = TRUE
+) {
+  # BEGIN GENERATED ARG_HANDLE: E, do not edit, see tools/generate-migrations.R
+  if (...length() > 0L) {
+    .arg_handle <- migrate_recover_args(
+      list(...),
+      current = list(P = P, path = path, directed = directed),
+      recover_new = c("P", "path", "directed"),
+      recover_old = c("P", "path", "directed"),
+      match_names = c("P", "path", "directed"),
+      match_to = c("P", "path", "directed"),
+      defaults = list(P = NULL, path = NULL, directed = TRUE),
+      head_args = c("graph"),
+      fn_name = "E"
+    )
+    list2env(.arg_handle$values, environment())
+    lifecycle::deprecate_soft(
+      "3.0.0",
+      what = I(.arg_handle$what),
+      details = .arg_handle$details
+    )
+  }
+  # END GENERATED ARG_HANDLE
+
   ensure_igraph(graph)
 
   update_es_ref(graph)