Add central documentation page for data.table options (#7075)

* add doc page for data.table options

* add script

* add install remote in workflow

* small typo

* restructure script

* restore (bad merge?)

* trailing ws

* terminal newline

* terminal newline

* more potential aliases

* clarification for reading outside interactive sessions

* Move the "See..." reference outside \describe{}

* rm extra '.'

* style change: mention default up-front

* sweep '`' usage

* Update .ci/linters/rd/options_doc_check.R

Co-authored-by: Michael Chirico <[email protected]>

* Update .ci/linters/rd/options_doc_check.R

Co-authored-by: Michael Chirico <[email protected]>

* chng if to else if and _ast to _for_dt_optopns

* remove unnecessary line

* further simplify

* more simplification

* simplify again: remove a helper

* further simplify, unify helper naming

* upd to sggsns

* updt sgns

* consistent naming style

* can't if(grepl(readLines())) b/c it's a vector

* fix naming at call site

* another renaming

* ignore nomatch (deprecated)

* add nm to desc

* one more [base] qualification

* fine-tune allow.cartesian description

---------

Co-authored-by: Michael Chirico <[email protected]>

Author: Mukulyadav2004

.ci/linters/rd/options_doc_check.R

@@ -0,0 +1,51 @@
+# Ensure that data.table options in code match documentation
+options_documentation_linter = function(rd_file) {
+  if (!grepl("\\name{data.table-options}", readChar(rd_file, 100L), fixed = TRUE)) return(invisible())
+
+  # Find options in R code
+  walk_r_ast_for_options = function(expr) {
+    if (is.call(expr) && length(expr) >= 2L && identical(expr[[1L]], quote(getOption)) && is.character(e2 <- expr[[2L]]) && startsWith(e2, "datatable.")) {
+      e2
+    } else if (is.recursive(expr)) {
+      unlist(lapply(expr, walk_r_ast_for_options))
+    }
+  }
+
+  # Find options in documentation
+  walk_rd_ast_for_options = function(rd_element) {
+    if (!is.list(rd_element)) return(character())
+
+    result = character()
+    if (isTRUE(attr(rd_element, "Rd_tag") == "\\code") && length(rd_element) >= 1L) {
+      content = rd_element[[1L]]
+      if (is.character(content) && startsWith(content, "datatable.")) {
+        result = content
+      }
+    }
+    c(result, unlist(lapply(rd_element, walk_rd_ast_for_options)))
+  }
+
+  code_opts = list.files("R", pattern = "\\.R$", full.names = TRUE) |>
+    lapply(\(f) lapply(parse(f), walk_r_ast_for_options)) |>
+    unlist() |>
+    unique() |>
+    setdiff("datatable.nomatch") # ignore deprecated option(s)
+
+  doc_opts = rd_file |>
+    tools::parse_Rd() |>
+    walk_rd_ast_for_options() |>
+    unique()
+
+  miss_in_doc = setdiff(code_opts, doc_opts)
+  miss_in_code = setdiff(doc_opts, code_opts)
+
+  if (length(miss_in_doc) > 0L || length(miss_in_code) > 0L) {
+    if (length(miss_in_doc) > 0L) {
+      cat(sprintf("Options in code but missing from docs: %s\n", toString(miss_in_doc)))
+    }
+    if (length(miss_in_code) > 0L) {
+      cat(sprintf("Options in docs but not in code: %s\n", toString(miss_in_code)))
+    }
+    stop("Please sync man/data.table-options.Rd with code options")
+  }
+}

.github/workflows/code-quality.yaml

@@ -61,3 +61,10 @@ jobs:
       - uses: r-lib/actions/setup-r@v2
       - name: Lint
         run: Rscript .ci/lint.R .ci/linters/md . '[.]R?md$'
+  lint-rd:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: r-lib/actions/setup-r@v2
+      - name: Lint Rd files
+        run: Rscript .ci/lint.R .ci/linters/rd man '[.]Rd$'

DESCRIPTION

@@ -103,5 +103,6 @@ Authors@R: c(
   person("Bill", "Evans",          role="ctb"),
   person("Reino", "Bruner",        role="ctb"),
   person(given="@badasahog",       role="ctb", comment="GitHub user"),
-  person("Vinit", "Thakur",        role="ctb")
+  person("Vinit", "Thakur",        role="ctb"),
+  person("Mukul", "Kumar",         role="ctb")
   )

man/data.table-options.Rd

@@ -0,0 +1,117 @@
+\name{data.table-options}
+\alias{data.table-options}
+\alias{data.table.options}
+\alias{datatable.options}
+\alias{datatable-options}
+
+\title{Global Options for the data.table Package}
+
+\description{
+  The data.table package uses a number of global options to control its
+  behavior. These are regular R options that can be set with options()
+  and retrieved with getOption(). For example:
+  \preformatted{
+    # Get the current value of an option
+    getOption("datatable.print.topn")
+
+    # Set a new value for an option
+    options(datatable.print.topn = 10)
+  }
+  This page provides a comprehensive, up-to-date list of all user-configurable
+  options. NB: If you're reading this on the web, make sure the version numbers match with what you have installed.
+}
+
+\section{Printing Options}{
+  See \code{\link{print.data.table}} for a full description of printing data.tables.
+  \describe{
+   \item{\code{datatable.print.topn}}{An integer, default \code{5L}. When a data.table is printed,
+     only the first topn and last topn rows are displayed.}
+   \item{\code{datatable.print.nrows}}{An integer, default \code{100L}. The total number of rows
+     to print before the topn logic is triggered.}
+   \item{\code{datatable.print.class}}{A logical, default \code{FALSE}. If \code{TRUE}, the class of
+     each column is printed below its name.}
+   \item{\code{datatable.print.keys}}{A logical, default \code{FALSE}. If \code{TRUE}, the table's
+     keys are printed above the data.}
+   \item{\code{datatable.show.indices}}{A logical, default \code{TRUE}. A synonym for \code{datatable.print.keys} for historical reasons.}
+   \item{\code{datatable.print.trunc.cols}}{A logical, default \code{FALSE}. If \code{TRUE} and a
+     table has more columns than fit on the screen, it truncates the middle columns.}
+   \item{\code{datatable.prettyprint.char}}{An integer, default \code{100L}. The maximum number of
+     characters to display in a character column cell before truncating.}
+   \item{\code{datatable.print.colnames}}{A logical, default \code{TRUE}. If \code{TRUE}, prints column names.}
+   \item{\code{datatable.print.rownames}}{A logical, default \code{TRUE}. If \code{TRUE}, prints row numbers.}
+  }
+}
+
+\section{File I/O Options (fread and fwrite)}{
+  See \code{\link{fread}} and \code{\link{fwrite}} for a full description of data.table I/O.
+  \describe{
+    \item{\code{datatable.fread.input.cmd.message}}{A logical, default \code{TRUE}. If \code{TRUE},
+      \code{fread} will print the shell command it is using when the input is a
+      command (e.g., \code{fread("grep ...")}).}
+    \item{\code{datatable.fread.datatable}}{A logical, default \code{TRUE}. If \code{TRUE}, \code{fread}
+      returns a \code{data.table}. If \code{FALSE}, it returns a \code{data.frame}.}
+    \item{\code{datatable.integer64}}{A character string, default \code{"integer64"}. Controls how \code{fread}
+      handles 64-bit integers. Can be "integer64", "double", or "character".}
+    \item{\code{datatable.logical01}}{A logical, default \code{FALSE}. If \code{TRUE}, \code{fread} will
+      interpret columns containing only 0 and 1 as logical.}
+    \item{\code{datatable.keepLeadingZeros}}{A logical, default \code{FALSE}. If \code{TRUE}, \code{fread}
+      preserves leading zeros in character columns by reading them as strings;
+      otherwise they may be coerced to numeric.}
+    \item{\code{datatable.logicalYN}}{A logical, default \code{FALSE}. If \code{TRUE}, \code{fread}
+      will interpret "Y" and "N" as logical.}
+    \item{\code{datatable.na.strings}}{A character vector, default \code{"NA"}. Global default for strings that
+      \code{fread} should interpret as \code{NA}.}
+    \item{\code{datatable.fwrite.sep}}{A character string, default \code{","}. The default separator
+      used by \code{fwrite}.}
+    \item{\code{datatable.showProgress}}{An integer or logical, default \code{\link[base]{interactive}()}. Controls whether
+      long-running operations like \code{fread} display a progress bar.}
+  }
+}
+
+\section{Join and Subset Options}{
+  \describe{
+    \item{\code{datatable.allow.cartesian}}{A logical, default \code{FALSE}. Controls the default value of the 
+    \code{allow.cartesian} parameter; see \code{\link{data.table}}. If the value of this parameter is FALSE, an error is raised as a safeguard against an explosive Cartesian join.}
+  }
+}
+
+\section{Performance and Indexing Options}{
+  \describe{
+    \item{\code{datatable.auto.index}}{A logical, default \code{TRUE}. If \code{TRUE}, \code{data.table}
+      automatically creates a secondary index on-the-fly when a column is first
+      used in a subset, speeding up all subsequent queries.}
+    \item{\code{datatable.use.index}}{A logical, default \code{TRUE}. A global switch to control
+      whether existing secondary indices are used for subsetting.}
+    \item{\code{datatable.forder.auto.index}}{A logical, default \code{TRUE}. Similar to \code{datatable.auto.index},
+      but applies to ordering operations (\code{forder}).}
+    \item{\code{datatable.optimize}}{A numeric, default \code{Inf}. Controls the GForce query
+      optimization engine. The default enables all possible optimizations.
+      See \code{\link{datatable.optimize}}.}
+    \item{\code{datatable.alloccol}}{An integer, default \code{1024L}. Controls the number of column
+      slots to pre-allocate, improving performance when adding many columns.
+      See \code{\link{alloc.col}}.}
+    \item{\code{datatable.reuse.sorting}}{A logical, default \code{TRUE}. If \code{TRUE}, \code{data.table}
+      can reuse the sorted order of a table in joins, improving performance.}
+  }
+}
+
+\section{Development and Verbosity Options}{
+  \describe{
+    \item{\code{datatable.quiet}}{A logical, default \code{FALSE}. The master switch to suppress all
+      \code{data.table} status messages, including the startup message.}
+    \item{\code{datatable.verbose}}{A logical, default \code{FALSE}. If \code{TRUE}, \code{data.table} will
+      print detailed diagnostic information as it processes a query.}
+    \item{\code{datatable.enlist}}{Experimental feature. Default is \code{NULL}. If set to a function
+      (e.g., \code{list}), the \code{j} expression can return a \code{list}, which will then
+      be "enlisted" into columns in the result.}
+  }
+}
+
+\seealso{
+  \code{\link[base]{options}},
+  \code{\link[base]{getOption}},
+  \code{\link{data.table}}
+}
+
+\keyword{data}
+\keyword{utilities}

src/assign.c

@@ -277,10 +277,10 @@ int checkOverAlloc(SEXP x)
   if (!isInteger(x) && !isReal(x))
     error(_("getOption('datatable.alloccol') should be a number, by default 1024. But its type is '%s'."), type2char(TYPEOF(x)));
   if (LENGTH(x) != 1)
-    error(_("getOption('datatable.alloc') is a numeric vector ok but its length is %d. Its length should be 1."), LENGTH(x));
+    error(_("getOption('datatable.alloccol') is a numeric vector ok but its length is %d. Its length should be 1."), LENGTH(x));
   int ans = asInteger(x);
   if (ans<0)
-    error(_("getOption('datatable.alloc')==%d.  It must be >=0 and not NA."), ans);
+    error(_("getOption('datatable.alloccol')==%d.  It must be >=0 and not NA."), ans);
   return ans;
 }