Package 'chunkhooks'

Benchmark chunks

Description

hook_benchmark sets a hook to benchmark chunks with the benchmark=TRUE option. The name of the trigger chunk option can be changed via the chunk_option parameter. The result is printed right after chunk outputs. See examples for the default printing format by format_benchmark.

Usage

hook_benchmark(
  trigger = "benchmark",
  default = NULL,
  format = format_benchmark,
  .set = TRUE
)

format_benchmark(result, options)

benchmarks

Arguments

trigger	A name of chunk option that triggers benchmark (default: "benchmark"). In order to trigger benchmark, specify TRUE as a value of this option.
default	A default value for the chunk option that triggers the hook (default: NULL).
format	A function to format a benchmark result (default: format_benchmark). It must accept two arguments, where the first is the benchmark result and the second is the list of current chunk options. NULL suppresses printing.
.set	TRUE or FALSE to set the hook.
result	A result of benchmark
options	A list of current chunk options

Format

An object of class environment of length 0.

Details

benchmarks records the results of benchmarks from chunks as a list named by chunk labels. If one requires complex formatting of benchmark results, then suppress automatic formatting by hook_benchmark(format = NULL). Then, retrieve benchmark results from benchmarks[["chunk-label"]]. Furthermore, format can happen conditionally by utilizing current chunk options via the second argument of the formatting function.

Value

invisible hook function

Examples

# Set a hook that triggers benchmarks if the `time` chunk option is not `NULL`.
hook_benchmark("time")

# Example of the default output format
# Input is sec. Output is prettified.
format_benchmark(1234, options = list(label = "example-chunk"))

---

Comment out codes based on their languages.

Description

Comment out codes based on their languages.

Usage

comment_out(x, engine, extra_syntax = character(0L))

Arguments

x	A character vector
engine	A string that defines the engine of the x. See names(comment_syntax) for the predefined engines.
extra_syntax	A named character vector which defines extra syntax to comment out. Each values should contain ⁠%s⁠ which is the placeholder to insert x. If definitions collides among comment_syntax and extra_syntax, then the latter has priority.

See Also

comment_syntax()

Examples

# Default behaviors
comment_out("R language", "R")
comment_out("Python language", "python")

# A customized behavior
comment_out(
  "Python language",
  "python",
  extra_syntax = c("python" = '"""%s"""')
)

---

Comment syntax.

Description

A named vector which defines comment syntax. This is internally used by hook_title_comment(), comment_title(), and comment_out().

Usage

comment_syntax

Format

An object of class character of length 38.

---

Comment title to chunk code

Description

Comment title to chunk code

Usage

comment_title(
  options = list(engine = "R"),
  template = "{engine}",
  extra_syntax = character(0L),
  ...
)

Arguments

options	A list of chunk options.
template	A template of title processed by glue::glue(). The processed value is automatically commented out by comment_out().
extra_syntax	A named character vector which defines extra syntax to comment out. Each values should contain ⁠%s⁠ which is the placeholder to insert x. If definitions collides among comment_syntax and extra_syntax, then the latter has priority.
...	Arguments passed to glue::glue()

See Also

comment_out()

Examples

comment_title(
  options = list(engine = "R"),
  template = "{engine}"
)

comment_title(
  options = list(engine = "css", label = "mystyle"),
  template = "{label}.{engine}"
)

---

Change the unit of figure size

Description

By default, figure size of R Markdown is specified with inches. This function changes the default unit.

Usage

hook_figure_unit(unit = "mm", .set = TRUE)

Arguments

unit	A string of an unit (default: "mm"). Available units follow. measurements::conv_unit_options$length
.set	TRUE or FALSE to set the hook.

Details

As a side effect, fig.retina is set to NULL because of https://github.com/yihui/knitr/issues/1876.

Value

invisible hook function

Examples

hook_figure_unit('mm')

---

Number lines on code blocks

Description

Number lines on code blocks created by chunks, i.e. source, output, message, warning, and/or error.

Usage

hook_numberLines(targets = "source", .set = TRUE)

Arguments

targets	A character vector specifying what kind of code blocks automatically number lines (default: "source"). Choices are "source", "output", "message", "warning", and/or "error".⁠⁠NULL' disables the automation.
.set	TRUE or FALSE to set the hook.

Value

invisible hook function

Examples

hook_numberLines("source")

---

Prepend title comment to chunks

Description

Prepend title comments to each chunks. By default, title is the name of the corresponding chunk engines.

Usage

hook_title_comment(
  trigger = "title",
  default = "{engine}",
  args = list(),
  .set = TRUE
)

Arguments

trigger	A name of chunk option triggers the hook.
default	A string or function as a default value of the triggering chunk option. If string, the value is given to glue::glue, and evaluates the expression by setting chunk options as an environment, and then automatically commented out. If function, it must have options parameter which receives chunk options, and return a string.
args	A list of arguments given to glue::glue() or callable default.
.set	TRUE or FALSE to set a default value and a hook to the trigger.

See Also

comment_title(), comment_out(), comment_syntax()

Examples

# Set hook which comments engine names of each chunks at the beginning.
hook_title_comment()

# Customize format
# For R chunks, let title comment be something like "chunk-label.R".
# Otherwise, fall back to the default behavior.
hook_title_comment(
  default = function(options) {
    if (options$engine == "R") {
      return(sprintf("# %s.%s", options$label, options$engine))
    }
    return(comment_title(options, template = "{engine}"))
  }
)

---