R/catalog_do.R

In fognyc/factorr: Tools for Retrieving Factor Time-Series Hosted on Remote Servers

#' Performs 'do' operations on the internal catalog.
#'
#' \code{catalog_do} takes a string argument representing an operation to be
#' performed on the internal catalog. The internal catalog is a
#' \code{tibble} object and its fields include a factor model descriptor
#' (\code{desc}), an associated acronym (\code{hdl}), a source url
#' (\code{url_src}), along with other fields.
#'
#' The function behaves differently under different operators, which is a
#' primitive form of function polymorphism. Each operator comes in the form of a
#' verb closely matching the intended operation.
#'
#' The internal catalog is used primarily to encode and maintain the
#' parameters required to perform each query (request) associated with a
#' particular data set hosted on remote server. Data sets are primarily
#' identified by the fields \code{desc} and \code{hdl} from a user's
#' perspective. Note that the catalog can't be modified by the user as it is
#' defined internally to protect its integrity. The catalog existence is
#' checked before implementing the command operator.
#'
#' The command operator \code{get} returns a copy of the catalog object, which
#' might be useful to extensively search/filter the catalog along any field.

#'
#' @param operation A string object, representing a command operator.
#' @param hdl A string object, representing the selected handle (\code{hdl}).
#'   Applicable when \code{operation = 'show_hdl_names'} and ignored otherwise.
#'   See also Return section below.
#' @return \item{printout}{Operator \code{show} prints to console the catalog
#'   object under the \code{tibble} framework.} \item{printout}{Operator
#'   \code{show_all} prints to console every line.} \item{printout}{Operator
#'   \code{show_hdl_names} prints to console the variable names available for a
#'   given handle.} \item{catalog}{Operator \code{get} returns a copy of the
#'   catalog object.} \item{charater vector}{Operator \code{get_names} returns
#'   the column names of the catalog \code{tibble}.}
#'
#' @importFrom rlang .data
#' @export
#
# If dplyr::select is in a package, using .data also prevents R CMD check from
# giving a NOTE about undefined global variables (provided that @importFrom
# rlang .data is inserted). Using rlang::.data (without @importFrom rlang .data)
# is another option. See Wickham, Hadley, R Packages, O'Reilly, 1st Edition,
# 2015, p. 89 for details

catalog_do <- function(operation = c('show', 'show_all', 'show_hdl_names',
                                     'get', 'get_names'), hdl = 'VOID') {

  if( !exists('catalog') ){
    stop(stringr::str_glue("Object 'catalog' does not exist."), call. = T)
  }
  operation <- match.arg(operation)

  if(operation == 'show'){
    print(dplyr::select(catalog, .data$desc, .data$hdl, .data$source))
  }

  if(operation == 'show_all'){
    n <- dim(catalog)[1]
    print(dplyr::select(catalog, .data$desc, .data$hdl), n = n)
  }

  if(operation == 'show_hdl_names'){
    obj <- catalog_do(operation = 'get')

    stopifnot(is.character(hdl))
    if(!(hdl %in% obj$hdl)){
      msg_suffix <- stringr::str_glue(" is not in the catalog.",
                                      " Check spelling or set parameter 'hdl'")
      stop(stringr::str_glue(hdl, msg_suffix), call. = T)
    }

    obj <- dplyr::filter(.data = obj, .data$hdl == !!hdl)
    print(obj$hdl_names)
  }

  if(operation == 'get'){
    return(catalog)
  }

  if(operation == 'get_names'){
    return(names(catalog))
  }
}