read_exercise: Reading LaTeX/Markdown Exercise Files

Description

Reading an exercise in either LaTeX format (i.e., after Sweave was run) or Markdown format (i.e., after knit was run).

Usage

read_exercise(file, markup = NULL, exshuffle = NULL)
  read_metainfo(file, markup = NULL, exshuffle = NULL)

Value

read_exercise returns a list with elements

question: a character vector with LaTeX/Markdown code from the question environment (excluding the answerlist environment, if any).
questionlist: a character vector with LaTeX/Markdown code from the answerlist environment within the question environment (if any).
solution: a character vector with LaTeX/Markdown code from the solution environment (excluding the answerlist environment, if any).
solutionlist: a character vector with LaTeX/Markdown code from the answerlist environment within the solution environment (if any).
metainfo: a list of metainformation options, see below.
supplements: a character vector with paths to supplementary files such as graphics or data files (if any).

read_metainfo returns a list with the following elements. Most elements may also be NULL (or empty) if the underlying information is not specified in the file. If file specifies extra information, there may also be additional list elements.

file: character with file name (without extension) of the exercise template.
markup: character indicating whether "latex" or "markdown" markup is used in the exercise.
type: character indicating exercise type: num, mchoice, schoice, string, or cloze.
name: character with short name/description (to be used for printing within R).
title: character with a pretty longer title.
section: character with sections for groups of exercises (using slashes for subsections like a URL).
version: character with version of exercise.
solution: correct solution. The type/value depends on the type of the exercise: num leads to a numeric vector (of length 1 or 2), mchoice/schoice lead to logical vector, string to a character vector (of length 1), and cloze leads to a list of solutions (depending on clozetype).
tolerance: numeric tolerance limits (of length 1 or 2) for numeric solutions.
clozetype: character indicating the types of the elements of a cloze exercise.
points: numeric with (default) points for correct solution.
time: numeric with (default) time (in seconds) for solution.
shuffle: logical indicating whether mchoice/schoice answers should be shuffled (in Moodle or other e-learning systems).
single: logical indicating whether radio buttons should be used in Moodle.
length: numeric with length of solution.
string: character with a collapsed string of the solution (and tolerance) for backward compatibility with exams.
maxchars: character with the maximum number of characters allowed in QTI text answers (exercise type: string).
abstention: character with the label to be used for an abstention button in schoice/mchoice answers (currently only supported by Moodle).

Arguments

file: character. Name of the LaTeX (.tex) or Markdown (.md) file that should be read into R.
markup: character specifying whether file is a "latex" or "markdown" exercise. By default (NULL) it is inferred from the file extension.
exshuffle: logical or integer. If the exshuffle argument is non-NULL it is used to overrule the exshuffle tag from the file (e.g., exshuffle = FALSE can be used to keep all available answers without permutation).

Details

read_exercise extracts the LaTeX/Markdown code from the question and solution environments/sections of the exercise file, extracting the corresponding answerlists separately (if any). Paths to supplementary files (such as graphics or data files) are stored and the metainformation is extracted (by calling read_metainfo which also includes sanity checks).

The supported metainformation commands are described in detail in vignette("exams2", package = "exams"), see Table 2. Essentially the extype command in is mapped to the type element of the returned list etc. (see the Value section below), using the right storage mode for each command (numeric, character, logical). Additionally, there is an exextra command which allows to set up arbitrary additional metainformation elements.

Examples

Run this code

## xexams() uses read_exercise() by default to read in
## each individual exercise, e.g., here for only a single
## exam with only a single exercise the result is:
set.seed(1090)
xexams("tstat.Rnw")[[1]][[1]]

## the corresponding Markdown version has:
set.seed(1090)
xexams("tstat.Rmd")[[1]][[1]]