close #1679: obtain the caption from the chunk option tab.cap for `…

…kable()`

NEWS.md

@@ -1,5 +1,9 @@
 # CHANGES IN knitr VERSION 1.46
 
+## NEW FEATURES
+
+- Added a new chunk option `tab.cap` to specify the table caption for `kable()` (thanks, @ulyngs, #1679). Previously, the caption could only be specified via the `caption` argument of `kable()`. Now you can set it in the chunk header if you want. Please note that this chunk option only works with a single `kable()` in each code chunk, and its value must be of length 1.
+
 ## BUG FIXES
 
 - `write_bib()` generated empty entries for packages without URLs (thanks, @bastistician, #2304).

R/defaults.R

@@ -137,7 +137,7 @@ opts_chunk_attr = local({
   opts$fig.id = 'logical'
   opts[c(
     'opts.label', 'resize.width', 'resize.height', 'fig.alt', 'fig.link', 'fig.sep',
-    'ffmpeg.bitrate', 'ffmpeg.format'
+    'tab.cap', 'ffmpeg.bitrate', 'ffmpeg.format'
   )] = 'character'
   opts$lang = 'list'
   opts$R.options = 'list'

R/table.R

@@ -35,10 +35,11 @@
 #'   are left-aligned. If \code{length(align) == 1L}, the string will be
 #'   expanded to a vector of individual letters, e.g. \code{'clc'} becomes
 #'   \code{c('c', 'l', 'c')}, unless the output format is LaTeX.
-#' @param caption The table caption.
+#' @param caption The table caption. By default, it is retrieved from the chunk
+#'   option \code{tab.cap}.
 #' @param label The table reference label. By default, the label is obtained
-#'   from \code{knitr::\link{opts_current}$get('label')}. To disable the label,
-#'   use \code{label = NA}.
+#'   from \code{knitr::\link{opts_current}$get('label')} (i.e., the current
+#'   chunk label). To disable the label, use \code{label = NA}.
 #' @param format.args A list of arguments to be passed to \code{\link{format}()}
 #'   to format table values, e.g. \code{list(big.mark = ',')}.
 #' @param escape Boolean; whether to escape special characters when producing
@@ -100,7 +101,8 @@
 #' kables(list(kable(d1, align = 'l'), kable(d2)), caption = 'A tale of two tables')
 kable = function(
   x, format, digits = getOption('digits'), row.names = NA, col.names = NA,
-  align, caption = NULL, label = NULL, format.args = list(), escape = TRUE, ...
+  align, caption = opts_current$get('tab.cap'), label = NULL, format.args = list(),
+  escape = TRUE, ...
 ) {
 
   format = kable_format(format)