R/generics.R

In shunsambongi/dsi: Interfaces for data sources and datasets

# driver ------------------------------------------------------------------

#' Test whether an object is a `dsi`-compatible driver
#'
#' @param x object to test
#' @param ... other params passed onto methods
#' @return a boolean
#' @export
is_driver <- function(x, ...) {
  UseMethod("is_driver")
}

#' @export
is_driver.default <- function(x, ...) FALSE

# connection --------------------------------------------------------------

#' Connect to a data source
#'
#' `connect` will create and return a connection. `connect_local` will create and
#' return a connection that will be automatically disconnected when the current
#' frame exits.
#'
#' @param x object that specifies the type of connection to create, e.g. a driver
#' @param ... other params passed onto methods
#' @param .envir the environment to use for scoping
#' @return a connection to a data source
#'
#' @seealso [disconnect()], [is_connected()]
#' @name connect
NULL

#' @rdname connect
#' @export
connect <- function(x, ...) {
  UseMethod("connect")
}

#' @rdname connect
#' @export
connect_local <- function(x, ..., .envir = parent.frame()) {
  UseMethod("connect_local")
}

#' @export
connect_local.default <- function(x, ..., .envir = parent.frame()) {
  con <- connect(x, ...)
  do.call(on.exit, list(substitute(dsi::disconnect(con))), envir = .envir)
  invisible(con)
}

#' Connection Operations
#'
#' @param x connection to a data source
#' @param ... other params passed onto methods
#' @seealso [connect()]
#' @name connection-ops
NULL

#' @rdname connection-ops
#' @export
disconnect <- function(x, ...) {
  UseMethod("disconnect")
}

#' @rdname connection-ops
#' @export
is_connected <- function(x, ...) {
  UseMethod("is_connected")
}


# datasource --------------------------------------------------------------

#' List the names of datasets
#'
#' @param x object that can query the data source, e.g. a connection
#' @param ... other params passed onto methods
#' @export
list_datasets <- function(x, ...) {
  UseMethod("list_datasets")
}


# datasets ----------------------------------------------------------------

#' Dataset Operations
#'
#' @param x connection to a data source
#' @param name name of the dataset
#' @param data `data.frame` to send to data source
#' @param ... other params passed onto methods
#' @name dataset-ops
NULL

#' @rdname dataset-ops
#' @export
read_dataset <- function(x, name, ...) {
  UseMethod("read_dataset")
}

#' @rdname dataset-ops
#' @export
write_dataset <- function(x, name, data, ...) {
  UseMethod("write_dataset")
}

#' @rdname dataset-ops
#' @export
remove_dataset <- function(x, name, ...) {
  UseMethod("remove_dataset")
}

#' @rdname dataset-ops
#' @export
exists_dataset <- function(x, name, ...) {
  UseMethod("exists_dataset")
}

#' @rdname dataset-ops
#' @export
list_fields <- function(x, name, ...) {
  UseMethod("list_fields")
}