Skip to content
/ QBL Public

Manages a testback of mulitple choice questions and coverts to a desired format.

License

Notifications You must be signed in to change notification settings

mercere99/QBL

Repository files navigation

QBL

QBL (pronounced "Quibble") is a Question Bank Language; it manages a repository of multiple choice questions that can be used to generate exams in a desired format.

Running QBL

Format:

./QBL [-dhilqvw] [-g question_count] [-rtx require/include/exclude_tags] [-o outfile] [question_file ...]

When executing QBL from the command line, you can provide any number of filenames to load from. If a number is provided, it indicates the number of questions to generate for the exam.

The following flags are also available:

General

Flag Meaning Example
-g or --generate Specify the number of questions to randomly generate. -g 20
-h or --help Provide additional information for using QBL and stop. -h
-o or --output Next arg will be the name to use for the output file. -o quiz1.html
-S or --set (TO IMPLEMENT) Run the following argument to set a value. -S var=12
-t or --title Specify the title to use for the generated quiz. -t "Quiz 1"
-v or --version Print out the current version of the software and stop. -v

Output types

Flag Meaning Example
-d or --d2l Output to D2L / Brightspace csv quiz upload format. -d
-l or --latex (PARTIALLY IMPLEMENTED) Output to Latex format -l
-q or --qbl Output to QBL format. -q
-w or --web Output to HTML format. -w
-c or --compressed Only works with Gradescope format; output questions in a compressed format that takes up less space -c

Tag management

Flag Meaning Example
-i or --include All questions with the provided tag(s) must be included. -i prereq,basic
-r or --require Exclude questions must that do not have any provided tag. -r cse101a,cse101b
-s or --sample For each listed tag, include specified no. of questions. -s topic1,topic2 10
-x or --exclude Exclude all questions with the provided tag(s). -x badtag

Note: All exclusions occur before any questions are included. Thus if a question has both an include and exclude tag, exclusion takes priority. Likewise if it is missing a required tag, it will always be excluded. Multiple tags may be included if separated by commas (no spaces allowed)

Question format

Which of the following are rules for QBL question formatting?
#example-tag #second-tag
:options=5   % Pick only 5 answers when placed on exam, including correct one.
* The first character(s) on a line determine the context of that line.
* Tags are placed on on one or more lines, and each tag beginning with a '#'
* Config tags can be intermixed with other tags and begin with a ':'
* Regular answer options each begin with a * or a [*] if it is a correct answer.
* Answers that begin with an extra `>` (e.g., `*>` or `[*>]`) will NOT be shuffled.
* Answers that begin with an extra `+` (e.g., `*+` or `[*>+]`) will always be included.
* Comments must be on their own line and begin with a `%` sign.
* Code-style can be indicated by `backticks` or by
    a line beginning with at least four spaces
* Other lines of text are always linked to either the question
  or the answer on the line before it.
[>] All of the above.

%---- Question break! --- 
T/F: A skipped (blank) line signals the start of a new question:
[*] True
* False

Specifically, the following line formats are available:

First Characters Meaning
letters, numbers, _ or ( Regular line of text; either a question or continuation of answer.
* Incorrect answer option.
[*] Correct answer option.
# Tag to identify groups of questions collectively.
^ Tag to indicate that only ONE question from a group should be used.
: Tag to set configuration option (must have an = to set value).
% Comment line.
four spaces Pre-formatted code block.
- Remove - and ignore other start format; allows blank lines in questions.
+ Question should always be selected.
! Question is alternate option that negates all answer correctness. Note: Make sure to have enough "correct" answers for this to work.
> (TO IMPLEMENT) Question should be kept in the same position relative to other Qs.
? (TO IMPLEMENT) Explanation about the previous line's Q or A (for post-exam learning)
{ ... } (TO IMPLEMENT) Mathematical equations for question setup.
=|@&~;<,./ Not yet specified.

The * or [*] at the beginning of the line can also have the * followed by > to indicate that the answer option should not be shuffled, and/or by + to indicate that this option should always be included in random sampling. For example, *>, [*>], *+ or [*+>] are all legal option beginnings.

Certain characters also have special meanings in the middle of a line. These will all begin with either a back tick (`) if we are changing mode or formatting, or a backslash (\) if we are inserting a special character. Anything that does not follow either of those two characters will be translated directly.

Examples of special formatting:

  `*Bold!`*
  ``Code``
  `/Italic`/
  `_Underlined!`_
  `^Superscript`^
  `.Subscript`.
  `~Strikethrough`~

TO IMPLEMENT: If any tags (e.g., keywords beginning with #, ^, or : above) are created outside of a question definition, they will apply to ALL questions that follow, until the end of the current file OR until they are replaced by a new tag block. A # by itself on a line will remove the current tag block.

Output formats

When running QBL questions can be loaded, manipulated, and re-saved into a format of the users choice. By default questions are saved in QBL format (described above), but alternative formats are typically more useful for providing to students.

Formats include:

Format Extension Override flag
D2L / Brightspace csv quiz upload .csv -d or --d2l
HTML (planned) .html -h or --html
Latex (planned) .tex -l or --latex
QBL .qbl -q or --qbl

(Planned) -i or --interact - Run directly as interactive command line (planned)

Question configuration tags

Questions can have configuration tags in the form of :options=5 or :alt_prob=0.1. These tags help the question writer fine-tune how the question will be processed by the system.

Available configuration tags are:

Config Tag Default Meaning
:correct 1 Number of correct answers to include as value (1) or range (2-4).
:options all Number of answer options to include (e.g., 5 or range 3-4).
:alt_prob 0.5 Probability of choosing alternate question if one exists. (TO IMPLEMENT)

About

Manages a testback of mulitple choice questions and coverts to a desired format.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Contributors 4

  •  
  •  
  •  
  •