refactor: snake_case attr-comb options & arguments, soft-deprecate dotted names

R/aaa-operators.R

@@ -35,7 +35,7 @@ connect_neighborhood_impl <- function(
 contract_vertices_impl <- function(
   graph,
   mapping,
-  vertex_attr_comb = igraph_opt("vertex.attr.comb")
+  vertex_attr_comb = igraph_opt("vertex_attr_combine")
 ) {
   # Argument checks
   ensure_igraph(graph)
@@ -245,7 +245,7 @@ simplify_impl <- function(
   graph,
   remove_multiple = TRUE,
   remove_loops = TRUE,
-  edge_attr_comb = igraph_opt("edge.attr.comb")
+  edge_attr_comb = igraph_opt("edge_attr_combine")
 ) {
   # Argument checks
   ensure_igraph(graph)

R/aaa-structural.R

@@ -166,7 +166,7 @@ to_directed_impl <- function(
 to_undirected_impl <- function(
   graph,
   mode = c("collapse", "each", "mutual"),
-  edge_attr_comb = igraph_opt("edge.attr.comb")
+  edge_attr_comb = igraph_opt("edge_attr_combine")
 ) {
   # Argument checks
   ensure_igraph(graph)

R/attributes.R

@@ -1387,7 +1387,7 @@ igraph.i.attribute.combination <- function(comb, allow_rename = FALSE) {
 #' vertex/edge attributes in these cases.
 #'
 #' The functions that support the combination of attributes have one or two
-#' extra arguments called `vertex.attr.comb` and/or `edge.attr.comb`
+#' extra arguments called `vertex_attr_combine` and/or `edge_attr_combine`
 #' that specify how to perform the mapping of the attributes. E.g.
 #' [contract()] contracts many vertices into a single one, the
 #' attributes of the vertices can be combined and stores as the vertex
@@ -1498,22 +1498,22 @@ igraph.i.attribute.combination <- function(comb, allow_rename = FALSE) {
 #' igraph_options(print.edge.attributes = TRUE)
 #'
 #' ## new attribute is the sum of the old ones
-#' simplify(g, edge.attr.comb = "sum")
+#' simplify(g, edge_attr_combine = "sum")
 #'
 #' ## collect attributes into a string
-#' simplify(g, edge.attr.comb = toString)
+#' simplify(g, edge_attr_combine = toString)
 #'
 #' ## concatenate them into a vector, this creates a complex
 #' ## attribute
-#' simplify(g, edge.attr.comb = "concat")
+#' simplify(g, edge_attr_combine = "concat")
 #'
 #' E(g)$name <- letters[seq_len(ecount(g))]
 #'
 #' ## both attributes are collected into strings
-#' simplify(g, edge.attr.comb = toString)
+#' simplify(g, edge_attr_combine = toString)
 #'
 #' ## harmonic average of weights, names are dropped
-#' simplify(g, edge.attr.comb = list(
+#' simplify(g, edge_attr_combine = list(
 #'   weight = function(x) length(x) / sum(1 / x),
 #'   name = "ignore"
 #' ))

R/community.R

@@ -417,14 +417,14 @@ cutat <- function(communities, no, steps) {
 contract.vertices <- function(
   graph,
   mapping,
-  vertex.attr.comb = igraph_opt("vertex.attr.comb")
+  vertex.attr.comb = igraph_opt("vertex_attr_combine")
 ) {
   # nocov start
   lifecycle::deprecate_warn("2.0.0", "contract.vertices()", "contract()")
   contract(
     graph = graph,
     mapping = mapping,
-    vertex.attr.comb = vertex.attr.comb
+    vertex_attr_combine = vertex.attr.comb
   )
 } # nocov end
 
@@ -3620,15 +3620,16 @@ communities <- groups.communities
 #'
 #' The attributes of the graph are kept. Graph and edge attributes are
 #' unchanged, vertex attributes are combined, according to the
-#' `vertex.attr.comb` parameter.
+#' `vertex_attr_combine` parameter.
 #'
 #' @param graph The input graph, it can be directed or undirected.
 #' @param mapping A numeric vector that specifies the mapping. Its elements
 #'   correspond to the vertices, and for each element the ID in the new graph is
 #'   given.
-#' @param vertex.attr.comb Specifies how to combine the vertex attributes in
+#' @inheritParams rlang::args_dots_empty
+#' @param vertex_attr_combine Specifies how to combine the vertex attributes in
 #'   the new graph. Please see [attribute.combination()] for details. The
-#'   default `NULL` uses the `vertex.attr.comb` igraph option.
+#'   default `NULL` uses the `vertex_attr_combine` igraph option.
 #' @return A new graph object.
 #' @author Gabor Csardi \email{csardi.gabor@@gmail.com}
 #' @keywords graphs
@@ -3640,7 +3641,7 @@ communities <- groups.communities
 #' E(g)$weight <- runif(ecount(g))
 #'
 #' g2 <- contract(g, rep(1:5, each = 2),
-#'   vertex.attr.comb = toString
+#'   vertex_attr_combine = toString
 #' )
 #'
 #' ## graph and edge attributes are kept, vertex attributes are
@@ -3652,16 +3653,54 @@ communities <- groups.communities
 contract <- function(
   graph,
   mapping,
-  vertex.attr.comb = NULL
+  ...,
+  vertex_attr_combine = NULL
 ) {
-  if (is.null(vertex.attr.comb)) {
-    vertex.attr.comb <- igraph_opt("vertex.attr.comb")
+  # BEGIN GENERATED ARG_HANDLE: contract, do not edit, see tools/generate-migrations.R
+  # fmt: skip
+  if (...length() > 0L) {
+    .arg_ambiguous <- base::intersect(base::names(base::substitute(...())), base::c("v", "ve", "ver", "vert", "verte", "vertex"))
+    if (base::length(.arg_ambiguous) > 0L) cli::cli_abort("Argument {.arg {(.arg_ambiguous[[1L]])}} matches multiple arguments of {.fn contract}.")
+    # Pre-3.0.0 signature: contract(graph, mapping, vertex.attr.comb)
+    .old_signature <- function(vertex.attr.comb, ...) {
+      if (...length() > 0L) {
+        .arg_extra <- base::names(base::substitute(...()))
+        .arg_extra <- .arg_extra[base::nzchar(.arg_extra)]
+        if (base::length(.arg_extra) == 0L) cli::cli_abort("Too many arguments passed to {.fn contract}.", call = base::parent.frame())
+        cli::cli_abort(base::c("Unexpected argument passed to {.fn contract}: {.arg {(.arg_extra)}}.", i = "Arguments after {.arg ...} must be spelled out in full."), call = base::parent.frame())
+      }
+      base::c(
+        if (!base::missing(vertex.attr.comb)) base::list(vertex_attr_combine = vertex.attr.comb)
+      )
+    }
+    .arg_handle <- .old_signature(...)
+    if (base::length(.arg_handle) > 0L) {
+      .arg_names <- base::names(.arg_handle)
+      .arg_conflict <- base::intersect(.arg_names, base::c(
+        if (!base::missing(vertex_attr_combine)) "vertex_attr_combine"
+      ))
+      if (base::length(.arg_conflict) > 0L) cli::cli_abort(base::c("Argument {.arg {(.arg_conflict)}} of {.fn contract} was supplied more than once.", i = "Pass it exactly once, by its new name {.arg {(.arg_conflict)}}."))
+      base::list2env(.arg_handle, base::environment())
+      lifecycle::deprecate_soft(
+        "3.0.0",
+        what = base::I("Calling `contract()` with positional or abbreviated arguments"),
+        details = base::c(
+          i = base::paste0("Detected call:  contract(", base::paste(base::c("graph", "mapping", base::c(vertex_attr_combine = "vertex.attr.comb")[.arg_names]), collapse = ", "), ")"),
+          i = base::paste0("Use instead:    contract(", base::paste(base::c("graph", "mapping", base::paste0(.arg_names, " = ")), collapse = ", "), ")")
+        )
+      )
+    }
+  }
+  # END GENERATED ARG_HANDLE
+
+  if (is.null(vertex_attr_combine)) {
+    vertex_attr_combine <- igraph_opt("vertex_attr_combine")
   }
 
   contract_vertices_impl(
     graph = graph,
     mapping = mapping,
-    vertex_attr_comb = vertex.attr.comb
+    vertex_attr_comb = vertex_attr_combine
   )
 }
 

R/conversion.R

@@ -740,7 +740,7 @@ as_edgelist <- function(
 #' E(g4)$weight <- seq_len(ecount(g4))
 #' ug4 <- as_undirected(g4,
 #'   mode = "mutual",
-#'   edge.attr.comb = list(weight = length)
+#'   edge_attr_combine = list(weight = length)
 #' )
 #' print(ug4, e = TRUE)
 #'
@@ -791,21 +791,59 @@ as_directed <- function(
 }
 
 #' @rdname as_directed
-#' @param edge.attr.comb Specifies what to do with edge attributes, if
+#' @param edge_attr_combine Specifies what to do with edge attributes, if
 #'   `mode="collapse"` or `mode="mutual"`.  In these cases many edges
 #'   might be mapped to a single one in the new graph, and their attributes are
 #'   combined. Please see [attribute.combination()] for details on
-#'   this. The default `NULL` uses the `edge.attr.comb` igraph option.
+#'   this. The default `NULL` uses the `edge_attr_combine` igraph option.
 #' @export
 as_undirected <- function(
   graph,
   mode = c("collapse", "each", "mutual"),
-  edge.attr.comb = NULL
+  ...,
+  edge_attr_combine = NULL
 ) {
+  # BEGIN GENERATED ARG_HANDLE: as_undirected, do not edit, see tools/generate-migrations.R
+  # fmt: skip
+  if (...length() > 0L) {
+    .arg_ambiguous <- base::intersect(base::names(base::substitute(...())), base::c("e", "ed", "edg", "edge"))
+    if (base::length(.arg_ambiguous) > 0L) cli::cli_abort("Argument {.arg {(.arg_ambiguous[[1L]])}} matches multiple arguments of {.fn as_undirected}.")
+    # Pre-3.0.0 signature: as_undirected(graph, mode, edge.attr.comb)
+    .old_signature <- function(edge.attr.comb, ...) {
+      if (...length() > 0L) {
+        .arg_extra <- base::names(base::substitute(...()))
+        .arg_extra <- .arg_extra[base::nzchar(.arg_extra)]
+        if (base::length(.arg_extra) == 0L) cli::cli_abort("Too many arguments passed to {.fn as_undirected}.", call = base::parent.frame())
+        cli::cli_abort(base::c("Unexpected argument passed to {.fn as_undirected}: {.arg {(.arg_extra)}}.", i = "Arguments after {.arg ...} must be spelled out in full."), call = base::parent.frame())
+      }
+      base::c(
+        if (!base::missing(edge.attr.comb)) base::list(edge_attr_combine = edge.attr.comb)
+      )
+    }
+    .arg_handle <- .old_signature(...)
+    if (base::length(.arg_handle) > 0L) {
+      .arg_names <- base::names(.arg_handle)
+      .arg_conflict <- base::intersect(.arg_names, base::c(
+        if (!base::missing(edge_attr_combine)) "edge_attr_combine"
+      ))
+      if (base::length(.arg_conflict) > 0L) cli::cli_abort(base::c("Argument {.arg {(.arg_conflict)}} of {.fn as_undirected} was supplied more than once.", i = "Pass it exactly once, by its new name {.arg {(.arg_conflict)}}."))
+      base::list2env(.arg_handle, base::environment())
+      lifecycle::deprecate_soft(
+        "3.0.0",
+        what = base::I("Calling `as_undirected()` with positional or abbreviated arguments"),
+        details = base::c(
+          i = base::paste0("Detected call:  as_undirected(", base::paste(base::c("graph", "mode", base::c(edge_attr_combine = "edge.attr.comb")[.arg_names]), collapse = ", "), ")"),
+          i = base::paste0("Use instead:    as_undirected(", base::paste(base::c("graph", "mode", base::paste0(.arg_names, " = ")), collapse = ", "), ")")
+        )
+      )
+    }
+  }
+  # END GENERATED ARG_HANDLE
+
   # Argument checks
   ensure_igraph(graph)
-  if (is.null(edge.attr.comb)) {
-    edge.attr.comb <- igraph_opt("edge.attr.comb")
+  if (is.null(edge_attr_combine)) {
+    edge_attr_combine <- igraph_opt("edge_attr_combine")
   }
 
   mode <- igraph_match_arg(mode)
@@ -814,7 +852,7 @@ as_undirected <- function(
   res <- to_undirected_impl(
     graph = graph,
     mode = mode,
-    edge_attr_comb = edge.attr.comb
+    edge_attr_comb = edge_attr_combine
   )
 
   res
@@ -1792,10 +1830,10 @@ as.directed <- function(
 as.undirected <- function(
   graph,
   mode = c("collapse", "each", "mutual"),
-  edge.attr.comb = igraph_opt("edge.attr.comb")
+  edge.attr.comb = igraph_opt("edge_attr_combine")
 ) {
   lifecycle::deprecate_warn("2.1.0", "as.undirected()", "as_undirected()")
-  as_undirected(graph = graph, mode = mode, edge.attr.comb = edge.attr.comb)
+  as_undirected(graph = graph, mode = mode, edge_attr_combine = edge.attr.comb)
 }
 
 #' Create a graph from an edge list matrix

R/make.R

@@ -1918,7 +1918,7 @@ graph_from_literal_i <- function(mf) {
   # to simplify (#824, #1981): `simplify()` rebuilds the graph sorted by
   # endpoint, and a formula that declares no loops and no multiple edges has no
   # reason to be rebuilt. The check belongs here rather than inside
-  # `simplify()`, where it also suppressed `edge.attr.comb` -- see the note
+  # `simplify()`, where it also suppressed `edge_attr_combine` -- see the note
   # there. `res` has no attributes yet, so skipping is unobservable beyond the
   # order.
   if (simplify && !is_simple(res)) {

R/migration-fixture.R

@@ -1,5 +1,6 @@
-# Test fixture for the in-place argument-migration generator (tools/migrations.R,
-# tools/generate-migrations.R). `migration_fixture()` carries a generated
+# Test fixture for the in-place argument-migration generator
+# (tools/migrations/fixture.R, tools/generate-migrations.R).
+# `migration_fixture()` carries a generated
 # ARG_HANDLE block that recovers a legacy call to its pre-3.0.0 signature
 # f(graph, n, weight, kind, directed) -- now
 # f(graph, n, ..., weights, type, directed), with `weight` renamed to `weights`