Title: Excerpt Structuring Comments from Your Code File and Set a Table of Contents
Version: 2.1.0
Description: Ever read or wrote source files containing sectioning comments? If these comments are markdown style section comments, you can excerpt them and set a table of contents using the 'python' package 'excerpts' (https://pypi.org/project/excerpts/).
URL: https://gitlab.com/fvafrcu/excerptr
Depends: R (≥ 3.3.0)
Imports: checkmate, reticulate
License: BSD_2_clause + file LICENSE
SystemRequirements: Python (>= 3.0.0)
Encoding: UTF-8
RoxygenNote: 7.3.3
Suggests: testthat, knitr, rmarkdown, devtools, RUnit, pkgload, fritools, rprojroot
VignetteBuilder: knitr
NeedsCompilation: no
Packaged: 2025-10-22 15:35:42 UTC; qwer
Author: Andreas Dominik Cullmann [aut, cre]
Maintainer: Andreas Dominik Cullmann <fvafrcu@mailbox.org>
Repository: CRAN
Date/Publication: 2025-10-26 20:30:02 UTC

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

Description

This is just an R interface to the python package excerpts (https://pypi.org/project/excerpts/).

Author(s)

Maintainer: Andreas Dominik Cullmann fvafrcu@mailbox.org

See Also

Useful links:

Excerpt Structuring Comments and Set a Table of Contents.

Description

Just a wrapper to the python function excerpts.excerpts. See https://pypi.org/project/excerpts/ for details.

Usage

excerptr(
  file_name,
  comment_character = "#",
  magic_character = "%",
  output_path = "",
  allow_pep8 = TRUE,
  prefix = "",
  postfix = "",
  run_pandoc = TRUE,
  compile_latex = FALSE,
  pandoc_formats = "tex"
)

Arguments

file_name

Name the file from which to excerpt.

comment_character

Should be "#" for R.

magic_character

The magic character marking the structuring comments in file_name.

output_path

Name the path where to output to.

allow_pep8

Don't bother. See excerpts.excerpts for details.

prefix

Give a prefix to use for output files.

postfix

Give a postfix to use for output files.

run_pandoc

Try to run pandoc on the output?

compile_latex

Try to compile LaTeX if pandoc has output LaTeX?

pandoc_formats

A character vector naming the output formats for pandoc.

Value

The status of excerpts.excerpts.

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")
}

Throw a Condition

Description

Throws a condition of class c("error", "excerptr", "condition").

Usage

throw(message_string, system_call = sys.call(-1), ...)

Arguments

message_string

The message to be thrown.

system_call

The call to be thrown.

...

Arguments to be passed to base::structure.

Details

We use this condition as an error dedicated to excerptr.

Value

The function does never return anything, it stops with a condition of class c("error", "excerptr", "condition").