dev UD

AGENTS.md

@@ -1,4 +1,4 @@
-# AGENTS.md
+
 
 ## Overview
 ReadWriter is an R package providing convenience functions for reading from and writing to text-based data files. The package aims to streamline common I/O tasks and complements other tools in the `@vertesy` ecosystem.
@@ -10,6 +10,12 @@ ReadWriter is an R package providing convenience functions for reading from and
 - `DESCRIPTION` – package metadata and dependency declarations.
 - `README.md` – installation instructions and a high-level overview.
 
+
+
+### Update the Source, Not Just the Documentation
+
+Documentations rebuilt and overwritten from upstream sources: `.Rd` files from roxygen annotations and DESCRIPTION and NAMESPACE from  `config.R` by `PackageTools::document_and_create_package()` relying on  `devtools::document()`  when I manually, regularly run `/Development/MYPACKAGE/Development/Create_the_MYPACKAGE_Package.R")`. Thus  always update the upstream sources first, then fix the downstream documentations correspondingly.
+
 ## Dependencies
 - Requires the `@vertesy` package [`Stringendo` (>=0.5.0)](https://github.com/vertesy/Stringendo) and CRAN packages `gtools`, `openxlsx`, `qs`, and `readr`.
 - Install `Stringendo` before installing ReadWriter:
@@ -23,6 +29,10 @@ ReadWriter is an R package providing convenience functions for reading from and
 - Run `R -q -e "devtools::document()"` to regenerate Rd files before committing.
 - Verify the package with `R -q -e "devtools::check(document = FALSE)"`; checks should pass with no errors.
 - There is currently no automated test suite. Manual testing of new functionality is encouraged.
+- In `/Development/MYPACKAGE/Development/Create_the_MYPACKAGE_Package.R")`, `PackageTools::document_and_create_package()` recreates an R package’s metadata and documentation from a configuration file. It runs `devtools::document()` to regenerate package documentation, including the DESCRIPTION and NAMESPACE. 
+
+
 
 ## Getting started
+
 New contributors should read `README.md` for installation details and review `R/ReadWriter.R` to understand available functions. For broader context and utility helpers, explore the `Stringendo` package and other repositories in the `@vertesy` organization.

DESCRIPTION

@@ -9,11 +9,12 @@ License: GPL-3 + file LICENSE
 BugReports: https://github.com/vertesy/ReadWriter/issues
 Depends: 
     Stringendo (>= 0.5.0)
-Imports: 
+Imports:
     gtools,
     openxlsx,
     qs,
-    readr
+    readr,
+    stringi
 Encoding: UTF-8
 Packaged: 2026-08-25 16:41:37.734198
 Roxygen: list(markdown = TRUE)

Development/Create_the_ReadWriter_Package.R

@@ -86,7 +86,8 @@ for (scriptX in ls.scripts.full.path) {
 }
 file.edit(paste0(repository.dir, "/R/list.of.functions.in.", package.name, ".det.md"))
 file.edit(paste0(repository.dir, "/README.md"))
-file.remove(paste0(repository.dir, "/R/list.of.functions.in.", package.name, ".det.md"))
+# file.remove(paste0(repository.dir, "/R/list.of.functions.in.", package.name, ".det.md"))
+file.remove(list.files(file.path(repository.dir, "R"), pattern = "^list\\.of\\.functions\\.in\\..+\\.det\\.md$", full.names = TRUE))
 
 d$PackageTools()
 PackageTools::copy_github_badge("active") # Add badge to readme via clipboard

Development/config.R

@@ -14,7 +14,7 @@ DESCRIPTION <- list(
   license = "GPL-3 + file LICENSE",
   depends = "Stringendo (>= 0.5.0)",
   remotes =  "github::vertesy/Stringendo",
-  imports = "qs, openxlsx, gtools, readr",
+  imports = "qs, openxlsx, gtools, readr, stringi",
   suggests = ""
 )
 

NAMESPACE

@@ -33,3 +33,4 @@ importFrom(readr,read_csv)
 importFrom(readr,read_csv2)
 importFrom(readr,read_delim)
 importFrom(readr,read_tsv)
+importFrom(stringi,stri_detect_regex)

R/Deprecated.Functions.R

@@ -54,73 +54,73 @@ read.simple.xls <- function(pfn = Stringendo::kollapse(...), row_namePos = NULL,
 # _________________________________________________________________________________________________
 
 
-#'
-#' # _________________________________________________________________________________________________
-#' #' @title write.simple.xlsx.old
-#' #' @description Write out a list of matrices/ data frames WITH ROW- AND COLUMN-
-#' #'   NAMES to a file with as an Excel (.xslx) file. Your output filename will be
-#' #'   either the variable's name. The output file will be located in "OutDir"
-#' #'   specified by you at the beginning of the script, or under your current
-#' #'   working directory. You can pass the PATH and VARIABLE separately (in
-#' #'   order), they will be concatenated to the filename.
-#' #' @param named_list A list of data frames to write out
-#' #' @param suffix A suffix added to the filename, Default: NULL
-#' #' @param fname A string for a manually defined filename. Default: substitute(named_list)
-#' #' @param o Set to TRUE to open file after writing out using 'system(open ...)' on OS X., Default: FALSE
-#' #' @param TabColor Tab Color in Excel, Default: 'darkgoldenrod1'
-#' #' @param Creator Creator, Default: ''
-#' #' @param HeaderCex Header color, Default: 12
-#' #' @param HeaderLineColor Header line color, Default: 'darkolivegreen3'
-#' #' @param HeaderCharStyle Header character style, Default: c("bold", "italic", "underline")[1]
-#' #' @param row_names Have rownames? Default: TRUE
-#' #' @param ... Multiple simple variables to parse.
-#' #' @examples
-#' #' \dontrun{
-#' #' if(interactive()){
-#' #'  # write.simple.xlsx(my.list.of.data.frames)
-#' #'  }
-#' #' }
-#' #' @seealso
-#' #'  \code{\link[openxlsx]{write.xlsx}}
-#' #' @export
-#' #' @importFrom openxlsx write.xlsx createStyle
-#'
-#' write.simple.xlsx.old <- function(named_list
-#'                                   , filename = substitute(named_list)
-#'                                   , suffix = NULL
-#'                                   , o = FALSE
-#'                                   , TabColor = "darkgoldenrod1", HeaderLineColor = "darkolivegreen3"
-#'                                   , HeaderCex = 12, Creator = ""
-#'                                   , HeaderCharStyle = c("bold", "italic", "underline")[1]
-#'                                   , row_names = TRUE, ...) {
-#'
-#'   warning("Switched using from openxlsx to readxl package 2023.11.22")
-#'
-#'   fname <- Stringendo::sppp(filename, suffix)
-#'   if ( !('list' %in% class(named_list))  ) named_list <- list(named_list) # convert to a list if needed
-#'
-#'   if (nchar(fname) > 100) fname <- kpp('_Output', idate())
-#'   FnP <- kpp(kpps(getwd(), fname), "xlsx")
-#'
-#'   hs <- openxlsx::createStyle(textDecoration = HeaderCharStyle, fontSize = HeaderCex
-#'                               , fgFill = HeaderLineColor)
-#'
-#'   if (row_names) {
-#'     FUNX <- function(x)  rownames_to_column(as.data.frame(x), var = "genes")
-#'     named_list <- lapply(named_list, FUNX)
-#'     # named_list <- rownames_to_column(as.data.frame(named_list), var = "genes")
-#'   }
-#'   print(named_list)
-#'   print(rownames(named_list))
-#'
-#'   openxlsx::write.xlsx(x = named_list, file = FnP, rowNames = FALSE
-#'                        , firstRow = TRUE
-#'                        , firstCol = TRUE
-#'                        , colWidths = "auto"
-#'                        , headerStyle = hs, tabColour = TabColor, creator = Creator)
-#'   if (o) { system(paste0("open ", fix_special_characters_bash(FnP)), wait = FALSE) }
-#' } # fun
-#'
+#
+# # _________________________________________________________________________________________________
+# #' @title write.simple.xlsx.old
+# #' @description Write out a list of matrices/ data frames WITH ROW- AND COLUMN-
+# #'   NAMES to a file with as an Excel (.xslx) file. Your output filename will be
+# #'   either the variable's name. The output file will be located in "OutDir"
+# #'   specified by you at the beginning of the script, or under your current
+# #'   working directory. You can pass the PATH and VARIABLE separately (in
+# #'   order), they will be concatenated to the filename.
+# #' @param named_list A list of data frames to write out
+# #' @param suffix A suffix added to the filename, Default: NULL
+# #' @param fname A string for a manually defined filename. Default: substitute(named_list)
+# #' @param o Set to TRUE to open file after writing out using 'system(open ...)' on OS X., Default: FALSE
+# #' @param TabColor Tab Color in Excel, Default: 'darkgoldenrod1'
+# #' @param Creator Creator, Default: ''
+# #' @param HeaderCex Header color, Default: 12
+# #' @param HeaderLineColor Header line color, Default: 'darkolivegreen3'
+# #' @param HeaderCharStyle Header character style, Default: c("bold", "italic", "underline")[1]
+# #' @param row_names Have rownames? Default: TRUE
+# #' @param ... Multiple simple variables to parse.
+# #' @examples
+# #' \dontrun{
+# #' if(interactive()){
+# #'  # write.simple.xlsx(my.list.of.data.frames)
+# #'  }
+# #' }
+# #' @seealso
+# #'  \code{\link[openxlsx]{write.xlsx}}
+# #' @export
+# #' @importFrom openxlsx write.xlsx createStyle
+#
+# write.simple.xlsx.old <- function(named_list
+#                                   , filename = substitute(named_list)
+#                                   , suffix = NULL
+#                                   , o = FALSE
+#                                   , TabColor = "darkgoldenrod1", HeaderLineColor = "darkolivegreen3"
+#                                   , HeaderCex = 12, Creator = ""
+#                                   , HeaderCharStyle = c("bold", "italic", "underline")[1]
+#                                   , row_names = TRUE, ...) {
+#
+#   warning("Switched using from openxlsx to readxl package 2023.11.22")
+#
+#   fname <- Stringendo::sppp(filename, suffix)
+#   if ( !('list' %in% class(named_list))  ) named_list <- list(named_list) # convert to a list if needed
+#
+#   if (nchar(fname) > 100) fname <- kpp('_Output', idate())
+#   FnP <- kpp(kpps(getwd(), fname), "xlsx")
+#
+#   hs <- openxlsx::createStyle(textDecoration = HeaderCharStyle, fontSize = HeaderCex
+#                               , fgFill = HeaderLineColor)
+#
+#   if (row_names) {
+#     FUNX <- function(x)  rownames_to_column(as.data.frame(x), var = "genes")
+#     named_list <- lapply(named_list, FUNX)
+#     # named_list <- rownames_to_column(as.data.frame(named_list), var = "genes")
+#   }
+#   print(named_list)
+#   print(rownames(named_list))
+#
+#   openxlsx::write.xlsx(x = named_list, file = FnP, rowNames = FALSE
+#                        , firstRow = TRUE
+#                        , firstCol = TRUE
+#                        , colWidths = "auto"
+#                        , headerStyle = hs, tabColour = TabColor, creator = Creator)
+#   if (o) { system(paste0("open ", fix_special_characters_bash(FnP)), wait = FALSE) }
+# } # fun
+#
 
 
 # _________________________________________________________________________________________________

R/ReadWriter.R

@@ -957,10 +957,12 @@ write.simple.xlsx <- function(
   )
 
   # assign row names if required
+  write_row_names <- has_row_names
   if (isFALSE(has_row_names)) {
-    assignRownames <- function(x) column.2.row.names(df, rowname_column = rowname_column, make_names = TRUE)
+    assignRownames <- function(x) column.2.row.names(x, rowname_column = rowname_column, make_names = TRUE)
     named_list <- lapply(named_list, assignRownames)
     message("Converting column ", rowname_column, " to row names: ", head(rownames(named_list[[1]])))
+    write_row_names <- TRUE # the converted identifiers must still be written as the sheet's row names
   }
 
   FnP <- construct.file.path(
@@ -970,7 +972,7 @@ write.simple.xlsx <- function(
   )
 
   openxlsx::write.xlsx(
-    x = named_list, file = FnP, rowNames = has_row_names,
+    x = named_list, file = FnP, rowNames = write_row_names,
     firstRow = FreezeFirstRow, firstCol = FreezeFirstCol,
     headerStyle = hs, tabColour = TabColor,
     colWidths = "auto", creator = Creator
@@ -1139,38 +1141,37 @@ write.simple.md.table <- function(
 #' @return The function does not return a value but writes the file to disk in the specified format.
 #'
 #' @importFrom qs qread
+#' @importFrom stringi stri_detect_regex
 #'
 #' @export qs.2.table
 
 qs.2.table <- function(path, out_file = c("tsv", "csv", "csv2", "excel")[1]) {
   # Ensure that the file exists and is a .qs file
-  stopifnot(file.exists(path), stringi::stri_detect(str = path, regex = "\\.qs$"))
+  stopifnot(file.exists(path), stringi::stri_detect_regex(str = path, pattern = "\\.qs$"))
 
   # Ensure out_file is one of the allowed choices
   out_file <- match.arg(out_file, c("tsv", "csv", "csv2", "excel"))
 
   # Read in the .qs file
-  data <- qs:qread(path)
+  data <- qs::qread(path)
 
-  # Determine the output file extension and write the file based on the output format
-  path_out <- Stringendo::ppp(base_filename, out_file)
-
-  if (out_file == "excel") {
-    # out_path <- ppp(base_filename, "xlsx")
-    Stringendo::ppp(base_filename, out_file)
-    ReadWriter::write.simple.xlsx(data, out_path)
-  }
+  # Base name (without extension) shared by all output formats
+  base_filename <- sub("\\.qs$", "", path)
 
   if (out_file == "tsv") {
-    ReadWriter::write.simple.tsv(data, path_out, separator = "\t")
+    ReadWriter::write.simple.tsv(data, manual_file_name = base_filename, separator = "\t")
+    out_path <- paste0(base_filename, ".tsv")
   } else if (out_file == "csv") {
-    ReadWriter::write.simple.tsv(data, path_out, separator = ",")
+    ReadWriter::write.simple.tsv(data, manual_file_name = base_filename, separator = ",")
+    out_path <- paste0(base_filename, ".csv")
   } else if (out_file == "csv2") {
+    ReadWriter::write.simple.tsv(data, manual_file_name = base_filename, separator = ";")
     out_path <- paste0(base_filename, ".csv")
-    ReadWriter::write.simple.tsv(data, path_out, separator = ";")
   } else if (out_file == "excel") {
+    # write.simple.xlsx() expects a list of sheets; wrap a bare table into one.
+    payload <- if (is.data.frame(data) || is.matrix(data)) list(data) else data
+    ReadWriter::write.simple.xlsx(payload, manual_file_name = base_filename)
     out_path <- paste0(base_filename, ".xlsx")
-    ReadWriter::write.simple.xlsx(data, out_path)
   }
 
   message("File saved as: ", out_path)