Rumbas (Rust + Numbas)

What is Rumbas ?

• A system to create online (randomized) (math) exercises, build on top of Numbas.
  • It is useful to https://docs.numbas.org.uk/en/latest/jme-reference.html
• All features of Numbas, are available in rumbas.
  • Randomised questions
    • You can use the Numbas JME language to generate random numbers, do calculations, etc.
  • Diagnostic mode: the exam reacts to the student's performance to choose appropriate questions.
  • Rich interaction: easy to include graphics, videos and interactive diagrams (GeoGebra and JSXGraph) through extensions.
  • Many answer types: numbers, mathematical expressions, multiple choice, matrix ...
  • Automatic and immediate marking
  • In your language: translated in 19 languages and counting.
  • LTI Integration: The Numbas LTI tool makes it easy to add Numbas assessments to virtual learning environments such as Blackboard, Canvas, Moodle and Brightspace.
    • The result of a rumbas compilation is a Numbas exam, so all information you find about using numbas exams, can be used for rumbas exams.
  • Extensions: a specific subset of all Numbas extensions is supported
• More features:
  • Multi language: easily make the same exam available in different languages
  • Templating: when you create different questions/exams that are almost identical, you can extract these identical parts to a template to reduce redundancy.
  • Version control systems (like git) can be used 🎉:
    • Text-based: yaml (and html and tex) specifications are converted to an web-based exam.
• Currently in beta, not all features are implemented yet.
• Do you want to use it? Read the Tutorial.

How does rumbas work?

• The content of exams and questions are specified in a subset of YAML. Please consult our reference for the specifics.
• The rumbas program converts these descriptions in YAML subset to a Numbas exam
• The rumbas program uses the Numbas codebase to convert these Numbas exams to an html exam.

Getting Started

This Getting Started Guide will learn you

• how to setup your own rumbas repo on Github, with a complete development environment using Github Codespaces
• to write and run your first question
• to write and run your first exam (TODO?)
• to get familiar with possible next steps to make more advanced use of rumbas (TODO).

It assumes a minimal familiarity with VSCode.

Create an empty rumbas repository

While you can use rumbas locally on your PC, the quickest way to get started is to use a Github Codespace from a template:

Note that you won't be able to easily save your work. If you've decided to make more serious use of rumbas, consider creating your own repo, and/or run rumbas locally on your PC with Docker:

• Go to https://github.com/m8rex/rumbas-codespaces-template, and click on the green 'Use this template' button to create your personal rumbas-repository by choosing the 'Create a new repository' option.

  • Place it under your personal account
  • Choose a name
  • Decide whether it should be a private or public repo.
  • You'll be sent to your new repo.

• In your newly created repo, click on the green 'Code' button, use the 'Codespaces' tab and click on the green 'Create codespace on main' button (or on the plus icon if you've already used Codespaces before...).

More information and different options to use rumbas can be found in the installation guide

Initialise you new rumbas project

This command will create a bunch of folders and files that you can explore later. Important for now is that all your questions will go in separate files in questions, and all your exams similarly go into files in the folder exams.

Create our first question

Create a first question about the price for shoes after a discount by pasting the appropriate YAML content into a new file questions/shoes.yaml.

---
type: normal # This is just a normal questions
# set the statement
statement: |
      You want to buy a pair of shoes, but wait for the sales to start.
      <br/>
      Originally, a pair of shoes was priced $\var{price_orig}$ euro.
      You now get a $\var{percent}$% reduction.
parts: # specifythe parts of the questions
  - type: gapfill # the first (and only) part is of type gapfill
    prompt: How much are the shoes now? [[0]] # [[0]] is used to place the first gap (index 0)
    gaps: # specify each gap
      - type: number_entry # the first (and only) gap has type number_entry
        answer: price_now # this is the correct answer (the variable `price_now`)
        marks: 1 # the amount of marks awarded when answered correctly
variables: # The variables for our question
  price_orig: random(15,20,25,30,35) # a random element of this list
  percent:    random(20,30,40,50,60) # a random element of this list
  price_now:  price_orig*(1-percent/100) # the answer

Compile our first question

There will now be a completely standard Numbas preview in the folder _output/en/questions/shoes.

View and test your first question

Installation

• The easiest way to experiment with rumbas, is by using it in Github Codespaces.
• You can also install it on your own device by installing docker
• It is also possible to install it completely manual, but this is not recommended.

Github Codespace

The easiest way to try out rumbas is in Github Codespaces. You don't need any installation. You do, however, need a Github Account. Which you can create for free.

It is best to use the last released version as described here.

Running the last released version

• Log in to your Github account (or create one if you don't have one yet).
• Follow the steps in the rumbas codespaces template repo to load a github codespace with the latest released version of rumbas.
• You will now have a VSCode interface in your browser.
• Open a terminal within the VSCode interface and type rumbas --version to check if the setup is working.
• You can (after generating exams) use the installed Live Server extension to show the generated exams. Click on the 'Go Live' button in the right bottom corner.

Running the latest (non released) version

Log in to your Github account (or create one if you don't have one yet).

Click on the following link to open the examples of this book in Github Codespaces. You can then run the examples in the browser.

Github Codespaces will do the following:

• Build the latest rumbas version, this might take a few minutes.
• Open a visual studio code window in the browser
• Open the main folder of the rumbas repo

What should you do:

• Click on the menu ocon in the left top corner.
• Go to 'File' -> 'Open folder'.
• Select one of the subfolders of the /workspaces/rumbas/examples folder.
• The codespace will reload.
• All exams and questions in the folder will be compiled.
• You can use the installed Live Server extension to show the generated exams. Click on the 'Go Live' button in the right bottom corner.
• You can use the 'Open folder' trick again to open a different example.
• You can close the codespace by clicking on 'Codespaces' in the left bottom corner and then clicking on 'Stop current codespace'.
• After closing the codespace, you can open it again by going to https://github.com/codespaces and it will be in the same state as before.

Recommended installation (with docker)

Install docker

• All information about docker can be found on the docker website.

• Make sure that it is added to the PATH environment variable. This might be a checkbox during the installation.

• Validate the installation by typing docker ps in a terminal / command prompt.

Simplifying docker usage

In principe, installing docker is enough to run rumbas but the commands will be cumbersome.

In this section we describe how to create bat or sh files to make the docker usage of rumbas transparant for the user.

Important: Make sure to explicitly use the latest version of rumbas (or at least a specific version, not latest)

Explanation

In the Windows and Unix sections below, we will explain how you can run rumbas in your terminal / command prompt by just writing rumbas or rumbas_shell.

• rumbas: You will be able to write rumbas in the terminal, instead of needing to type the whole docker command with the volume mount.
• rumbas_shell: Always starting a container might be a bit to slow and overkill. With this script you can run rumbas-shell to get a docker container where you can repeatedly execute rumbas commands. Because of the current implementation of the docker container, it is best to call /usr/app/entrypoint.sh <path> instead of calling rumbas directly. Just calling rumbas will only work if you don't use custom themes.

Windows

We will create a folder docker_scripts on the C drive and add it to the PATH environment variable. In this folder you can create a file for each of the following two scripts.

Creating the docker_scripts folder

• Create a folder 'docker_scripts' on the C drive
• Click on the window icon in the left bottom corner
• Search for 'Edit environment variables' and click on it
• Select 'Path' and click 'edit'
• Click on 'New'
• Typ 'C:\docker_scripts'
• Click on 'Ok'
• Open a new terminal so the new PATH variable is set

In this folder you need to create a file for each of the following two scripts.

rumbas.bat

Place the following text in the file rumbas.bat in the docker_scripts folder.

@echo off
set str=%*
set "str=%str:\=/%"
docker run --rm -v %cd%:/rumbas ghcr.io/m8rex/rumbas:0.7.1 %str%

rumbas_shell.bat

Place the following text in the file rumbas_shell.bat in the docker_scripts folder.

@echo off
docker run -it --rm -v %cd%:/rumbas --entrypoint=sh ghcr.io/m8rex/rumbas:0.7.1

Unix

We will create a folder docker_scripts in /usr/local/bin

sudo mkdir /usr/local/bin/docker_scripts

And add it to the path by adding to following line to the ~/.bashrc file:

export PATH=$PATH:/usr/local/bin/docker_scripts

In this folder you can create a file for each of the following two scripts.

rumbas

Place the following text in the file rumbas.bat in the docker_scripts folder.

#!/bin/sh
docker run --rm -v $PWD:/rumbas ghcr.io/m8rex/rumbas:0.7.1 $@

Afterwards execute: sudo chmod +x /usr/local/bin/docker_scripts/rumbas

rumbas_shell

Place the following text in the file rumbas_shell.bat in the docker_scripts folder.

#!/bin/sh
docker run -it --rm -v $PWD:/rumbas --entrypoint=sh ghcr.io/m8rex/rumbas:0.7.1

Afterwards execute: sudo chmod +x /usr/local/bin/docker_scripts/rumbas_shell

Explicit docker usage

It is possible to run rumbas in docker without using the docker_scripts setup.

• Run docker run --rm -it -v <absolute_path_to_rumbas_repo>:/rumbas ghcr.io/m8rex/rumbas:0.7.1 rumbas <command>
  • e.g.docker run --rm -it -v C:\Users\jesse\Documents\rumbas-examples:/rumbas ghcr.io/m8rex/rumbas:0.7.1 compile exams/M0/algebra/begintest.yaml

Installation

Manual Installation (Advanced Usage)

It is possible to use rumbas without using docker, but this implies some manual installation of software.

Prerequisites

Python 3

Python 3 should be installed and added to the PATH

Running python --version in the terminal / command prompt should yield a version bigger than 3.

The Numbas codebase

rumbas uses Numbas to compile the exams to html.

Clone / Download the numbas code from Github and place it in a folder on your machine.

Set the environment variable NUMBAS_FOLDER to the path of this new folder.

The Numbas extensions

You will need to download all extensions that you want to use and place them in the extensions folder of the NUMBAS_FOLDER.

You can find most extensions at Github.

It is important that you name the folder of the extension exactly as they are named in rumbas.

You can always look at the Dockerfile of rumbas to see how the naming should happen and where you can find the extensions.

The Numbas themes

The themes that are being used in the rumbas repo, should be copied to the themes folder in the NUMBAS_FOLDER.

The Dockerfile uses this script to make sure that the themes are correct.

The rumbas binary

In the future, you might find these binaries on the rumbas Github Releases.

For now, you will need to build the binary yourself.

Building the binary

• Install the rust
• Execute cargo build --release in the rumbas folder.

You can also use cargo install --path . in the rumbas folder to build and install the binary.

Tutorial

This tutorial will give you some hands on experience with the rumbas system.

To follow along with the tutorials, you will need an installation of rumbas.

Your first question

We will start your journey with rumbas by creating a simple question in the rumbas system. This question will be a simple calculation question.

You can create a folder by right clicking on the left bar that shows the file system.

Step 1: Questions folder

Step 2: Create a question

This file will contain the yaml code for the question. To know which fields we can set for a question, you can look at the Reference for question page. For now we will show the fields that can be set for a question:

For now we will just look at the 'normal' question type.

We can set a value for each of these fields.

---
type: normal # set the type to normal
# type has to be set as an 'internal tag' so all fields of 'Question' are set on the samen level
statement: How much is 9 * 3?
advice: You could calculate 10 * 3 and then subtract 3. This yields 3 * 10 - 3 = 30 - 3 = 27
# Add one part
parts:
  - type: number_entry
    prompt: Enter your answer in the inputbox
    marks: 5 # Give 5 points for a correct answer
    answer: 27 # Set the correct answer
    show_correct_answer: true
    show_feedback_icon: true
    display_correct_as_fraction: false
    allow_fractions: false
    fractions_must_be_reduced: false
    fractions_must_be_reduced_hint: false
    partial_credit_if_fraction_not_reduced: 0
    display_correct_in_style: &style english-plain
    allowed_notation_styles:
      - *style
    custom_marking: none
    steps: []
    steps_penalty: 0
    adaptive_marking: none
    part_name: none
# All fields below are not imporant yet, but need to be specified. Rumbas doesn't use any internal default values.
builtin_constants: # all constants will be disabled
  e: false
  pi: false
  i: false
custom_constants: []
variables: {}
grouped_variables: none
variables_test:
  condition: ""
  max_runs: 1
functions: {}
preamble:
  css: ""
  js: ""
navigation:
  can_regenerate: false
  show_title_page: false
  confirm_when_leaving: false
extensions:
  jsx_graph: false
  stats: false
  geogebra: false
  eukleides: false
  chemistry: false
  download_text_file: false
  graphs: false
  linear_algebra: false
  linear_codes: false
  optimisation: false
  permutations: false
  polynomials: false
  quantities: false
  random_person: false
  written_number: false
  sqlite: false
  text: false
diagnostic_topic_names: []
resources: []
custom_part_types: []
rulesets: {}

Step 3: Try compiling the first question

Now we can compile the question. To do this, we need to open a terminal in the folder of your rumbas project. Then we can run the following command:

rumbas check questions/first_question.yaml

This command will now show an error about the question not belonging to a rumbas project. This is because our rumbas repository is missing a crucial file. This file is the .rumbasrc.yaml - mind the dot (.) at the start - file. This file contains the settings for the rumbas repository.

---
version: 0.8.0 # The rumbas version that this repository uses.

Step 4: Try compiling the first question again

Now we can try compiling the question again.

This time we will get a different error. This error is because we are missing another crucial file in our rumbas project. This file is the exams/questions_preview.yaml file.

Because this file makes use a feature of rumbas that we will explain later (templating), we will create an exam that uses our question and compile that exam.

To know which fields we can set for a question, you can look at the Reference for exam page. For now we will show the fields that can be set for a question.

For now we will just look at the normal exam type. This is the exam type that we will use for our first exam.

We can set a value for each of these fields.

---
type: normal # set the type to normal
# type has to be set as an 'internal tag' so all fields of 'NormalExam' are set on the samen level
name: First Exam
question_groups:
  - name: Group 1
    picking_strategy:
      type: all_ordered
    questions:
      - first_question.yaml
navigation:
  mode: sequential
  start_password: none
  can_regenerate: true
  show_steps: false
  show_title_page: false
  confirm_when_leaving: false
  show_names_of_question_groups: true
  allow_printing: false
  can_move_to_previous: true 
  browsing_enabled: true
  show_results_page: never
  on_leave: 
    action: none
feedback:
  percentage_needed_to_pass: 50
  show_name_of_student: false
  show_current_marks: true # whether the current score is shown
  show_maximum_marks: true
  show_answer_state: true
  allow_reveal_answer: true
  review:
    show_score: true
    show_feedback: true
    show_expected_answer: true
    show_advice: true
  advice: "Please practice more"
  intro: "An introductory text"
  feedback_messages: []
timing:
  duration_in_seconds: none # no time limit
  allow_pause: true 
  on_timeout: 
    action: none
  timed_warning: 
    action: none
locales: # this can be used to localize your exams (have it available in multiple languages)
  - name: en # custom name
    numbas_locale: en-GB # English (United Kingdom)
numbas_settings:
  theme: default # use the default numbas theme

Step 5: Compiling our first exam

Now we can compile the exam. To do this, we need to open a terminal in the folder of your rumbas project. Then we can run the following command:

rumbas check exams/first_exam.yaml

rumbas compile exams/first_exam.yaml

This command will create a folder in _output/en/exams/first_exam with the compiled exam.

Step 6: Try the exam

After starting your local webserver, you should be able to browse to the exam. You can find the url in the terminal. It should be something like http://localhost:8000/en/exams/first_exam/.

You can also find the exam in the online demo.

Step 7: Using variables

This question will always ask the same question (3 * 9). We can make this question more interesting by using variables to do any number times 9.

Let's copy our first_question.yaml file to first_question_with_variables.yaml and add variables. To do this we will:

• Add a variable named a with a value of 3
• Change the statement, answer and correct_answer so it uses the variable a instead of the number 3.

---
type: normal
statement: How much is 9 * {a}? # this changed
advice: You could calculate 10 * {a} and then subtract {a}. This yields {a} * 10 - {a} = {a * 10} - {a} = {a*9} # this changed
parts:
  - type: number_entry
    prompt: Enter your answer in the inputbox
    marks: 5 
    answer: a * 9 # this changed
    show_correct_answer: true
    show_feedback_icon: true
    display_correct_as_fraction: false
    allow_fractions: false
    fractions_must_be_reduced: false
    fractions_must_be_reduced_hint: false
    partial_credit_if_fraction_not_reduced: 0
    display_correct_in_style: &style english-plain
    allowed_notation_styles:
      - *style
    custom_marking: none
    steps: []
    steps_penalty: 0
    adaptive_marking: none
    part_name: none
variables:
  a: 3 # this changed
# All fields below are not imporant yet, but need to be specified. Rumbas doesn't use any internal default values.
builtin_constants: # all constants will be disabled
  e: false
  pi: false
  i: false
custom_constants: []
grouped_variables: none
variables_test:
  condition: ""
  max_runs: 1
functions: {}
preamble:
  css: ""
  js: ""
navigation:
  can_regenerate: false
  show_title_page: false
  confirm_when_leaving: false
extensions:
  jsx_graph: false
  stats: false
  geogebra: false
  eukleides: false
  chemistry: false
  download_text_file: false
  graphs: false
  linear_algebra: false
  linear_codes: false
  optimisation: false
  permutations: false
  polynomials: false
  quantities: false
  random_person: false
  written_number: false
  sqlite: false
  text: false
diagnostic_topic_names: []
resources: []
custom_part_types: []
rulesets: {}

Now we will create a new exam that uses this question. We will copy the first_exam.yaml file to first_exam_with_variables.yaml and add the new question to the questions field.

---
type: normal
name: First Exam
question_groups:
  - name: Group 1
    picking_strategy:
      type: all_ordered
    questions:
      - first_question.yaml
      - first_question_with_variables.yaml # We added this
navigation:
  mode: sequential
  start_password: none
  can_regenerate: true
  show_steps: false
  show_title_page: false
  confirm_when_leaving: false
  show_names_of_question_groups: true
  allow_printing: false
  can_move_to_previous: true 
  browsing_enabled: true
  show_results_page: never
  on_leave: 
    action: none
feedback:
  percentage_needed_to_pass: 50
  show_name_of_student: false
  show_current_marks: true
  show_maximum_marks: true
  show_answer_state: true
  allow_reveal_answer: true
  review:
    show_score: true
    show_feedback: true
    show_expected_answer: true
    show_advice: true
  advice: "Please practice more"
  intro: "An introductory text"
  feedback_messages: []
timing:
  duration_in_seconds: none 
  allow_pause: true 
  on_timeout: 
    action: none
  timed_warning: 
    action: none
locales: 
  - name: en 
    numbas_locale: en-GB
numbas_settings:
  theme: default

We can then compile all exams with the following command:

rumbas compile exams

And open the new exam in the browser by browsing to http://localhost:8000/en/exams/first_exam_with_variables/.

You can also find the exam in the online demo.

Step 8: Using randomisation

Now we will create a question that uses randomisation. We will copy the first_question_with_variables.yaml file to first_question_with_randomisation.yaml and change the value of variable a to random(1..10). This will choose a random integer between 1 and 10 as value for a.

---
type: normal
statement: How much is 9 * {a}? 
advice: You could calculate 10 * {a} and then subtract {a}. This yields {a} * 10 - {a} = {a * 10} - {a} = {a*9}
parts:
  - type: number_entry
    prompt: Enter your answer in the inputbox
    marks: 5 
    answer: a * 9 
    show_correct_answer: true
    show_feedback_icon: true
    display_correct_as_fraction: false
    allow_fractions: false
    fractions_must_be_reduced: false
    fractions_must_be_reduced_hint: false
    partial_credit_if_fraction_not_reduced: 0
    display_correct_in_style: &style english-plain
    allowed_notation_styles:
      - *style
    custom_marking: none
    steps: []
    steps_penalty: 0
    adaptive_marking: none
    part_name: none
variables:
  a: random(1..10) # this changed
# All fields below are not imporant yet, but need to be specified. Rumbas doesn't use any internal default values.
builtin_constants: # all constants will be disabled
  e: false
  pi: false
  i: false
custom_constants: []
grouped_variables: none
variables_test:
  condition: ""
  max_runs: 1
functions: {}
preamble:
  css: ""
  js: ""
navigation:
  can_regenerate: false
  show_title_page: false
  confirm_when_leaving: false
extensions:
  jsx_graph: false
  stats: false
  geogebra: false
  eukleides: false
  chemistry: false
  download_text_file: false
  graphs: false
  linear_algebra: false
  linear_codes: false
  optimisation: false
  permutations: false
  polynomials: false
  quantities: false
  random_person: false
  written_number: false
  sqlite: false
  text: false
diagnostic_topic_names: []
resources: []
custom_part_types: []
rulesets: {}

Now we will create a new exam that uses this question. We will copy the first_exam_with_variables.yaml file to first_exam_with_randomisation.yaml and add the new question to the questions field.

---
type: normal
name: First Exam
question_groups:
  - name: Group 1
    picking_strategy:
      type: all_ordered
    questions:
      - first_question.yaml
      - first_question_with_variables.yaml
      - first_question_with_randomisation.yaml # We added this
navigation:
  mode: sequential
  start_password: none
  can_regenerate: true
  show_steps: false
  show_title_page: false
  confirm_when_leaving: false
  show_names_of_question_groups: true
  allow_printing: false
  can_move_to_previous: true 
  browsing_enabled: true
  show_results_page: never
  on_leave: 
    action: none
feedback:
  percentage_needed_to_pass: 50
  show_name_of_student: false
  show_current_marks: true
  show_maximum_marks: true
  show_answer_state: true
  allow_reveal_answer: true
  review:
    show_score: true
    show_feedback: true
    show_expected_answer: true
    show_advice: true
  advice: "Please practice more"
  intro: "An introductory text"
  feedback_messages: []
timing:
  duration_in_seconds: none 
  allow_pause: true 
  on_timeout: 
    action: none
  timed_warning: 
    action: none
locales: 
  - name: en 
    numbas_locale: en-GB
numbas_settings:
  theme: default

We can then compile all exams with the following command:

rumbas compile exams

And open the new exam in the browser by browsing to http://localhost:8000/en/exams/first_exam_with_randomisation/.

You can also find the exam in the online demo.

Using defaults

In the previous example we saw how to create a question and an exam. In this example we will look at how to use default files to reduce the size of our question and exam files.

Create a new rumbas project

Default files folder

This folder will contain default files that you want to use in your project. These files specify global defaults for your project.

Default exam files

For an exam we can specify a couple of different default files to specify global defaults for exams.

Navigation

Our three exams use exactly the same navigation. We can therefore move the navigation field to a default file.

The navigation field of an exam can be specified in a file named navigation.yaml in the defaults folder.

---
mode: sequential
start_password: none
can_regenerate: true
show_steps: false
show_title_page: false
confirm_when_leaving: false
show_names_of_question_groups: true
allow_printing: false
can_move_to_previous: true 
browsing_enabled: true
show_results_page: never
on_leave: 
  action: none

Feedback

Our three exams use exactly the same feedback. We can therefore move the feedback field to a default file.

The feedback field of an exam can be specified in a file named feedback.yaml in the defaults folder.

---
percentage_needed_to_pass: 50
show_name_of_student: false
show_current_marks: true
show_maximum_marks: true
show_answer_state: true
allow_reveal_answer: true
review:
  show_score: true
  show_feedback: true
  show_expected_answer: true
  show_advice: true
advice: "Please practice more"
intro: "An introductory text"
feedback_messages: []

Timing

Our three exams use exactly the same timing. We can therefore move the timing field to a default file.

The timing field of an exam can be specified in a file named timing.yaml in the defaults folder.

---
duration_in_seconds: none # no time limit
allow_pause: true 
on_timeout: 
  action: none
timed_warning: 
  action: none

Locales

Our three exams use exactly the same locales. We can therefore move the locales field to a default file.

The locales field of an exam can be specified in a file named locales.yaml in the defaults folder.

---
- name: en # custom name
  numbas_locale: en-GB # English (United Kingdom)

Numbas Settings

Our three exams use exactly the same Numbas settings. We can therefore move the numbas_settings field to a default file.

The numbas_settings field of an exam can be specified in a file named numbas_settings.yaml in the defaults folder.

---
theme: default # use the default numbas theme

Resulting exam files

Our exam files are now a lot smaller. Our exam with randomisation is now:

---
type: normal
name: First Exam
question_groups:
  - name: Group 1
    picking_strategy:
      type: all_ordered
    questions:
      - first_question.yaml
      - first_question_with_variables.yaml
      - first_question_with_randomisation.yaml

Overriding defaults

These defaults are useful to reduce the size of your exam files. However, sometimes you will want to override the default values. For example, you might want to change the show_current_marks field of the feedback field for a specific exam. This can easily be done without needing to specify all fields of feedback.

---
type: normal
name: First Exam
feedback:
  show_current_marks: false # overrride this field
  # all other feedback settings are taken from the default file
question_groups:
  - name: Group 1
    picking_strategy:
      type: all_ordered
    questions:
      - first_question.yaml
      - first_question_with_variables.yaml
      - first_question_with_randomisation.yaml

You can also find the exam in the online demo.

Step 4: Default question files

Default question files

We can do the same thing for question files. For example, we can move the all question fields (except question_groups) to a default file.

---
builtin_constants: # all constants will be disabled
  e: false
  pi: false
  i: false
custom_constants: []
variables: {}
grouped_variables: none
variables_test:
  condition: ""
  max_runs: 1
functions: {}
preamble:
  css: ""
  js: ""
navigation:
  can_regenerate: false
  show_title_page: false
  confirm_when_leaving: false
extensions:
  jsx_graph: false
  stats: false
  geogebra: false
  eukleides: false
  chemistry: false
  download_text_file: false
  graphs: false
  linear_algebra: false
  linear_codes: false
  optimisation: false
  permutations: false
  polynomials: false
  quantities: false
  random_person: false
  written_number: false
  sqlite: false
  text: false
diagnostic_topic_names: []
resources: []
custom_part_types: []
rulesets: {}

We also add the variables field in here and set it to an empty hash by default. This is because we will be able to override the variables field in the question files that do use variables.

Our question files are now a lot smaller. Our question with variables is now:

---
type: normal
statement: How much is 9 * {a}?
advice: You could calculate 10 * {a} and then subtract {a}. This yields {a} * 10 - {a} = {a * 10} - {a} = {a*9} # this changed
parts:
  - type: number_entry
    prompt: Enter your answer in the inputbox
    marks: 5 
    answer: a * 9
    show_correct_answer: true
    show_feedback_icon: true
    display_correct_as_fraction: false
    allow_fractions: false
    fractions_must_be_reduced: false
    fractions_must_be_reduced_hint: false
    partial_credit_if_fraction_not_reduced: 0
    display_correct_in_style: &style english-plain
    allowed_notation_styles:
      - *style
    custom_marking: none
    steps: []
    steps_penalty: 0
    adaptive_marking: none
    part_name: none
variables:
  a: 3

Default question part files

There is still some duplication of settings within the number_entry question parts. We can move the settings of the number_entry question parts to a default file.

---
show_correct_answer: true
show_feedback_icon: true
display_correct_as_fraction: false
allow_fractions: false
fractions_must_be_reduced: false
fractions_must_be_reduced_hint: false
partial_credit_if_fraction_not_reduced: 0
display_correct_in_style: &style english-plain
allowed_notation_styles:
  - *style
custom_marking: none
steps: []
steps_penalty: 0
adaptive_marking: none
part_name: none

Our question files are now even smaller. Our question with variables is now:

---
type: normal
statement: How much is 9 * {a}?
advice: You could calculate 10 * {a} and then subtract {a}. This yields {a} * 10 - {a} = {a * 10} - {a} = {a*9} # this changed
parts:
  - type: number_entry
    prompt: Enter your answer in the inputbox
    marks: 5 
    answer: a * 9
variables:
  a: 3

Multi language questions

One of the most important features of rumbas is that it is easy to create different language versions of the same question.

Create a new rumbas project

Translating the statement

Currently our question with variables is defined in yaml as follows:

---
type: normal
statement: How much is 9 * {a}?
advice: You could calculate 10 * {a} and then subtract {a}. This yields {a} * 10 - {a} = {a * 10} - {a} = {a*9}
parts:
  - type: number_entry
    prompt: Enter your answer in the inputbox
    marks: 5 
    answer: a * 9
variables:
  a: 3

Currently this question is only available in English. We want to make this question available in Dutch as well.

Let's take a look again at the structure of a questions.

We see that the statement and advice fields have the type Translation.

For now we will focus on the first option, the TranslationStruct.

---
content: # the content of form TranslationContent
placeholders: {} # empty for now

Let's now have a look at TranslationContent.

The first option is the most important for now. It says that we can specify different versions of the content in different languages by using a hash.

---
content:
  en: english content
  nl: dutch content
placeholders: {} # empty for now

---
type: normal
statement: 
  content: 
    en: How much is 9 * {a}?
    nl: Hoeveel is 9 * {a}?
  placeholders: {}
advice: 
  content: 
    en: You could calculate 10 * {a} and then subtract {a}. This yields {a} * 10 - {a} = {a * 10} - {a} = {a*9}
    nl: Je kan 10 * {a} berekenen en dan {a} daarvan aftrekken. Dit geeft {a} * 10 - {a} = {a * 10} - {a} = {a*9}
  placeholders: {}
parts:
  - type: number_entry
    prompt: 
      content:
        en: Enter your answer in the inputbox
        nl: Geef je antwoord in in het invulveld
      placeholders: {}
    marks: 5 
    answer: a * 9
variables:
  a: 3

---
- name: en # custom name
  numbas_locale: en-GB # English (United Kingdom)

---
- name: en # custom name
  numbas_locale: en-GB # English (United Kingdom)
- name: nl # custom name
  numbas_locale: nl-NL # Dutch (The Netherlands)

You can access the dutch exams at http://localhost:8000/nl/exams/first_question_with_variables/

You can also find the dutch exam and english exam in the online demo.

Placeholders

If we look at statement and advice we see that some values (mostly math expressions) are language independant.

---
type: normal
statement: 
  content: 
    en: How much is 9 * {a}?
    nl: Hoeveel is 9 * {a}?
  placeholders: {}
advice: 
  content: 
    en: You could calculate 10 * {a} and then subtract {a}. This yields {a} * 10 - {a} = {a * 10} - {a} = {a*9}
    nl: Je kan 10 * {a} berekenen en dan {a} daarvan aftrekken. Dit geeft {a} * 10 - {a} = {a * 10} - {a} = {a*9}
  placeholders: {}
parts:
  - type: number_entry
    prompt: 
      content:
        en: Enter your answer in the inputbox
        nl: Geef je antwoord in in het invulveld
      placeholders: {}
    marks: 5 
    answer: a * 9
variables:
  a: 3

This is where placeholders come in. Placeholders can be specified by name and then be used in the content field by writing {name}.

---
type: normal
statement: 
  content: 
    en: How much is {formula}?
    nl: Hoeveel is {formula}?
  placeholders:
      formula: 9 * {a}
advice: 
  content: 
    en: You could calculate {times10} and then subtract {a}. This yields {result}
    nl: Je kan {times10} berekenen en dan {a} daarvan aftrekken. Dit geeft {result}
  placeholders:
    times10: 10 * {a} 
    result: '{a} * 10 - {a} = {a * 10} - {a} = {a*9}'
parts:
  - type: number_entry
    prompt: 
      content:
        en: Enter your answer in the inputbox
        nl: Geef je antwoord in in het invulveld
      placeholders: {}
    marks: 5 
    answer: a * 9
variables:
  a: 3

---
content: "{command} $5x^2-10$."
placeholders:
  command: 
    content:
      nl: Ontbind in factoren
      en: Factorize
    placeholders: {}

Locale Folders

It might happen that you want to use the same text in different questions or exams. This is where the FileString type comes in.

Let's take a look at the FileString type.

Using the FileString type in combination with locale folders gives us a powerful mechanism to reuse text in different questions and exams.

This yields following yaml code for the question

---
type: normal
statement: 
  content: how-much.html
  placeholders:
      formula: 9 * {a}
advice: 
  content: 
    en: You could calculate {times10} and then subtract {a}. This yields {result}
    nl: Je kan {times10} berekenen en dan {a} daarvan aftrekken. Dit geeft {result}
  placeholders:
    times10: 10 * {a} 
    result: '{a} * 10 - {a} = {a * 10} - {a} = {a*9}'
parts:
  - type: number_entry
    prompt: 
      content:
        en: Enter your answer in the inputbox
        nl: Geef je antwoord in in het invulveld
      placeholders: {}
    marks: 5 
    answer: a * 9
variables:
  a: 3

And questions/locale-nl/how-much.html file:

Hoeveel is {formula}?

And questions/locale-en/how-much.html file:

How much is {formula}?

Using Templates

Another very important feature of rumbas, is its templating feature. This feature allows you to create a template for a question or exam. This template can then be used to create multiple questions or exams. This is very useful when you have a lot of questions or exams that are very similar.

Create a new rumbas project

Add a question and an exam

We will add an exam with the following content:

---
type: normal
name: Exam
question_groups:
  - name: Group 1
    picking_strategy:
      type: all_ordered
    questions:
      - question.yaml

And also add a question with the following content:

---
type: normal
statement:
  content:
    nl: Hoveel is {formula}?
    en: How much is {formula}?
  placeholders:
    formula: 9 * {a}
advice:
  content: 
    en: You could calculate {times10} and then subtract {a}. This yields {result}
    nl: Je kan {times10} berekenen en dan {a} daarvan aftrekken. Dit geeft {result}
  placeholders:
    times10: 10 * {a} 
    result: '{a} * 10 - {a} = {a * 10} - {a} = {a*9}'
parts:
  - type: number_entry
    prompt: 
      content:
        en: Enter your answer in the inputbox
        nl: Geef je antwoord in in het invulveld
      placeholders: {}
    marks: 5 
    answer: a * 9 
variables:
  a: random(1..10)

Using a template

Create a template

We might want to create a lot of questions that are very similar to the question we just created. In some cases, we might want to let the variable a go up to 100 or be limited between 1 and 5.

To do this, we copy the contents of question.yaml to question_template.yaml and make the change the value of the variable a to template:a. This yields the following content for question_template.yaml:

---
type: normal
statement:
  content:
    nl: Hoveel is {formula}?
    en: How much is {formula}?
  placeholders:
    formula: 9 * {a}
advice:
  content: 
    en: You could calculate {times10} and then subtract {a}. This yields {result}
    nl: Je kan {times10} berekenen en dan {a} daarvan aftrekken. Dit geeft {result}
  placeholders:
    times10: 10 * {a} 
    result: '{a} * 10 - {a} = {a * 10} - {a} = {a*9}'
parts:
  - type: number_entry
    prompt: 
      content:
        en: Enter your answer in the inputbox
        nl: Geef je antwoord in in het invulveld
      placeholders: {}
    marks: 5 
    answer: a * 9 
variables:
  a: template:a # this field is now templatable and has template-key 'a'

There is no meaning behind the _template suffix of the file name, we just use it for the example.

Now that we have added a value of the form template:<template-key> the question_template.yaml file is a template. We can now use this template to create multiple questions.

Loading the template in an exam

The easiest way to use this templated question, is by loading it in an exam and giving values for each template key.

We will load the template two times in the exam. The first time we will set the value of a to 3 so it will always yield the same question. The second time, we set it to random(10..100) to let a be a random value between 10 and 100.

We will change our exam.yaml file to the following:

---
type: normal
name: Exam
question_groups:
  - name: Group 1
    picking_strategy:
      type: all_ordered
    questions:
      - question.yaml
      - type: template # we will load it as a template
        template: question_template.yaml # this template will be loaded
        a: 3 # this is filled in for `template:a`
      - type: template # we will load it as a template
        template: question_template.yaml # this template will be loaded
        a: random(10..100) # this is filled in for `template:a`

What if we forget to set a template key?

What would happen when we don't set all template keys? Let's try it out.

We will change our exam.yaml file to the following:

---
type: normal
name: Exam
question_groups:
  - name: Group 1
    picking_strategy:
      type: all_ordered
    questions:
      - question.yaml
      - type: template # we will load it as a template
        template: question_template.yaml # this template will be loaded
        a: 3 # this is filled in for `template:a`
      - type: template # we will load it as a template
        template: question_template.yaml # this template will be loaded
        a: random(10..100) # this is filled in for `template:a`
      - type: template
        template: question_template.yaml

This will yield an error message like the following:

[2023-01-25][09:48:30][rumbas_support::input][ERROR] Found 1 missing template keys:
[2023-01-25][09:48:30][rumbas_support::input][ERROR] 1  a at question_groups.0.questions.3.question_template.yaml.variables.a

Which says that we forgot to set the value of a for the fourth question (index 3 when you count from 0).

Using default values for template keys

It is possible to defined default values for template keys. This allows you to override the value but also have a default value that is used when the value is not set.

We will demonstrate this by allowing the marks for the question to be set by a template key, but also have a default value of 5 marks.

We will change our question_template.yaml file to the following:

---
type: normal
statement:
  content:
    nl: Hoveel is {formula}?
    en: How much is {formula}?
  placeholders:
    formula: 9 * {a}
advice:
  content: 
    en: You could calculate {times10} and then subtract {a}. This yields {result}
    nl: Je kan {times10} berekenen en dan {a} daarvan aftrekken. Dit geeft {result}
  placeholders:
    times10: 10 * {a} 
    result: '{a} * 10 - {a} = {a * 10} - {a} = {a*9}'
parts:
  - type: number_entry
    prompt: 
      content:
        en: Enter your answer in the inputbox
        nl: Geef je antwoord in in het invulveld
      placeholders: {}
    marks:
      template_key: marks
      default_valie: 5 
    answer: a * 9 
variables:
  a: template:a # this field is now templatable and has template-key 'a'

This allows us to optionally specify the value of the template key marks in the exam. If we don't specify it, it will use the default value of 5.

We will change our exam.yaml file to the following:

---
type: normal
name: Exam
question_groups:
  - name: Group 1
    picking_strategy:
      type: all_ordered
    questions:
      - question.yaml
      - type: template
        template: question_template.yaml 
        a: 3 # we don't specify the marks here, so it will be 5
      - type: template
        template: question_template.yaml 
        a: random(10..100)
        marks: 10 # assign 10 marks to the more difficult version

Create a question that uses a template

If you want to reuse a version of a question that uses a template, you can create a question that uses a template.

We will create a question that uses the template we created in the previous section.

We will create a question_using_template.yaml file with the following content:

---
type: template
template: question_template.yaml 
a: random([11,55,78])

We can now include this question in an exam.

Rumbas CLI commands

All commands

$ rumbas --help
Make online exercises great again!

Usage: rumbas [OPTIONS] <COMMAND>

Commands:
  compile
          Compile a rumbas exam (or question)
  check
          Check a rumbas exam (or question)
  watch
          Watch a path
  fmt
          Format a rumbas exam (or question)
  import
          Import a numbas .exam file
  init
          Initialize a rumbas project in this folder
  update-repo
          Update the repository to the next rumbas version
  export
          Export a rumbas exam as one yaml. All default files and templating is resolved
  schema
          Creates files with the json schemas (beta). See https://github.com/m8rex/rumbas-examples/tree/main/.vscode for usage instructions
  generate-shell-completion
          Generate shell completion file. Placing this file at the right location and reloading your shell, will give you shell completion for rumbas
  editor-output
          Generates a folder structure that can be hosted and used as an 'editor' in the numbas lti provider
  help
          Print this message or the help of the given subcommand(s)

Options:
  -v...
          Sets the level of verbosity
          
          -v    sets the level to ERROR
          
          -vv   sets the level to WARN
          
          -vvv   sets the level to INFO
          
          -vvvv   sets the level to DEBUG
          
          The default is -vvv

  -q
          Enables quiet mode. Nothing is logged. This has precedence over the verbose option

  -h, --help
          Print help information (use `-h` for a summary)

  -V, --version
          Print version information

compile

$ rumbas compile --help
Compile a rumbas exam (or question)

You can pass a path to a folder to compile all files in the folder.

Usage: compile [OPTIONS] <EXAM_OR_QUESTION_PATHS>...

Arguments:
  <EXAM_OR_QUESTION_PATHS>...
          The path to the exam or question file to compile.
          
          If a folder within the questions or exams folder is used, all questions/exams in that folder will be compiled.
          
          It is possible to specify multiple paths to folder/files.

Options:
  -s, --scorm
          Include the files necessary to make a SCORM package

  -z, --zip
          Create a zip file instead of a directory

      --no-minification
          Don't perform minification on the created js in the exam. Useful if you don't have uglifyjs or want to debug something

  -h, --help
          Print help information (use `-h` for a summary)

check

$ rumbas check --help
Check a rumbas exam (or question)

You can pass a path to a folder to check all files in the folder.

Usage: check <EXAM_OR_QUESTION_PATHS>...

Arguments:
  <EXAM_OR_QUESTION_PATHS>...
          The path to the exam or question file to check.
          
          If a folder within the questions or exams folder is used, all questions/exams in that folder will be checked.
          
          It is possible to specify multiple paths to folder/files.

Options:
  -h, --help
          Print help information (use `-h` for a summary)

watch

$ rumbas watch --help
Watch a path

Usage: watch [OPTIONS] <PATH>

Arguments:
  <PATH>
          The path to watch

Options:
  -o
          Only check exams and questions that change due to file changes, but don't compile them with numbas

  -h, --help
          Print help information

fmt

$ rumbas fmt --help
Format a rumbas exam (or question).

You can pass a path to a folder to format all files in the folder.

Usage: fmt <EXAM_OR_QUESTION_PATHS>...

Arguments:
  <EXAM_OR_QUESTION_PATHS>...
          The path to the exam or question file to format.
          
          If a folder within the questions or exams folder is used, all questions/exams in that folder will be formatted.
          
          It is possible to specify multiple paths to folder/files.

Options:
  -h, --help
          Print help information (use `-h` for a summary)

import

$ rumbas import --help
Import a numbas .exam file

Resources have to be manually placed in the resources folder

Usage: import [OPTIONS] <EXAM_PATH>

Arguments:
  <EXAM_PATH>
          The path to the numbas .exam file

Options:
  -q
          Tells rumbas that this is the exam file of a numbas question instead of of a numbas exam

  -h, --help
          Print help information (use `-h` for a summary)

init

$ rumbas init --help
Initialize a rumbas project in this folder

Usage: init [OPTIONS]

Options:
      --summative
          Whether the defaults should be of summative nature (instead of formative)

  -h, --help
          Print help information

update-repo

$ rumbas update-repo --help
Update the repository to the next rumbas version

Usage: update-repo

Options:
  -h, --help
          Print help information

export

$ rumbas export --help
Export a rumbas exam as one yaml. All default files and templating is resolved.

Can be useful to debug exams / questions that don't behave as expected

Usage: export <EXAM_OR_QUESTION_PATHS>...

Arguments:
  <EXAM_OR_QUESTION_PATHS>...
          The path to the exams to export
          
          If a folder within the questions or exams folder is used, all questions/exams in that folder will be exported.
          
          It is possible to specify multiple paths to folder/files.

Options:
  -h, --help
          Print help information (use `-h` for a summary)

schema

$ rumbas schema --help
Creates files with the json schemas (beta). See https://github.com/m8rex/rumbas-examples/tree/main/.vscode for usage instructions

Usage: schema

Options:
  -h, --help
          Print help information

generate-shell-completion

$ rumbas generate-shell-completion --help
Generate shell completion file. Placing this file at the right location and reloading your shell, will give you shell completion for rumbas.

Example for bash: rumbas generate-shell-completion bash | sudo tee /usr/share/bash-completion/completions/rumbas

Usage: generate-shell-completion <SHELL>

Arguments:
  <SHELL>
          The shell for which the shell competion should be generated
          
          [possible values: bash, elvish, fish, powershell, zsh]

Options:
  -h, --help
          Print help information (use `-h` for a summary)

editor-output

$ rumbas editor-output --help
Generates a folder structure that can be hosted and used as an 'editor' in the numbas lti provider

Only exams are compiled.

Usage: editor-output <OUTPUT_PATH> <URL_PREFIX>

Arguments:
  <OUTPUT_PATH>
          The path to the folder where the output should be generated

  <URL_PREFIX>
          The url prefix for all editor api calls

Options:
  -h, --help
          Print help information (use `-h` for a summary)

help

$ rumbas help --help
Print this message or the help of the given subcommand(s)

Usage: help [COMMAND]...

Arguments:
  [COMMAND]...
          Print help for the subcommand(s)

Features

Rumbas is a library for creating and running assessments. It is designed to be used in a variety of ways, and can be used in a variety of contexts. This chapter describes the features of Rumbas, and how they can be used.

Rumbas tries to support all features that Numbas supports, and adds some new features. The new features are:

• Templating for questions and exams. This allows you to create the format of a question or exam once, and then use it in multiple questions or exams with different values.
• Multi language support. This allows you to create questions and exams in multiple languages while sharing the language independent parts.
  • Locale folders allow you to specify different values for different languages and to reuse these values in different questions or exams.
• Explicity: Rumbas does not use any default values within the program. All values must be explicitly set, and the program will not guess what you want. This makes it easier to understand what is going on, and to debug problems.
  • Default value files can (and should) be used to specify default values for your questions and exams.

Default files

Multi language

Locales folders

Templates

Summary

• Exam
• Question

Yaml subset used by Rumbas

The source code for any rumbas exam or question is written in a subset of YAML.

This page sections show you how to write YAML files for Rumbas.

Datatypes

The following datatypes are used in the rumbas yaml files. The following sections will explain how each of these can be represented in the yaml files.

Strings

Strings can be written in many ways in yaml, each with their specific advantages and disadvantages.

Unquoted strings

Unquoted strings are the most basic form of string. They are written as a sequence of characters, without any quotes.

This is an unquoted string

Advantages:

• Easy to write
• Backslashes (\) are not interpreted as escape characters. This means that you can write a string containing a backslash without having to escape it.
  • Special characters like newlines and tabs are not interpreted as escape characters.
  • Makes it easy to type a string containing jme commands.

Disadvantages:

• Newlines (enters) can only be inserted by leaving a blank line.
• Can't contain colons (:) followed by a space or a hashtag (#) after a space.

Single quoted strings

Single quoted strings are written between single quotes.

'This is a single quoted string'

means

This is a single quoted string

Advantages:

• Can contain colons (:) followed by a space or a hashtag (#) after a space.
• Backslashes (\) are not interpreted as escape characters. This means that you can write a string containing a backslash without having to escape it.
  • Special characters like newlines and tabs are not interpreted as escape characters.
  • Makes it easy to type a string containing jme commands.

Disadvantages:

• Newlines (enters) can only be inserted by leaving a blank line.
• Can't contain single quotes ('). They need to be escaped with a single quote (').

'It''s a single quoted string with a jme simplify command \simplify{2x+3}'

means

It's a single quoted string  with a jme simplify command \simplify{2x+3}

As you can see we need to type two single quotes to get one single quote in the string. This is because the single quote is used to mark the start and end of the string. If we want to type a single quote in the string we need to escape it with another single quote.

Double quoted strings

Double quoted strings are written between double quotes.

"This is a double quoted string"

means

This is a double quoted string

Advantages:

• Can contain colons (:) followed by a space or a hashtag (#) after a space.
• Can contain single quotes (') without having to escape them.
• Newlines can be added by placing an escape character (\) at the end of the line.

Disadvantages:

• Can't contain double quotes ("). They need to be escaped with a backslash (\).
• Backslashes (\) are interpreted as escape characters. This means that you can't write a string containing a backslash without escaping it.
  • Special characters like newlines and tabs are interpreted as escape characters.
  • Makes it hard to type a string containing jme commands. Because you will need to escape each backslash.

"It's a double quoted string with a jme simplify command \\simplify{2x+3}"

means

It's a double quoted string with a jme simplify command \simplify{2x+3}

We need to write two backslashes to get one backslash in the string. This is because the backslash is used as the escape character. If we want to type a backslash in the string we need to escape it with another backslash.

Folded strings

Folded strings are written after a greater than sign (>). Newlines are not preserved, they are replaced by a space. Blank lines can be used to insert a newline.

>
    This is a folded string.
    It can contain newlines.

    It can contain colons (:) followed by a space or a hashtag (#) after a space.

    It can contain single quotes (') without having to escape them.
    It can contain double quotes (") without having to escape them.

    It can contain backslashes (\) without having to escape them.

means

This is a folded string. It can contain newlines.
It can contain colons (:) followed by a space or a hashtag (#) after a space.
It can contain single quotes (') without having to escape them. It can contain double quotes (") without having to escape them.
It can contain backslashes (\) without having to escape them.

As you can see, newline are replaced by a space. Blank lines are replaced by a newline.

Literal strings

Literal strings are written after a pipe (|). Newlines are preserved.

|
    This is a literal string.
    It can contain newlines.
    It can contain colons (:) followed by a space or a hashtag (#) after a space.

    It can contain single quotes (') without having to escape them.
    It can contain double quotes (") without having to escape them.
    It can contain backslashes (\) without having to escape them.

means

This is a literal string.
It can contain newlines.
It can contain colons (:) followed by a space or a hashtag (#) after a space.

It can contain single quotes (') without having to escape them.
It can contain double quotes (") without having to escape them.
It can contain backslashes (\) without having to escape them.

As you can see, newlines are preserved. The text is literally as typed, except for the leading spaces that are removed.

Hashes

Hashes map keys to values. They are written as a list of key-value pairs, separated by colons (:). The keys may only contain letters, numbers, and underscores.

key1: value1
key2: value2

The values can be any yaml value, even other hashes.

key1: value1
level1: # the value of this key is a hash
  key2: value2
  level2: # the value of this key is a hash
    key3: value3

The order of the keys in a hash has no meaning. The following two hashes are identical.

some_key: value1
another_key: value2

another_key: value2
some_key: value1

An empty hash can be written as {}.

empty_subhash: {}

Arrays

Arrays are an ordered list of values. They can be written inline or as a block.

Block arrays

Block arrays are written after a dash (-) and a space. Each value is written on a new line.

- value1
- value2

The values can be any yaml value, even other arrays or hashes.

hash_key: 
  - value1
  - value2
other_key: # the value of this key is an array
  - key: value # the value of the first element of the array is a hash
    other: value
  - other_element
list_of_lists:
   # the value of the elements of the array below, are arrays themselves
   - - value1 
     - value2
   - - value3
     - value4

Inline arrays

Inline arrays can be used to write a list of values on a single line. They are written between square brackets ([ and ]), with values separated by commas (,).

[ value1, value2 ]

These values can be any value, except for block hashes or block arrays.

This is mostly used to represent an empty array [] or an array of a small amount of strings.

Anchors and aliases

Anchors and aliases can be used to reference a value multiple times. This is useful when you want to use the same value multiple times, but don't want to write it multiple times.

Anchors are written after an ampersand (&). They are then followed by a key. The key can be any string, but it is recommended to use a unique key.

key1: &anchor_key value
key2: *anchor_key

which is identical to

key1: value
key2: value

It is also possible to use anchors for whole hashes and arrays.

hash_value: &hash
  key1: value1
  key2: value2
also_hash_value: *hash

which is identical to

hash_value:
  key1: value1
  key2: value2
also_hash_value:
  key1: value1
  key2: value2

It is obviously also possible to reference an anchor multiple times.

a_key: &value_to_reuse This can be some long text or any other datatype
another_key: *value_to_reuse
third_key: *value_to_reuse

which is identical to

a_key: This can be some long text or any other datatype
another_key: This can be some long text or any other datatype
third_key: This can be some long text or any other datatype

Yaml files

Each yaml file start with three dashes: --- and is then followed by either a hash or an array.

---
key1: value1
key2: value2

---
- value1
- value2

Comments

Comments can be written after a hashtag (#) The hashtag needs to be the first character on a line or there should be a space in front of it (in unquoted strings). They can be written on a separate line or after a value.

# This is a comment before the opening dashes
---
key1: value1 # This is a comment
# This is a comment before a key
key2: value2 # This is another comment

Writing Rumbas Yaml

The source code for any rumbas exam or question is written in a subset of YAML.

This section will show you how to write YAML files for Rumbas.

Basic objects

The Exam, Question and Custom Part Type reference shows tables that explain the dataformat for rumbas. In its most basic form, it looks like the following reference for the QuestionPartMatrixRangedDimension type which is used to specify the possible sizes for a matrix. If you are new to rumbas, you don't need to (and can't) understand yet what this type is used for. It is just used as an example to explain how to read such a table.

The tables lists three fields that has to be present in the yaml for the object. The first column is the name of the field, the second column is the datatype of the field and the third column is a description of the field.

An example would be the following:

default: 2
min: 1
max: 4 # could also be set to none to indicate no maximum

The order of the keys has no meaning, so we could just as well write:

max: 4
min: 1
default: 2

Object with an [any] field

Some objects have a field name [any] in their reference. This means that any other key-value pair can be added to the object.

This can be represented in yaml by adding any key-value pair to the hash.

template: path_to_template
# we can add as many other key-value pairs as we want (due to the [any] field)
any_key: any_value
another_key: another_value

Choice object

Some of the datatypes in the reference can take multiple forms.

This following datatype is either a TranslationStruct or a FileString. See the One of the following items: text.

To represent this datatype in yaml, you would either write a TranslationStruct or a FileString.

A TranslationStruct is specified as follows:

Which could be represented in yaml as follows:

# TranslationStruct
content: Some content
placeholders: {}

The yaml above is thus also a valid yaml for a Translation.

A FileString is specified as follows:

Which could be represented in yaml as follows:

# FileString
file:path/to/file

or

# FileString
any string value

The yaml above is thus also a valid yaml for a Translation.

Choice object with explicit tag

Sometimes it is needed to explicitly specify the type of a choice object. This is done by adding a specific key-value pair to the object.

This specification below says that we should write the yaml as one of the three given options and add the key-value pair type: <tag-value> to the object to specify which option we chose. This is denoted by the Internal tag named type text.

If we want to choose the template option, we would write the following yaml for an ExamFileType:

type: template # set the internal tag
# TemplateFile
template: path_to_template 
any_key: any_value

If we want to choose the normal option, we would write the following yaml for an ExamFileType:

type: normal # set the internal tag
# NormalExam
name: The name of the exam
# ... more fields

If we want to choose the diagnostic option, we would write the following yaml for an ExamFileType:

type: diagnostic # set the internal tag
# DiagnosticExam
name: The name of the diagnostic exam
# ... more fields

Folder structure

The folder structure of a rumbas project is important. Some names are reserved and have a special meaning.

• A folder named defaults that contains the default specifications
• A folder named questions that contains the questions
• A folder named exams that contains the exams
• A folder named themes the contains your custom themes
• A folder named custom_part_types that contains custom_part_types
• A folder named resources that contains the resources that are used in exams or questions.

Default folders

TODO: list the files that can be set

It is important to note that rumbas does not specify any default value by itself. Numbas does however have a quite extensive range of options that can be set. Setting all these options for every question and exam would be a real hassle and the files would not be readable.

To prevent this problem, the default folders were created.

Folders named default can be specified:

• In the root of the rumbas project
• In any (sub)folder in the exams folder
• In any (sub)folder in the questions folder

When the description of a question/exam is read:

• All default folders in ancestor folders are examined for default values:
  • e.g. if a question is positioned in questions/M0/algebra/H1/nul_in_N_and_Z.yaml the following default folders will be checked:
    • questions/M0/algebra/H1/default
    • questions/M0/algebra/default
    • questions/M0/default/
    • questions/default
    • default
• The default folders are examined in order: first the 'closer' ones.
  • e.g. The folders will be examined in the order shown above

Locale folders

Each subfolder of the exams and questions folder can have a locale folder. This are folders with a name of the form locale-<locale-key>. They allow easily translating things that are used many times.

ExamFileType

Internal tag named type.

One of the following items:

TemplateFile

NormalExam

Translation

One of the following items:

TranslationStruct

TranslationContent

One of the following items:

FileString

One of the following items:

Locale

SupportedLocale

One of the following items:

NormalNavigation

Internal tag named mode.

One of the following items:

SequentialNavigation

ShowResultsPage

One of the following items:

LeaveAction

Internal tag named action.

One of the following items:

LeaveActionMessage

MenuNavigation

Timing

TimeoutAction

Internal tag named action.

One of the following items:

TimeoutActionWarn

Feedback

Review

FeedbackMessage

QuestionGroup

PickingStrategy

Internal tag named type.

One of the following items:

PickingStrategyRandomSubset

QuestionPathOrTemplate

One of the following items:

NumbasSettings

DiagnosticExam

DiagnosticNavigation

Diagnostic

DiagnosticScript

One of the following items:

LearningObjective

LearningTopic

QuestionFileType

Internal tag named type.

One of the following items:

TemplateFile

Question

Translation

One of the following items:

TranslationStruct

TranslationContent

One of the following items:

FileString

One of the following items:

QuestionPart

One of the following items:

QuestionPartBuiltin

Internal tag named type.

One of the following items:

QuestionPartJME

Number

One of the following items:

CustomMarking

JMENote

AdaptiveMarking

VariableReplacement

VariableReplacementStrategy

One of the following items:

JMEAnswerSimplification

JMEAnswerDisplay

JMEAccuracy

CheckingType

Internal tag named type.

One of the following items:

CheckingTypeDataFloat

CheckingTypeDataNatural

JMEPatternRestriction

JMEValueGenerator

JMEFileString

One of the following items:

JMELengthRestriction

JMEStringRestriction

QuestionPartGapFill

QuestionPartChooseOne

MultipleChoiceAnswerData

One of the following items:

MultipleChoiceAnswer

MultipleChoiceAnswerDataNumbasLike

ChooseOneDisplay

Internal tag named type.

One of the following items:

ChooseOneDisplay_radio

QuestionPartChooseMultiple

MultipleChoiceWarningType

One of the following items:

MultipleChoiceMarkingMethod

One of the following items:

QuestionPartMatchAnswersWithItems

MultipleChoiceMatchAnswerData

Internal tag named type.

One of the following items:

MultipleChoiceMatchAnswers

MatchAnswersItem

MatchAnswersItemMarks

MultipleChoiceMatchAnswerDataNumbasLike

MatchAnswerWithItemsDisplay

Internal tag named type.

One of the following items:

MatchAnswersWithChoicesDisplayCheck

MatchAnswersWithChoicesLayout

MatchAnswersWithChoicesLayoutType

One of the following items:

QuestionPartNumberEntry

NumberEntryAnswer

One of the following items:

NumberEntryAnswerRange

AnswerStyle

One of the following items:

QuestionPartPatternMatch

PatternMatchMode

One of the following items:

QuestionPartInformation

QuestionPartExtension

QuestionPartMatrix

QuestionPartMatrixDimensions

QuestionPartMatrixDimension

One of the following items:

QuestionPartMatrixRangedDimension

QuestionPartCustom

BuiltinConstants

CustomConstant

VariablesTest

Preamble

QuestionNavigation

Extensions

ResourcePath

CustomPartTypeDefinition

Translation

One of the following items:

TranslationStruct

TranslationContent

One of the following items:

FileString

One of the following items:

CustomPartTypeSetting

Internal tag named input_type.

One of the following items:

CustomPartTypeSettingCheckBox

CustomPartTypeSettingCode

CustomPartTypeSettingMathematicalExpression

CustomPartTypeSettingString

CustomPartTypeSettingDropDown

CustomPartTypeSettingDropDownChoice

CustomPartTypeSettingPercentage

JMENote

Extensions

CustomPartInputWidget

Internal tag named type.

One of the following items:

CustomPartStringInputOptions

CustomPartInputOptionValueTranslatableString

CustomPartInputOptionValueBool

CustomPartNumberInputOptions

CustomPartInputOptionValueAnswerStyles

AnswerStyle

One of the following items:

CustomPartRadioGroupInputOptions

CustomPartInputOptionValueTranslatableStrings