From 615667c633a690127cf860bbd16fb0f0876d87cf Mon Sep 17 00:00:00 2001
From: Axel Klenk <axel.klenk@gmail.com>
Date: Tue, 15 Oct 2024 21:15:11 +0200
Subject: [PATCH] add check for readGMT() input and examples section

---
 NAMESPACE        |  1 +
 R/GSVA-package.R |  1 +
 R/gsvaNewAPI.R   | 31 ++++++++++++++++++++++++++++---
 man/readGMT.Rd   | 28 +++++++++++++++++++++++++---
 4 files changed, 55 insertions(+), 6 deletions(-)

diff --git a/NAMESPACE b/NAMESPACE
index 963eef1..4a5a6d0 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -79,6 +79,7 @@ importFrom(SingleCellExperiment,SingleCellExperiment)
 importFrom(SpatialExperiment,SpatialExperiment)
 importFrom(SummarizedExperiment,SummarizedExperiment)
 importFrom(SummarizedExperiment,assay)
+importFrom(cli,cli_abort)
 importFrom(cli,cli_alert_info)
 importFrom(cli,cli_alert_success)
 importFrom(cli,cli_alert_warning)
diff --git a/R/GSVA-package.R b/R/GSVA-package.R
index befdb0e..3baa525 100644
--- a/R/GSVA-package.R
+++ b/R/GSVA-package.R
@@ -33,4 +33,5 @@
 #' currentBlockId read_block gridReduce write_block close t colSums
 #' @importFrom HDF5Array HDF5RealizationSink writeHDF5Array
 #' @importFrom BiocSingular runRandomSVD
+#' @importFrom cli cli_abort cli_alert_info cli_alert_warning cli_alert_success
 NULL
diff --git a/R/gsvaNewAPI.R b/R/gsvaNewAPI.R
index 234123d..123facc 100644
--- a/R/gsvaNewAPI.R
+++ b/R/gsvaNewAPI.R
@@ -863,9 +863,8 @@ geneIdsToGeneSetCollection <- function(geneIdsList,
 #' @description Imports a list of gene sets from a GMT (Gene Matrix Transposed)
 #' format file, offering a choice of ways to handle duplicated gene set names.
 #' 
-#' @param con A connection object or character string containing e.g.
-#' the file name or URL of a GTM file.  This is directly passed to [`readLines`]
-#' and hence may contain anything that `readLines()` can handle.
+#' @param con A connection object or a non-empty character string of length 1
+#' containing e.g. the filename or URL of a (possibly compressed) GMT file. 
 #'
 #' @param sep The character string separating members of each gene set in the
 #' GMT file.
@@ -919,6 +918,28 @@ geneIdsToGeneSetCollection <- function(geneIdsList,
 #' 
 #' @seealso [`readLines`], [`GeneSetCollection`], [`getGmt`]
 #'
+#' @examples
+#' library(GSVA)
+#' library(GSVAdata)
+#'
+#' fname <- system.file("extdata", "c7.immunesigdb.v2024.1.Hs.symbols.gmt.gz",
+#'                      package="GSVAdata")
+#'
+#' ## by default, guess geneIdType from content and return a GeneSetCollection
+#' genesets <- readGMT(fname)
+#' genesets
+#'
+#' ## how to manually override the geneIdType
+#' genesets <- readGMT(fname, geneIdType=NullIdentifier())
+#' genesets
+#' 
+#' ## return a simple list instead of a GeneSetCollection
+#' genesets <- readGMT(fname, valueType="list")
+#' head(genesets, 2)
+#'
+#' ## the list has a geneIdType, too
+#' gsvaAnnotation(genesets)
+#'
 #' @aliases readGMT
 #' @name readGMT
 #' @rdname readGMT
@@ -932,6 +953,10 @@ readGMT <- function (con,
                      deduplUse = c("first", "drop", "union", "smallest", "largest"),
                      ...) {
     valueType <- match.arg(valueType)
+
+    if((!.isCharLength1(con)) && (!inherits(con, "connection"))) {
+        cli_abort("Argument 'con' is not a valid filename, URL or connection.")
+    }
     
     ## from GSEABase::getGmt()
     lines <- strsplit(readLines(con, ...), sep)
diff --git a/man/readGMT.Rd b/man/readGMT.Rd
index ba257f9..55462f9 100644
--- a/man/readGMT.Rd
+++ b/man/readGMT.Rd
@@ -15,9 +15,8 @@ readGMT(
 )
 }
 \arguments{
-\item{con}{A connection object or character string containing e.g.
-the file name or URL of a GTM file.  This is directly passed to \code{\link{readLines}}
-and hence may contain anything that \code{readLines()} can handle.}
+\item{con}{A connection object or a non-empty character string of length 1
+containing e.g. the filename or URL of a (possibly compressed) GMT file.}
 
 \item{sep}{The character string separating members of each gene set in the
 GMT file.}
@@ -77,6 +76,29 @@ argument \code{valueType}.
 \description{
 Imports a list of gene sets from a GMT (Gene Matrix Transposed)
 format file, offering a choice of ways to handle duplicated gene set names.
+}
+\examples{
+library(GSVA)
+library(GSVAdata)
+
+fname <- system.file("extdata", "c7.immunesigdb.v2024.1.Hs.symbols.gmt.gz",
+                     package="GSVAdata")
+
+## by default, guess geneIdType from content and return a GeneSetCollection
+genesets <- readGMT(fname)
+genesets
+
+## how to manually override the geneIdType
+genesets <- readGMT(fname, geneIdType=NullIdentifier())
+genesets
+
+## return a simple list instead of a GeneSetCollection
+genesets <- readGMT(fname, valueType="list")
+head(genesets, 2)
+
+## the list has a geneIdType, too
+gsvaAnnotation(genesets)
+
 }
 \seealso{
 \code{\link{readLines}}, \code{\link{GeneSetCollection}}, \code{\link{getGmt}}