@java-memory-playground/java-memory-playground 0.2.3 → 0.2.5

package/dist/memory.d.ts

@@ -11,6 +11,14 @@ export declare const numericDataTypes: string[];
 export declare const primitveDataTypes: string[];
 /** The class name of the heap objects that hold String values. */
 export declare const STRING_KLASS = "String";
+export declare const ARRAY_KLASS = "Array";
+/**
+ * The field holding an array's length.
+ *
+ * Java fixes it when the array is created and there is no assigning to it
+ * afterwards, so the diagram does not offer a field to type in either.
+ */
+export declare const ARRAY_LENGTH = "length";
 /** Types always offered in a type picker, before the user's own classes. */
 export declare const builtInDataTypes: string[];
 /**
@@ -97,6 +105,14 @@ export type Step = {
      * they build against it.
      */
     exercise?: boolean;
+    /**
+     * Assignments the reader may run against this step, in an order they choose.
+     *
+     * Each is evaluated when it is pressed, against the diagram as it stands, so
+     * running them in the wrong order produces the broken picture rather than a
+     * wrong answer. They belong to the instruction, like the label and the note.
+     */
+    statements?: string[];
     objects: Objs;
     variables: Variables;
     methodCalls: MethodCalls;

package/dist/statements.d.ts

@@ -0,0 +1,67 @@
+import { CustomEdgeType, CustomNodeType } from "./types";
+/**
+ * Assignments a reader can fire at the diagram, one at a time.
+ *
+ * Dragging an edge onto its target says where a reference should end up. It
+ * cannot say what `neu.next = current.next` means, because that depends on
+ * where `current.next` points *at the moment the line runs* — which is the
+ * whole difficulty of rewiring a linked list. An assignment executed against
+ * the current state says it: run the two lines the other way round and the
+ * reader watches the node point at itself.
+ *
+ * The right-hand side is read from the diagram on screen, never from the text,
+ * so a wrong order produces the broken picture rather than a wrong answer.
+ */
+/** One side of an assignment: a root name followed by attribute steps. */
+type Path = {
+    root: string;
+    attributes: string[];
+};
+/**
+ * A place a reference can be written to: an edge leaving `nodeId`. A global
+ * variable has one nameless outgoing edge; an object attribute and a local
+ * variable of a frame each have one per handle.
+ */
+export type Slot = {
+    nodeId: string;
+    /** The source handle, or undefined for a global variable. */
+    handle?: string;
+};
+export type StatementError = {
+    code: "malformed";
+} | {
+    code: "unknownName";
+    name: string;
+} | {
+    code: "nullDereference";
+    path: string;
+} | {
+    code: "unknownAttribute";
+    name: string;
+    klass: string;
+} | {
+    code: "notAReference";
+    path: string;
+};
+export type StatementResult = {
+    ok: true;
+    edges: CustomEdgeType[];
+} | {
+    ok: false;
+    error: StatementError;
+};
+/** Splits `a.b = c.d` into its two sides. */
+export declare const parseStatement: (text: string) => {
+    target: Path;
+    source: Path | null;
+} | null;
+/**
+ * Runs one assignment against a diagram and returns the edges it leaves behind.
+ *
+ * Nothing is mutated: a caller that gets an error can show it without having
+ * half-applied the line.
+ */
+export declare const executeStatement: (text: string, nodes: CustomNodeType[], edges: CustomEdgeType[]) => StatementResult;
+/** Splits an authored list, so that a teacher may type them on one line. */
+export declare const parseStatementList: (text: string) => string[];
+export {};

package/dist/store.d.ts

@@ -2,6 +2,7 @@ import type { EdgeChange, NodeChange, Viewport } from "@xyflow/react";
 import { ExerciseResult } from "./canonical";
 import { Memory } from "./memory";
 import { Translations } from "./translations";
+import { StatementError } from "./statements";
 import { CustomEdgeType, CustomNodeType } from "./types";
 export type Route = "view" | "config";
 /**
@@ -17,9 +18,33 @@ export type StoreStep = {
     label?: string;
     note?: string;
     exercise?: boolean;
+    statements?: string[];
     nodes: CustomNodeType[];
     edges: CustomEdgeType[];
 };
+/** One line the reader ran, kept in the order they ran them. */
+export type StatementEntry = {
+    text: string;
+    /** Why it could not run, when it could not. */
+    error?: StatementError;
+};
+/**
+ * Where a step stands for the reader, as the strip of dots shows it.
+ *
+ * `none` is a step with nothing to do — a step of the trace, which is simply
+ * read. The other three are the life of an exercise step: `untried` until it is
+ * checked, then `correct` or `wrong` until the diagram is changed again.
+ */
+export type StepStatus = "none" | "untried" | "correct" | "wrong";
+/**
+ * A check, kept with the fingerprint of the diagram it judged, so that editing
+ * the step afterwards puts it back to `untried` instead of leaving a verdict
+ * standing over a diagram nobody has checked.
+ */
+export type CheckedAttempt = {
+    result: ExerciseResult;
+    fingerprint: string;
+};
 export type GcPredictionResult = {
     /** Unreachable objects the prediction found. */
     found: number;
@@ -45,7 +70,15 @@ export type RFState = {
      * playground so that their attempt can be compared with it.
      */
     solutions: Record<number, StoreStep>;
-    exerciseResult: ExerciseResult | null;
+    /** The last check of each exercise step, by step index. */
+    exerciseResults: Record<number, CheckedAttempt>;
+    /** What the reader has run on each step, by step index. */
+    statementLog: Record<number, StatementEntry[]>;
+    /**
+     * The state each step was in before its first statement ran, so that the
+     * reader can start the sequence over without hunting for the undo key.
+     */
+    statementStart: Record<number, StoreStep>;
     /** Ids of the objects a prediction has marked as unreachable, while running. */
     gcPrediction: string[] | null;
     gcResult: GcPredictionResult | null;
@@ -60,6 +93,7 @@ export type RFState = {
     addStep: () => void;
     deleteStep: (index: number) => void;
     setStepLabel: (index: number, label: string) => void;
+    setStepNote: (index: number, note: string) => void;
     /** The nodes and edges of the step on screen. */
     getNodes: () => CustomNodeType[];
     getEdges: () => CustomEdgeType[];
@@ -79,6 +113,16 @@ export type RFState = {
     checkExercise: () => void;
     revealSolution: () => void;
     clearExerciseResult: () => void;
+    /** The check of the step on screen, or null if it has none or it is stale. */
+    getExerciseResult: () => ExerciseResult | null;
+    getStepStatus: (index: number) => StepStatus;
+    setStepStatements: (index: number, statements: string[]) => void;
+    /** Runs one line against the step on screen and records what it did. */
+    runStatement: (text: string) => void;
+    /** Puts the step back to where the first line found it. */
+    resetStatements: () => void;
+    getStatements: () => string[];
+    getStatementLog: () => StatementEntry[];
     startGcPrediction: () => void;
     toggleGcPrediction: (id: string) => void;
     cancelGcPrediction: () => void;

package/dist/translations.d.ts

@@ -26,14 +26,36 @@ export interface Translations {
     deleteStep: string;
     stepLabel: string;
     stepLabelPlaceholder: string;
+    stepNote: string;
+    stepNotePlaceholder: string;
+    showHint: string;
+    hideHint: string;
     exerciseStep: string;
     exerciseStepHint: string;
     yourTurn: string;
+    exerciseBadge: string;
     checkAnswer: string;
     showSolution: string;
     exerciseCorrect: string;
     exerciseWrong: (wrong: string[]) => string;
     exerciseExtra: (extra: string[]) => string;
+    statements: string;
+    statementsPlaceholder: string;
+    statementsHint: string;
+    runStatement: (statement: string) => string;
+    statementLog: string;
+    resetStatements: string;
+    resetStatementsHint: string;
+    statementMalformed: string;
+    statementUnknownName: (name: string) => string;
+    statementNullDereference: (path: string) => string;
+    statementUnknownAttribute: (name: string, klass: string) => string;
+    statementNotAReference: (path: string) => string;
+    stepOverview: string;
+    stepStatusNone: (step: number) => string;
+    stepStatusUntried: (step: number) => string;
+    stepStatusCorrect: (step: number) => string;
+    stepStatusWrong: (step: number) => string;
     declareLocalVariable: string;
     returnMethod: string;
     returnOnlyTopOfStack: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@java-memory-playground/java-memory-playground",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "author": "Mike Barkmin",
   "description": "React components for visualizing the Java stack and heap.",
   "homepage": "https://github.com/openpatch/java-memory-playground#readme",