small enhancement to UCSC.api.url()

Bioconductor · Mar 20, 2024 · d91d167 · d91d167
1 parent a345940
commit d91d167
Show file tree

Hide file tree

Showing 3 changed files with 42 additions and 17 deletions.
diff --git a/R/UCSC.api.url.R b/R/UCSC.api.url.R
@@ -5,7 +5,18 @@
 
 
 ### Exported.
-UCSC.api.url <- function() getOption("UCSC.api.url")
+UCSC.api.url <- function(new_url=NULL)
+{
+    ans <- getOption("UCSC.api.url")
+    if (is.null(new_url))
+        return(ans)
+    if (!(isSingleString(new_url) && nzchar(new_url)))
+        stop(wmsg("'new_url' must be a single (non-empty) string"))
+    if (!startsWith(tolower(new_url), "http"))
+        stop(wmsg("'new_url' must start with \"http\""))
+    options(UCSC.api.url=new_url)
+    invisible(ans)  # return old URL invisibly
+}
 
 
 ### - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

diff --git a/R/zzz.R b/R/zzz.R
@@ -4,7 +4,6 @@
     ## - Europe: https://genome-euro.ucsc.edu/cgi-bin/hubApi
     ## - Asia: https://genome-asia.ucsc.edu/cgi-bin/hubApi
     ## - Mirror installation: https://your.server.edu/cgi-bin/hubApi
-    url <- "https://api.genome.ucsc.edu"  # primary URL (West Coast)
-    options(UCSC.api.url=url)
+    UCSC.api.url("https://api.genome.ucsc.edu")  # primary URL (West Coast)
 }
 
diff --git a/man/UCSC.api.url.Rd b/man/UCSC.api.url.Rd
@@ -2,27 +2,39 @@
 
 \alias{UCSC.api.url}
 
-\title{Use an alternative UCSC API URL}
+\title{Get or set the default UCSC API URL}
 
 \description{
-  Get the default UCSC API URL or change it to an alternative URL.
+  Get or set the default UCSC API URL.
 }
 
 \usage{
-UCSC.api.url()
+UCSC.api.url(new_url=NULL)
+}
+
+\arguments{
+  \item{new_url}{
+    Alternative UCSC API URL to use by default.
+  }
 }
 
 \details{
-    \code{UCSC.api.url} is just a convenience wrapper for
-    \code{getOption("UCSC.api.url")}.
+  \code{UCSC.api.url()} is just a convenience wrapper for
+  \code{getOption("UCSC.api.url")}.
 
-    To use an alternative UCSC API URL, set \code{UCSC.api.url}
-    global option to the new URL e.g. with:
-\preformatted{options(UCSC.api.url="https://genome-asia.ucsc.edu/cgi-bin/hubApi")}
+  To change the default UCSC API URL, call \code{UCSC.api.url(new_url)}
+  where \code{new_url} is a single string containing the alternative URL.
+  Note that this is just a convenience wrapper for
+  \code{options(UCSC.api.url=new_url)}.
 }
 
 \value{
-  The UCSC API URL used by default.
+  When called with no argument, \code{UCSC.api.url()} returns the URL of
+  the UCSC API that is currently used by default.
+
+  When passed a new URL, \code{UCSC.api.url(new_url)} returns the URL of
+  the UCSC API that was \emph{previously} used by default. Note that the
+  URL is returned invisibly.
 }
 
 \seealso{
@@ -35,12 +47,15 @@ UCSC.api.url()
 }
 
 \examples{
-UCSC.api.url()
+UCSC.api.url()  # current default UCSC API URL
+get_UCSC_chrom_sizes("ce11", recache=TRUE)
 
-## To use the mirror in Asia:
-\dontrun{
-options(UCSC.api.url="https://genome-asia.ucsc.edu/cgi-bin/hubApi")
-}
+## Temporarily use the mirror in Asia:
+old_url <- UCSC.api.url("https://genome-asia.ucsc.edu/cgi-bin/hubApi")
+get_UCSC_chrom_sizes("ce11", recache=TRUE)
+
+## Restore old URL:
+UCSC.api.url(old_url)
 }
 
 \keyword{manip}