Dynamic diagram

Dependencies

Third-party components

Dynamic diagram uses

• cytoscape,
• and socket.io

but in order to work offline, preinstall script downloads it inside this folder

- public
  - diagram
    - lib

So, if you do a npm install or npm i this process will occur automatically. For further explanation or if you need to upgrade the current version of these libraries, please see download-libs.sh.

Fonts

We use Inter font inside the dynamic diagram page, but instead of using a CDN we have manually downloaded a WOFF which is a light version of the font. This font file is located in a special font folder:

This file is < 17 kb size, so it's not .gitignored, but we want to keep a minimum amount of typefaces (a.k.a. fonts) used. For now, just one is enough.

If you plan to change the typeface, keep in mind these resources:

• 5 steps to faster web fonts
• Google Font helper, allows you to convert a google font into a woff file (collecting only required fonts of a specific typeface, remember that bold/italic/regular is a font and Inter/Verdana/Noto/Ubuntu is the typeface name)

Running everything locally

This strategy allows us to have all dependencies in local files inside the server: you don't need Internet connection at all in order to run wollok-ts-cli and open a dynamic diagram.

All files in public are accessible via localhost:3000 web server.

Interaction between REPL and Dynamic Diagram

Every time we start the REPL, we have

• a client process (the REPL)
• and a server process (Node web server, hosting index.html with dynamic pages)

The communication from client to server is achieved via socket.io, emitting these events:

• initDiagram: dynamic diagram started for first time. The server will set the dark/light mode, and eventually any other configuration.
• updateDiagram: any time there is a change in Wollok VM. We call updateDiagram 1. on start, 2. on any REPL command executed.

Diagram Generator

updateDiagram event is associated with getDataDiagram function in diagramGenerator.ts file.

This function gets the current frame for the interpreter, and

• filters objects that doesn't belong to imported definitions for the current file
• filters objects like true, false, self, that are required by Wollok VM
• and traverses the whole graph between the objects, avoid duplicating already created nodes

This includes root references from REPL and wkos and their references.

Imported definitions: dynamic diagram vs. VM

Lets recap on "filters objects that doesn't belong to imported definitions for the current file". If we have the following example:

// file example1.wlk
import example2.*
import example3.*

object pepita { }

// file example2.wlk
object raul { }

// file example3.wlk
object veronica { } 

// file example4.wlk
object r2d2 { }

Inside Wollok VM, we will have: pepita, raul, veronica, and example4.r2d2

That said, in REPL console for example1.wlk trying to get a reference to r2d2 will result in a reference error while example4.r2d2 will work. We decided to filter example4.r2d2 in the dynamic diagram to avoid showing references that could be misleading or confusing. If we generate the diagram for example1 we'll only show pepita, raul & veronica.

Diagram generator's output

A node will return

• id: unique identifier
• label: the shorter representation we can have for an Object. For example, dates will show 10/22/2023, while strings will show "pepita", etc.
• type: literal for wollok built-in objects, object for custom objects, null (specific for null references) or REPL.
• fontsize: the font size based on label width (the longer the label the smaller the font size)
• mode: light / dark -> not defined by diagram generator, but by the diagram.js file (see above explanation)

An edge will return

• id: unique identifier
• source and target: ids of the referenced nodes
• style: dotted for collections, solid for the rest
• width: thicker for REPL references, normal for the rest
• label: the name of the reference (like energia), except for set elements
• fontsize: based on label width

Diagram.js

Reload diagram

El método reloadDiagram es simple: elimina los nodos que dejaron de estar y eventualmente

redibuja todo el layout de nuevo si la configuración Pin Objects está desactivada (por defecto): esto tiene como ventaja que los nodos quedan siempre bien dibujados y no hay colisiones, aunque eso cambia el lugar donde están los objetos. genera los nodos de los objetos nuevos, si la configuración Pin Objects está activada. Esto tiene como ventaja que cuando son muchos objetos (150), agregar un elemento solo lleva 8 ms, aunque es probable que los objetos colisionen y haya que moverlos manualmente.