CAT-SOOP API: catsoop.language

Handling of the CAT-SOOP specification language(s): Markdown, XML, and Python

The real goal of parsing of a page's source is to convert it back to the original Python specification format. Markdown is translated to XML, which is translated to Python. The overall flow when parsing a page is:

  1. If the content file is in Markdown, parse it down to HTML.
  2. If the content file was in Markdown or XML, parse it down to Python (stripping out comments and seperating <question> tags into appropriate calls to catsoop.tutor.question).

View Source

Members

  • catsoop.language.Comment (type, lines 1481-1485)

    An HTML comment <https://dev.w3.org/html5/spec-LC/syntax.html#comments>_ or XML comment <https://www.w3.org/TR/REC-xml/#sec-comments>_.

 

  • catsoop.language.DIAGRAM_START (Pattern)

 

  • catsoop.language.Doctype (type, lines 1495-1532)

    A document type declaration <https://www.w3.org/TR/REC-xml/#dt-doctype>_.

 

  • catsoop.language.get_python_output (function, lines 534-632)

    Helper function. Evaluate code in the given environment, and return its output, if any.

    Makes use of a special variable cs___WEBOUT, which is a file-like object. Any data written to cs___WEBOUT will be returned. Overwrites print in the given environment so that it outputs to cs___WEBOUT instead of to stdout.

    Parameters:

    • context: the context associated with this request
    • code: a strin containing the Python code to be executed
    • variables: a dictionary representing the environment in which the code should be executed

    Optional Parameters:

    • line_offset (default 0): the offset, in lines, of this code's <python> tag from the top of the source file; used in case an error occurs, to try to point authors to the right location in the original source file

    Returns: a string containing any values written to cs___WEBOUT

 

  • catsoop.language.handle_custom_tags (function, lines 765-1114)

    Process custom HTML tags

    This function begins by calling cs_course_handle_custom_tags on the input text, so that courses can implement their own custom HTML tags. This function is responsible for handling the following custom tags:

    • <chapter>, <section>, <subsection>, etc.
    • <chapter*>, <section*>, etc.
    • <ref>
    • <tableofcontents/>
    • <footnote>
    • <showhide>
    • <math> and <displaymath>

    It also takes care of making sure links, images, etc are referencing real URLs instead of internal URLs, and also for making sure that syntax highlighting is approprtiately applied for code snippets.

    It is not responsible for handling Python tags or includes (which are handled elsewhere, before this function is invoked).

    Parameters:

    • context: the context associated with this request
    • text: a string containing the raw HTML source of the page, after running through the handler

    Returns: a string representing the updated HTML after custom tags have been handled

 

  • catsoop.language.handle_includes (function, lines 677-731)

    Handles all <include> tags in the provided text, replacing them with the contents of the files they reference.

    Parameters:

    • context: the context associated with this request
    • text: a string containing the raw HTML source of the page

    Returns: a string representing the updated HTML after includes have been handled

 

  • catsoop.language.handle_math_tags (function, lines 1117-1147)

    Handles <math> and <displaymath> tags, replacing them with <span> and <div> elements with appropriate classes so the Javascript math renderer can find them.

    Parameters:

    • context: the context associated with this request
    • text: a string containing the raw HTML source of the page

    Returns: a string representing the updated HTML after math tags have been handled

 

  • catsoop.language.handle_python_tags (function, lines 734-762)

    Process all Python-related custom tags.

    Firstly, each @{} is translated into an appropriate <printf> tag. Then, <python> and <printf> tags are handled sequentially, each being replaced with its output after having its code evaluated in the current context (using catsoop.language.get_python_output).

    Parameters:

    • context: the context associated with this request
    • text: a string containing the raw HTML source of the page

    Returns: a string representing the updated HTML after python tags have been handled

 

  • catsoop.language.md_pre_handle (function, lines 195-224)

    Translate the value in cs_content from Markdown to HTML

    Parameters:

    • context: the context associated with this request (from which cs_content is taken)

    Optional Parameters:

    • xml (default True): whether catsoop.language.xml_pre_handle should be invoked after translating to HTML

    Returns: None

 

  • catsoop.language.py_pre_handle (function, lines 227-242)

    'Pre-handler' for Python.

    This function exists to mirror the interface of md_pre_handle and xml_pre_handle, but it does nothing (since the cs_problem_spec does not need any additional processing at this point).

    Parameters:

    • context: the context associated with this request (from which cs_content is taken)

    Returns: None

 

  • catsoop.language.source_transform_string (function, lines 429-449)

    Convert the given string to HTML, based on the syntax associated with the type of the current content file.

    If the content file is Markdown, this will translate the string into HTML and handle custom tags. If the content file is in HTML or Python, custom tags will be handled, but no other translation will occur.

    Parameters:

    • context: the context associated with this request
    • s: the string to be translated to HTML

    Returns: the translated string

 

  • catsoop.language.xml_pre_handle (function, lines 84-188)

    Translate the value in cs_content from XML to Python, storing the result as cs_problem_spec in the given context.

    This function mostly strips out comments and converts <question> tags into appropriate calls to catsoop.tutor.question.

    Parameters:

    • context: the context associated with this request (from which cs_content is taken)

    Returns: None