[experimental] standardize function arguments (#678)

* add standardize_case-names()

* more wb_to_df() to snake_case

* * wb_load

* wb_add_chart_xml
* wb_add_drawing
* wb_add_mschart
* wb_add_image
* wb_add_plot

deprecate start_col/start_row make dims the first arg after sheet

* * wb_workbook
* wb_add_comment
* wb_remove_comment

deprecate col, row, gridExpand

* * wb_add_named_region

* * wb_add_cell_style

* fix and reduce examples

* * add standardize()
* wb_add_chartsheet

* * wb_add_font
* wb_add_data_validation

* * wb_add_dxfs_style
* create_dxfs_style

* * wb_add_data
* wb_add_data_table
* wb_add_formula

Reodering arguments so that `x` is after `dims` sadly caused to much fallout in our own tests

* * write_xlsx
* write_data
* write_data_table
* write_formula

* * wb_add_worksheet

* * wb_add_ignore_error

* * fix worksheets

* * wb_set_base_font

* * wb_set_bookview

* * wb_set_header_footer

* * wb_set_sheetview

* * create_border

* * create_border
* create_cell_style
* create_tablestyle

* update NEWS

* make functions and classes internal

NAMESPACE

@@ -30,9 +30,6 @@ export(delete_data)
 export(dims_to_dataframe)
 export(dims_to_rowcol)
 export(fmt_txt)
-export(get_cell_refs)
-export(get_date_origin)
-export(guess_col_type)
 export(int2col)
 export(na_strings)
 export(next_sheet)
@@ -41,15 +38,10 @@ export(read_xlsx)
 export(read_xml)
 export(remove_comment)
 export(rowcol_to_dims)
-export(style_mgr)
 export(styles_on_sheet)
 export(temp_xlsx)
 export(wbChartSheet)
-export(wbComment)
-export(wbHyperlink)
-export(wbSheetData)
 export(wbWorkbook)
-export(wbWorksheet)
 export(wb_add_border)
 export(wb_add_cell_style)
 export(wb_add_chart_xml)
@@ -130,7 +122,6 @@ export(wb_set_selected)
 export(wb_set_sheet_names)
 export(wb_set_sheet_visibility)
 export(wb_set_sheetview)
-export(wb_sheet_data)
 export(wb_to_df)
 export(wb_ungroup_cols)
 export(wb_ungroup_rows)
@@ -141,7 +132,6 @@ export(wb_ws)
 export(write_comment)
 export(write_data)
 export(write_datatable)
-export(write_file)
 export(write_formula)
 export(write_xlsx)
 export(xl_open)

NEWS.md

@@ -1,18 +1,27 @@
 # openxlsx2 (development version)
 
+## New features
+
+* Function arguments are now defaulting to `snake_case`. For the time being, both arguments are accepted and `camelCase` will be switched to `snake_case` under the hood. Documentation like vignettes and examples are currently still displaying `camelCase` and maybe some `camelCase` function slipped through. [678](https://github.com/JanMarvin/openxlsx2/pull/678)
+
 ## Breaking changes
 
 * Order of arguments in `wb_add_named_region()` changed, because previously overlooked `dims` argument was added.
+* In various functions the order of `dims` was changed, to highlight it's importance
 
 * Cleanups
  * remove deprecated functions
 
  * remove deprecated arguments
  * `xy` argument
+ * arguments `col`, `row`, `cols`, `rows`. `start_col`, `start_row` and `gridExpand` were deprecated in favor of `dims`. Numeric vectors can be converted to `dims` using `rowcol_to_dims()`
 
  * deprecating function
  * `convertToExcelDate()` for `convert_to_excel_date()`
-
+
+ * make `get_cell_refs()`, `get_date_origin()`, `guess_col_type()`, and `write_file()` internal functions
+ * make classes `styles_mgr()`, `wbSheetData`, `wbWorksheet`, `wbChartsheet`, `wbComment`, `wbHyperlink` internal
+
 ***************************************************************************
 
 

R/class-chart-sheet.R

@@ -101,48 +101,49 @@ wbChartSheet <- R6::R6Class(
 
 
  #' @description add sheetview
- #' @param colorId colorId
- #' @param defaultGridColor defaultGridColor
- #' @param rightToLeft rightToLeft
- #' @param showFormulas showFormulas
- #' @param showGridLines showGridLines
- #' @param showOutlineSymbols showOutlineSymbols
- #' @param showRowColHeaders showRowColHeaders
- #' @param showRuler showRuler
- #' @param showWhiteSpace showWhiteSpace
- #' @param showZeros showZeros
- #' @param tabSelected tabSelected
- #' @param topLeftCell topLeftCell
- #' @param view view
- #' @param windowProtection windowProtection
- #' @param workbookViewId workbookViewId
- #' @param zoomScale zoomScale
- #' @param zoomScaleNormal zoomScaleNormal
- #' @param zoomScalePageLayoutView zoomScalePageLayoutView
- #' @param zoomScaleSheetLayoutView zoomScaleSheetLayoutView
+ #' @param sheet sheet
+ #' @param color_id,default_grid_color Integer: A color, default is 64
+ #' @param right_to_left Logical: if TRUE column ordering is right to left
+ #' @param show_formulas Logical: if TRUE cell formulas are shown
+ #' @param show_grid_lines Logical: if TRUE the worksheet grid is shown
+ #' @param show_outline_symbols Logical: if TRUE outline symbols are shown
+ #' @param show_row_col_headers Logical: if TRUE row and column headers are shown
+ #' @param show_ruler Logical: if TRUE a ruler is shown in page layout view
+ #' @param show_white_space Logical: if TRUE margins are shown in page layout view
+ #' @param show_zeros Logical: if FALSE cells containing zero are shown blank if !showFormulas
+ #' @param tab_selected Integer: zero vector indicating the selected tab
+ #' @param top_left_cell Cell: the cell shown in the top left corner / or top right with rightToLeft
+ #' @param view View: "normal", "pageBreakPreview" or "pageLayout"
+ #' @param window_protection Logical: if TRUE the panes are protected
+ #' @param workbook_view_id integer: Pointing to some other view inside the workbook
+ #' @param zoom_scale,zoom_scale_normal,zoom_scale_page_layout_view,zoom_scale_sheet_layout_view Integer: the zoom scale should be between 10 and 400. These are values for current, normal etc.
+ #' @param ... additional arguments
  #' @return The `wbWorksheetObject`, invisibly
  set_sheetview = function(
- colorId = NULL,
- defaultGridColor = NULL,
- rightToLeft = NULL,
- showFormulas = NULL,
- showGridLines = NULL,
- showOutlineSymbols = NULL,
- showRowColHeaders = NULL,
- showRuler = NULL,
- showWhiteSpace = NULL,
- showZeros = NULL,
- tabSelected = NULL,
- topLeftCell = NULL,
- view = NULL,
- windowProtection = NULL,
- workbookViewId = NULL,
- zoomScale = NULL,
- zoomScaleNormal = NULL,
- zoomScalePageLayoutView = NULL,
- zoomScaleSheetLayoutView = NULL
+ color_id = NULL,
+ default_grid_color = NULL,
+ right_to_left = NULL,
+ show_formulas = NULL,
+ show_grid_lines = NULL,
+ show_outline_symbols = NULL,
+ show_row_col_headers = NULL,
+ show_ruler = NULL,
+ show_white_space = NULL,
+ show_zeros = NULL,
+ tab_selected = NULL,
+ top_left_cell = NULL,
+ view = NULL,
+ window_protection = NULL,
+ workbook_view_id = NULL,
+ zoom_scale = NULL,
+ zoom_scale_normal = NULL,
+ zoom_scale_page_layout_view = NULL,
+ zoom_scale_sheet_layout_view = NULL,
+ ...
  ) {
 
+ standardize(...)
+
  # all zoom scales must be in the range of 10 - 400
 
  # get existing sheetView
@@ -154,27 +155,27 @@ wbChartSheet <- R6::R6Class(
  sheetView <- xml_attr_mod(
  sheetView,
  xml_attributes = c(
- # order according to Ecma Office Open XML Part 1. p3929
- windowProtection = as_xml_attr(windowProtection),
- showFormulas = as_xml_attr(showFormulas),
- showGridLines = as_xml_attr(showGridLines),
- showZeros = as_xml_attr(showZeros),
- rightToLeft = as_xml_attr(rightToLeft),
- tabSelected = as_xml_attr(tabSelected),
- showRuler = as_xml_attr(showRuler),
- showOutlineSymbols = as_xml_attr(showOutlineSymbols),
- defaultGridColor = as_xml_attr(defaultGridColor),
- showWhiteSpace = as_xml_attr(showWhiteSpace),
+ colorId = as_xml_attr(color_id),
+ defaultGridColor = as_xml_attr(default_grid_color),
+ rightToLeft = as_xml_attr(right_to_left),
+ showFormulas = as_xml_attr(show_formulas),
+ showGridLines = as_xml_attr(show_grid_lines),
+ showOutlineSymbols = as_xml_attr(show_outline_symbols),
+ showRowColHeaders = as_xml_attr(show_row_col_headers),
+ showRuler = as_xml_attr(show_ruler),
+ showWhiteSpace = as_xml_attr(show_white_space),
+ showZeros = as_xml_attr(show_zeros),
+ tabSelected = as_xml_attr(tab_selected),
+ topLeftCell = as_xml_attr(top_left_cell),
  view = as_xml_attr(view),
- topLeftCell = as_xml_attr(topLeftCell),
- colorId = as_xml_attr(colorId),
- zoomScale = as_xml_attr(zoomScale),
- showRowColHeaders = as_xml_attr(showRowColHeaders),
- zoomScaleNormal = as_xml_attr(zoomScaleNormal),
- zoomScalePageLayoutView = as_xml_attr(zoomScalePageLayoutView),
- zoomScaleSheetLayoutView = as_xml_attr(zoomScaleSheetLayoutView),
- workbookViewId = as_xml_attr(workbookViewId)
- )
+ windowProtection = as_xml_attr(window_protection),
+ workbookViewId = as_xml_attr(workbook_view_id),
+ zoomScale = as_xml_attr(zoom_scale),
+ zoomScaleNormal = as_xml_attr(zoom_scale_normal),
+ zoomScalePageLayoutView = as_xml_attr(zoom_scale_page_layout_view),
+ zoomScaleSheetLayoutView = as_xml_attr(zoom_scale_sheet_layout_view)
+ ),
+ remove_empty_attr = FALSE
  )
 
  self$sheetViews <- xml_node_create(

R/class-color.R

@@ -43,27 +43,3 @@ wb_color <- function(
 wb_colour <- wb_color
 
 is_wbColour <- function(x) inherits(x, "wbColour")
-
-#' takes colour and returns color
-#' @param ... ...
-#' @returns void. assigns an object in the parent frame
-#' @keywords internal
-#' @noRd
-standardize_color_names <- function(...) {
-
- # since R 4.1.0: ...names()
- args <- list(...)
- got <- names(args)
- # can be Color or color
- got_color <- which(grepl("colour", tolower(got)))
-
- if (length(got_color)) {
- for (got_col in got_color) {
- color <- got[got_col]
- name_color <- stringi::stri_replace_all_fixed(color, "olour", "olor", )
- # since R 3.5.0: ...elt(got_col)
- value_color <- args[[got_col]]
- assign(name_color, value_color, parent.frame())
- }
- }
-}

R/class-comment.R

@@ -2,7 +2,8 @@
 #'
 #' A comment
 #'
-#' @export
+#' @keywords internal
+#' @noRd
 wbComment <- R6::R6Class(
  "wbComment",
 
@@ -179,6 +180,7 @@ create_comment <- function(text,
 #' @param comment A Comment object. See [create_comment()].
 #' @param dims worksheet cell "A1"
 #' @rdname comment
+#' @keywords internal
 #' @export
 write_comment <- function(
  wb,
@@ -339,6 +341,7 @@ write_comment <- function(
 #' @param gridExpand If `TRUE`, all data in rectangle min(rows):max(rows) X min(cols):max(cols)
 #' will be removed.
 #' @rdname comment
+#' @keywords internal
 #' @export
 remove_comment <- function(
  wb,
@@ -378,7 +381,9 @@ remove_comment <- function(
 
  toKeep <- !sapply(wb$comments[[sheet]], "[[", "ref") %in% comb
 
+ # FIXME: if all comments are removed we should drop to wb$comments <- list()
  wb$comments[[sheet]] <- wb$comments[[sheet]][toKeep]
+
 }
 
 wb_comment <- function(text = character(), author = character(), style = character()) {

R/class-hyperlink.R

@@ -2,7 +2,8 @@
 #'
 #' A hyperlink
 #'
-#' @export
+#' @keywords internal
+#' @noRd
 wbHyperlink <- R6::R6Class(
  "wbHyperlink",
 

R/class-sheet-data.R

@@ -3,7 +3,8 @@
 #'
 #' A hyperlink
 #'
-#' @export
+#' @keywords internal
+#' @noRd
 wbSheetData <- R6::R6Class(
  "wbSheetData",
  public = list(
@@ -27,8 +28,10 @@ wbSheetData <- R6::R6Class(
  )
 )
 
+## TODO is this even used?
 #' @rdname wbSheetData
-#' @export
+#' @keywords internal
+#' @noRd
 wb_sheet_data <- function() {
  wbSheetData$new()
 }

R/class-style_mgr.R

@@ -65,7 +65,8 @@
 #' wb$set_cell_style("SUM", "C7:C16", wb$styles_mgr$get_xf_id("new_xf"))
 #' # wb_open(wb)
 #'
-#' @export
+#' @keywords internal
+#' @noRd
 style_mgr <- R6::R6Class("wbStylesMgr", {
 
  public <- list(
@@ -603,7 +604,6 @@ style_mgr <- R6::R6Class("wbStylesMgr", {
  #' "Title"
  #' "Total"
  #' "Warning Text"
- #' @export
  init_named_style = function(name, font_name = "Arial", font_size = 11) {
 
  # we probably should only have unique named styles. check if style is found.
@@ -973,7 +973,7 @@ style_mgr <- R6::R6Class("wbStylesMgr", {
  border_id <- self$get_border_id(border_xml)
  }
 
- cell_style_xml <- create_cell_style(numFmtId = numFmtId, fontId = font_id, fillId = fill_id, borderId = border_id, is_cell_style_xf = TRUE)
+ cell_style_xml <- create_cell_style(num_fmt_id = numFmtId, font_id = font_id, fill_id = fill_id, border_id = border_id, is_cell_style_xf = TRUE)
  attr(cell_style_xml, "cellStyleXf") <- TRUE
  self$add(cell_style_xml, name)
  xf_fr_id <- self$get_cellStyleXf_id(name)