[Home] [MBL Reference] [SMPL Reference]

Mathe:Buddy Compiled Language (MBCL)

2023-02-24

NOTE This reference guide is OUTDATED. We will rewrite it later. Up to now, refer to directory /lib/mbcl/ in the repository.

This document describes the syntax of the mathe:buddy compiled language (MBCL), which can be used to express mathematical based online courses technically.

Introduction

MBCL is a JSON-based format defined for the mathe:buddy App. Each MBCL-JSON file stores a complete course, defined by the Mathe:Buddy Language (MBL).

MBL is intended to be used by course creators, i.e. humans, while MBCL is a pure computer language.

This document assumes detailed knowledge about MBL. Definitions are not repeated here.

The reference compiler to translate MBL to MBCL can be found on GitHub.

JSON Specification

Intrinsic Data Types

We use the following intrinsic data types.

Custom JSON Datatype Definition Language

We use the following custom notation instead of JSON-schema in this document to denote the structure of data.

(Note: JSON-schema is NOT used, since its notation is rather long s.t. the context can only be grasped hardly.)

Courses

A course represents the root of an MBCL file. It contains a set of chapters.

MBCL_Course = {
  "debug": "No" | "Chapter" | "Level",
  "title": STRING,
  "author": STRING,
  "mbclVersion": INTEGER,
  "dateModified": UNIX_TIMESTAMP,
  "chapters": MBCL_Chapter[]
};

Example:

{
  "debug_level": "No",
  "title": "higher math 1",
  "author": "TH Koeln",
  "mbclVersion": 1,
  "dateModified": 1669712632,
  "chapters": []
}

Chapters

A chapter consists of a set of levels.

MBCL_Chapter = {
  "fileId": STRING,
  "title": STRING,
  "label": STRING,
  "author": STRING
  "posX": INTEGER,
  "posY": INTEGER,
  "requires": IDENTIFIER<MBCL_Chapter.file_id>[],
  "units": MBCL_Unit[],
  "levels": MBCL_Level[]
};

Example:

{
  "file_id": "cmplx",
  "title": "Complex Numbers",
  "label": "cmplx",
  "author": "Knuth",
  "pos_x": 0,
  "pos_y": 0,
  "requires": [],
  "units": [],
  "levels": []
}

Levels

A level defines a part of course, consisting of e.g. text, exercises and games.

MBCL_Level = {
  "fileId": STRING,
  "title": STRING,
  "posX": INTEGER,
  "posY": INTEGER,
  "requires": IDENTIFIER<MBCL_Level.file_id>[],
  "items": MBCL_LevelItem[]
};
MBCL_LevelItem = {
  "type": "AlignCenter"
    | "AlignLeft"
    | "AlignRight"
    | "BoldText"
    | "Color"
    | "DefAxiom"
    | "DefClaim"
    | "DefConjecture"
    | "DefCorollary"
    | "DefDefinition"
    | "DefIdentity"
    | "DefLemma"
    | "DefParadox"
    | "DefProposition"
    | "DefTheorem"
    | "Enumerate"
    | "EnumerateAlpha"
    | "Equation"
    | "Error"
    | "Example"
    | "Exercise"
    | "Figure"
    | "InlineMath"
    | "InputField"
    | "ItalicText"
    | "Itemize"
    | "LineFeed"
    | "MultipleChoice"
    | "MultipleChoiceOption"
    | "NewPage"
    | "Paragraph"
    | "Reference"
    | "Section"
    | "SingleChoice"
    | "SingleChoiceOption"
    | "Span"
    | "SubSection"
    | "SubSubSection"
    | "Table"
    | "Text"
    | "VariableReference",
  ?"title": STRING,
  ?"label": STRING,
  ?"error": STRING,
  ?"text": STRING,
  ?"id": STRING,
  ?"equationData": MBCL_EquationData,
  ?"exerciseData": MBCL_ExerciseData,
  ?"figureData": MBCL_FigureData,
  ?"tableData": MBCL_TableData,
  ?"inputFieldData": MBCL_InputFieldData,
  ?"singleOrMultipleChoiceOptionData": MBCL_SingleOrMultipleChoiceOptionData
};

Attention: title, label, error, text and id are stored only in case the string length is greater than zero.

!!!!! TODO: MUST UPDATE DOCUMENTATION STARTING FROM HERE !!!!!

UNIT = {
  "title": STRING,
  "levels": IDENTIFIER<LEVEL.file_id>[]
};

Sectioning

A title is used as level title. (Sub-)Sections subdivide a level.

SECTION = {
  "type": "section" | "subsection" | "subsubsection",
  "text": STRING,
  "label": IDENTIFIER
};

Paragraphs

A paragraph hierarchically defines a part of text, including format options and equations, alignment, enumerations etc.

TEXT = {
  "type": "paragraph" | "inline_math" | "bold" | "italic" | "itemize"
        | "enumerate" | "enumerate_alpha" | "span"
        | "align_left" | "align_center" | "align_right",
  "items": TEXT[]
} | {
  "type": "text",
  "value": STRING
} | {
  "type": "linefeed"
} | {
  "type": "color",
  "key": INTEGER
} | {
  "type": "reference",
  "label": IDENTIFIER<SECTION.label|BLOCK_ITEM.label>
} | {
  "type": "error",
  "message": STRING
};

The following example represents a paragraph containing an italic text    Hello, world \(x^2 + y^2\)!    that ends with a line feed.

{
  "type": "paragraph",
  "items": [
    {
      "type": "italic",
      "items": [
        { "type": "text", "value": "Hello, world" },
        { "type": "inline_math", "items": [{"type":"text","value":"x^2+y^2"}]}
        { "type": "text", "value": "!" }
      ]
    },
    {
      "type": "linefeed"
    }
  ]
}

Block Items

For example display style equations, figures and exercises are called block items. The following abstract type defines attributes that are common to all block items.

abstract(BLOCK_ITEM) = {
  abstract("type"): IDENTIFIER,
  "title": STRING,
  "label": IDENTIFIER
  "error": STRING
};

Attribute error is used to indicate syntax errors in the MBL definition.

Display Style Equations

A (numbered) equation is rendered in display style by the following object.

EQUATION extends BLOCK_ITEM = {
  "type": "equation",
  "value": STRING,
  "numbering": INTEGER,
  "options": EQUATION_OPTION[]
};
EQUATION_OPTION = "align_left" | "align_center" | "align_right" | "align_equals";

If attribute numbering is set to a negative value, the numbering is not displayed.

Definitions

A definition (and in the same way a theorem, lemma, …) is rendered as block. It may contain text and display-style equation items.

DEFINITION extends BLOCK_ITEM = {
  "type": "definition" | "theorem" | "lemma" | "corollary" | "proposition"
        | "conjecture" | "axiom" | "claim" | "identity" | "paradox",
  "items": DEFINITION_ITEM[]
};
DEFINITION_ITEM = EQUATION | TEXT;

Examples

EXAMPLE extends DEFINITION = {
  "type": "example"
};

Exercises

An exercise includes a set variables with values that can be used in the question text or as answers.

The attribute instance defines concrete values for each variable. Randomized questions may have multiple (distinct) instances.

EXERCISE extends BLOCK_ITEM = {
  "type": "exercise",
  "variables": {
    IDENTIFIER: EXERCISE_VARIABLE
  },
  "instances": EXERCISE_INSTANCE[],
  "text": EXERCISE_TEXT
};

Note: a label is created automatically, if none is provided.

Exercise text is extended to the following types:

EXERCISE_TEXT extends TEXT = {
  "type": "variable",
  "variable": IDENTIFIER<EXERCISE.VARIABLES>
} | {
  "type": "text_input",
  "input_id": UNIQUE_IDENTIFIER,
  "input_type": "int" | "real"
              | "complex_normal" | "complex_polar"
              | "int_set" | "int_set_n_args"
              | "vector" | "vector_flex"
              | "matrix" | "matrix_flex_rows" | "matrix_flex_cols" | "matrix_flex"
              | "term",
  "input_require": IDENTIFIER[],
  "input_forbid": IDENTIFIER[],
  "variable": IDENTIFIER<EXERCISE.VARIABLES>,
  "width": INTEGER
} | {
  "type": "choices_input",
  "input_id": UNIQUE_IDENTIFIER,
  "variable": IDENTIFIER<EXERCISE.VARIABLES>,
  "count": INTEGER
} | {
  "type": "multiple_choice" | "single_choice",
  "input_id": UNIQUE_IDENTIFIER,
  "items": EXERCISE_SINGLE_MULTIPLE_CHOICE_OPTION[]
};
EXERCISE_VARIABLE = {
  "type": "bool" | "int" | "int_set" | "real" | "real_set"
        | "complex" | "complex_set" | "vector" | "matrix" | "term"
};
EXERCISE_INSTANCE = {
  IDENTIFIER<EXERCISE.VARIABLES>: MATH_STRING
};
EXERCISE_SINGLE_MULTIPLE_CHOICE_OPTION = {
  "variable": IDENTIFIER<EXERCISE.VARIABLES>,
  "text": TEXT
};

Figures

A figure renders a graphics file, as well as an optional caption.

FIGURE extends BLOCK_ITEM = {
  "file_path": STRING,
  "data": STRING,
  "caption": MBL_TEXT,
  "options": FIGURE_OPTION[]
};
FIGURE_OPTION = "width_X";

Tables

A table renders tabular data.

TABLE extends BLOCK_ITEM = {
  "options": TABLE_OPTION[],
  "head": TABLE_ROW,
  "rows": TABLE_ROW[]
};
TABLE_ROW = {
  "columns": MBL_TEXT[];
}
TABLE_OPTION = "align_left" | "align_center" | "align_right";

Page Breaks

NEWPAGE = {
  "type": "new_page"
};

Errors

An error block is used for development purposes only. It is used, if a course developer defined a block type that is unknown (or unimplemented).

ERROR extends BLOCK_ITEM = {
  "type": "error",
  "message": STRING
};

Compressed Courses

The MBCL file size can be reduced by using LZ-based compression npm-package.

Author: Andreas Schwenk, TH Köln