|
1 | | -# Dill    |
| 1 | +# Dill    |
2 | 2 |
|
3 | 3 |
|
4 | 4 | ## What is Dill? |
5 | 5 |
|
6 | | -Dill (**Debugging Interactively in the Parsley Library**) is a cross-platform, visual, reactive and interactive debugger to be used with the _modern_ parser combinator library for Scala, [Parsley](https://github.com/j-mie6/parsley). |
| 6 | +`Dill` (**Debugging Interactively in the Parsley Library**) is a cross-platform, visual, interactive debugger to be used with the parser combinator library for Scala, [`Parsley`](https://github.com/j-mie6/parsley). |
7 | 7 |
|
8 | | -## How do I install it? |
9 | 8 |
|
10 | | -Dill is distributed as a binary executable and can be installed below according to your machine's operating system from the [releases](https://github.com/j-mie6/parsley-debug-app/releases/) page. |
| 9 | +## How do I install it? |
11 | 10 |
|
| 11 | +`Dill` is distributed as a binary executable and can be installed below according to your machine's operating system from the [releases](https://github.com/j-mie6/parsley-debug-app/releases/) page. |
12 | 12 | To build the `Dill` debugger on your own machine, go to [building](#building). |
13 | 13 |
|
14 | | -## Usage |
15 | 14 |
|
16 | | -You will first need to [install](#how-do-i-install-it) / [build](#building) the `Dill` debugging application onto your machine. Then once the application has started, you are ready to start sending it debug information from within `Parsley`. |
| 15 | +## Usage |
17 | 16 |
|
18 | | -First, ensure that your project has the `remote-view` project as a dependency (you will of course need to have the `Parsley` project as a dependency too). |
| 17 | +You will first need to [install](#how-do-i-install-it) / [build](#building) the `Dill` debugging application onto your machine. Then once the application has started, you are ready to start sending it debug information from within `Parsley`: |
19 | 18 |
|
20 | | -Then import the `DillRemoteView` object from `parsley.debug`. |
| 19 | +- First, ensure that your project has the `remote-view` project as a dependency (you will of course need to have the `Parsley` library as a dependency too). |
| 20 | +- Import the `DillRemoteView` object from `parsley.debug`. |
| 21 | +- Then on the parser which you would like to debug, attach the `DillRemoteView` object, before the parse step. |
21 | 22 |
|
22 | | -Then, on the parser which you would like to debug, attach the `DillRemoteView` object before the parse step. |
| 23 | +**`test.sc`**: the following `scala` script uses `Parsley 5.0.0-M12` |
23 | 24 |
|
24 | | -The following scala script uses `Parsley 5.0.0-M10`: |
| 25 | +```scala |
25 | 26 |
|
26 | | -`test.sc` : |
27 | | -```scala |
28 | 27 | //> using repository sonatype-s01:snapshots |
29 | 28 |
|
30 | | -//> using dep com.github.j-mie6::parsley:5.0.0-M10 |
31 | | -//> using dep com.github.j-mie6::parsley-debug:5.0.0-M10 |
32 | | -//> using dep com.github.j-mie6::parsley-debug-remote:0.1-a60d211-SNAPSHOT |
| 29 | +//> using dep com.github.j-mie6::parsley:5.0.0-M12 |
| 30 | +//> using dep com.github.j-mie6::parsley-debug:5.0.0-M12 |
| 31 | +//> using dep com.github.j-mie6::parsley-debug-remote::0.1-ac6943f-SNAPSHOT |
| 32 | +//> using options -experimental |
33 | 33 |
|
34 | 34 | import parsley.quick.* |
35 | 35 | import parsley.syntax.character.{charLift, stringLift} |
36 | 36 | import parsley.debug.combinator.* |
37 | 37 | import parsley.debug.DillRemoteView |
| 38 | +import scala.annotation.experimental |
| 39 | + |
| 40 | +/* Annotations to assign parser names to combinators */ |
| 41 | +@experimental @parsley.debuggable |
| 42 | +object Parser { |
| 43 | + val hello: Parsley[Unit] = whitespaces ~> ('h' ~> ("ello" | "i")).void <~ whitespaces |
| 44 | + val subject: Parsley[Unit] = whitespaces ~> ("world" | "jamie").void <~ whitespaces |
| 45 | + val greeting: Parsley[Unit] = (hello ~> subject ~> "!" ~> eof) |
| 46 | +} |
38 | 47 |
|
39 | | -('h' ~> ("ello" | "i") ~> " world!" ~> eof).attach(DillRemoteView).parse("hello world!1") |
| 48 | +Parser.greeting.attach(DillRemoteView).parse("hello jamie!") |
40 | 49 |
|
41 | 50 | ``` |
42 | 51 |
|
43 | 52 | _To run this snippet, simply run_ `scala test.sc`. |
44 | 53 |
|
45 | | -You will then be able to view a representation of the abstract syntax tree generated by `Parsley`. To reload the tree from the backend, simply press the reload button in the tree view. |
| 54 | +You will then be able to view a representation of the abstract syntax tree generated by `Parsley`: |
46 | 55 |
|
47 | | -## Building |
48 | | -The frontend of the application is written using ScalaJS, and uses the `sbt` build system, the frontend compiles down to a single `JavaScript` file located in `./static`. The backend uses the `Tauri` package to host the frontend, and the `Rocket` package to host a server to receive the tree from `Parsley`. We use `npm` to manage the various packages. |
| 56 | + |
49 | 57 |
|
50 | | -### To run the project, execute `sbt start`. |
51 | 58 |
|
52 | | -This will install the node packages required to build the project, build the front and backend, and then start the generated executable. |
| 59 | +## Building |
53 | 60 |
|
54 | | -To start the application in development mode, we use the sbt development server for the frontend, and the standard tauri development server. |
| 61 | +The frontend of the application is written using [`ScalaJS`](https://www.scala-js.org/) and [`Laminar`](https://laminar.dev/), and uses the `sbt` build system, the frontend compiles down to a single `JavaScript` file located in `./static`. The backend uses the [`Tauri`](https://v2.tauri.app/) package to host the frontend, and the [`Rocket`](https://rocket.rs/) package to host a server to receive the tree from `Parsley`. We use `npm` to manage the various packages. |
55 | 62 |
|
56 | | -### To run the project in development mode, execute |
57 | | -- `sbt ~buildFrontend` to start the sbt development server. |
58 | | -- `sbt buildBackendDev` in a different terminal to start the tauri development server. |
| 63 | +**To run the project, execute `sbt run`:** |
59 | 64 |
|
60 | | -_This will cause a quick-reload when any of the source files are modified._ |
| 65 | +This will install the node packages required to build the project, build the front and backend, and then start the generated executable. |
61 | 66 |
|
62 | | -## Examples |
| 67 | +**To run the project in development mode, execute:** |
| 68 | +- `sbt ~buildFrontend` to start the sbt frontend development server. |
| 69 | +- `sbt runBackend` in a different terminal to start the [`Tauri`](https://v2.tauri.app/) app. |
63 | 70 |
|
64 | | -The following images are screenshots of two example parser trees. |
| 71 | +_This will cause a quick-reload when any of the source files are modified._ |
65 | 72 |
|
66 | | - |
67 | | - |
68 | 73 |
|
69 | 74 | ## Bug Reports |
70 | 75 |
|
71 | | -If you encounter a bug when using Dill, try and minimise the example of the parser input that triggers the bug. If possible, make a self contained example: this will help to identify the issue without too much issue. |
| 76 | +If you encounter a bug when using `Dill`, please try to make a self contained example: this will help to identify the issue. |
| 77 | +Then, create a new [issue](https://github.com/j-mie6/parsley-debug-app/issues) - if possible, please include screenshots and a description of the bug. |
72 | 78 |
|
73 | | -Then, create a new [issue](https://github.com/j-mie6/parsley-debug-app/issues), including, if possible, screenshots and a description of the bug. |
74 | 79 |
|
75 | 80 | ## How does it work? |
76 | 81 |
|
77 | | -- The `remote-view` backend for `parsley-debug` posts the debug tree from the parser to the Rocket HTTP server running within the `Dill` debugger. |
78 | | -- The Rocket server transforms and passes off a representation of the debug tree to the tauri application in `Rust`. |
79 | | -- The frontend then queries the tauri application for the debug tree. |
80 | | -- Upon receipt of the tree, the frontend renders the tree on the screen. |
| 82 | +- The `remote-view` backend for `parsley-debug` posts the debug tree from the parser to the [`Rocket`](https://rocket.rs/) HTTP server running within the `Dill` debugger. |
| 83 | +- The [`Rocket`](https://rocket.rs/) server transforms and passes off a representation of the debug tree to the [`Tauri`](https://v2.tauri.app/) application in `Rust`. |
| 84 | +- The frontend then queries the [`Tauri`](https://v2.tauri.app/) application for the debug tree. |
| 85 | +- Upon receiving of the tree, the frontend renders the tree on the screen. |
0 commit comments