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

@@ -1364,7 +1364,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
@@ -1475,22 +1475,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

@@ -3593,13 +3593,14 @@ 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.
 #' @return A new graph object.
 #' @author Gabor Csardi \email{csardi.gabor@@gmail.com}
@@ -3612,7 +3613,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
@@ -3624,12 +3625,35 @@ communities <- groups.communities
 contract <- function(
   graph,
   mapping,
-  vertex.attr.comb = igraph_opt("vertex.attr.comb")
+  ...,
+  vertex_attr_combine = igraph_opt("vertex_attr_combine")
 ) {
+  # BEGIN GENERATED ARG_HANDLE: contract, do not edit, see tools/generate-migrations.R
+  if (...length() > 0L) {
+    .arg_handle <- migrate_recover_args(
+      list(...),
+      current = list(vertex_attr_combine = vertex_attr_combine),
+      recover_new = c("vertex_attr_combine"),
+      recover_old = c("vertex.attr.comb"),
+      match_names = c("vertex.attr.comb", "vertex_attr_combine"),
+      match_to = c("vertex_attr_combine", "vertex_attr_combine"),
+      defaults = list(vertex_attr_combine = igraph_opt("vertex_attr_combine")),
+      head_args = c("graph", "mapping"),
+      fn_name = "contract"
+    )
+    list2env(.arg_handle$values, environment())
+    lifecycle::deprecate_soft(
+      "3.0.0",
+      what = I(.arg_handle$what),
+      details = .arg_handle$details
+    )
+  }
+  # END GENERATED ARG_HANDLE
+
   contract_vertices_impl(
     graph = graph,
     mapping = mapping,
-    vertex_attr_comb = vertex.attr.comb
+    vertex_attr_comb = vertex_attr_combine
   )
 }
 

R/conversion.R

@@ -698,7 +698,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)
 #'
@@ -736,7 +736,8 @@ as_directed <- function(
 }
 
 #' @rdname as_directed
-#' @param edge.attr.comb Specifies what to do with edge attributes, if
+#' @inheritParams rlang::args_dots_empty
+#' @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
@@ -745,8 +746,31 @@ as_directed <- function(
 as_undirected <- function(
   graph,
   mode = c("collapse", "each", "mutual"),
-  edge.attr.comb = igraph_opt("edge.attr.comb")
+  ...,
+  edge_attr_combine = igraph_opt("edge_attr_combine")
 ) {
+  # BEGIN GENERATED ARG_HANDLE: as_undirected, do not edit, see tools/generate-migrations.R
+  if (...length() > 0L) {
+    .arg_handle <- migrate_recover_args(
+      list(...),
+      current = list(edge_attr_combine = edge_attr_combine),
+      recover_new = c("edge_attr_combine"),
+      recover_old = c("edge.attr.comb"),
+      match_names = c("edge.attr.comb", "edge_attr_combine"),
+      match_to = c("edge_attr_combine", "edge_attr_combine"),
+      defaults = list(edge_attr_combine = igraph_opt("edge_attr_combine")),
+      head_args = c("graph", "mode"),
+      fn_name = "as_undirected"
+    )
+    list2env(.arg_handle$values, environment())
+    lifecycle::deprecate_soft(
+      "3.0.0",
+      what = I(.arg_handle$what),
+      details = .arg_handle$details
+    )
+  }
+  # END GENERATED ARG_HANDLE
+
   # Argument checks
   ensure_igraph(graph)
   mode <- igraph_match_arg(mode)
@@ -755,7 +779,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

R/migrate-args.R

@@ -1,8 +1,8 @@
 # Runtime helper behind the generated `# ... ARG_HANDLE` blocks (see
-# tools/migrations.R, tools/generate-migrations.R). Hand-written and tested
-# directly -- the generated blocks only carry the per-function configuration and
-# call this. Kept a plain function (not an inline closure) so it is easy to step
-# through in a debugger.
+# tools/migrations/README.md, tools/generate-migrations.R). Hand-written and
+# tested directly -- the generated blocks only carry the per-function
+# configuration and call this. Kept a plain function (not an inline closure) so
+# it is easy to step through in a debugger.
 #
 # Pure: it inspects `dots` against the supplied maps and returns the recovered
 # values plus the deprecation message parts, or NULL when there is nothing to

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`