roc/crates/editor/README.md

🚧 Work In Progress 🚧

The editor is a work in progress, only a limited subset of Roc expressions are currently supported.

Unlike most editors, we use projectional or structural editing to edit the Abstract Syntax Tree directly. This will allow for cool features like excellent auto-complete, refactoring and never needing to format your code.

Getting started

• Install the compiler, see here.
• Run the following from the roc folder:

cargo run edit

Troubleshooting

If you encounter problems with integrated graphics hardware, install mesa-vulkan-drivers and vulkan-tools.

If you encounter an error like gfx_backend_vulkan ... Failed to detect any valid GPUs in the current config ... make sure the correct graphics card drivers are installed. On ubuntu sudo ubuntu-drivers autoinstall can resolve the problem. If the error persists, take a look here to see if your GPU supports vulkan. Use of OpenGL instead of vulkan should be available in several months.

Make sure to create an issue if you encounter any problems not listed above.

Inspiration

We thank the following open source projects in particular for inspiring us when designing the Roc editor:

• learn-wgpu
• rgx
• elm-editor
• iced

How does it work?

To take a look behind the scenes, open the editor with ./roc edit or cargo run edit and press F11. This debug view shows important data structures that can be found in editor/src/editor/mvc/ed_model.rs. Add or delete some code to see how these data structures are updated.

From roc to render:

• ./roc edit or cargo run edit is first handled in cli/src/main.rs, from there the editor's launch function is called (editor/src/editor/main.rs).
• In run_event_loop we initialize the winit window, wgpu, the editor's model(EdModel) and start the rendering loop.
• The ed_model is filled in part with data obtained by loading and typechecking the roc file with the same function (load_and_typecheck) that is used by the compiler.
• ed_model also contains an EdModule, which holds the parsed abstract syntax tree (AST).
• In the init_model function:
  • The AST is converted into a tree of MarkupNode. The different types of MarkupNode are similar to the elements/nodes in HTML. A line of roc code is represented as a nested MarkupNode containing mostly text MarkupNodes. The line foo = "bar" is represented as three text MarkupNode; representing foo, = and bar. Multiple lines of roc code are represented as nested MarkupNode that contain other nested MarkupNode.
  • CodeLines holds a Vec of String, each line of code is a String. When saving the file, the content of CodeLines is written to disk.
  • GridNodeMap maps every position of a char of roc code to a MarkNodeId, for easy interaction with the caret.
• Back in editor/src/editor/main.rs we convert the EdModel to RenderedWgpu by calling model_to_wgpu.
• The RenderedWgpu is passed to the glyph_brush to draw the characters(glyphs) on the screen.

Important files

To understand how the editor works it is useful to know the most important files:

• editor/src/editor/main.rs
• editor/src/editor/mvc/ed_update.rs
• editor/src/editor/mvc/ed_model.rs
• editor/src/editor/mvc/ed_view.rs
• editor/src/editor/render_ast.rs
• editor/src/editor/render_debug.rs

Important folders/files outside the editor folder:

• code_markup/src/markup/convert
• code_markup/src/markup/nodes.rs
• ast/src/lang/core/def
• ast/src/lang/core/expr
• ast/src/lang/core/ast.rs
• ast/src/lang/env.rs

Contributing

We welcome new contributors ❤️ and are happy to help you get started. Check CONTRIBUTING.md for more info.