@dodona/papyros 0.1.702 → 0.1.923-tar

package/dist/Backend.d.ts

@@ -1,22 +1,76 @@
-import { PapyrosEvent } from "./PapyrosEvent";
-import { Channel } from "sync-message";
-export declare abstract class Backend {
-    onEvent: (e: PapyrosEvent) => any;
-    runId: number;
+import { CompletionContext, CompletionResult } from "@codemirror/autocomplete";
+import { BackendEvent } from "./BackendEvent";
+import { SyncExtras } from "comsync";
+/**
+ * Interface to represent the CodeMirror CompletionContext in a worker
+ */
+export interface WorkerAutocompleteContext {
+    /**
+     * Whether the autocompletion was explicitly requested (using keybindings)
+     */
+    explicit: boolean;
+    /**
+     * The absolute position in the CodeMirror document
+     */
+    pos: number;
+    /**
+     * The line number of the cursor while completing (1-based)
+     */
+    line: number;
+    /**
+     * The column number of the cursor while completing (1-based)
+     */
+    column: number;
+    /**
+     * The full text to autocomplete for
+     */
+    text: string;
+    /**
+     * The match before the cursor (determined by a regex)
+     */
+    before: {
+        from: number;
+        to: number;
+        text: string;
+    } | null;
+}
+export declare abstract class Backend<Extras extends SyncExtras = SyncExtras> {
+    protected extras: Extras;
+    protected onEvent: (e: BackendEvent) => any;
+    /**
+     * Constructor is limited as it is meant to be used as a WebWorker
+     * Proper initialization occurs in the launch method when the worker is started
+     * Synchronously exposing methods should be done here
+     */
     constructor();
     /**
-     * Initialize the backend, setting up any globals required
-     * @param {function(PapyrosEvent):void} onEvent Callback for when events occur
-     * @param {Channel} channel for communication with the main thread
+     * @return {any} The function to expose methods for Comsync to allow interrupting
+     */
+    protected syncExpose(): any;
+    /**
+     * Initialize the backend by doing all setup-related work
+     * @param {function(BackendEvent):void} onEvent Callback for when events occur
      * @return {Promise<void>} Promise of launching
      */
-    launch(onEvent: (e: PapyrosEvent) => void, channel: Channel): Promise<void>;
-    abstract _runCodeInternal(code: string): Promise<any>;
+    launch(onEvent: (e: BackendEvent) => void): Promise<void>;
     /**
-     * Validate and run arbitrary code
+     * Executes the given code
+     * @param {Extras} extras Helper properties to run code
      * @param {string} code The code to run
-     * @param {string} runId The uuid for this execution
      * @return {Promise<void>} Promise of execution
      */
-    runCode(code: string, runId: number): Promise<void>;
+    abstract runCode(extras: Extras, code: string): Promise<void>;
+    /**
+     * Converts the context to a cloneable object containing useful properties
+     * to generate autocompletion suggestions with
+     * @param {CompletionContext} context Current context to autocomplete for
+     * @param {RegExp} expr Expression to match the previous token with
+     * @return {WorkerAutocompleteContext} Completion context that can be passed as a message
+     */
+    static convertCompletionContext(context: CompletionContext, expr?: RegExp): WorkerAutocompleteContext;
+    /**
+     * Generate autocompletion suggestions for the given context
+     * @param {WorkerAutocompleteContext} context Context to autcomplete in
+     */
+    abstract autocomplete(context: WorkerAutocompleteContext): Promise<CompletionResult | null>;
 }

package/dist/BackendEvent.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Enum representing all possible types for supported events
+ */
+export declare enum BackendEventType {
+    Start = "start",
+    End = "end",
+    Input = "input",
+    Output = "output",
+    Sleep = "sleep",
+    Error = "error",
+    Interrupt = "interrupt"
+}
+/**
+ * All possible types for ease of iteration
+ */
+export declare const BACKEND_EVENT_TYPES: BackendEventType[];
+/**
+ * Interface for events used for communication between threads
+ */
+export interface BackendEvent {
+    /**
+     * The type of action generating this event
+     */
+    type: BackendEventType;
+    /**
+     * The actual data stored in this event
+     */
+    data: any;
+    /**
+     * The format used for the data to help with parsing
+     */
+    contentType?: string;
+}

package/dist/BackendManager.d.ts

@@ -1,5 +1,57 @@
-import { Remote } from "comlink";
 import { Backend } from "./Backend";
 import { ProgrammingLanguage } from "./ProgrammingLanguage";
-export declare function getBackend(language: ProgrammingLanguage): Remote<Backend>;
-export declare function stopBackend(backend: Remote<Backend>): void;
+import { BackendEvent, BackendEventType } from "./BackendEvent";
+import { Channel } from "sync-message";
+import { SyncClient } from "comsync";
+/**
+ * Callback type definition for subscribers
+ * @param {BackendEvent} e The published event
+ */
+declare type BackendEventListener = (e: BackendEvent) => void;
+/**
+ * Abstract class to implement the singleton pattern
+ * Static methods group functionality
+ */
+export declare abstract class BackendManager {
+    /**
+     * Map programming languages to Backend constructors
+     */
+    private static createBackendMap;
+    /**
+     * Map to cache Backends per ProgrammingLanguage
+     */
+    private static backendMap;
+    /**
+     * Map an event type to interested subscribers
+     * Uses an Array to maintain order of subscription
+     */
+    static subscriberMap: Map<BackendEventType, Array<BackendEventListener>>;
+    /**
+     * The channel used to communicate with the SyncClients
+     */
+    static channel: Channel;
+    /**
+     * @param {ProgrammingLanguage} language The language to support
+     * @param {Function} backendCreator The constructor for a SyncClient
+     */
+    static registerBackend(language: ProgrammingLanguage, backendCreator: () => SyncClient<Backend>): void;
+    /**
+     * Start a backend for the given language and cache for reuse
+     * @param {ProgrammingLanguage} language The programming language supported by the backend
+     * @return {SyncClient<Backend>} A SyncClient for the Backend
+     */
+    static startBackend(language: ProgrammingLanguage): SyncClient<Backend>;
+    /**
+     * Register a callback for when an event of a certain type is published
+     * @param {BackendEventType} type The type of event to subscribe to
+     * @param {BackendEventListener} subscriber Callback for when an event
+     * of the given type is published
+     */
+    static subscribe(type: BackendEventType, subscriber: BackendEventListener): void;
+    /**
+     * Publish an event, notifying all listeners for its type
+     * @param {BackendEventType} e The event to publish
+     */
+    static publish(e: BackendEvent): void;
+}
+export {};

package/dist/CodeEditor.d.ts

@@ -2,22 +2,116 @@ import { LanguageSupport } from "@codemirror/language";
 import { Compartment, Extension } from "@codemirror/state";
 import { ProgrammingLanguage } from "./ProgrammingLanguage";
 import { EditorView } from "@codemirror/view";
+import { CompletionSource } from "@codemirror/autocomplete";
 import { RenderOptions } from "./util/Util";
+/**
+ * Component that provides useful features to users writing code
+ */
 export declare class CodeEditor {
+    /**
+     * Reference to the user interface of the editor
+     */
     editorView: EditorView;
+    /**
+     * Compartment to change language at runtime
+     */
     languageCompartment: Compartment;
+    /**
+     * Compartment to configure indentation level at runtime
+     */
     indentCompartment: Compartment;
+    /**
+     * Compartment to configure the placeholder at runtime
+     */
     placeholderCompartment: Compartment;
+    /**
+    * Compartment to configure the panel at runtime
+     */
     panelCompartment: Compartment;
-    constructor(language: ProgrammingLanguage, editorPlaceHolder: string, initialCode?: string, indentLength?: number);
+    /**
+     * Compartment to configure the autocompletion at runtime
+     */
+    autocompletionCompartment: Compartment;
+    /**
+     * Construct a new CodeEditor
+     * @param {ProgrammingLanguage} language The used programming language
+     * @param {string} editorPlaceHolder The placeholder for the editor
+     * @param {string} initialCode The initial code to display
+     * @param {number} indentLength The length in spaces for the indent unit
+     */
+    constructor(initialCode?: string, indentLength?: number);
+    /**
+     * Render the editor with the given options and panel
+     * @param {RenderOptions} options Options for rendering
+     * @param {HTMLElement} panel The panel to display at the bottom
+     * @return {HTMLElement} The rendered element
+     */
     render(options: RenderOptions, panel?: HTMLElement): HTMLElement;
-    setLanguage(language: ProgrammingLanguage, editorPlaceHolder: string): void;
+    /**
+     * Set the language that is currently used
+     * @param {ProgrammingLanguage} language The language to use
+     */
+    setLanguage(language: ProgrammingLanguage): void;
+    /**
+     * @param {CompletionSource} completionSource Function to obtain autocomplete results
+     */
+    setCompletionSource(completionSource: CompletionSource): void;
+    /**
+     * Set the length in spaces of the indentation unit
+     * @param {number} indentLength The number of spaces to use
+     */
     setIndentLength(indentLength: number): void;
+    /**
+     * Set the panel that is displayed at the bottom of the editor
+     * @param {HTMLElement} panel The panel to display
+     */
     setPanel(panel: HTMLElement): void;
+    /**
+     * @return {string} The code within the editor
+     */
     getCode(): string;
+    /**
+     * @param {string} code The new code to be shown in the editor
+     */
     setCode(code: string): void;
+    /**
+     * Put focus on the CodeEditor
+     */
     focus(): void;
+    /**
+     * @param {number} indentLength The amount of spaces to use
+     * @return {string} The indentation unit to use
+     */
     static getIndentUnit(indentLength: number): string;
+    /**
+     * @param  {ProgrammingLanguage} language The language to support
+     * @return {LanguageSupport} CodeMirror LanguageSupport for the language
+     */
     static getLanguageSupport(language: ProgrammingLanguage): LanguageSupport;
+    /**
+    *  - [syntax highlighting depending on the language](#getLanguageSupport)
+    *  - [line numbers](#gutter.lineNumbers)
+    *  - [special character highlighting](#view.highlightSpecialChars)
+    *  - [the undo history](#history.history)
+    *  - [a fold gutter](#fold.foldGutter)
+    *  - [custom selection drawing](#view.drawSelection)
+    *  - [multiple selections](#state.EditorState^allowMultipleSelections)
+    *  - [reindentation on input](#language.indentOnInput)
+    *  - [the default highlight style](#highlight.defaultHighlightStyle) (as fallback)
+    *  - [bracket matching](#matchbrackets.bracketMatching)
+    *  - [bracket closing](#closebrackets.closeBrackets)
+    *  - [autocompletion](#autocomplete.autocompletion)
+    *  - [rectangular selection](#rectangular-selection.rectangularSelection)
+    *  - [active line highlighting](#view.highlightActiveLine)
+    *  - [active line gutter highlighting](#gutter.highlightActiveLineGutter)
+    *  - [selection match highlighting](#search.highlightSelectionMatches)
+    * Keymaps:
+    *  - [the default command bindings](#commands.defaultKeymap)
+    *  - [search](#search.searchKeymap)
+    *  - [commenting](#comment.commentKeymap)
+    *  - [linting](#lint.lintKeymap)
+    *  - [indenting with tab](#commands.indentWithTab)
+    *  @return {Array<Extension} Default extensions to use
+    */
     static getExtensions(): Array<Extension>;
 }

package/dist/CodeRunner.d.ts

@@ -0,0 +1,102 @@
+import { CodeEditor } from "./CodeEditor";
+import { InputManager } from "./InputManager";
+import { ProgrammingLanguage } from "./ProgrammingLanguage";
+import { ButtonOptions, RenderOptions } from "./util/Util";
+/**
+ * Enum representing the possible states while processing code
+ */
+export declare enum RunState {
+    Loading = "loading",
+    Running = "running",
+    AwaitingInput = "awaiting_input",
+    Stopping = "stopping",
+    Ready = "ready"
+}
+/**
+ * Helper component to manage and visualize the current RunState
+ */
+export declare class CodeRunner {
+    /**
+     * The currently used programming language
+     */
+    private programmingLanguage;
+    /**
+     * The editor in which the code is written
+     */
+    readonly editor: CodeEditor;
+    /**
+     * Component to request and handle input from the user
+     */
+    readonly inputManager: InputManager;
+    /**
+     * The backend that executes the code asynchronously
+     */
+    private backend;
+    /**
+     * Current state of the program
+     */
+    private state;
+    /**
+     * Buttons managed by this component
+     */
+    private buttons;
+    /**
+     * Construct a new RunStateManager with the given listeners
+     * @param {ProgrammingLanguage} programmingLanguage The language to use
+     */
+    constructor(programmingLanguage: ProgrammingLanguage);
+    /**
+     * Start the backend to enable running code
+     */
+    start(): Promise<void>;
+    /**
+     * Interrupt the currently running code
+     * @return {Promise<void>} Promise of stopping
+     */
+    stop(): Promise<void>;
+    /**
+     * 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>;
+    getProgrammingLanguage(): ProgrammingLanguage;
+    /**
+     * Get the button to run the code
+     */
+    get runButton(): HTMLButtonElement;
+    /**
+     * Get the button to interrupt the code
+     */
+    get stopButton(): HTMLButtonElement;
+    /**
+     * Show or hide the spinning circle, representing a running animation
+     * @param {boolean} show Whether to show the spinner
+     */
+    showSpinner(show: boolean): void;
+    /**
+     * Show the current state of the program to the user
+     * @param {RunState} state The current state of the run
+     * @param {string} message Optional message to indicate the state
+     */
+    setState(state: RunState, message?: string): void;
+    getState(): RunState;
+    /**
+     * Add a button to display to the user
+     * @param {ButtonOptions} options Options for rendering the button
+     * @param {function} onClick Listener for click events on the button
+     */
+    addButton(options: ButtonOptions, onClick: () => void): void;
+    /**
+     * Render the RunStateManager with the given options
+     * @param {RenderOptions} statusPanelOptions Options for rendering the panel
+     * @param {RenderOptions} inputOptions Options for rendering the InputManager
+     * @param {RenderOptions} codeEditorOptions Options for rendering the editor
+     * @return {HTMLElement} The rendered RunStateManager
+     */
+    render(statusPanelOptions: RenderOptions, inputOptions: RenderOptions, codeEditorOptions: RenderOptions): HTMLElement;
+    /**
+     * Run the code that is currently present in the editor
+     * @return {Promise<void>} Promise of running the code
+     */
+    runCode(): Promise<void>;
+}

package/dist/Constants.d.ts

@@ -1,19 +1,20 @@
 import { ProgrammingLanguage } from "./ProgrammingLanguage";
-export declare const MAIN_APP_ID = "papyros";
-export declare const OUTPUT_TA_ID = "code-output-area";
-export declare const INPUT_AREA_WRAPPER_ID = "code-input-area-wrapper";
-export declare const INPUT_TA_ID = "code-input-area";
-export declare const EDITOR_WRAPPER_ID = "code-area";
-export declare const PANEL_WRAPPER_ID = "code-status-panel";
-export declare const STATE_SPINNER_ID = "state-spinner";
-export declare const APPLICATION_STATE_TEXT_ID = "application-state-text";
-export declare const RUN_BTN_ID = "run-code-btn";
-export declare const STOP_BTN_ID = "stop-btn";
-export declare const SEND_INPUT_BTN_ID = "send-input-btn";
-export declare const SWITCH_INPUT_MODE_A_ID = "switch-input-mode";
-export declare const PROGRAMMING_LANGUAGE_SELECT_ID = "programming-language-select";
+export declare const MAIN_APP_ID: string;
+export declare const OUTPUT_TA_ID: string;
+export declare const INPUT_AREA_WRAPPER_ID: string;
+export declare const INPUT_TA_ID: string;
+export declare const USER_INPUT_WRAPPER_ID: string;
+export declare const EDITOR_WRAPPER_ID: string;
+export declare const PANEL_WRAPPER_ID: string;
+export declare const STATE_SPINNER_ID: string;
+export declare const APPLICATION_STATE_TEXT_ID: string;
+export declare const RUN_BTN_ID: string;
+export declare const STOP_BTN_ID: string;
+export declare const SEND_INPUT_BTN_ID: string;
+export declare const SWITCH_INPUT_MODE_A_ID: string;
+export declare const EXAMPLE_SELECT_ID: string;
+export declare const LOCALE_SELECT_ID: string;
+export declare const PROGRAMMING_LANGUAGE_SELECT_ID: string;
 export declare const DEFAULT_PROGRAMMING_LANGUAGE = ProgrammingLanguage.Python;
-export declare const EXAMPLE_SELECT_ID = "example-select";
-export declare const LOCALE_SELECT_ID = "locale-select";
 export declare const DEFAULT_LOCALE = "nl";
-export declare const DEFAULT_SERVICE_WORKER = "inputServiceWorker.js";
+export declare const DEFAULT_SERVICE_WORKER = "InputServiceWorker.js";

package/dist/InputManager.d.ts

@@ -1,32 +1,32 @@
-import { PapyrosEvent } from "./PapyrosEvent";
+import { BackendEvent } from "./BackendEvent";
 import { RenderOptions } from "./util/Util";
-import { Channel } from "sync-message";
+import { UserInputHandler } from "./input/UserInputHandler";
 export declare enum InputMode {
     Interactive = "interactive",
     Batch = "batch"
 }
 export declare const INPUT_MODES: InputMode[];
-interface InputSession {
-    lineNr: number;
-}
 export declare class InputManager {
-    renderOptions: RenderOptions;
-    inputMode: InputMode;
-    waiting: boolean;
-    batchInput: string;
-    onSend: () => void;
-    session: InputSession;
-    channel: Channel;
-    messageId: string;
-    constructor(onSend: () => void, inputMode: InputMode);
-    get enterButton(): HTMLButtonElement;
-    get inputArea(): HTMLInputElement;
-    render(options?: RenderOptions): void;
+    private inputMode;
+    private inputHandlers;
+    private renderOptions;
+    private waiting;
+    private prompt;
+    private sendInput;
+    constructor(sendInput: (input: string) => void);
+    private buildInputHandlerMap;
+    getInputMode(): InputMode;
     setInputMode(inputMode: InputMode): void;
-    setWaiting(waiting: boolean, prompt?: string): void;
-    sendLine(): Promise<boolean>;
-    onInput(e?: PapyrosEvent): Promise<void>;
+    get inputHandler(): UserInputHandler;
+    render(options: RenderOptions): void;
+    waitWithPrompt(waiting: boolean, prompt?: string): void;
+    onUserInput(): Promise<void>;
+    /**
+     * Asynchronously handle an input request by prompting the user for input
+     * @param {BackendEvent} e Event containing the input data
+     * @return {Promise<void>} Promise of handling the request
+     */
+    onInputRequest(e: BackendEvent): Promise<void>;
     onRunStart(): void;
     onRunEnd(): void;
 }
-export {};

package/dist/{library.d.ts → Library.d.ts}

@@ -1,9 +1,9 @@
+import { BackendEvent } from "./BackendEvent";
 import { CodeEditor } from "./CodeEditor";
 import { InputManager, InputMode } from "./InputManager";
 import { OutputManager } from "./OutputManager";
 import { Papyros } from "./Papyros";
-import { PapyrosEvent } from "./PapyrosEvent";
-import { StatusPanel } from "./StatusPanel";
+import { CodeRunner, RunState } from "./CodeRunner";
 export * from "./ProgrammingLanguage";
-export type { PapyrosEvent };
-export { Papyros, CodeEditor, StatusPanel, InputManager, InputMode, OutputManager, };
+export type { BackendEvent };
+export { Papyros, CodeEditor, RunState, CodeRunner, InputManager, InputMode, OutputManager, };

package/dist/OutputManager.d.ts

@@ -1,23 +1,75 @@
-import { PapyrosEvent } from "./PapyrosEvent";
+import { BackendEvent } from "./BackendEvent";
 import { RenderOptions } from "./util/Util";
+/**
+ * Shape of Error objects that are easy to interpret
+ */
 export interface FriendlyError {
+    /**
+     * The name of the Error
+     */
     name: string;
+    /**
+     * Traceback for where in the code the Error occurred
+     */
     traceback?: string;
+    /**
+     * General information about this type of Error
+     */
     info?: string;
-    why?: string;
+    /**
+    * Information about what went wrong in this case
+    */
     what?: string;
+    /**
+     * Information about why this is wrong and how to fix it
+     */
+    why?: string;
+    /**
+     * Where specifically in the source code the Error occurred
+     */
     where?: string;
 }
+/**
+ * Component for displaying code output or errors to the user
+ */
 export declare class OutputManager {
-    outputAreaId: string;
     options: RenderOptions;
+    constructor();
+    /**
+     * Retrieve the parent element containing all output parts
+     */
     get outputArea(): HTMLElement;
+    /**
+     * Render an element in the next position of the output area
+     * @param {string} html Safe string version of the next child to render
+     */
     renderNextElement(html: string): void;
-    spanify(text: string, ignoreEmpty?: boolean): string;
-    showOutput(output: PapyrosEvent): void;
-    showError(error: FriendlyError | string): void;
+    /**
+     * Convert a piece of text to a span element for displaying
+     * @param {string} text The text content for the span
+     * @param {boolean} ignoreEmpty Whether to remove empty lines in the text
+     * @param {string} className Optional class name for the span
+     * @return {string} String version of the created span
+     */
+    spanify(text: string, ignoreEmpty?: boolean, className?: string): string;
+    /**
+     * Display output to the user, based on its content type
+     * @param {BackendEvent} output Event containing the output data
+     */
+    showOutput(output: BackendEvent): void;
+    /**
+     * Display an error to the user
+     * @param {BackendEvent} error Event containing the error data
+     */
+    showError(error: BackendEvent): void;
+    /**
+     * Render the OutputManager with the given options
+     * @param {RenderOptions} options Options for rendering
+     * @return {HTMLElement} The rendered output area
+     */
     render(options: RenderOptions): HTMLElement;
+    /**
+     * Clear the contents of the output area
+     */
     reset(): void;
-    onRunStart(): void;
-    onRunEnd(): void;
 }