R/excerptr.R

In excerptr: Excerpt Structuring Comments from Your Code File and Set a Table of Contents

#' Excerpt Structuring Comments and Set a Table of Contents.
#'
#' Just a wrapper to the python function \command{excerpts.excerpts}.
#' See \url{https://pypi.org/project/excerpts/} for details.
#'
#' @param file_name Name the file from which to excerpt.
#' @param comment_character Should be "#" for R.
#' @param magic_character The magic character marking the structuring comments
#' in \code{file_name}.
#' @param output_path Name the path where to output to.
#' @param allow_pep8 Don't bother. See \command{excerpts.excerpts} for details.
#' @param prefix Give a prefix to use for output files.
#' @param postfix Give a postfix to use for output files.
#' @param run_pandoc Try to run \command{pandoc} on the output?
#' @param compile_latex Try to compile LaTeX if \command{pandoc} has output
#' LaTeX?
#' @param pandoc_formats A character vector naming the output formats for
#' \command{pandoc}.
#' @return The status of \command{excerpts.excerpts}.
#' @export
#' @examples
#' if (reticulate::py_available(initialize = TRUE)) {
#'     root <- system.file(package = "excerptr")
#'     test_files <- file.path(root, "excerpts", "tests", "files")
#'     outpath <- tempdir()
#'     python_source <- "some_code.py"
#'     f <- normalizePath(file.path(test_files, python_source))
#'     cat(readLines(f), sep = "\n")
#'     tryCatch(
#'              excerptr(file_name = file.path(test_files, python_source),
#'                       output_path = tempdir(), run_pandoc = FALSE,
#'                       compile_latex = FALSE,
#'                       pandoc_formats = c("tex", "html")),
#'              error = identity)
#'     f <- file.path(outpath, sub("\\.py$", ".md", python_source))
#'     if (!fritools::is_cran()) cat(readLines(f), sep = "\n")
#' }
excerptr <- function(file_name, comment_character = "#", magic_character = "%",
             output_path = "", allow_pep8 = TRUE,
             prefix = "", postfix = "", run_pandoc = TRUE,
             compile_latex = FALSE, pandoc_formats = "tex") {
    checkmate::qassert(file_name, "S1")
    checkmate::qassert(comment_character, "S1")
    checkmate::qassert(magic_character, "S1")
    checkmate::qassert(output_path, "S1")
    checkmate::qassert(allow_pep8, "B1")
    checkmate::qassert(prefix, "S1")
    checkmate::qassert(postfix, "S1")
    checkmate::qassert(run_pandoc, "B1")
    checkmate::qassert(compile_latex, "B1")
    checkmate::qassert(pandoc_formats, "S+")
    if (!reticulate::py_module_available("excerpts"))
        reticulate::py_require("excerpts")
    excerpts <- reticulate::import("excerpts")
    status <- excerpts[["excerpts"]](file_name = file_name,
                                        comment_character = comment_character,
                                        magic_character = magic_character,
                                        output_path = output_path,
                                        allow_pep8 = allow_pep8,
                                        prefix = prefix, postfix = postfix,
                                        run_pandoc = run_pandoc,
                                        compile_latex = compile_latex,
                                        pandoc_formats =
                                            as.list(pandoc_formats))
    return(status)
}