Export pkg_file_lua for package author to use (#1904)

Author: cderv

NAMESPACE

@@ -73,6 +73,7 @@ export(pandoc_variable_arg)
 export(pandoc_version)
 export(parse_html_notebook)
 export(pdf_document)
+export(pkg_file_lua)
 export(powerpoint_presentation)
 export(publish_site)
 export(relative_to)

NEWS.md

@@ -5,6 +5,9 @@ rmarkdown 2.4
     - New exported function `pandoc_lua_filter_args()` to return the Pandoc command-line argument to add a Lua filter.
     - New argument `lua_filters` in `pandoc_options()` to pass the Lua filter paths to use with a format. This allow output format authors to add filters for a custom format using the `pandoc` argument of `output_format()` and to get filters from a format using `fmt$pandoc$lua_filters`.
     - The Lua filters of an output format are now passed to Pandoc in `render()`. By default, they are passed to Pandoc before any other format-defined or user-defined Pandoc arguments (usually via the `pandoc_args` option of an output format). This ensures that filters of an output format are executed first. To change the default, you need to deal with it in a custom format (i.e., modify the elements in `fmt$pandoc$lua_filters`, such as reordering them).
+    - New exported function `pkg_file_lua()` to get the full system path of a
+    Lua filter included in a package source within `inst/rmarkdown/lua` folder.
+    (thanks, @atusy, #1903)
 
 - Fixed the path separators for the `css` parameter in YAML frontmatter for HTML output files under Windows. Previously, forward slashes in `css` paths were converted to backslashes (thanks, @jonathan-g, #1862).
 

R/context_document.R

@@ -132,7 +132,8 @@ context_document <- function(toc = FALSE,
       args = args,
       keep_tex = FALSE,
       ext = ext,
-      lua_filters = pkg_file_lua("pagebreak.lua")),
+      lua_filters = pkg_file_lua("pagebreak.lua")
+    ),
     clean_supporting = !isTRUE(keep_tex),
     keep_md = keep_md,
     df_print = df_print,

R/html_document_base.R

@@ -169,7 +169,8 @@ html_document_base <- function(theme = NULL,
     knitr = NULL,
     pandoc = pandoc_options(
       to = "html", from = NULL, args = args,
-      lua_filters = pkg_file_lua(c("pagebreak.lua", "latex-div.lua"))),
+      lua_filters = pkg_file_lua(c("pagebreak.lua", "latex-div.lua"))
+    ),
     keep_md = FALSE,
     clean_supporting = FALSE,
     pre_knit = pre_knit,

R/md_document.R

@@ -81,7 +81,8 @@ md_document <- function(variant = "markdown_strict",
       from = from_rmarkdown(extensions = md_extensions),
       args = args,
       ext = ext,
-      lua_filters = if (number_sections) pkg_file_lua("number-sections.lua")),
+      lua_filters = if (number_sections) pkg_file_lua("number-sections.lua")
+    ),
     clean_supporting = FALSE,
     df_print = df_print,
     post_processor = post_processor

R/odt_document.R

@@ -83,8 +83,9 @@ odt_document <- function(number_sections = FALSE,
       to = "odt",
       from = from_rmarkdown(fig_caption, md_extensions),
       args = args,
-      lua_filters = pkg_file_lua(c(
-        "pagebreak.lua", if (number_sections) "number-sections.lua"))),
+      lua_filters = pkg_file_lua(
+        c("pagebreak.lua", if (number_sections) "number-sections.lua"))
+    ),
     keep_md = keep_md,
     pre_processor = pre_processor,
     intermediates_generator = intermediates_generator

R/pdf_document.R

@@ -199,7 +199,8 @@ pdf_document <- function(toc = FALSE,
       args = args,
       latex_engine = latex_engine,
       keep_tex = keep_tex,
-      lua_filters = pkg_file_lua(c("pagebreak.lua", "latex-div.lua"))),
+      lua_filters = pkg_file_lua(c("pagebreak.lua", "latex-div.lua"))
+    ),
     clean_supporting = !keep_tex,
     keep_md = keep_md,
     df_print = df_print,

R/rtf_document.R

@@ -77,7 +77,8 @@ rtf_document <- function(toc = FALSE,
       to = "rtf",
       from = from_rmarkdown(extensions = md_extensions),
       args = args,
-      lua_filters = if (number_sections) pkg_file_lua("number-sections.lua")),
+      lua_filters = if (number_sections) pkg_file_lua("number-sections.lua")
+    ),
     keep_md = keep_md,
     pre_processor = pre_processor,
     post_processor = post_processor

R/util.R

@@ -33,16 +33,46 @@ pandoc_output_ext <- function(ext, to, input) {
   paste0(".", to)
 }
 
-pkg_file <- function(...) {
-  system.file(..., package = "rmarkdown")
-}
-
-pkg_file_arg <- function(...) {
-  pandoc_path_arg(pkg_file(...))
-}
-
-pkg_file_lua <- function(...) {
-  pkg_file("rmd", "lua", ...)
+pkg_file <- function(..., package = "rmarkdown") {
+  system.file(..., package = package)
+}
+
+pkg_file_arg <- function(..., package = "rmarkdown") {
+  pandoc_path_arg(pkg_file(..., package = package))
+}
+
+#' Get Lua filters full paths in a package
+#'
+#' Lua filters stored in a source package in \code{inst/rmarkdown/lua} will installed in
+#' \code{rmarkdown/lua} in the package path. This function finds the full path of the
+#' Lua filters on the system for installed packages.
+#'
+#'
+#' @param filters Character vector of filename for the Lua filter to retrieve in
+#'   \code{rmarkdown/lua} folder of the package. By default, if none is
+#'   provided, it returns the folder path.
+#' @param package Package name in which to look for the filters. It is set to
+#'   \code{rmarkdown} by default
+#' @return Character vector of absolute file paths for the Lua filter from the
+#'   package. If a filter is not found, it does not error. The returned path
+#'   will already be escaped correctly using \code{\link{pandoc_path_arg}} to be
+#'   used by Pandoc.
+#' @export
+#' @examples
+#' # List all Lua filters stored in the rmarkdown package
+#' pkg_file_lua()
+#' # or in a specific package
+#' pkg_file_lua(package = "bookdown")
+#' # get a specific filter
+#' pkg_file_lua(c("pagebreak.lua", "latex_div.lua"), package = "rmarkdown")
+#' # do not error if not found but return an empty path
+#' pkg_file_lua("donotexist.lua", package = "rmarkdown")
+pkg_file_lua <- function(filters = NULL, package = "rmarkdown") {
+  if (is.null(package) || length(package) > 1)
+    stop("One package name in which to look for Lua filters must be provided.", call. = FALSE)
+  lua_folder <- pkg_file("rmarkdown", "lua", package = package)
+  if (is.null(filters)) filters <- list.files(lua_folder, "[.]lua$")
+  pandoc_path_arg(file.path(lua_folder, filters))
 }
 
 #' @rdname rmarkdown_format