gpkg_connect in-place; closes #8

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: gpkg
 Type: Package
 Title: Utilities for the OGC 'GeoPackage' Format
-Version: 0.0.5.9001
+Version: 0.0.5.9002
 Authors@R: person(given="Andrew", family="Brown", email="brown.andrewg@gmail.com", role = c("aut", "cre"))
 Maintainer: Andrew Brown <brown.andrewg@gmail.com>
 Description: High-level wrapper functions to build Open Geospatial Consortium (OGC) 'GeoPackage' files (<https://www.geopackage.org/>). 'GDAL' utilities for read and write of spatial data are provided via the 'terra' package. Additional 'GeoPackage' and 'SQLite' specific functions manipulate attributes and tabular data via the 'RSQLite' package.

NAMESPACE

@@ -54,6 +54,7 @@ export(gpkg_write_attributes)
 importFrom(DBI,dbConnect)
 importFrom(DBI,dbDisconnect)
 importFrom(DBI,dbGetQuery)
+importFrom(DBI,dbIsValid)
 importFrom(DBI,dbListTables)
 importFrom(methods,show)
 importFrom(utils,packageVersion)

R/gpkg-connection.R

@@ -1,6 +1,9 @@
 
 #' Create SQLite Connection to GeoPackage
 #'
+#' Method for creating and connecting `SQLiteConnection` object stored within `geopackage` object.
+#' @details The S3 method for `geopackage` objects uses in-place modification to update the parent object by name. That is, if you call `gpkg_connect()` on an object `g` then as a side-effect `g` is updated in the user environment. This behavior is considered by many to be non-idiomatic for R, but it is useful to provide a simple way to connect an existing object without having to retain references to pointers to connection objects. To avoid replacement of object values in the parent frame, you can use the `character` method. That is `g <- gpkg_connect(g$dsn)` is equivalent to `gpkg_connect(g)` when `g` is a `geopackage`.
+#'
 #' @param x Path to GeoPackage
 #'
 #' @return A DBIConnection (SQLiteConnection) object. `NULL` on error.
@@ -12,7 +15,10 @@ gpkg_connect <- function(x)
 #' @export
 #' @rdname gpkg-connnection
 gpkg_connect.geopackage <- function(x) {
+ obj <- as.character(substitute(x))
  x$con <- gpkg_connect(x$dsn)$con
+ # update object in parent frame
+ try(assign(obj, x, envir = parent.frame()))
  x
 }
 
@@ -71,7 +77,7 @@ gpkg_disconnect.SQLiteConnection <- function(x) {
 #' @param x A _geopackage_ object, a path to a GeoPackage or an _SQLiteConnection_
 #' @return An SQLiteConnection with logical attribute `"disconnect"` indicating whether it should be disconnected after use.
 #' @noRd
-#' @imporFrom DBI dbIsValid
+#' @importFrom DBI dbIsValid
 #' @keywords internal
 .gpkg_connection_from_x <- function(x) {