Package {tutorizeR}

Build callout-style MCQ lines

Description

Build callout-style MCQ lines

Usage

build_callout_question_lines(question, answers, language = "en")

Build normalized chunk block object

Description

Build normalized chunk block object

Usage

build_chunk_block(
  spec,
  body_lines,
  fence,
  raw_lines,
  inline = FALSE,
  start_line = NA_integer_,
  end_line = NA_integer_
)

Build default setup chunk when none is present

Description

Build default setup chunk when none is present

Usage

build_default_setup_chunk(language, seed = NULL)

Build generic engine chunk header

Description

Build generic engine chunk header

Usage

build_engine_chunk_header(engine, label = NULL, options = character())

Build exercise lines from source R chunk

Description

Build exercise lines from source R chunk

Usage

build_exercise_lines(format, exercise_label, source_chunk, language, tags)

Build learnr::question chunk lines

Description

Build learnr::question chunk lines

Usage

build_learnr_question_lines(question, answers, label, allow_retry = TRUE)

Build MCQ lines according to selected mode

Description

Build MCQ lines according to selected mode

Usage

build_mcq_for_chunk_mode(
  source_chunk,
  format,
  mcq_label_base,
  registry,
  language,
  question_bank,
  mcq_source,
  index
)

Build YAML header lines for target format

Description

Build YAML header lines for target format

Usage

build_output_yaml(source_yaml, format, language = "en")

Build placeholder MCQ for chunk-level MCQ generation

Description

Build placeholder MCQ for chunk-level MCQ generation

Usage

build_placeholder_mcq(format, mcq_label, source_chunk, language)

Build knitr R chunk header

Description

Build knitr R chunk header

Usage

build_r_chunk_header(label = NULL, options = character())

Build solution lines from source R chunk

Description

Build solution lines from source R chunk

Usage

build_solution_lines(format, solution_label, source_chunk, language)

Build converted tutorial lines from parsed document blocks

Description

Build converted tutorial lines from parsed document blocks

Usage

build_tutorial_lines(
  parsed,
  format,
  assessment,
  language = "en",
  seed = NULL,
  question_bank = NULL,
  mcq_source = c("inline", "bank", "mixed")
)

Render a generated tutorial and return render status

Description

Render a generated tutorial and return render status

Usage

check_tutorial(file, language = c("en", "fr"))

Arguments

Value

Invisibly, the render output path or the error object.

Examples

if (interactive()) {
  check_tutorial("analysis-tutorial.Rmd")
}

Render check implementation for generated learnr tutorials

Description

Render check implementation for generated learnr tutorials

Usage

check_tutorial_render(file, language = "en")

Convert all '.Rmd'/'.qmd' files in a folder

Description

Converts every matching source file in 'dir', with resilient per-file error handling and a summary report.

Usage

convert_folder(
  dir = ".",
  pattern = "\\.(Rmd|qmd)$",
  recursive = FALSE,
  output_dir = NULL,
  format = c("learnr", "quarto-live"),
  assessment = c("code", "mcq", "both"),
  overwrite = FALSE,
  language = c("en", "fr"),
  seed = NULL,
  verbose = TRUE,
  question_bank = NULL,
  mcq_source = c("inline", "bank", "mixed"),
  lint_strict = FALSE
)

Arguments

Value

A 'tutorize_folder_report' object (invisibly).

Examples

labs <- file.path(tempdir(), "labs")
out <- file.path(tempdir(), "tutorials")
dir.create(labs, recursive = TRUE, showWarnings = FALSE)
writeLines(
  c("---", "title: Demo", "---", "", "```{r}", "1 + 1", "```"),
  file.path(labs, "demo.Rmd")
)
report <- convert_folder(labs, output_dir = out, recursive = TRUE, verbose = FALSE)
print(report)

Backward-compatible wrapper for tutorial conversion

Description

'convert_to_tutorial()' is kept for compatibility with earlier versions. New code should use [tutorize()].

Usage

convert_to_tutorial(
  input_file,
  output_file = NULL,
  assessment = c("code", "mcq", "both"),
  format = c("learnr", "quarto-live"),
  add_mcq = NULL,
  question_bank = NULL,
  mcq_source = c("inline", "bank", "mixed"),
  lint_strict = FALSE
)

Arguments

Value

Invisibly, the generated output file path.

Examples

input <- tempfile(fileext = ".Rmd")
output <- tempfile(fileext = ".Rmd")
writeLines(c("---", "title: Demo", "---", "", "```{r}", "1 + 1", "```"), input)
convert_to_tutorial(input, output_file = output)

Count generated MCQ blocks in already rendered lines

Description

Count generated MCQ blocks in already rendered lines

Usage

count_generated_mcq(lines, format)

Decide effective conversion mode for one source chunk

Description

Decide effective conversion mode for one source chunk

Usage

derive_assessment_mode(assessment, tags)

Derive LMS items from parsed chunks

Description

Derive LMS items from parsed chunks

Usage

derive_manifest_items(blocks, include_solutions = TRUE)

Detect conflicting tag combinations

Description

Detect conflicting tag combinations

Usage

detect_tag_conflict(tags)

Detect unknown tutorizeR tags from comment lines

Description

Detect unknown tutorizeR tags from comment lines

Usage

detect_unknown_tags(lines)

Drop option tokens by key name

Description

Drop option tokens by key name

Usage

drop_options(option_tokens, keys)

Build an empty lint findings table

Description

Build an empty lint findings table

Usage

empty_findings()

Estimate expected completion time in minutes

Description

Estimate expected completion time in minutes

Usage

estimate_completion_minutes(stats)

Export a profile-aware LMS manifest

Description

Export a profile-aware LMS manifest

Usage

export_lms_manifest(
  input,
  output_file = NULL,
  profile = c("generic", "canvas", "moodle"),
  include_solutions = TRUE,
  language = c("en", "fr")
)

Arguments

Value

A 'tutorize_lms_manifest' object.

Export a tutorial-ready package scaffold (opt-in)

Description

Export a tutorial-ready package scaffold (opt-in)

Usage

export_tutorial_package(
  input,
  path = NULL,
  package_name = NULL,
  overwrite = FALSE
)

Arguments

Value

Invisibly returns the created package path.

Extract markdown heading titles from parsed blocks

Description

Extract markdown heading titles from parsed blocks

Usage

extract_section_titles(blocks)

Locate an i18n YAML file for the given language

Description

Locate an i18n YAML file for the given language

Usage

find_i18n_file(language)

Build a simple line diff between source and output

Description

Build a simple line diff between source and output

Usage

generate_simple_diff(source_lines, output_lines)

Load i18n dictionary from YAML with cache

Description

Load i18n dictionary from YAML with cache

Usage

get_i18n_dictionary(language)

Check whether lint report contains blocking errors

Description

Check whether lint report contains blocking errors

Usage

has_lint_errors(report)

Check whether a chunk option already exists

Description

Check whether a chunk option already exists

Usage

has_option(option_tokens, key)

Determine if block is explicit MCQ definition block

Description

Determine if block is explicit MCQ definition block

Usage

is_mcq_block(block)

Determine if block is MCQ reference block

Description

Determine if block is MCQ reference block

Usage

is_mcq_ref_block(block)

Determine if chunk is R engine

Description

Determine if chunk is R engine

Usage

is_r_chunk(block)

Determine if chunk is setup chunk

Description

Determine if chunk is setup chunk

Usage

is_setup_chunk(block)

RStudio Addin: Convert active document to tutorial

Description

Opens a lightweight prompt flow (format, assessment, output directory, overwrite) and converts the currently active file.

Usage

launch_tutorizeR_addin()

Value

Invisibly returns the 'tutorize_report' object, or 'NULL' when cancelled.

RStudio Addin: Convert a folder to tutorials

Description

Prompts for folder and conversion options, then converts all matching files.

Usage

launch_tutorizeR_folder_addin()

Value

Invisibly returns a 'tutorize_folder_report' object, or 'NULL' when cancelled.

RStudio Addin: Preview conversion with lint and diff

Description

Opens a gadget with Source, Output, Diff, Lint and Logs tabs.

Usage

launch_tutorizeR_preview_addin()

Value

Invisibly returns a 'tutorize_report' object or 'NULL'.

Build a lint finding row

Description

Build a lint finding row

Usage

lint_row(code, severity, message, line = NA_integer_, chunk_label = "")

Lint source pedagogical constraints before conversion

Description

Lint source pedagogical constraints before conversion

Usage

lint_source(
  input,
  question_bank = NULL,
  language = c("en", "fr"),
  strict = FALSE
)

Arguments

Value

A 'tutorize_lint_report' object.

Load a reusable MCQ question bank from YAML/JSON files

Description

Load a reusable MCQ question bank from YAML/JSON files

Usage

load_question_bank(
  path,
  recursive = TRUE,
  format = c("auto", "yaml", "json"),
  strict = TRUE,
  language = c("en", "fr")
)

Arguments

Value

A 'tutorize_question_bank' object.

Lookup nested translation key in dictionary

Description

Lookup nested translation key in dictionary

Usage

lookup_i18n_key(dict, key)

Register and generate unique deterministic labels

Description

Register and generate unique deterministic labels

Usage

make_unique_label(base, registry)

Build folder conversion report object

Description

Build folder conversion report object

Usage

new_tutorize_folder_report(results)

Construct a lint report object

Description

Construct a lint report object

Usage

new_tutorize_lint_report(source, findings, context = "source")

Build a conversion report object

Description

Build a conversion report object

Usage

new_tutorize_report(
  input_file,
  output_file,
  format,
  assessment,
  stats,
  render_result,
  warnings = character(),
  lint_report = NULL,
  messages = character()
)

Normalize root object to list of question entries

Description

Normalize root object to list of question entries

Usage

normalize_question_entries(raw)

Normalize one question entry to a canonical list

Description

Normalize one question entry to a canonical list

Usage

normalize_question_item(x, source_file = "")

Parse knitr/quarto chunk specification

Description

Parse knitr/quarto chunk specification

Usage

parse_chunk_spec(spec)

Transform source lines into converted tutorial body

Description

Transform source lines into converted tutorial body

Usage

parse_chunks(lines, assessment = "code", format = "learnr")

Parse an input R Markdown / Quarto document into structured blocks

Description

Parse an input R Markdown / Quarto document into structured blocks

Usage

parse_input_document(input_file)

Parse markdown body into text/chunk blocks

Description

Parse markdown body into text/chunk blocks

Usage

parse_markdown_blocks(lines)

Parse YAML from a tutorizeR-mcq-ref block

Description

Parse YAML from a tutorizeR-mcq-ref block

Usage

parse_mcq_ref_yaml(block)

Parse YAML from a tutorizeR-mcq block

Description

Parse YAML from a tutorizeR-mcq block

Usage

parse_mcq_yaml(block)

Parse a single question-bank file

Description

Parse a single question-bank file

Usage

parse_question_bank_file(file)

Parse teacher tags declared in code comments

Description

Parse teacher tags declared in code comments

Usage

parse_tutorizer_tags(lines)

Print method for folder conversion reports

Description

Print method for folder conversion reports

Usage

## S3 method for class 'tutorize_folder_report'
print(x, ...)

Arguments

Value

'x', invisibly.

Print method for lint reports

Description

Print method for lint reports

Usage

## S3 method for class 'tutorize_lint_report'
print(x, ...)

Arguments

Value

'x', invisibly.

Print method for LMS manifest exports

Description

Print method for LMS manifest exports

Usage

## S3 method for class 'tutorize_lms_manifest'
print(x, ...)

Arguments

Value

'x', invisibly.

Print method for tutorize conversion reports

Description

Print method for tutorize conversion reports

Usage

## S3 method for class 'tutorize_report'
print(x, ...)

Arguments

Value

'x', invisibly.

Register external label without modification

Description

Register external label without modification

Usage

register_label(label, registry)

Resolve effective language for tutorizeR

Description

Resolve effective language for tutorizeR

Usage

resolve_language(language = NULL)

Resolve output file path from user input

Description

Resolve output file path from user input

Usage

resolve_output_file(
  input,
  format,
  output_dir = NULL,
  output_file = NULL,
  language = "en"
)

Resolve file list for question-bank loading

Description

Resolve file list for question-bank loading

Usage

resolve_question_bank_files(path, recursive = TRUE, format = "auto")

Run conversion preview gadget

Description

Run conversion preview gadget

Usage

run_preview_gadget(input_file)

Sanitize chunk labels to portable deterministic strings

Description

Sanitize chunk labels to portable deterministic strings

Usage

sanitize_label(x)

Select question(s) from a loaded question bank

Description

Select question(s) from a loaded question bank

Usage

select_questions_from_bank(
  bank,
  ids = NULL,
  n = NULL,
  strategy = c("ordered", "random"),
  tags = NULL,
  difficulty = NULL,
  language = NULL
)

Split optional YAML front matter from body lines

Description

Split optional YAML front matter from body lines

Usage

split_front_matter(lines)

Split a comma-separated option string while preserving quoted commas

Description

Split a comma-separated option string while preserving quoted commas

Usage

split_option_tokens(x)

Strip teacher tag comments from chunk body

Description

Strip teacher tag comments from chunk body

Usage

strip_tag_lines(lines)

Remove leading YAML front matter lines

Description

Remove leading YAML front matter lines

Usage

strip_yaml(lines)

Translate a tutorizeR message key

Description

Looks up a message key in language dictionaries and interpolates named placeholders (for example, "{name}").

Usage

tr(key, ..., language = NULL)

Arguments

Value

A translated character string.

Convert a parsed MCQ block to output lines

Description

Convert a parsed MCQ block to output lines

Usage

transform_mcq_block(block, format, index)

Convert a parsed MCQ reference block to output lines

Description

Convert a parsed MCQ reference block to output lines

Usage

transform_mcq_ref_block(block, format, index, question_bank, language = "en")

Transform existing setup chunk and inject required lines for learnr

Description

Transform existing setup chunk and inject required lines for learnr

Usage

transform_setup_chunk(block, format, language, seed, registry)

Trim trailing blank lines from final output

Description

Trim trailing blank lines from final output

Usage

trim_trailing_blank_lines(lines)

Convert a source document into an interactive tutorial

Description

'tutorize()' is the canonical high-level API. It converts an existing '.Rmd' or '.qmd' source document into a tutorial-ready document for 'learnr' or 'quarto-live'.

Usage

tutorize(
  input,
  output_dir = NULL,
  format = c("learnr", "quarto-live"),
  assessment = c("code", "mcq", "both"),
  overwrite = FALSE,
  language = c("en", "fr"),
  seed = NULL,
  verbose = TRUE,
  output_file = NULL,
  question_bank = NULL,
  mcq_source = c("inline", "bank", "mixed"),
  lint_strict = FALSE
)

Arguments

Value

A 'tutorize_report' object (invisibly).

Examples

input <- tempfile(fileext = ".qmd")
writeLines(c("---", "title: Demo", "---", "", "```{r}", "1 + 1", "```"), input)
rep <- tutorize(
  input,
  output_dir = tempdir(),
  format = "learnr",
  assessment = "both",
  overwrite = TRUE,
  verbose = FALSE
)
print(rep)

Validate tutorizeR input arguments

Description

Performs defensive checks for file path, format, assessment, and extension.

Usage

validate_input(
  input,
  format = c("learnr", "quarto-live"),
  assessment = c("code", "mcq", "both"),
  language = c("en", "fr")
)

Arguments

Value

Invisibly returns 'TRUE' if validation succeeds.

Run a lightweight markdown parse validation when commonmark is available

Description

Run a lightweight markdown parse validation when commonmark is available

Usage

validate_markdown_structure(lines)

Validate expected MCQ fields

Description

Validate expected MCQ fields

Usage

validate_mcq_definition(definition, index)

Validate expected MCQ ref fields

Description

Validate expected MCQ ref fields

Usage

validate_mcq_ref_definition(definition, language = "en")

Validate output path and overwrite strategy

Description

Validate output path and overwrite strategy

Usage

validate_output(
  output_file,
  input_file,
  overwrite = FALSE,
  language = c("en", "fr")
)

Arguments

Value

Invisibly returns 'TRUE' if validation succeeds.

Validate a 'tutorize_question_bank' object

Description

Validate a 'tutorize_question_bank' object

Usage

validate_question_bank(bank, strict = TRUE, language = c("en", "fr"))

Arguments

Value

A 'tutorize_lint_report' object.

Validate one normalized question item

Description

Validate one normalized question item

Usage

validate_question_item(q, language = "en")

Write a conversion report to JSON or YAML

Description

Write a conversion report to JSON or YAML

Usage

write_tutorize_report(report, file, format = c("json", "yaml"), pretty = TRUE)

Arguments

Value

Invisibly returns 'file'.