sellquiz / sellquiz

An open source domain-specific language for online assessment (Created at TH Köln, Germany) https://sell.f07-its.fh-koeln.de/

SELL Quiz

The Simple E-Learning Language (=: SELL) is an open standard for mathematical e-learning questions with the following objectives:

• Simple syntax: No unneeded overhead. Defining a task/question should be similar to describe the task/question on a blackboard.
• Expressive language: Programs are short and concise such that the semantics can be grasped quickly. Irrelevant detail is avoided.
• Reuse of established standards: We inherit AsciiMath for mathematical expressions and Markdown for text formatting.

Project website: https://sell.f07-its.fh-koeln.de/

Project maintainer: Andreas Schwenk / TH Köln.

Language Definition

SELL is a domain-specific language (DSL). Visit the official website for detailed information.

Hello, World!

The following example demonstrates a question written in SELL.

Matrix Operations

	a := { 1, 2, 3 }
	A, C in MM( 2 x 1 | a )
	B in MM( 2 x 2 | a )
	D := (A + B^T * C)^T

Please calculate:
* $ (A + B^T * C)^T = #D $

Click here to run the example

More Examples

You'll find a set of working examples (in the German language) here. The corresponding SELL-code can be found in this repository in directory /examples/

Usage

Website Embedding:

Visit https://github.com/sellquiz/sellquiz-standalone

Moodle Plugin:

(work in progress. Please come back later)

Ilias Plugin:

(work in progress. Please come back later)

Developers

• Run ./install.sh to install Node.js dependencies and check for other dependencies.
• Run ./build.sh to build SELL.
• Open index-highlevel.html for a demonstration of the high-level API in the browser.
• Open src/index-lowlevel.html for a demonstration of the low-level API in the browser.
• You'll find a demonstration of the low-level API for Node.js in file index-lowlevel-api.ts.

(We provide a VS Code launch configuration in .code/launch.json.)

• For debugging, you may use src/test.ts (a launch configuration for VS Code is available). This file parses imported SELL-questions with Node.js and writes also test-sell.html, which can be tested in a web browser. Refer to the information in the terminal output.

Functions

autoCreateQuiz

▸ autoCreateQuiz(sellCode, htmlDivElement): boolean

Creates a quiz including HTML control elements. This function can be used for a trivial integration of a stand-alone SELL quiz into a website. WARNING: do not mix using this high-level function and low-level functions.

Parameters

Name	Type	Description
sellCode	string	SELL source code of one or multiple questions (divided by a line equal to %%%)
htmlDivElement	HTMLElement	HTML element that will contain all questions.

Returns

boolean

Success.

Defined in

index.ts:38

---

autoEvaluateQuiz

▸ autoEvaluateQuiz(questionID, htmlQuestionElementID): boolean

Evaluates a quiz that has been created by autoCreateQuiz(..). This function is called automatically.

Parameters

Name	Type	Description
questionID	number	Question index.
htmlQuestionElementID	string	Identifier of the (global) HTML element that contains all questions.

Returns

boolean

Success.

Defined in

index.ts:59

---

backupQuestion

▸ backupQuestion(questionID): string

Creates a backup of a question which includes internal states (for example random variables).

resturns Stringified JSON object of the question state or null in case that an error occourred.

Parameters

Name	Type	Description
questionID	number	Question index.

Returns

string

Defined in

index.ts:113

---

createQuestion

▸ createQuestion(sellCode): number

Creates a new question.

Parameters

Name	Type	Description
sellCode	string	SELL source code of a single question.

Returns

number

Question index or -1 in case of errors.

Defined in

index.ts:93

---

createQuestionFromBackup

▸ createQuestionFromBackup(questionBackupStr): number

Creates a new question from a question backup (refer to function backupQuestion(..)).

Parameters

Name	Type
questionBackupStr	string

Returns

number

Question index or -1 in case of errors.

Defined in

index.ts:104

---

disableInputFields

▸ disableInputFields(questionID): boolean

Disables all input field HTML elements for editing.

Parameters

Name	Type	Description
questionID	number	Question index.

Returns

boolean

Success.

Defined in

index.ts:246

---

enableInputFields

▸ enableInputFields(questionID): boolean

Enables all input field HTML elements for editing.

Parameters

Name	Type	Description
questionID	number	Question index.

Returns

boolean

Success.

Defined in

index.ts:237

---

evaluateQuestion

▸ evaluateQuestion(questionID): boolean

Evaluates the student answers of a question. This function does NOT read and write HTML elements. Also refer to functions "readStudentAnswersFromHtmlElements" and "writeFeedbackToHtmlElements".

Parameters

Name	Type	Description
questionID	number	Question index.

Returns

boolean

Success.

Defined in

index.ts:177

---

getErrorLog

▸ getErrorLog(): string

Gets the error log for the last created question.

Returns

string

Error log.

Defined in

index.ts:130

---

getFeedbackText

▸ getFeedbackText(questionID): string

Gets the feedback text of an already evaluated question.

Parameters

Name	Type	Description
questionID	number	Question Index.

Returns

string

Success.

Defined in

index.ts:216

---

getQuestionBody

▸ getQuestionBody(questionID): string

Gets the question body.

Parameters

Name	Type	Description
questionID	number	Question index.

Returns

string

Body as HTML code or an empty string, if the question does not exist.

Defined in

index.ts:151

---

getQuestionInputFields

▸ getQuestionInputFields(questionID): [{ [id: string]: string; }]

Gets the input fields of a question. *

Parameters

Name	Type	Description
questionID	number	Question index.

Returns

[{ [id: string]: string; }]

Array of dictionaries with entries "element_id" for the HTML element identifier, "element_type" for the HTML element type (refer to enum SellInputElementType in file quiz.js) and "solution_variable_id" the identifier of the corresponding soluion variable.

Defined in

index.ts:122

---

getQuestionTitle

▸ getQuestionTitle(questionID): string

Gets the question title.

Parameters

Name	Type	Description
questionID	number	Question index.

Returns

string

Title as HTML code or an empty string, if the question does not exist.

Defined in

index.ts:139

---

getScore

▸ getScore(questionID): number

Gets the evaluation score of an already evaluted question.

Parameters

Name	Type	Description
questionID	number	Question Index.

Returns

number

Score in range [0, 1]

Defined in

index.ts:228

---

readStudentAnswersFromHtmlElements

▸ readStudentAnswersFromHtmlElements(questionID): boolean

Reads student answers from HTML elements. Also refer to functions "evaluateQuestion" and "writeFeedbackToHtmlElements".

Parameters

Name	Type	Description
questionID	number	Question index.

Returns

boolean

Success.

Defined in

index.ts:186

---

refreshMatrixDimensions

▸ refreshMatrixDimensions(questionID, matrixId, deltaRows, deltaCols): boolean

Updates the number of rows and columns of a matrix input. Thes function is mainly called internally.

Parameters

Name	Type	Description
questionID	number	Question index.
matrixId	string	-
deltaRows	number	Number of rows added (subtracted).
deltaCols	number	Number of columns added (subtracted).

Returns

boolean

Success.

Defined in

index.ts:267

---

refreshQuestion

▸ refreshQuestion(questionID): boolean

Refreshes the HTML elements of a questions. This is mainly required for matrices that can be resized by students. This function is mainly called internally.

Parameters

Name	Type	Description
questionID	number	Question index.

Returns

boolean

Success.

Defined in

index.ts:255

---

reset

▸ reset(): void

Remove all questions.

Returns

void

Defined in

index.ts:28

---

setGenerateInputFieldHtmlCode

▸ setGenerateInputFieldHtmlCode(enable?): void

Enables (or disables) the generation of HTML code for input and feedback element.

Parameters

Name	Type	Default value	Description
enable	boolean	true	If false, then getQuestionBody() returns HTML code that includes only placeholders for input and feedback fields. Placeholders have the form '$$ID', where ID can be obtained by calling getQuestionInputFields().

Returns

void

Defined in

index.ts:84

---

setLanguage

▸ setLanguage(langID): void

Sets the language for text outputs. Default is "en" := English.

Parameters

Name	Type	Description
langID	string	Language identifier (one of {"en", "de"}).

Returns

void

Defined in

index.ts:76

---

setQuestionHtmlElement

▸ setQuestionHtmlElement(questionID, element): boolean

Sets the HTML element that contains the question body (Alternatively, the element can also be a parent element of the question body). This function must be called once before calling "readStudentAnswersFromHtmlElements" or "writeFeedbackToHtmlElements".

Parameters

Name	Type	Description
questionID	number	Question index.
element	HTMLElement	HTML element that contains the question body.

Returns

boolean

Success.

Defined in

index.ts:164

---

setStudentAnswerManually

▸ setStudentAnswerManually(questionID, solutionVariableID, answerStr): boolean

Sets a student answer string manually. Also refer to functions "getInputElements" and "backupQuestion"

Parameters

Name	Type	Description
questionID	number	Question index.
solutionVariableID	string	-
answerStr	string	Answer string in ASCII-math encoding (e.g. "a+bi" for complex numbers, "[a,b,c]" for vectors, "[[a,b],[c,d]]" for matrices).

Returns

boolean

Success.

Defined in

index.ts:197

---

writeFeedbackToHtmlElements

▸ writeFeedbackToHtmlElements(questionID): boolean

Writes feedback to HTML elements. Also refer to functions "evaluateQuestion" and "readStudentAnswersFromHtmlElements".

Parameters

Name	Type	Description
questionID	number	Question index.

Returns

boolean

Success.

Defined in

index.ts:206

Language Grammar

sell =
  title { code | text };
code =
  "§CODE_START" { (code_prop | code_hint | assign) "\n" } "§CODE_END";
code_prop =
  "input" ("rows"|"cols") ":=" ("resizeable"|"static");
code_hint =
  "?" text;
assign =
    ID {"," ID} (":="|"=") expr
  | ID {"," ID} "in" (matrix_def | set | expr)
  | ID "[" expr "," expr "]" (":="|"=") expr
  | ID "[" expr "," expr "]" "in" (matrix_def | set | expr)
  | ID "(" ID {"," ID} ")" (":="|"=") symbolic_term;
expr =
  or;
or =
  and [ "or" and ];
and =
  equal [ "and" equal ];
equal =
  compare [ ("=="|"!=") compare ];
compare =
  add [ ("<="|"<"|">="|">") add ];
add =
  mul { ("+"|"-") mul };
mul =
  pow { ("*"|"/"|"mod") pow };
pow =
  unary { ("^") unary };
unary = (
    "-" unary;
  | INT
  | "true" | "false"
  | "not" unary
  | "i" | "j" | "T"
  | function_call
  | ID
  | "..."
  | matrix
  | "(" expr ")"
) [ factorial ];
matrix =
  "[" "[" expr {"," expr} "]" { "," "[" expr {"," expr} "]" } "]";
function_call =
  ("abs"|"binomial"|"integrate"|"conj"|"sqrt"|"xgcd"|"det"|"rank"|"inv"
     |"eye"|"eigenvalues_sym"|"triu"|"sin"|"cos"|"asin"|"acos"|"tan"
     |"atan"|"norm2"|"dot"|"cross"|"linsolve"| "is_zero")
  ID "(" [ expr {"," expr} ] ")";
factorial =
  "!";
matrix_def =
  "MM" "(" expr "x" expr "|" expr [ {"," ("invertible"|"symmetric")} ] ")";
set =
  "{" [ expr { "," expr } ] "}";
symbolic_term =
  symbolic_term_add;
symbolic_term_expr =
  symbolic_term_add;
symbolic_term_add =
  symbolic_term_mul { ("+"|"-") symbolic_term_mul };
symbolic_term_mul =
  symbolic_term_pow { ("*"|"/") symbolic_term_pow };
symbolic_term_pow =
  symbolic_term_unary { "^" symbolic_term_unary };
symbolic_term_unary =
    "(" symbolic_term_expr ")"
  | INT ["!"]
  | FLOAT
  | ("exp"|"sin"|"cos") "(" symbolic_term_expr ")"
  | "diff" "(" symbolic_term_expr "," ID  ")"
  | ID
  | ID "(" [ expr { "," epxr } ] ")"
  | "-" symbolic_term_pow;
title =
  { ID | "#" ID | MISC } "\n";
text =
  { single_multiple_choice | itemize | inline_listing | listing
    | inline_math | im_input | ID | MISC };
itemize =
  "*";
single_multiple_choice =
    "(" ("x"|expr) ")"
  | "[" ("x"|expr) "]";
inline_listing =
  "`" { MISC } "`";
listing =
  "```" { MISC } "```";
inline_math =
  "$" { im_expr } "$";
im_expr =  /*similar to ASCII math*/
  im_list;
im_list =
  im_assign { (","|":"|"->"|"|->") } im_assign;
im_assign =
  im_other_binary_op "=" im_other_binary_op;
im_other_binary_op =
  im_relational { ("in"|"notin"|"uu"|"^^"|"vv"|"@") } im_relational;
im_relational =
  im_add { ("<"|"<="|">"|">="|"!=") im_add };
im_add =
  im_mul { ("+"|"-") im_mul };
im_mul =
  im_pow { ("*"|"/") im_pow };
im_pow =
  im_unary { "^" im_unary };
im_unary = (
    im_input
  | "text" "(" { MISC } ")"
  | "augmented" "(" ID "|" ID ")"
  | ("sum"|"prod"|"lim"|"int") [ "_" expr ] [ "^" expr ]
  | "RR" | "ZZ" | "QQ" | "CC"
  | "oo" | "infty"
  | "equiv" | "mod"
  | "EE" | "AA"
  | "dx" | "dy" | "dz"
  | "bar" im_unary
  | "-" unary
  | " "
  | INT | FLOAT
  | ID
  | ID "[" (INT|":") "," (INT|":") "]"
  | "\"" ID "\""
  | "(" im_expr ")"
  | "{" { im_expr } "}"
  | "|"
  | "\"
  | "\\"
  | "..."
  | im_matrix
) [ "!" | {"'"} ];
im_matrix =
    "["        "[" im_expr {"," im_expr} "]"
         { "," "[" im_expr {"," im_expr} "]" } "]";
  | "("        "(" im_expr {"," im_expr} "]"
         { "," "[" im_expr {"," im_expr} ")" } ")";
im_input =
  "#" [ "[" "diff" ID "]" ] (
      ID
    | "\"" (ID|INT) { "|" (ID|INT) } "\""    /* gap question text */
  );