From f52603d43313846a8285f024bd00bd7c5120df99 Mon Sep 17 00:00:00 2001
From: Teun van den Brand <tahvdbrand@gmail.com>
Date: Fri, 6 Sep 2024 11:24:59 +0200
Subject: [PATCH 1/6] write `as.gtable()` generic and methods

---
 R/gtable.R | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/R/gtable.R b/R/gtable.R
index 807aed4..3297d3d 100644
--- a/R/gtable.R
+++ b/R/gtable.R
@@ -272,3 +272,41 @@ gtable_height <- function(x) sum(x$heights)
 #' @param x A gtable object
 #' @export
 gtable_width <- function(x) sum(x$widths)
+
+#' Convert to a gtable
+#'
+#' @param x An object to convert.
+#' @param ... Arguments forwarded to methods.
+#'
+#' @return A gtable object
+#' @export
+as.gtable <- function(x, ...) {
+  check_dots_used()
+  UseMethod("as.gtable")
+}
+
+#' @export
+as.gtable.default <- function(x, ...) {
+  cli::cli_abort("Can't convert {.obj_type_friendly {x}} to a {.cls gtable}.")
+}
+
+#' @export
+as.gtable.gtable <- function(x, ...) x
+
+#' @export
+#' @describeIn as.gtable Creates a 1-cell gtable containing the grob.
+as.gtable.grob <- function(x, widths = NULL, heights = NULL, ...) {
+  if (length(widths) > 1) {
+    widths <- widths[1]
+    cli::cli_warn("{.arg widths} truncated to length 1.")
+  }
+  if (length(heights) > 1) {
+    heights <- heights[1]
+    cli::cli_warn("{.arg heights} truncated to length 1.")
+  }
+  table <- gtable(
+    widths  = widths  %||% grobWidth(x),
+    heights = heights %||% grobHeight(x)
+  )
+  gtable_add_grob(table, x, t = 1L, l = 1L, b = 1L, r = 1L, ...)
+}

From 27c977521311762c18c4d43f4d3319883f85917e Mon Sep 17 00:00:00 2001
From: Teun van den Brand <tahvdbrand@gmail.com>
Date: Fri, 6 Sep 2024 11:25:25 +0200
Subject: [PATCH 2/6] write tests

---
 tests/testthat/_snaps/gtable.md | 11 +++++++++++
 tests/testthat/test-gtable.R    | 24 ++++++++++++++++++++++++
 2 files changed, 35 insertions(+)
 create mode 100644 tests/testthat/_snaps/gtable.md
 create mode 100644 tests/testthat/test-gtable.R

diff --git a/tests/testthat/_snaps/gtable.md b/tests/testthat/_snaps/gtable.md
new file mode 100644
index 0000000..f4a1920
--- /dev/null
+++ b/tests/testthat/_snaps/gtable.md
@@ -0,0 +1,11 @@
+# as.gtable sensibly converts objects
+
+    Can't convert an integer vector to a <gtable>.
+
+---
+
+    Arguments in `...` must be used.
+    x Problematic argument:
+    * foo = "bar"
+    i Did you misspell an argument name?
+
diff --git a/tests/testthat/test-gtable.R b/tests/testthat/test-gtable.R
new file mode 100644
index 0000000..5b13c1f
--- /dev/null
+++ b/tests/testthat/test-gtable.R
@@ -0,0 +1,24 @@
+test_that("as.gtable sensibly converts objects", {
+
+  # gtable --> gtable is a no-op
+  g1 <- gtable(unit(1, "npc"), unit(1, "npc"))
+  g2 <- circleGrob(r = unit(1, "cm"))
+
+  expect_identical(as.gtable(g1), g1)
+
+  test <- as.gtable(g2)
+  expect_s3_class(test, "gtable")
+  expect_equal(as.numeric(convertUnit(gtable_width(test), "cm")), 2)
+  expect_equal(as.numeric(convertUnit(gtable_height(test), "cm")), 2)
+
+  expect_warning(
+    as.gtable(g2, widths = unit(c(1, 1), "cm")),
+    "truncated to length 1"
+  )
+  expect_warning(
+    as.gtable(g2, heights = unit(c(1, 1), "cm")),
+    "truncated to length 1"
+  )
+  expect_snapshot_error(as.gtable(1:5))
+  expect_snapshot_error(as.gtable(g1, foo = "bar"))
+})

From 917a597ec345c45376742aa66249ee1258e02631 Mon Sep 17 00:00:00 2001
From: Teun van den Brand <tahvdbrand@gmail.com>
Date: Fri, 6 Sep 2024 11:25:38 +0200
Subject: [PATCH 3/6] document

---
 NAMESPACE        |  4 ++++
 man/as.gtable.Rd | 27 +++++++++++++++++++++++++++
 2 files changed, 31 insertions(+)
 create mode 100644 man/as.gtable.Rd

diff --git a/NAMESPACE b/NAMESPACE
index fa44789..e99ed42 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -2,6 +2,9 @@
 
 S3method("[",gtable)
 S3method("dimnames<-",gtable)
+S3method(as.gtable,default)
+S3method(as.gtable,grob)
+S3method(as.gtable,gtable)
 S3method(cbind,gtable)
 S3method(dim,gtable)
 S3method(dimnames,gtable)
@@ -15,6 +18,7 @@ S3method(print,gtable)
 S3method(rbind,gtable)
 S3method(t,gtable)
 S3method(widthDetails,gtable)
+export(as.gtable)
 export(gtable)
 export(gtable_add_col_space)
 export(gtable_add_cols)
diff --git a/man/as.gtable.Rd b/man/as.gtable.Rd
new file mode 100644
index 0000000..2f21fbe
--- /dev/null
+++ b/man/as.gtable.Rd
@@ -0,0 +1,27 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/gtable.R
+\name{as.gtable}
+\alias{as.gtable}
+\alias{as.gtable.grob}
+\title{Convert to a gtable}
+\usage{
+as.gtable(x, ...)
+
+\method{as.gtable}{grob}(x, widths = NULL, heights = NULL, ...)
+}
+\arguments{
+\item{x}{An object to convert.}
+
+\item{...}{Arguments forwarded to methods.}
+}
+\value{
+A gtable object
+}
+\description{
+Convert to a gtable
+}
+\section{Methods (by class)}{
+\itemize{
+\item \code{as.gtable(grob)}: Creates a 1-cell gtable containing the grob.
+
+}}

From 5be98b1735bbb798f21aa11a7824a236d4294af4 Mon Sep 17 00:00:00 2001
From: Teun van den Brand <tahvdbrand@gmail.com>
Date: Fri, 6 Sep 2024 11:31:47 +0200
Subject: [PATCH 4/6] add news bullet

---
 NEWS.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/NEWS.md b/NEWS.md
index 320985c..c47e981 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -1,5 +1,7 @@
 # gtable (development version)
 
+* Added `as.gtable()` S3 method (#97).
+
 # gtable 0.3.5
 
 # gtable 0.3.4

From 604785783ff14bca7bd7fa7d0473cabab83ad750 Mon Sep 17 00:00:00 2001
From: Teun van den Brand <tahvdbrand@gmail.com>
Date: Fri, 6 Sep 2024 11:37:29 +0200
Subject: [PATCH 5/6] document `widths`/`heights`

---
 R/gtable.R       | 2 ++
 man/as.gtable.Rd | 3 +++
 2 files changed, 5 insertions(+)

diff --git a/R/gtable.R b/R/gtable.R
index 3297d3d..8d96d8e 100644
--- a/R/gtable.R
+++ b/R/gtable.R
@@ -295,6 +295,8 @@ as.gtable.gtable <- function(x, ...) x
 
 #' @export
 #' @describeIn as.gtable Creates a 1-cell gtable containing the grob.
+#' @param widths,heights Scalar unit setting the size of the table. Defaults
+#'   to [grid::grobWidth()] and [grid::grobHeight()] of `x` respectively.
 as.gtable.grob <- function(x, widths = NULL, heights = NULL, ...) {
   if (length(widths) > 1) {
     widths <- widths[1]
diff --git a/man/as.gtable.Rd b/man/as.gtable.Rd
index 2f21fbe..df8c89e 100644
--- a/man/as.gtable.Rd
+++ b/man/as.gtable.Rd
@@ -13,6 +13,9 @@ as.gtable(x, ...)
 \item{x}{An object to convert.}
 
 \item{...}{Arguments forwarded to methods.}
+
+\item{widths, heights}{Scalar unit setting the size of the table. Defaults
+to \code{\link[grid:grobWidth]{grid::grobWidth()}} and \code{\link[grid:grobWidth]{grid::grobHeight()}} of \code{x} respectively.}
 }
 \value{
 A gtable object

From a308111cde629afe9c602fb7a2a776bf44b533b6 Mon Sep 17 00:00:00 2001
From: Teun van den Brand <tahvdbrand@gmail.com>
Date: Fri, 6 Sep 2024 11:52:55 +0200
Subject: [PATCH 6/6] add to pkgdown index

---
 _pkgdown.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/_pkgdown.yml b/_pkgdown.yml
index e2b7da3..071b4a8 100644
--- a/_pkgdown.yml
+++ b/_pkgdown.yml
@@ -19,6 +19,7 @@ reference:
   - gtable_col
   - gtable_row
   - gtable_spacer
+  - as.gtable
 
 - title: Modification
   contents: