david-yz-liu/memory-viz

Javascript library for creating beginner-friendly memory model diagrams.

MemoryViz: Creating memory model diagrams

This package generates memory model diagrams for Python code in the style of CSC110/111/148 at the University of Toronto. This uses the Rough.js Javascript library to emulate the look of hand-drawn diagrams.

Note: this project is currently experimental, and may undergo significant changes before stabilizing.

Installation (users)

1. Install Node.js.

2. Install the memory-viz package:

   $ npm install memory-viz

Sample usage

Running the following file:

const { draw } = require("memory-viz");

const objects = [
    {
        type: ".frame",
        name: "__main__",
        id: null,
        value: { lst1: 82, lst2: 84, p: 99, d: 10, t: 11 },
    },
    {
        type: "str",
        id: 19,
        value: "David is cool!",
        style: ["highlight"],
    },
    {
        type: "int",
        id: 13,
        value: 7,
    },
];

const m = draw(objects, true, { width: 1300 });

m.save("simple_demo.svg");

produces a file simple_demo.svg that looks like the following:

For more information, check out the project documentation website and demo.

MemoryViz CLI

To use the MemoryViz CLI, run:

$ npx memory-viz <path-to-file>

where <path-to-file> is the path to a file containing MemoryViz-compatible JSON. If a file path is not provided, the CLI will take input from standard input.

You may also specify an output path using the --output option (see documentation). If no output path is provided, the CLI will print to standard output.

Note: The CLI currently does not support typing input directly into the terminal. Instead, use piping or other strategies to pass data into standard input.

For more information, check out the project documentation website.

Developers

Installation

1. First, clone this repository.

2. Install Node.js.

3. Open a terminal in your local code of the repository, and then run:

   $ npm install

4. Compile the Javascript assets using webpack:

   $ npm run build-dev --workspace=memory-viz

5. Install the pre-commit hooks to automatically format your code when you make commits:

   $ npx husky install
   $ npm pkg set scripts.prepare="husky install"
   $ npx husky add .husky/pre-commit "npx lint-staged"

Automatic Javascript compilation

Rather than running npm run build-dev to recompile your Javascript bundle every time you make a change, you can instead run the following command:

$ npm run watch --workspace=memory-viz

This will use webpack to watch for changes to the Javascript source files and recompile them automatically.

Note: this command will keep running until you manually terminate it (Ctrl + C), and so you'll need to open a new terminal window to enter new terminal commands like running the demo below.

Running tests

To run the test suite, execute the following command:

$ npm run test --workspace=memory-viz

Building and running the documentation website

See docs/README.md.

Building and running the demo website

1. First, build the assets using Webpack:

   $ npm run build-dev --workspace=memory-viz-demo

2. Then run the website:

   $ npm run start --workspace=memory-viz-demo

3. Visit the website at http://localhost:9000.

memory-viz's Issues

Trailing zeroes not appearing for objects of type 'float'

Problem: When generating visualizations for objects of type float, the images do not show the trailing zeroes.

Current behaviour:
Input: [ { "name": "float", "id": 13, "value": 7.0 } ]
Output:

Expected behaviour: it should show 7.0 as opposed to 7.

Note that this problem only occurs with trailing zeroes. Other values such as 7.123 display properly.

Add i18n support

i18n can be added to react via https://react.i18next.com/ or alike. Can refer to Markus for example i18n structure. This should make string literals more manageable, both when user facing and when testing.

Issue with Accessing Example Diagram Images in README.md

Hi,

The example diagrams in the README.md are inaccessible, hindering visualization of the library's example input.

Accessing the diagram images results in an error: