Data Visualizer

The data visualizer tool is a tool that allows the visualization of data in a convenient way.

draw_data is the Source function corresponding to the data visualizer.

How to use

draw_data is a varargs function; multiple data structures can be used as parameters in a single draw_data call. Each draw_data call maps to a single step, which can then be stepped through using the left and right arrow keys (when the side content panel is focused), or the "Prev" and "Next" buttons.

For example, the following will generate a single step containing two drawings, one for each list.

draw_data(list(1,2,3), list(4,5,6));

Code structure

The code for the data visualizer resides in src/features/listVisualizer

src/features/listVisualizer:
- drawable -- React components corresponding to various drawings
  - Drawable.ts -- exposes the Drawables to external classes
  - ArrowDrawable.tsx -- draws an arrow used with pairs and functions
  - FunctionDrawable.tsx -- draws two balls representing a function
  - NullDrawable.tsx -- draws the line corresponding to a slash, which represents a null value in a box-and-pointer diagram
  - PairDrawable.tsx -- draws two boxes representing a pair
- tree
  - TreeNode.ts -- exposes the TreeNodes to external classes
  - BaseTreeNode.ts -- TreeNode class representing a tree node
  - Tree.tsx -- Tree class responsible for parsing a Source data structure; TreeDrawer class responsible for drawing a parsed Tree
  - DataTreeNode.tsx -- A TreeNode that corresponds to a piece of data (data is defined as a non-pair and non-function)
  - DrawableTreeNode.tsx -- A TreeNode that has a pre-defined drawable, i.e. FunctionTreeNode and PairTreeNode. These are nodes that represent non-primitives, and can be pointed at back twice in the same structure (e.g. `pair(lst, lst)`)
  - FunctionTreeNode.tsx -- TreeNode representing a function
  - PairTreeNode.tsx -- TreeNode representing a pair
- Config.ts -- configuration for drawings
- list.js -- definitions of Source data structures and functions, in Javascript
- ListVisualizer.tsx -- the main public-facing class
- ListVisualizerTypes.tsx -- Typescript type definitions corresponding to Source types (pairs, lists, etc.).
- ListVisualizerUtils.tsx -- utility functions

The data visualizer also makes use of:

• src/commons/saga/WorkspaceSaga.ts
• src/commons/util/JsSlangHelper.ts
• src/commons/sideContent/SideContentListVisualizer.tsx

Summary

The main outfacing code is in ListVisualizer.tsx, where the static functions init, drawData, and clear are exposed. This is used by the corresponding side content React component ` (the one responsible for rendering the content of the draw data tool at the right side of Source Academy Playground) to render the drawings of the data.

What happens in a single "run" of the code in Source Academy is:

1. WorkplaceSaga cleans up the environment, and calls ListVisualizer.clear to reset the list visualizer's state.
2. Each call of draw_data in the code corresponds to a Step, which corresponds to an array of drawings, one for each structure in the varargs. The internal steps list of ListVisualizer is then appended with the new Step, and ListVisualizer.setSteps is called.
3. At the end of all the calls, the side content React component has an array of Steps corresponding to the draw_data calls.

ListVisualizer

ListVisualizer.init

ListVisualizer.init is called by SideContentListVisualizer to attach a listener function setSteps. setSteps will be called by ListVisualizer when the steps -- each corresponding to a draw_data call -- are updated.

ListVisualizer.draw_data

ListVisualizer.drawData is the function that corresponds to draw_data in Source Academy.

The way that draw_data invokes this is via JsSlangHelper.visualizeList, which is called by Source.

ListVisualizer.clear

ListVisualizer.clear is used to reset the list visualizer's state whenever the code is re-run, so as to clear the drawings.