markio 0.2.6

Defines a format for representing I/O based programming questions and implements a parser for it.

The .markio format is a markdown-based format for representing IO based programming questions. This library consists in a parser and a processor for this format. It does not judge submissions by executing programming tasks and comparing inputs/outputs but it provides some data structures that makes the implementation of such a program much easier.

The syntax

Markio files are regular markdown files with a conventional structure used to represent an IO based programming question. The markio` parser processes the markdown source and returns a dictionary with the document structure. A .markio markdown file begins like this:

Hello Person
============

    Author: Chips Chipperfield <[e-mail]>
    Slug: hello-person
    Timeout: 1s
    Tags: #begginer #basic

A program that prints a personalized greeting to the user.

The document must start with an h1-level title corresponding to the question title name. The title may be followed by an optional block with meta data. Each metadata field is optional and only the fields shown above are supported. The title and metadata information are accessible from the parsed structure directly in the ‘title’, ‘author’, ‘slug’, etc keys.

Bellow that, it is possible to specify a single-paragraph short description. This description is available both in the ‘short_description’ attribute of the parsed structure.

The file than consists of various h2-sections. Most of these sections are accessed in the parsed dictionary as a lowercase version of their title names:

Description
-----------

Create a program that asks the user name and prints the message
"Hello, <name>!" on the screen. The program output should be **exactelly**
as requested, i.e., you should use **exactely** the same case and pontuaction
marks as in the example string. You can assume that the input name is at
most 100 characters long.

### Inputs

A more thorough description of inputs.

### Outputs

Description of the desired outputs.

This obligatory section contains a long description text for the question. It accepts more or less arbitrary markdown text but all headings must be level 3 or above. The raw markdown can be accessed by the ‘description’ key in the parsed structure.

Example
-------

    What is your name? <John>
    Hello John!

The ‘example’ section must contain a single block of .iospec data. For more info check http://gihub.com/fabiommendes/iospec. IoSpec is a simple language for specifying a sequence of inputs and outputs in a program interaction. Users should avoid using input-only specifications in this section.

Although these examples might be used to judge submissions, the content of this section is displayed to the student. Tests designed to judge a program should go in the “Tests” section.

Tests
-----

    @input Mary
    @input mary
    @input Long Name
    @input $string[<100]

This section also contains a single block of .iospec data with the various tests used to judge submissions. Input-only interactions are allowed and encouraged.

Placeholder
-----------

    A paragraph with the defaut comments that should be included in the
    placeholder source.

This optional section is used to store the default comment string that should be placed as the placeholder text in the <textarea> used in submission forms.

Answer Key (Python3)
-------------------

    # Indentation is necessary to mark source as a code block in markdown!

    name = input('What is your name? ')
    print('Hello, %s!' % name)

Answer Key (C)
--------------

    #include<stdio.h>

    main() {
        char buffer[101];

        puts("What is your name? ");
        scanf("%s", buffer);
        printf("Hello, %s!\n", buffer);
    }

This section defines a reference program that can be used to compute the correct input/output sequences from the tests iospec. The reference solution can be given in more than one language (which is specified inside parenthesis). Markio do not grade or run these programs directly, however other graders may use the redundant information to cross-check responses.

The source code can be accessed at parsed.answer_key['python3'].

Placeholder (Python3)
---------------------

    # Type here your response. Remember to use the print() and input()
    # functions

Finally, it is possible to define a per-language placeholder text. This overrides the default placeholder input for a single specific language.

The placeholder code can be accessed at parsed.placehoder['python3'].

TLE Answer (python3)
--------------------

import time

name = input('What is your name? ')
time.sleep(1)
print('Hello, %s!' % name)

The TLE (time limit exceeded) answer is used to calibrate the timeout for submissions in a specific language. This section should contain the implementation of an inefficient algorithm that the judge wants to disallow. This is a robust method to specify the timeout that is calibrated to the host machine processing power and is based on a well defined criteria rather than an arbitrarily chosen duration.

Translations (not ready)

Many programming quizzes involve internationalization-agnostic interactions. They can be easily translated to different human languages since only the user facing strings need to be adapted. If the input/output strings themselves need to be translated, it is necessary to create a whole new markio file.

The translated sections can be put inside the main markio file or put on a separate file. In the first case, it is necessary to append the language code inside parenthesis after the section number (ex.: Description (pt-BR)). The placeholder text should be Placeholder (python3, pt-BR). The title, short description and slug should be placed as metadata:

Title (pt-BR): Olá Pessoa
Slug (pt-BR): ola-pessoa
Short description (pt-BR): Um programa que imprime uma saudação personalizada.

The alternative translation file should be named as <name>.pt_BR.markio. The markio parser accepts translated section names for many languages. The user may choose to use the translated values or their english counterparts.

The default language is english. If the user does not need an english version of the question, the main markio io file will be the same as a translation file. In that case the filename is expected to be something like my-file.pt_BR.markio and all sections should be present. The markio parser understands translated section names for a few languages. If your language is not present, please contribute with translations!

Acessory files (not ready)

The content of all sections of a markio source that contains only a block of source code (basically all sections but the title and description) can rather be put inside a separate file. If the markio parser finds a file named as my-file.answer_key.c in the same directory as the main source, it will automatically fill the contents of the Answer Key (C). If both an external source and the section content are present, the external file takes precedence.

Command line (not ready)

This package installs the markio command that can perform several operations on markio files.

…