\name{getAnnotationHubOption}

\alias{getAnnotationHubOption}
\alias{setAnnotationHubOption}

\title{Get and set options for default AnnotationHub behavior.}

\description{
  These functions get or set options for creation of new
  \sQuote{AnnotationHub} instances.
}

\usage{
getAnnotationHubOption(arg)
setAnnotationHubOption(arg, value)
}

\arguments{
  \item{arg}{The character(1) hub options to set. see \sQuote{Details}
    for current options.}
  \item{value}{The value to be assigned to the hub option.}
}

\details{
  Supported options include:

  \describe{

    \item{\dQuote{URL}:}{character(1). The base URL of the annotation
      hub. Default: \url{https://annotationhub.bioconductor.org}}

    \item{\dQuote{CACHE}:}{character(1). The location of the hub
      cache. Default: \dQuote{AnnotationHub} in the user's directory
      established by \code{rappdirs::user_cache_dir()}.}

    \item{\dQuote{MAX_DOWNLOADS}:}{numeric(1). The integer number of
      downloads allowed before triggering an error. This is to help
      avoid accidental download of a large number of AnnotationHub
      members.}

    \item{\dQuote{PROXY}:}{\code{request} object returned by
      \code{httr::use_proxy()}. The \code{request} object describes a proxy
      connection allowing Internet access, usually through a restrictive
      firewall. Setting this option sends all AnnotationHub requests through
      the proxy. Default: NULL.

      In \code{setHubOption("PROXY", value)}, \code{value} can be one of NULL,
      a \code{request} object returned by \code{httr::use_proxy()}, or a
      well-formed URL as character(1). The URL can be completely
      specified by \code{http://username:password@proxy.dom.com:8080};
      \code{username:password} and port (e.g. \code{:8080}) are optional.}

    \item{\dQuote{TESTING}:}{logical(1). TRUE/FALSE should the AnnotationHub
      testing environment be used. AnnotationHub does automatic
      filtering particularly with regards to OrgDbs. The
      \code{TESTING=TRUE} setting will allow for all OrgDbs for a given
      devel version to also be displayed. (This option should really
      only be set by a OrgDb contributing maintainer for testing and
      debugging). Default: FALSE.}

    \item{\dQuote{LOCAL}:}{logical(1). TRUE/FALSE should the AnnotationHub
      create a hub consisting only of previously downloaded resourcesd.
      Default: FALSE.}

   }

  Default values may also be determined by system and global R
  environment variables visible \emph{before} the package is loaded. Use
  options or variables preceeded by \dQuote{ANNOTATION_HUB_}, e.g.,
  \code{options(ANNOTATION_HUB_MAX_DOWNLOADS=10)} prior to package load
  sets the default number of downloads to 10. 

}

\value{The requested or successfully set option.}

\author{Martin Morgan \url{mtmorgan@fhcrc.org} and Lori Shepherd}

\examples{
getAnnotationHubOption("URL")
\dontrun{
setAnnotationHubOption("CACHE", "~/.myHub")
}
}
\keyword{ manip }
