Skip to main content

module lang::rascal::tutor::Compiler

rascal-0.40.13-BOOT2
rascal-tutor-0.19.9

compiles .rsc and .md files to markdown by executing Rascal-specific code and inlining its output

Usage​

import lang::rascal::tutor::Compiler;

Dependencies​

import Message;
import Exception;
import IO;
import String;
import Node;
import List;
import Relation;
import Location;
import ParseTree;
import util::Reflective;
import util::FileSystem;
import util::Monitor;
import ValueIO;
import lang::yaml::Model;
import lang::rascal::tutor::repl::TutorCommandExecutor;
import lang::rascal::tutor::apidoc::GenerateMarkdown;
import lang::rascal::tutor::apidoc::ExtractInfo;
import lang::rascal::tutor::Indexer;
import lang::rascal::tutor::Names;
import lang::rascal::tutor::Output;
import lang::rascal::tutor::Includer;
import lang::rascal::\syntax::Rascal;

Description​

This compiler collects .rsc files and .md files from a PathConfig's srcs folders.

Every .rsc file is compiled to a .md file with an outline of the declarations contained in the file and the contents of the @synopsis, @description, @pitfalls, @benefits, @examples tags with those declarations. @doc is also supported for backward compatibility's purposes. The resulting markdown is processed by the rest of the compiler, as if written by hand.

Every .md file is scanned for rascal-shell between triple backticks elements. The contents between the backticks are executed by a private Rascal REPL and the output is captured in different ways. Normal IO via stderr and stdout is literally printed back and HTML or image output is inlined into the document.

For (nested) folders in the srcs folders, which do not contain an index.md file, or a <name>.md file where the name is equal to the name of the current folder, a fresh index.md file is generated.

function defaultCompile​

void defaultCompile(bool clean=false)

function compile​

compiles each pcfg.srcs folder as a course root

list[Message] compile(PathConfig pcfg, CommandExecutor exec = createExecutor(pcfg))

function storeImportantProjectMetaData​

void storeImportantProjectMetaData(PathConfig pcfg)

function generatePackageIndex​

void generatePackageIndex(PathConfig pcfg)

function compileCourse​

list[Message] compileCourse(loc root, PathConfig pcfg, CommandExecutor exec, Index ind)

function compile​

list[Message] compile(loc src, PathConfig pcfg, CommandExecutor exec, Index ind, int sidebar_position=-1)

function compileDirectory​

list[Message] compileDirectory(loc d, PathConfig pcfg, CommandExecutor exec, Index ind, int sidebar_position=-1)

function generateIndexFile​

list[Message] generateIndexFile(loc d, PathConfig pcfg, int sidebar_position=-1)

function compileRascalFile​

Translates Rascal source files to docusaurus markdown.

list[Message] compileRascalFile(loc m, PathConfig pcfg, CommandExecutor exec, Index ind)

function createDetailsList​

This uses another nested directory listing to construct information for the TOC embedded in the current document.

list[str] createDetailsList(loc m, PathConfig pcfg)

function compileMarkdownFile​

list[Message] compileMarkdownFile(loc m, PathConfig pcfg, CommandExecutor exec, Index ind, int sidebar_position=-1)

function compileMarkdown​

list[Output] compileMarkdown(loc m, PathConfig pcfg, CommandExecutor exec, Index ind, int sidebar_position=-1)

function compileMarkdown​

Skip double quoted blocks

list[Output] compileMarkdown([str first:/^\s*``````/, *block, str second:/^``````/, *str rest], int line, int offset, PathConfig pcfg, CommandExecutor exec, Index ind, list[str] dtls, int sidebar_position=-1)

function compileMarkdown​

Include Rascal code from Rascal source files

list[Output] compileMarkdown([str first:/^\s*```rascal-include<rest1:.*>$/, *str components, /^\s*```/, *str rest2], int line, int offset, PathConfig pcfg, CommandExecutor exec, Index ind, list[str] dtls, int sidebar_position=-1)

function compileMarkdown​

Include Rascal REPL commands literally and execute them as side-effects in the REPL without reporting output unless there are unexpected errors.

list[Output] compileMarkdown([str first:/^\s*```rascal-commands<rest1:.*>$/, *str block, /^\s*```/, *str rest2], int line, int offset, PathConfig pcfg, CommandExecutor exec, Index ind, list[str] dtls, int sidebar_position=-1)

function compileMarkdown​

execute rascal-shell blocks on the REPL

list[Output] compileMarkdown([str first:/^\s*```rascal-shell<rest1:.*>$/, *block, /^\s*```/, *str rest2], int line, int offset, PathConfig pcfg, CommandExecutor exec, Index ind, list[str] dtls, int sidebar_position=-1)

function compileMarkdown​

execute rascal-shell-prepare blocks on the REPL

list[Output] compileMarkdown([str first:/^\s*```rascal-prepare<rest1:.*>$/, *block, /^\s*```/, *str rest2], int line, int offset, PathConfig pcfg, CommandExecutor exec, Index ind, list[str] dtls, int sidebar_position=-1)

function compileMarkdown​

inline an itemized list of details (collected from the details YAML section in the header)

list[Output] compileMarkdown([str first:/^\s*\(\(\(\s*TOC\s*\)\)\)\s*$/, *str rest], int line, int offset, PathConfig pcfg, CommandExecutor exec, Index ind, list[str] dtls, int sidebar_position=-1)

function compileMarkdown​

inline an itemized list of details (collected from the details YAML section in the header)

list[Output] compileMarkdown([str first:/^\s*\(\(\(\s*TODO<msg:[^\)]*>\s*\)\)\)\s*$/, *str rest], int line, int offset, PathConfig pcfg, CommandExecutor exec, Index ind, list[str] dtls, int sidebar_position=-1)

function compileMarkdown​

Inline example files literally, in Rascal loc notation, but do not compile further from there. Works only if positioned on a line by itself.

list[Output] compileMarkdown([str first:/^\s*\(\(\|<url:[^\|]+>\|\)\)\s*$/, *str rest], int line, int offset, PathConfig pcfg, CommandExecutor exec, Index ind, list[str] dtls, int sidebar_position=-1)

function compileMarkdown​

implement subscript syntax for [aeh-pr-vx] (the subscript alphabet is incomplete in unicode)

list[Output] compileMarkdown([/^<prefix:.*>~<digits:[aeh-pr-vx0-9\(\)+\-]+>~<postfix:.*>$/, *str rest], int line, int offset, PathConfig pcfg, CommandExecutor exec, Index ind, list[str] dtls, int sidebar_position=-1)

function compileMarkdown​

detect unsupported subscripts

list[Output] compileMarkdown([/^<prefix:.*>~<digits:[^~]*[^aeh-pr-vx0-9]+[^~]*>~<postfix:.*>$/, *str rest], int line, int offset, PathConfig pcfg, CommandExecutor exec, Index ind, list[str] dtls, int sidebar_position=-1)

function compileMarkdown​

Resolve labeled links

list[Output] compileMarkdown([/^<prefix:.*>\[<title:[^\]]*>\]\(\(<link:[A-Za-z0-9\-\ \t\.\:]+>\)\)<postfix:.*>$/, *str rest], int line, int offset, PathConfig pcfg, CommandExecutor exec, Index ind, list[str] dtls, int sidebar_position=-1)

function compileMarkdown​

Resolve unlabeled links

default list[Output] compileMarkdown([/^<prefix:.*>\(\(<link:[A-Za-z0-9\-\ \t\.\:]+>\)\)<postfix:.*>$/, *str rest], int line, int offset, PathConfig pcfg, CommandExecutor exec, Index ind, list[str] dtls, int sidebar_position=-1)

function compileMarkdown​

extract what's needed from the header and print it back, also set sidebar_position

list[Output] compileMarkdown([a:/^\-\-\-\s*$/, *str header, b:/^\-\-\-\s*$/, *str rest], int line, int offset, PathConfig pcfg, CommandExecutor exec, Index ind, list[str] dtls, int sidebar_position=-1)

function compileMarkdown​

Removes empty sections in the middle of a document

list[Output] compileMarkdown([str first:/^\s*#+\s+<title:.*>$/, *str emptySection, nextSection:/^\s*#+\s+.*$/, *str rest], int line, int offset, PathConfig pcfg, CommandExecutor exec, Index ind, list[str] dtls, int sidebar_position=-1)

function compileMarkdown​

Divide the work over sections to avoid stackoverflows

list[Output] compileMarkdown([str first:/^\s*#+\s+<title:.*>$/, *str body, nextSection:/^\s*#+\s+.*$/, *str rest], int line, int offset, PathConfig pcfg, CommandExecutor exec, Index ind, list[str] dtls, int sidebar_position=-1)

function compileMarkdown​

Removes empty sections at the end of a document

list[Output] compileMarkdown([str first:/^\s*#+\s+<title:.*>$/, *str emptySection, /^\s*$/], int line, int offset, PathConfig pcfg, CommandExecutor exec, Index ind, list[str] dtls, int sidebar_position=-1)

function compileMarkdown​

this is when we have processed all the input lines

list[Output] compileMarkdown([], int _/*line*/, int _/*offset*/, PathConfig _, CommandExecutor _, Index _, list[str] _, int sidebar_position=-1)

function compileMarkdown​

all other lines are simply copied to the output stream

default list[Output] compileMarkdown([str head, *str tail], int line, int offset, PathConfig pcfg, CommandExecutor exec, Index ind, list[str] dtls, int sidebar_position=-1)

function compileRascalShell​

list[Output] compileRascalShell(list[str] block, bool allowErrors, bool isContinued, int lineOffset, int offset, PathConfig pcfg, CommandExecutor exec, Index _)

function compileRascalShellPrepare​

Prepare blocks run the REPL but show no input or output

list[Output] compileRascalShellPrepare(list[str] block, bool isContinued, int lineOffset, int offset, PathConfig pcfg, CommandExecutor exec, Index _)

function skipEmpty​

list[str] skipEmpty([/^s*$/, *str rest])

default list[str] skipEmpty(list[str] lst)

function filterErrors​

str filterErrors(str errorStream)

list[str] filterErrors([/^warning, ambiguity/, *str rest])

list[str] filterErrors([/^Generating parser/, *str rest])

default list[str] filterErrors([str head, *str tail])

list[str] filterErrors([])

function length​

int length(list[str] lines)

int length(str line)