Feature/#37 named by sheet (#216)

* issue #37: add worksheetName with 'null' default

* WIP troubleshooting java xlcall method

* poi 4.1.0 update dependency jars

* Updated XLConnect jar

* POI 4.1.0 remove jar in wrong location

* POI 4.1.0 - java changes recommended in review

* POI 4.1.0: released xlconnect java

* #37: fix tests, use XLConnect java 1.0.0 + changes

* #37 updated xlconnect java

* #37: clean up code, add test case

* #37 add negative test case

* #37 documentation

* #37 fix doc of readNamedRegion

* gh #37: write in specific sheet's named region

* gh #37: create, check existence, and append to named region + tests

* gh #37 clearNamedRegion of specified worksheet

* gh #37: add clear Named region test with worksheet name

* #37 create name: set worksheet if name provided

* gh #37: sync jar, dev version

* #37 add and clean up doc

* gh#37 test: formula sheet vs scope sheet

* gh#37 fix scope v formula - sheet property in java

* #37 fix clearNamedRegion (java), cleanup, clearer doc

* gh#37: remove jcenter, seems down

* gh #37: test cloning names

* #37 fix cloning names (java)

* #37 match worksheet name strictly (Java)

* gh#37 adapt doc to strict matching

* #37 correct null check in readNamed...

* Review: null handling / default value

* Review: parameter name change to '...scope'

* Review: write Named region - WIP?

* Review: write Named region - doc

* Review: use "" for explicit global scope

* Fix doc syntax

* Review: worksheet scope for ref coordinates + doc fixes

* Review: scoped removeName, doc fix

* Review: scoped addImage, missing default

* Review - fix doc

* Review: addImage backwards compat

* addImage fix doc

* review:  dimension-abiding readNamedRegion

* Restore full clear named region check

* Test write named to file with scope vector

* Proposed fix, test change, fix read test

* Fixed test

* attributes (handling new java cls, setting attrs)

* processing attributes, working for n scopes

* jar - handle null scope in create

* Adapted attribute handling with suggested approach

* correctly set names

* clean up, ws scope attribute when null (jar)

* WIP read named region attributes

* note after discussing with Riccardo

* attribute value is array of string

* Attributes in dataframe from java

* preserve attributes in extractRowNames

* use xlconnect-java rebased - with `overwriteFormulaCells`

* Jar from rebased XLConnect-java (refactoring)

* align xlcWithAttr... with changes to xlcCall

* avoid overwriting names when setting attributes

* checkTrue instead of checkExists for bool with attributes

* test write named region using (supported) scalar formula values only

* Doc: fix argument order in writeNamedRegionToFile

* combined version of xlcCall + Attributes

* test that attributes are set on existsName

* test creating scoped names

* remove unused code, reorder lines for clarity

* define and test attributes toggle

* implement attributes toggle

* add scope param and clarify attribute handling in documentation

* writeNamedRegionToFile: handle len(formula)>1

* refactoring: align function param order

* missing in \usage of appendNamedRegion-methods

* troubleshooting LaTeX output on newer R versions (?)

* fix itemize syntax

* line break not required

* test presence attributes on dataframes

* preserve java attributes on dataframes

* test: write then read two dataframes at once

* xlc-java candidate snapshot (refactored, no API changes)

* clean up debug statements

* jar from CI build

* XLConnect jar with cleaned up code

* leave out scoped names when cloning

* document effect of new option

* draft NEWS

* readNamedRegion: worksheet scope negative case

* clean up: reword doc, code formatting, comments

* .recycle=FALSE as of previous impl. in getDefinedNames

* simplified formula handling in writeNamedRegionToFile

* add examples for existsName, read/ write named region

* return attributes for getReferenceCoordinatesForName

* worksheet scope attribute values for getDefinedNames

* doc: reflect getDefinedNames in changes, more explicit attribute name

* attributes on getReferenceFormula

* doc review named range / named region

* more user-friendly name for attribute toggle

* jar from rebased xlconnect-java

* remove old xlc jar (rebase leftover)

* final JAR built on xlc-java master

.github/workflows/ci-tests.yml

@@ -32,7 +32,6 @@ jobs:
             r-version: oldrel
             java: 17 #8
             vignettes: true
-            xlc-repo: https://jcenter.bintray.com
             timezone-name: Europe/Zurich
           - os-name: ubuntu # windows-2019, macos-10.15]
             os-version: latest
@@ -45,7 +44,6 @@ jobs:
             r-version: devel
             java: 17
             vignettes: true
-            xlc-repo: https://jcenter.bintray.com
             timezone-name: Pacific/Marquesas
           - os-name: macos # TODO fix java / R interaction
             os-version: latest

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: XLConnect
 Type: Package
 Title: Excel Connector for R
-Version: 1.0.10
+Version: 1.1.0.9999
 Authors@R: c(person("Mirai Solutions GmbH", role = "aut",
                     email = "[email protected]"),
              person("Martin", "Studer", role = "cre",

NEWS

@@ -1,5 +1,12 @@
 XLConnect News
 --------------
+
+1.1.0 tbd
+
+  * Support for worksheet scoped names including [#37](https://github.com/miraisolutions/xlconnect/issues/37)
+    * specify scope of names when writing and reading names, and more
+    * new option to receive information on the scope in which a name was found
+
 1.0.9 2024-04-17
  * Use com.zaxxer.sparsebits.SparseBitSet instead of java.util.BitSet
  * (#212) fix for loading relative path workbooks under Java 8

R/XLConnectSettings.R

@@ -44,6 +44,8 @@ XLConnectSettings <- function(pdesc) {
 	options(XLConnect.Sheet = "#xlc#")
 	# Rowname column (used by xlcDump, xlcRestore)
 	options(XLConnect.RownameCol = ".rownames")
+
+	options(XLConnect.setCustomAttributes = FALSE)
 
 	invisible()
 }

R/dataframeFromJava.R

@@ -72,9 +72,12 @@ dataframeFromJava <- function(df, check.names) {
       res[[i]] = v
   	}
 
-  	# Apply names
-  	names(res) = columnNames
-
-  	data.frame(res, check.names = check.names, stringsAsFactors = FALSE)
+  	# Preserve attributes
+  	toSet = (attributes(df))[!names(attributes(df)) %in% c("jobj", "jclass", "class", "package")]
+	names(res) = columnNames
+  	result = data.frame(res, check.names = check.names, stringsAsFactors = FALSE)
+	# combine attributes to avoid overwriting names, rownames, colnames
+	attributes(result) <- c(attributes(result), toSet)
+  	result
 	})
 }

R/extractRownames.R

@@ -30,7 +30,10 @@
 extractRownames <- function(x, col) {
   if(is(x, "list")) {
     if(is.null(col)) col = list(NULL)
-    mapply(extractRownames, x, col, SIMPLIFY = FALSE)
+    res <- mapply(extractRownames, x, col, SIMPLIFY = FALSE)
+    attributes(res) <- attributes(x)
+    res
+
   } else{
   	# use attr(x, "row.names") instead of row.names or rownames
   	# since row.names coerces to character for backward compatibility

R/withAttributesFromJava.R

@@ -0,0 +1,43 @@
+#############################################################################
+#
+# XLConnect
+# Copyright (C) 2010-2024 Mirai Solutions GmbH
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+#
+#############################################################################
+
+#############################################################################
+#
+# Utility function for converting XLConnect java objects with added attributes
+# to R variables with the corresponding attributes.
+# Sets the attributes if option XLConnect.setCustomAttributes is TRUE. 
+# Otherwise only unwraps the java object.
+#
+# Author: Simon Poltier, Mirai Solutions GmbH
+#
+#############################################################################
+
+withAttributesFromJava <- function(jobj) {
+
+    unwrapped <- jobj$getValue()
+    allANames = .jcall(jobj, "[S", "getAttributeNames")
+
+    if(getOption("XLConnect.setCustomAttributes")){
+        for(i in seq(along = allANames)) {
+            attr(unwrapped, allANames[i]) <- jobj$getAttributeValue(allANames[i])
+        }
+    }
+    unwrapped
+  }

R/workbook.addImage.R

@@ -26,13 +26,13 @@
 #
 #############################################################################
 
-setGeneric("addImage", 
-	function(object, filename, name, originalSize = FALSE) standardGeneric("addImage"))
+setGeneric("addImage",
+	function(object, filename, name, originalSize = FALSE, worksheetScope = NULL) standardGeneric("addImage"))
 
-setMethod("addImage", 
-		signature(object = "workbook"), 
-		function(object, filename, name, originalSize = FALSE) {
-			xlcCall(object, "addImage", filename, name, originalSize)
+setMethod("addImage",
+		signature(object = "workbook"),
+		function(object, filename, name, originalSize = FALSE, worksheetScope = NULL) {
+			xlcCall(object, "addImage", filename, name, originalSize, worksheetScope %||% .jnull())
 			invisible()
 		}
 )

R/workbook.appendNamedRegion.R

@@ -28,17 +28,17 @@
 
 setGeneric("appendNamedRegion",
 	function(object, data, name, header = FALSE, overwriteFormulaCells = TRUE,
-	         rownames = NULL) standardGeneric("appendNamedRegion"))
+	         rownames = NULL, worksheetScope = NULL) standardGeneric("appendNamedRegion"))
 
 setMethod("appendNamedRegion", 
 	signature(object = "workbook", data = "ANY"), 
 	function(object, data, name, header = FALSE, overwriteFormulaCells = TRUE,
-	         rownames = NULL) {
+	         rownames = NULL, worksheetScope = NULL) {
 		if(is.character(rownames))
 			data <- includeRownames(data, rownames)
 		# pass data.frame's to Java - construct RDataFrameWrapper Java object references
 		data <- lapply(wrapList(data), dataframeToJava)
-		xlcCall(object, "appendNamedRegion", data, name, header, overwriteFormulaCells, .simplify = FALSE)
+		xlcCall(object, "appendNamedRegion", data, name, header, overwriteFormulaCells, worksheetScope %||% .jnull(), .simplify = FALSE)
 		invisible()
 	}
 )

R/workbook.clearNamedRegion.R

@@ -1,38 +1,38 @@
-#############################################################################
-#
-# XLConnect
-# Copyright (C) 2010-2024 Mirai Solutions GmbH
-#
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with this program.  If not, see <https://www.gnu.org/licenses/>.
-#
-#############################################################################
-
-#############################################################################
-#
-# Clearing a named region
-# 
-# Author: Nicola Lambiase, Mirai Solutions GmbH
-#
-#############################################################################
-
-setGeneric("clearNamedRegion",
-		function(object, name) standardGeneric("clearNamedRegion"))
-
-setMethod("clearNamedRegion", 
-		signature(object = "workbook", name = "character"), 
-		function(object, name) {
-			xlcCall(object, "clearNamedRegion", name)
-			invisible()
-		}
-)
+#############################################################################
+#
+# XLConnect
+# Copyright (C) 2010-2024 Mirai Solutions GmbH
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+#
+#############################################################################
+
+#############################################################################
+#
+# Clearing a named region
+# 
+# Author: Nicola Lambiase, Mirai Solutions GmbH
+#
+#############################################################################
+
+setGeneric("clearNamedRegion",
+		function(object, name, worksheetScope = NULL) standardGeneric("clearNamedRegion"))
+
+setMethod("clearNamedRegion", 
+		signature(object = "workbook", name = "character"), 
+		function(object, name, worksheetScope = NULL) {
+			xlcCall(object, "clearNamedRegion", name, worksheetScope %||% .jnull(), .simplify = FALSE)
+			invisible()
+		}
+)

R/workbook.createName.R

@@ -1,38 +1,38 @@
-#############################################################################
-#
-# XLConnect
-# Copyright (C) 2010-2024 Mirai Solutions GmbH
-#
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with this program.  If not, see <https://www.gnu.org/licenses/>.
-#
-#############################################################################
-
-#############################################################################
-#
-# Creating names in a workbook
-# 
-# Author: Martin Studer, Mirai Solutions GmbH
-#
-#############################################################################
-
-setGeneric("createName",
-	function(object, name, formula, overwrite = FALSE) standardGeneric("createName"))
-
-setMethod("createName", 
-		signature(object = "workbook"), 
-		function(object, name, formula, overwrite = FALSE) {
-			xlcCall(object, "createName", name, formula, overwrite)
-			invisible()
-		}
-)
+#############################################################################
+#
+# XLConnect
+# Copyright (C) 2010-2024 Mirai Solutions GmbH
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+#
+#############################################################################
+
+#############################################################################
+#
+# Creating names in a workbook
+# 
+# Author: Martin Studer, Mirai Solutions GmbH
+#
+#############################################################################
+
+setGeneric("createName",
+	function(object, name, formula, overwrite = FALSE, worksheetScope = NULL) standardGeneric("createName"))
+
+setMethod("createName", 
+		signature(object = "workbook"), 
+		function(object, name, formula, overwrite = FALSE, worksheetScope = NULL) {
+			xlcCall(object, "createName", name, formula, overwrite, worksheetScope %||% .jnull())
+			invisible()
+		}
+)

R/workbook.existsName.R

@@ -1,37 +1,37 @@
-#############################################################################
-#
-# XLConnect
-# Copyright (C) 2010-2024 Mirai Solutions GmbH
-#
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with this program.  If not, see <https://www.gnu.org/licenses/>.
-#
-#############################################################################
-
-#############################################################################
-#
-# Checking existence of names in a workbook
-# 
-# Author: Martin Studer, Mirai Solutions GmbH
-#
-#############################################################################
-
-setGeneric("existsName",
-	function(object, name) standardGeneric("existsName"))
-
-setMethod("existsName", 
-		signature(object = "workbook"), 
-		function(object, name) {
-			xlcCall(object, "existsName", name)
-		}
-)
+#############################################################################
+#
+# XLConnect
+# Copyright (C) 2010-2024 Mirai Solutions GmbH
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+#
+#############################################################################
+
+#############################################################################
+#
+# Checking existence of names in a workbook
+# 
+# Author: Martin Studer, Mirai Solutions GmbH
+#
+#############################################################################
+
+setGeneric("existsName",
+	function(object, name, worksheetScope = NULL) standardGeneric("existsName"))
+
+setMethod("existsName", 
+		signature(object = "workbook"), 
+		function(object, name, worksheetScope = NULL) {
+		  xlcCall(object, "existsName", name, worksheetScope %||% .jnull(), .withAttributes = TRUE)
+		}
+)