@dodona/papyros 0.1.702 → 0.1.923-tar

package/dist/Papyros.d.ts

@@ -1,70 +1,135 @@
 import "./Papyros.css";
-import { Remote } from "comlink";
-import { Backend } from "./Backend";
-import { CodeEditor } from "./CodeEditor";
-import { InputManager, InputMode } from "./InputManager";
-import { PapyrosEvent } from "./PapyrosEvent";
+import { InputMode } from "./InputManager";
 import { ProgrammingLanguage } from "./ProgrammingLanguage";
 import { RenderOptions, ButtonOptions } from "./util/Util";
-import { StatusPanel } from "./StatusPanel";
+import { RunState, CodeRunner } from "./CodeRunner";
 import { OutputManager } from "./OutputManager";
-declare enum PapyrosState {
-    Loading = "loading",
-    Running = "running",
-    AwaitingInput = "awaiting_input",
-    Stopping = "stopping",
-    Ready = "ready"
-}
-declare class PapyrosStateManager {
-    state: PapyrosState;
-    statusPanel: StatusPanel;
-    get runButton(): HTMLButtonElement;
-    get stopButton(): HTMLButtonElement;
-    constructor(statusPanel: StatusPanel, onRunClicked: () => void, onStopClicked: () => void);
-    setState(state: PapyrosState, message?: string): void;
-    render(options: RenderOptions): HTMLElement;
-}
-interface PapyrosCodeState {
-    programmingLanguage: ProgrammingLanguage;
-    editor: CodeEditor;
-    backend: Remote<Backend>;
-    runId: number;
-}
+/**
+ * Configuration options for this instance of Papyros
+ */
 interface PapyrosConfig {
+    /**
+     * Whether Papyros is run in standAlone mode or embedded in an application
+     */
     standAlone: boolean;
+    /**
+     * The programming language to use
+     */
     programmingLanguage: ProgrammingLanguage;
+    /**
+     * The language to use
+     */
     locale: string;
+    /**
+     * The InputMode to use
+     */
     inputMode: InputMode;
 }
+/**
+ * Options for rendering Papyros
+ */
 interface PapyrosRenderOptions {
-    papyros?: RenderOptions;
-    code?: RenderOptions;
-    panel?: RenderOptions;
-    input?: RenderOptions;
-    output?: RenderOptions;
+    /**
+     * Options to render Papyros itself, only used in standAlone mode
+     */
+    standAloneOptions?: RenderOptions;
+    /**
+     * RenderOptions for the code editor
+     */
+    codeEditorOptions?: RenderOptions;
+    /**
+     * RenderOptions for the status panel in the editor
+     */
+    statusPanelOptions?: RenderOptions;
+    /**
+     * RenderOptions for the input field
+     */
+    inputOptions?: RenderOptions;
+    /**
+     * RenderOptions for the output field
+     */
+    outputOptions?: RenderOptions;
 }
+/**
+ * Class that manages multiple components to form a coding scratchpad
+ */
 export declare class Papyros {
-    stateManager: PapyrosStateManager;
-    codeState: PapyrosCodeState;
-    inputManager: InputManager;
+    /**
+     * Config used to initialize Papyros
+     */
+    config: PapyrosConfig;
+    /**
+     * Component to run code entered by the user
+     */
+    codeRunner: CodeRunner;
+    /**
+     * Component to handle output generated by the user's code
+     */
     outputManager: OutputManager;
-    constructor(programmingLanguage: ProgrammingLanguage, inputMode: InputMode);
-    get state(): PapyrosState;
+    /**
+     * Whether this instance has been launched
+     */
+    private launched;
+    /**
+     * Construct a new Papyros instance
+     * @param {PapyrosConfig} config Properties to configure this instance
+     */
+    constructor(config: PapyrosConfig);
+    /**
+     * @return {RunState} The current state of the user's code
+     */
+    getState(): RunState;
+    /**
+     * Launch this instance of Papyros, making it ready to run code
+     * @return {Promise<Papyros>} Promise of launching, chainable
+     */
     launch(): Promise<Papyros>;
+    /**
+     * Set the used programming language to the given one to allow editing and running code
+     * @param {ProgrammingLanguage} programmingLanguage The language to use
+     */
     setProgrammingLanguage(programmingLanguage: ProgrammingLanguage): Promise<void>;
+    /**
+     * @param {string} code The code to use in the editor
+     */
     setCode(code: string): void;
+    /**
+     * @return {string} The currently written code
+     */
     getCode(): string;
-    startBackend(): Promise<void>;
-    static fromElement(config: PapyrosConfig, renderOptions: PapyrosRenderOptions): Papyros;
-    configureInput(allowReload: boolean, serviceWorkerRoot?: string, serviceWorkerName?: string): Promise<boolean>;
-    onError(e: PapyrosEvent): void;
-    onInput(e: PapyrosEvent): Promise<void>;
-    onMessage(e: PapyrosEvent): void;
-    runCode(): Promise<void>;
-    stop(): Promise<void>;
-    render(standAlone: boolean, programmingLanguage: ProgrammingLanguage, locale: string, renderOptions: PapyrosRenderOptions): void;
+    /**
+     * Configure how user input is handled within Papyros
+     * By default, we will try to use SharedArrayBuffers
+     * If this option is not available, the optional arguments become relevant
+     * They are needed to register a service worker to handle communication between threads
+     * @param {string} serviceWorkerRoot URL for the directory where the service worker lives
+     * @param {string} serviceWorkerName The name of the file containing the script
+     * @param {boolean} allowReload Whether we are allowed to force a reload of the page
+     * This allows using SharedArrayBuffers without configuring the HTTP headers yourself
+     * @return {Promise<boolean>} Promise of configuring input
+     */
+    configureInput(serviceWorkerRoot?: string, serviceWorkerName?: string): Promise<boolean>;
+    /**
+     * Render Papyros with the given options
+     * @param {PapyrosRenderOptions} renderOptions Options to use
+     */
+    render(renderOptions: PapyrosRenderOptions): void;
+    /**
+     * Add a button to the status panel within Papyros
+     * @param {ButtonOptions} options Options to render the button with
+     * @param {function} onClick Listener for click events on the button
+     */
     addButton(options: ButtonOptions, onClick: () => void): void;
+    /**
+     * @param {ProgrammingLanguage} language The language to check
+     * @return {boolean} Whether Papyros supports this language by default
+     */
     static supportsProgrammingLanguage(language: string): boolean;
+    /**
+     * Convert a string to a ProgrammingLanguage
+     * @param {string} language The language to convert
+     * @return {ProgrammingLanguage | undefined} The ProgrammingLanguage, or undefined if not supported
+     */
     static toProgrammingLanguage(language: string): ProgrammingLanguage | undefined;
 }
 export {};

package/dist/ProgrammingLanguage.d.ts

@@ -1,3 +1,6 @@
+/**
+ * String enum representing programming languages supported by Papyros
+ */
 export declare enum ProgrammingLanguage {
     Python = "Python",
     JavaScript = "JavaScript"

package/dist/RunListener.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Interface for components that maintain state based on runs of code
+ */
+export interface RunListener {
+    /**
+     * Inform this listener that a new run started
+     */
+    onRunStart(): void;
+    /**
+     * Inform this listener that the run ended
+     */
+    onRunEnd(): void;
+}

package/dist/examples/PythonExamples.d.ts

@@ -8,4 +8,5 @@ export declare const PYTHON_EXAMPLES: {
     Unicode: string;
     Files: string;
     Matplotlib: string;
+    Sleep: string;
 };

package/dist/input/BatchInputHandler.d.ts

@@ -0,0 +1,31 @@
+import { InputMode } from "../InputManager";
+import { RenderOptions } from "../util/Util";
+import { UserInputHandler } from "./UserInputHandler";
+export declare class BatchInputHandler extends UserInputHandler {
+    /**
+     * The index of the next line in lines to send
+     */
+    private lineNr;
+    /**
+     * The previous input of the user
+     * Is restored upon switching back to InputMode.Batch
+     */
+    private previousInput;
+    /**
+     * Construct a new BatchInputHandler
+     * @param {function()} inputCallback  Callback for when the user has entered a value
+     */
+    constructor(inputCallback: () => void);
+    onToggle(active: boolean): void;
+    getInputMode(): InputMode;
+    /**
+     * Retrieve the lines of input that the user has given so far
+     * @return {Array<string>} The entered lines
+     */
+    protected get lines(): Array<string>;
+    hasNext(): boolean;
+    next(): string;
+    onRunStart(): void;
+    onRunEnd(): void;
+    render(options: RenderOptions): HTMLElement;
+}

package/dist/input/InteractiveInputHandler.d.ts

@@ -0,0 +1,20 @@
+import { InputMode } from "../InputManager";
+import { RenderOptions } from "../util/Util";
+import { UserInputHandler } from "./UserInputHandler";
+/**
+ * Input handler that takes input from the user in an interactive fashion
+ */
+export declare class InteractiveInputHandler extends UserInputHandler {
+    /**
+     * Retrieve the button that users can click to send their input
+     */
+    get sendButton(): HTMLButtonElement;
+    getInputMode(): InputMode;
+    hasNext(): boolean;
+    next(): string;
+    waitWithPrompt(waiting: boolean, prompt?: string): void;
+    onToggle(): void;
+    onRunStart(): void;
+    onRunEnd(): void;
+    render(options: RenderOptions): HTMLElement;
+}

package/dist/input/UserInputHandler.d.ts

@@ -0,0 +1,61 @@
+import { InputMode } from "../InputManager";
+import { RenderOptions } from "../util/Util";
+/**
+ * Base class for components that handle input from the user
+ */
+export declare abstract class UserInputHandler {
+    /**
+     * Whether we are waiting for the user to input data
+     */
+    protected waiting: boolean;
+    protected inputCallback: () => void;
+    /**
+     * Construct a new UserInputHandler
+     * @param {function()} inputCallback  Callback for when the user has entered a value
+     */
+    constructor(inputCallback: () => void);
+    /**
+     * Whether this handler has input ready
+     */
+    abstract hasNext(): boolean;
+    /**
+     * Consume and return the next input value
+     *
+     * Assumes hasNext() has been called and returned true,
+     * otherwise behaviour can produce incorrect results
+     * @return {string} The next value
+     */
+    abstract next(): string;
+    /**
+     * Render this UserInputHandler with the given options
+     * @param {RenderOptions} options The options to use while rendering
+     * @return {HTMLElement} The parent with the new content
+     */
+    abstract render(options: RenderOptions): HTMLElement;
+    abstract onRunStart(): void;
+    abstract onRunEnd(): void;
+    /**
+     * Retrieve the InputMode corresponding to this handler
+     * @return {InputMode} The InputMode enum value
+     */
+    abstract getInputMode(): InputMode;
+    /**
+     * Enable or disable this UserInputHandler
+     * @param {boolean} active Whether this component is active
+     */
+    abstract onToggle(active: boolean): void;
+    /**
+     * Retrieve the HTMLInputElement for this InputHandler
+     */
+    get inputArea(): HTMLInputElement;
+    /**
+     * Wait for input of the user for a certain prompt
+     * @param {boolean} waiting Whether we are waiting for input
+     * @param {string} prompt Optional message to display if waiting
+     */
+    waitWithPrompt(waiting: boolean, prompt?: string): void;
+    /**
+     * Helper method to reset internal state
+     */
+    protected reset(): void;
+}

package/dist/util/HTMLShapes.d.ts

@@ -1,2 +1,15 @@
+/**
+ * Draw a circle using an HTML svg element
+ * @param {string} id HTML id for this element
+ * @param {string} color The color of the circle
+ * @return {string} A string representation of the circle
+ */
 export declare const svgCircle: (id: string, color: string) => string;
+/**
+ * Wrap text (best a single character) in a circle to provide information to the user
+ * @param {string} content The symbol in the circle, e.g. ? of !
+ * @param {string} title The information to display when hovering over the element
+ * @param {string} color The color of the circle and the symbol
+ * @return {string} A string representation of the circle with content
+ */
 export declare const inCircle: (content: string, title: string, color: string) => string;

package/dist/util/Logging.d.ts

@@ -1,6 +1,15 @@
+/**
+ * Enum representing the importance of a log message
+ * This is helpful for debugging while allowing filtering in production
+ */
 export declare enum LogType {
     Debug = 0,
     Error = 1,
     Important = 2
 }
+/**
+ * Helper method to log useful information at runtime
+ * @param {LogType} logType The importance of this log message
+ * @param {any[]} args The data to log
+ */
 export declare function papyrosLog(logType: LogType, ...args: any[]): void;

package/dist/util/Util.d.ts

@@ -1,21 +1,107 @@
 import I18n from "i18n-js";
 export declare const t: typeof I18n.t;
+/**
+ * Add the translations for Papyros to the I18n instance
+ */
 export declare function loadTranslations(): void;
 export declare function getLocales(): Array<string>;
+/**
+ * Constructs the options for use within an HTML select element
+ * @param {Array<T>} options All options to display in the list
+ * @param {function(T):string} optionText Function to convert the elements to a string
+ * @param {T} selected The initially selected element in the list, if any
+ * @return {string} The string representation of the select options
+ */
 export declare function getSelectOptions<T>(options: Array<T>, optionText: (option: T) => string, selected?: T): string;
+/**
+ * Constructs an HTML select element
+ * @param {string} selectId The HTML id for the element
+ * @param {Array<T>} options to display in the list
+ * @param {function(T):string} optionText to convert elements to a string
+ * @param {T} selected The initially selected element in the list, if any
+ * @param {string} labelText Optional text to display in a label
+ * @return {string} The string representation of the select element
+ */
 export declare function renderSelect<T>(selectId: string, options: Array<T>, optionText: (option: T) => string, selected?: T, labelText?: string): string;
+/**
+ * Interface for options to use while rendering a button element
+ */
 export interface ButtonOptions {
+    /**
+     * The HTML id of the button
+     */
     id: string;
+    /**
+     * The text to display in the button, can also be HTML
+     */
     buttonText: string;
+    /**
+     * Optional classes to apply to the button
+     */
     extraClasses?: string;
 }
+/**
+ * Construct a HTML button string from the given options
+ * @param {ButtonOptions} options The options for the button
+ * @return {string} HTML string for the button
+ */
 export declare function renderButton(options: ButtonOptions): string;
-export declare function addListener<T extends string>(elementId: string, onEvent: (e: T) => void, eventType?: string, attribute?: string): void;
+/**
+ * Helper type to access a HTML element, either via its id or the element itself
+ */
+declare type ElementIdentifier = string | HTMLElement;
+/**
+ * Add a listener to an HTML element for an event on an attribute
+ * Element attributes tend to be strings, but string Enums can also be used
+ * by using the type-parameter T
+ * @param {ElementIdentifier} elementId Identifier for the element
+ * @param {function(T)} onEvent The listener for the event
+ * @param {string} eventType The type of the event
+ * @param {string} attribute The attribute affected by the event
+ */
+export declare function addListener<T extends string>(elementId: ElementIdentifier, onEvent: (e: T) => void, eventType?: string, attribute?: string): void;
+/**
+ * Unset the selected item of a select element to prevent a default selection
+ * @param {ElementIdentifier} selectId Identifier for the select element
+ */
 export declare function removeSelection(selectId: string): void;
+/**
+ * Useful options for rendering an element
+ */
 export interface RenderOptions {
+    /**
+     * String identifier for the parent in which the element will be rendered
+     */
     parentElementId: string;
+    /**
+     * Names of HTML classes to be added to the element, separated by 1 space
+     */
     classNames?: string;
+    /**
+     * Extra attributes to add to the element, such as style or data
+     */
     attributes?: Map<string, string>;
 }
-export declare function getElement(element: string | HTMLElement): HTMLElement;
+/**
+ * Resolve an ElementIdentifier to the corresponding HTLMElement
+ * @param {ElementIdentifier} elementId The identifier for the element
+ * @return {T} The corresponding element
+ */
+export declare function getElement<T extends HTMLElement>(elementId: ElementIdentifier): T;
+/**
+ * Renders an element with the given options
+ * @param {RenderOptions} options Options to be used while rendering
+ * @param {string | HTMLElement} content What to fill the parent with.
+ * If the content is a string, it should be properly formatted HTML
+ * @return {HTMLElement} The parent with the new child
+ */
 export declare function renderWithOptions(options: RenderOptions, content: string | HTMLElement): HTMLElement;
+/**
+ * Parse the data contained within a PapyrosEvent using its contentType
+ * Supported content types are: text/plain, text/json, img/png;base64
+ * @param {string} data The data to parse
+ * @param {string} contentType The content type of the data
+ * @return {any} The parsed data
+ */
+export declare function parseData(data: string, contentType?: string): any;
+export {};

package/dist/workers/input/InputWorker.d.ts

@@ -1,6 +1,22 @@
+/**
+ * Class that is used in a service worker to allow synchronous communication
+ * between threads. This is achieved in two different ways.
+ * Responses can be modified by attaching headers allowing the use of shared memory.
+ * Requests to certain endpoints can be used with synchronous requests
+ * to achieve the same goal.
+ */
 export declare class InputWorker {
-    hostName: string;
-    syncMessageListener: (e: FetchEvent) => boolean;
+    private hostName;
+    private syncMessageListener;
+    /**
+     * Create a worker for a specific domain
+     * @param {string} hostName The name of the host domain
+     */
     constructor(hostName: string);
+    /**
+     * Process and potentially handle a fetch request from the application
+     * @param {FetchEvent} event The event denoting a request to a url
+     * @return {boolean} Whether the event was handled
+     */
     handleInputRequest(event: FetchEvent): Promise<boolean>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dodona/papyros",
-  "version": "0.1.702",
+  "version": "0.1.923-tar",
   "private": false,
   "homepage": ".",
   "devDependencies": {
@@ -31,9 +31,10 @@
     "ts-jest": "^27.0.7",
     "ts-loader": "^9.2.6",
     "typescript": "^4.1.2",
-    "webpack": "^5.64.0",
-    "webpack-cli": "^4.9.1",
-    "webpack-dev-server": "^4.6.0",
+    "url-loader": "^4.1.1",
+    "webpack": "^5.70.0",
+    "webpack-cli": "^4.9.2",
+    "webpack-dev-server": "^4.7.4",
     "worker-loader": "^3.0.8"
   },
   "dependencies": {
@@ -51,14 +52,17 @@
     "@codemirror/search": "^0.19.3",
     "@codemirror/state": "^0.19.6",
     "comlink": "^4.3.1",
+    "comsync": "^0.0.7",
     "escape-html": "^1.0.3",
     "i18n-js": "^3.8.0",
-    "sync-message": "^0.0.8"
+    "pyodide-worker-runner": "^0.0.8",
+    "sync-message": "^0.0.9"
   },
   "scripts": {
-    "start": "webpack serve --mode development",
-    "build:package": "webpack build --mode production --env=entry=./src/Library.ts",
-    "build:app": "webpack build --mode production --env=entry=./src/App.ts",
+    "start": "yarn setup && webpack serve --mode development",
+    "setup": "bash scripts/setup.sh",
+    "build:app": "bash scripts/build_package.sh development",
+    "build:library": "bash scripts/build_package.sh production",
     "test": "echo No tests defined yet",
     "lint": "eslint  --ext '.js' --ext '.ts' src",
     "validate:translations": "node scripts/ValidateTranslations.js"
@@ -82,6 +86,6 @@
   "bugs": {
     "url": "https://github.com/dodona-edu/papyros/issues"
   },
-  "main": "./dist/index.js",
-  "types": "./dist/library.d.ts"
+  "main": "./dist/Library.js",
+  "types": "./dist/Library.d.ts"
 }

package/dist/PapyrosEvent.d.ts

@@ -1,6 +0,0 @@
-export interface PapyrosEvent {
-    type: "input" | "output" | "script" | "success" | "error";
-    data: string;
-    runId: number;
-    content?: string;
-}

package/dist/StatusPanel.d.ts

@@ -1,17 +0,0 @@
-import { ButtonOptions, RenderOptions } from "./util/Util";
-interface DynamicButton {
-    id: string;
-    buttonHTML: string;
-    onClick: () => void;
-}
-export declare class StatusPanel {
-    buttons: Array<DynamicButton>;
-    constructor();
-    addButton(options: ButtonOptions, onClick: () => void): void;
-    get statusSpinner(): HTMLElement;
-    get statusText(): HTMLElement;
-    showSpinner(show: boolean): void;
-    setStatus(status: string): void;
-    render(options: RenderOptions): HTMLElement;
-}
-export {};