add_cloze: Functions for Managing the Meta-Information of Exercises

In exams: Automatic Generation of Exams in R

Functions for Managing the Meta-Information of Exercises

Description

Functions for adding elements to the meta-information of an exercise and for formatting the collected meta-information, respectively.

Usage

  add_cloze(solution, choices = NULL, type = NULL, tolerance = NULL,
    answertag = TRUE, ...)

  format_metainfo(field)

  initialize_exercise()

Arguments

solution	solution for an answer field in an exercise. See also the details below.
choices	vector of answer alternatives in a single-choice or multiple-choice exercise. See also the details below.
type	character. Optional specification of the type for an answer field, by default inferred from solution. Currently, "num", "string", "schoice", and "mchoice" are the standard types. Additionally, some exams2xyz interfaces support "essay", "file", or "verbatim" as part of a cloze.
tolerance	numeric. Tolerance to be used in case of a numeric solution. By default selected via num_to_tol.
answertag	logical. Should an ANSWERi tag be returned for inclusion in the text?
...	optional arguments for formatting a numeric solution via fmt (only applied if any arguments are specified).
field	character indicating whether the "type", "solution", "tolerance", or the "answerlist" for the exercise should be returned, formatted suitably.

Details

The function add_cloze(solution) adds meta-information to an internal list in order to facilitate tracking of the elements in an exercise, especially in cloze exercises.

If solution is numeric, a num element is added along with the corresponding tolerance, by default selected via num_to_tol(solution). Optionally, the solution can be formatted via fmt, e.g., to obtain a rounding to a given number of digits etc.

If solution is a character, a string element is added.

Additionally, solution can be a numeric or character vector or matrix in which case all elements are added (row-wise) to the meta-information and suitably-formatted answer tags are included as well (if answertag = TRUE, default).

Finally, if solution is a named logical vector, an mchoice or schoice element is added. The type can either be specified explicitly and otherwise schoice is used if solution has exactly one TRUE element. Alternatively, add_cloze(solution, choices) can be used to define single-choice or multiple-choice exercises where choices contains a vector of answer alternatives and solution a subset of choices with the correct solution(s). See also the examples below.

Using format_metainfo(type) the collected meta-information can be extracted, suitably formatted for inclusion in an exercise. The format_metainfo("answerlist") is intended to be included at the end of the question section while the other types ("type", "solution", and "tolerance") are intended to be included in the meta-information tags.

The function initialize_exercise() resets and initializes the exercise meta-information in the package's internal environment. Usually, this does not have be called by the user because it is called automatically prior to processing an exercise file. However, it is still provided for testing and illustration purposes as in the examples below.

See Also

answerlist

Examples

## initialize meta-information (done automatically within xweave())
initialize_exercise()

## add num, string, schoice, and mchoice elements
add_cloze(123.456789)

add_cloze("ABC")

add_cloze("high", c("low", "neutral", "high"))

add_cloze(c(
  "Zurich is the capital of Switzerland." = FALSE,
  "Italian is an official language in Switzerland." = TRUE,
  "Switzerland is part of the European Union." = FALSE
), type = "mchoice")

## add a numeric matrix
tab <- matrix(10^(1:4), ncol = 2, byrow = TRUE,
  dimnames = list(c("Top", "Bottom"), c("Left", "Right")))
add_cloze(tab)

## format collected meta-information
format_metainfo("type")
format_metainfo("solution")
format_metainfo("tolerance")
writeLines(format_metainfo("answerlist"))

## re-initialize cloze meta-information for cleanup
initialize_exercise()


## equivalent specifications of single/multiple-choice elements
add_cloze("high", c("low", "neutral", "high"), type = "schoice")
add_cloze(c("low" = FALSE, "neutral" = FALSE, "high" = TRUE), type = "schoice")

## format collected meta-information
format_metainfo("type")
format_metainfo("solution")
writeLines(format_metainfo("answerlist"))

## re-initialize cloze meta-information for cleanup
initialize_exercise()

exams documentation built on April 27, 2026, 3:02 a.m.