@dodona/papyros 0.1.7-rc → 0.1.8-tar

package/README.md

@@ -12,29 +12,22 @@
   </a>
 </p>
 
-Papyros is a programming scratchpad in the browser. It allows running arbitrary
-in various programming languages directly in your browser, no installation required.
+Papyros is a programming scratchpad in the browser. It allows running code
+directly in your browser, no installation required. Right now, the focus in on providing a great experience for Python, while also supporting JavaScript.
 By taking away obstacles between students and coding, the learning experience becomes
-smoother and less error-prone. 
-
-Papyros aims to be:
-
-- **Easy to use** by having minimal installation instructions and an intuitive user interface
-- **Flexible** to support many programming languages
+smoother and less error-prone.
 
 Currently, Papyros provides support for the following programming languages:
 - Python, powered by [Pyodide](https://pyodide.org/en/stable/)
 - JavaScript, powered by your browser
 
-## Installation
+## Using Papyros in your own project
 
 You can install Papyros on your system using npm:
 ```shell
 npm install -g @dodona/papyros
 ```
 
-## Usage
-
 Papyros currently supports two modes of operation: stand-alone and embedded.
 
 In stand-alone mode, Papyros runs as a full application in the browser. 
@@ -51,6 +44,38 @@ The following options are supported:
 - standAlone: Whether to operate in stand-alone or embedded mode as described above.
 - locale: The locale to use, currently English and Dutch translations are provided.
 - programmingLanguage: The language to use in the CodeEditor and Backend
+- inputMode: How the users can provide input, according to the [InputMode enum](/src/InputManager.ts)
+
+Furthermore, you can provide fine-grained configuration in embedded mode by providing RenderOptions
+to each main component in the application. You minimally need to specify the ID of the parent element.
+You can also specify attributes, such as style or data, or classNames to be used.
+The main components are the following:
+- code -> the CodeEditor
+- panel -> the StatusPanel in the CodeEditor
+- input -> The field for the user input
+- output -> The panel for output of the code
+
+### User input
+
+Important to note is that handling asynchronous input in a synchronous way is not straightforward.
+This requires advanced features which are not available by default in your browser. We support two options
+
+The most efficient and practical way is using SharedArrayBuffers, which requires the presence of certain HTTP headers.
+The following headers must be set on resources using Papyros.
+```json
+'Cross-Origin-Opener-Policy': 'same-origin',
+'Cross-Origin-Embedder-Policy': 'require-corp'
+```
+If you are also embedding other components (such as iframes) in those pages, you will also need to set
+'Cross-Origin-Resource-Policy' to 'cross-origin' to make them work correctly. In order to limit the effect of this
+change, it is advised to restrict access using the 'Access-Control-Allow-Origin'-header to prevent abuse of including code.
+
+If you would like to use this project without enabling these HTTP headers, we provide a solution using a service worker.
+If your application does not use a service worker yet, a default service worker is pre-built and included in the package.
+Simply copy the file located [here](dist/inputServiceWorker.js) to a location of choice in your application where it can be served.
+Then, before launching your instance of Papyros, make a call to configureInput with the location of the folder and the name of the file.
+
+If you already use a service worker, simply include our functionality in your existing worker using imports. An example can be found [here](src/InputServiceWorker.ts). Afterwards, inform Papyros of this using configureInput as above.
 
 ## Documentation
 
@@ -78,4 +103,4 @@ You can view the results in your browser by visting http://localhost:8080.
 
 ## Try it online
 
-Start coding immediately in your [browser](https://docs.dodona.be/papyros/).
+Start coding immediately in your [browser](https://papyros.dodona.be/).

package/dist/Backend.d.ts

@@ -1,22 +1,81 @@
-import { PapyrosEvent } from "./PapyrosEvent";
+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 {
-    onEvent: (e: PapyrosEvent) => any;
-    runId: number;
-    constructor();
-    /**
-     * Initialize the backend, setting up any globals required
-     * @param {function(PapyrosEvent):void} onEvent Callback for when events occur
-     * @param {Uint8Array} inputTextArray Optional shared buffer for input
-     * @param {Int32Array} inputMetaData Optional shared buffer for metadata about input
+    protected syncExtras: SyncExtras;
+    protected onEvent: (e: BackendEvent) => any;
+    /**
+     *  Constructor is limited as it is meant to be used as a WebWorker
+     *  These are then exposed via Comlink. Proper initialization occurs
+     *  in the launch method when the worker is started
+     * @param {Array<string>} syncMethods The methods to expose
+     */
+    constructor(syncMethods?: string[]);
+    /**
+     * @return {any} The function to expose methods for Comsync to allow interrupting
+     */
+    protected syncExpose(): any;
+    /**
+     * Expose all the methods that should support being interrupted
+     * @param {Array<string>} syncMethods The names of the methods to expose
+     */
+    protected exposeMethods(syncMethods: Array<string>): void;
+    /**
+     * 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, inputTextArray?: Uint8Array, inputMetaData?: Int32Array): 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 {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: SyncExtras, 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: string;
+    /**
+     * The format used for the data to help with parsing
+     */
+    contentType: string;
+}

package/dist/BackendManager.d.ts

@@ -1,5 +1,49 @@
-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;
+declare class Cacheable<T> {
+    private cached;
+    private createFn;
+    constructor(createFn: () => T);
+    get(): T;
+}
+/**
+ * Abstract class to implement the singleton pattern
+ * Static methods group functionality
+ */
+export declare abstract class BackendManager {
+    static createWorkerMap: Map<ProgrammingLanguage, Cacheable<SyncClient<Backend>>>;
+    static channel: Channel;
+    /**
+     * Map an event type to interested subscribers
+     * Uses an Array to maintain order of subscription
+     */
+    static subscriberMap: Map<BackendEventType, Array<BackendEventListener>>;
+    private static buildSyncClientMap;
+    /**
+     * Start a backend for the given language, while storing the worker
+     * @param {ProgrammingLanguage} language The programming language supported by the backend
+     * @return {Remote<Backend>} A Comlink proxy 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

@@ -1,12 +1,117 @@
-import { Compartment } from "@codemirror/state";
+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;
-    constructor(element: HTMLElement, language: ProgrammingLanguage, initialCode?: string, indentLength?: number);
+    /**
+     * Compartment to configure the placeholder at runtime
+     */
+    placeholderCompartment: Compartment;
+    /**
+    * Compartment to configure the panel at runtime
+     */
+    panelCompartment: Compartment;
+    /**
+     * 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;
+    /**
+     * 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,15 +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_TA_ID = "code-input-area";
-export declare const EDITOR_WRAPPER_ID = "code-area";
-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 TERMINATE_BTN_ID = "terminate-btn";
-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 LOCALE_SELECT_ID = "locale-select";
 export declare const DEFAULT_LOCALE = "nl";
-export declare const INPUT_RELATIVE_URL = "/__papyros_input";
-export declare const SERVICE_WORKER_PATH = "./inputServiceWorker.js";
+export declare const DEFAULT_SERVICE_WORKER = "inputServiceWorker.js";

package/dist/InputManager.d.ts

@@ -0,0 +1,32 @@
+import { BackendEvent } from "./BackendEvent";
+import { RenderOptions } from "./util/Util";
+import { UserInputHandler } from "./input/UserInputHandler";
+export declare enum InputMode {
+    Interactive = "interactive",
+    Batch = "batch"
+}
+export declare const INPUT_MODES: InputMode[];
+export declare class InputManager {
+    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;
+    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;
+}

package/dist/InputServiceWorker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/Library.d.ts

@@ -0,0 +1,10 @@
+import { BackendEvent } from "./BackendEvent";
+import { CodeEditor } from "./CodeEditor";
+import { InputManager, InputMode } from "./InputManager";
+import { OutputManager } from "./OutputManager";
+import { Papyros } from "./Papyros";
+import { CodeRunner, RunState } from "./CodeRunner";
+import { InputWorker } from "./workers/input/InputWorker";
+export * from "./ProgrammingLanguage";
+export type { BackendEvent };
+export { Papyros, CodeEditor, RunState, CodeRunner, InputManager, InputMode, OutputManager, InputWorker };

package/dist/OutputManager.d.ts

@@ -0,0 +1,75 @@
+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;
+    /**
+    * 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 {
+    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;
+    /**
+     * 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;
+}