lmh01 / alpha_tui

My attempt to write a runtime environment and debugger for the Alpha-Notation used in my SysInf lecture.

alpha_tui

This is my attempt at writing a runtime environment and debugger for the Alpha-Notation used in my Systemnahe Informatik lecture at university.

Programs are read in and interpreted, a terminal ui is then opened where you can run the program line by line or by using breakpoints. It is also supported to start a playground environment by using the playground command.

Pull requests and bug reports are welcome. See CONTRIBUTING.md for further details.

Contents

1. Getting started
   • Compile from source
   • Using nix
2. Interface and usage
   • Load command
   • Playground command
   • Check command
   • Error handling
3. Instructions
   • Memory cells
   • Substitutions
   • Examples
4. CLI options
   • General options
   • Examples

Getting started

1. Download the newest release specific for your system
2. Extract the .zip file
3. Create a program by using the text editor of your choice or try an example program located in examples/programs. The examples might help you write your program.
4. Run alpha_tui by opening a terminal in the folder and then typing .\alpha_tui load FILENAME, for an example program this command could look like this: .\alpha_tui load examples/programs/faculty.alpha
5. The terminal ui will open where you can run the program line by line by using the [r] key

Compile from source

To compile the program from source the rust toolchain is needed (install via rustup). Once installed you can run the program by typing cargo run. To submit arguments you can use --, for example cargo run -- -h will print help.

Using nix

This Repository provides a flake. If you have flakes enabled you can use

nix shell github:lmh01/alpha_tui

to start a shell in which alpha_tui is installed.

alpha_tui's Issues

Make "Execution finished!" window less wide

In "Load"-Mode, the "Execution finished!" window should be less wide such that the content of the memory cells section to the right is still fully visible

Add hint to `parse_instruction::missing_expression` error that it may be caused by missing whitespaces

If the whitespaces in an instruction are missing, it is also not recognised.

Add some sort of syntax highlighting

If would be nice if different parts of the code could be highlighted using colors.
For example label names could be colored separately from the rest.

Implementation

I'm currently not sure if ratatui provides an easy way on how this could be implemented so this issue will for now only track this idea.

TODO

• Update cli docs of write alignment arg (and possibly documentation) that alignment writing also changes letters: eg. a -> $\alpha$ (maybe the command line option should be renamed then
• Document that now all a entered in a program will be displayed as $\alpha0$

Make instructions parse when = is used

Currently assignment operations are only allowed if := is written. This should be changed to also accept programs where only = is written.

TODO

• Update documentation
• Implement that

Add new accumulator gamma

Add in a new accumulator that is specifically used to provide index values to index memory cells.

Related to #4.

Tasks

• Parsing
• Runtime handling
• Tests
• Make index memory cells accept gamma accumulator as input
• Add cli option to disable gamma accumulator

Improve MD Documentation about command line parameters

• reference index memory cells and gamma accumulator everywhere where memory cells and accumulators are mentioned
• deduplicate information about --memory-config-file
• improve example of an alpha_tui command line invocation using many cli parameters

Update handling of keybinding hints

The current way on how keybinding hints are managed and displayed could be better.

I should replace the current handling (and especially the display of keybinding hints) with the way I did it for admin_tui.

One issue that will be fixed by that is that currently the keybinding hints section will be missing when the terminal is zoomed in by a large amount. This will also make the keybinding hints displayed multi line, if not all hints are fitting in one line.

I will however try to keep the theming.

Accumulators and Memory cells should be created on demand in playground mode

Currently a runtime error occurs when a value is assigned to an accumulator or a memory cell that does not exist in the playground mode. Instead of the runtime error, the accumulator or memory cell should be created on demand, before the value is assigned. This should only be the case in the playground mode (maybe the whole behavior should be disableable using a cli argument).

To implement it, I think I could utalize the Settings struct in the RuntimeArgs struct, to add a new field that stores if memory cells/ accumulators should be created on demand. This could then also be used in the normal load mode, when enabled via command line argument.

Maybe the cli argument to enable that in the load mode could be something like --memory-on-demand. This should probably not conflict with any other parameters, as this would allow for all fields to be empty, when the program starts and that required fields are then only created if needed.

For the playground mode, disabling this automatic creation when needed, the argument could be --no-memory-on-demand.

The runtime settings are then set, according to the command issued and the parameters provided.

Double input when pressing a key on windows

On windows, when a key is pressed, the action behind the key is executed multiple times. This is probably related to a to short waiting time after a key is pressed.

Ideas

• Try to increase the sleep duration after an input is made
  • If that fixes the problem, try to use the increated sleep duration in windows builds only (there should be a way in rust that can be used to do that (something like windows only or i think)

Limit instruction set

It would be nice if it where possible to limit the available instructions.

If a program that is checked with the subcommand check uses instructions that are not allwoed, the check should fail.

Implementation idea.

The allowed instructions could be defined in a file that is then provided as a parameter. The program then compiles the program and checks if all instructions used are allowed. If the instructions file is not provided, all instructions will be allowed.

The instructions file could contain one allowed instruction per file. The way allowed instructions are defined could be something like this:

A = Any accumulator
M = Any memory cell
C = Constant
Y = Gamma
OP = Any operator (maybe add command line option that can limit the available operators?)
CMP = Any comparison (maybe add command line option that can limit the available comparisons?)

Example way to define allwoed instructions:
A := M
A := A OP Y

Code

It may be possible to reuse the code that parses instructions. For that the allowed instructions file will be parsed to instructions, using the same code that parses the instructions of a program. Then the program is parsed and it is then checked if the parsed instructions only contain allowed instructions. For that however to work, the allowed instructions list has to contain instructions that can be parsed, not dummy instructions like above.

Example pseudo code

let allowed_instructions = Instructions::try_from("allowed_instructions.txt")?;
let instructions = Instructions::try_from("instructions")?;

for i in instructions {
  if !allowed_instructions.contains(i) {
    return Err(InstructionBuildError::InstructionNotAllowed("This instruction is not allowed in the current instruction set!"));
  }
}
// At this point it is verified that `instructions` only contains instructions that are allowed

Tasks

• Update documentation
• Add tests for display implementations

Debug feature: continue execution at line

It should be possible to continue execution at a specific line.
The line that was previously run should be marked gray, when the line is selected that should be run next.

Implementation

It could be implemented the same way as breakpoints except that the marked line is executed when the corresponding keybind is pressed.

Check what the minimal terminal size is that makes the program work

I should check what the minimal terminal size is where the program is still usable.

If that size is undershot, the tui will not be displayed, instead a text "terminal to small" or something similar should be displayed.

This minimal size should be determined for sandbox mode and load mode independently.

This behavior should probably be overridable using a cli flag.

Add check subcommand

The check subcommand should do the following: it is tried to build the supplied program, if that succeeds the program exits with 0, if an error is detected the error is printed and the program exits with value != 0.
Is related to #6.

Add limit for amount of available index memory cells

It should be added because the following program will freeze alpha_tui when run to finish (= next breakpoint, when no breakpoint is set):

y := 0
loop:
p(y) := y
y := y + 1
goto loop

--disable-memory-detection should not force the usage of --memory-cells and --accumulators

--disable-memory-detection should not force the usage of --memory-cells / --memory-cells-file and --accumulators, because it can happen that a program only requires memory cells or accumulators. If anything is missing the runtime will fail to build and explain the missing thing nicely, so that check is not required and is creating a requirement to assign memorycells / accumulators if the aren't even used.

Implement display of rip and call stack

When functions are called, the return address is saved onto a call stack. That call stack and the line of the next instruction should be displayed in the tui.

The call stack should be displayable by option (toggle with keybinding, default is hidden).
The next instruction line (name the label "next instruction") should be shown all the time and be placed in a new block below the memory cells block.

If a value is pushed onto the call stack (because a function was called) the new line should be highlighted with the same color as all other changes. If nothing changes, the currently topmost value should be highlighted in another color, to symbolize that this is the instruction that should be run, after the function is returned.

Change default behaviour of --accumulators and --memory-cells when --disable-memory-detection is set

While --disable-memory-detection is set, --accumulators and --memory-cells are currently both mandatory.
This should no longer be the case.
Instead, if omitted, zero accumulators / no (named) memory cells should be assumed.

Note that the requested change should only influence the behavior in combination with --disable-memory-detection.

Enable "Run to end" and "Run custom instruction" before "Start" is hit

In "Load"-Mode, enable these hotkeys already before the first instruction of a program is executed

Implement sandbox mode

After #24 was implemented it is now possible to run a custom instruction while a program is loaded.

This should make it quite easy to implement a kind of sandbox mode, where no program is loaded actively and where some things are changed:

This should be done the following way:

• The current run custom instruction popup will be placed below the main instruction window and will always remain open
• The main instruction window is empty when opened and no program needs to be supplied to the program
• Entered custom commands are appended to the main instruction window (newest at the bottom, like a terminal)

I will have to see how and if GOTO, CALL and IF commands and their labels can be implemented, but I currently don't see a good way on how that could work nicely.

TODO

• update documentation to include picture of this new sandbox mode (main readme (or maybe in new documentation page?))
• add example on how this sandbox mode can be used to demo gif
• hide breakpoint and next instruction windows
• implement function
• check if all commands that are marked as always available work with this new sandbox command. Commands that don't do anything, should be moved to the subcommand (if argument is applicable to multiple subcomands, but not sandbox, maybe I can utilize argument groups to be able to define them once and use them in multiple subcommands)

Rename sandbox mode to playground mode

Playground mode would be a better fitting name. When this is done, it needs to be changed in the docs, the tui and the command needs to be updated.

Allow Escape to quit program in Load mode

As it is done in the playground mode.
But still keep q as an option for quitting in Load mode

Update Screenshots and documentation

The screenshots need to be updated as the keybindings where changed and the call stack and next instruction are now displayed.

Documentation needs to be updated to explain what the call stack means and how it is displayed (automatically, when call instruction was found). Also explain what the next instruction field means.

Always allow NOOP instruction, regardless of the content of the allowed-instructions-file

Currently, an error is created if an empty line is contained in the source code.
At the same time, specifying NOOP in the allowed instructions file doesn't work.

Empty lines should always be allowed in sourcecode.

Index memory cells are not cleared when resetting program

The memory cells section still contains index memory cell values when the program is reset.

Print α before each accumulator in the accumulator listing

To make it more easily readable

Change hotkeys

Change the following (hotkeys and description):

• Run [r] -> Start [s]
• Run to end [n] -> Run to end [r]
• Run next instruction [r] -> Run next instruction [n]
• Reset [s] -> Reset [t]
• Toggle breakpoint [t] -> Toggle breakpoint [b]

Add option to limit the available operations

It would be nice to have the option --operations that specifies which operations should be allowed.

Tasks

• Update documentation
• Write tests

Rework --memeory-cells-file

--memory-cells-file should be reworked to be able to also load values for accumulators and if the gamma register is enabled. This would then mean that --disable-memory-detection can be used to only supply the new file. The new parameter could be named --memory-config-file.

TODO

• double check CLI to make sure that everything is updated to work with the changes

Add Option to disable stack

There should be both a command line parameter (in the category of memory-related command line parameters) and support in the json memory config files to disable the stack entirely.
Any attempt to use push, pop or stackOP may result in an error message (at parsing-time for loaded programs, at runtime for injected custom instructions).

The stack in the tui interface may become invisible if this option is set.

Run one line of code while program has been loaded

A function should be added with which one line of code can be run, while a program is loaded.

Ideas

• Command history, where the input is filtered (maybe this will help: https://docs.rs/trie-rs/latest/trie_rs/)
• a specific keybind is pressed, then a input window is opened, where the command is then entered. Is is then checked, if it works and then run against the current state of the app

Implement edit mode

This is just a tracking issue for ideas on how an edit mode could be implemented, it is currently not planned to actually add such mode. Edit mode would be launched with the new subcommand create or when the program is started without any subcommand (this is to be decided, maybe both ways?) to create a new alpha notation program within the program.

Implementation ideas

• A separate app struct could be created that contains all functions required to create a runtime (= the build runtime that contains all the instructions) and that contains a complete separate and new tui. When a runtime was successfully build it can be used to create an instance of the current App struct that takes a runtime as parameter and takes ownership.
  If it is done this way, the current app struct has to be renamed and things would probably have to be reorganized.
  But as far as I see it, it is the best way. This way I will not create conflicts with the current runtime environment implementation.

Fix panic when very little space is avilable in terminal (when load command is used)

The program panics, when the terminal space is shrunken so much, that the keybinding hints can not be displayed anymore. This only happens when the load command is used, and not when in sandbox mode.

I think that I fixed this issue for the sandbox mode previously, and didn't verify, that the load mode is unaffected. This needs to be fixed.

cli parameter names

rename --allowed-instructions to --allowed-instructions-file for consistency

Update instruction documentation

The instructioon documentation needs to be updated to include the following:

• ; can be written to end of instruction, it is ignored when the instruction is parsed

Add option to circumvent instruction limit

There should be an option that circumvents the instruction limit introduced in 82a357a

Reorganize CLI arguments

The arguments should be reorganized to use subcommands.
To build and run a program the subcommand could be "run", where the file is supplied as third argument, direct behind the subcommand name.

Tasks

• Move flags that only have a usage when a program is loaded into load subcommand
• Update documentation

Update demo gif

The demo gif currently shown in the readme is outdated.

I was however not yet able to generate a new gif, because the tool I'm using for that (vhs) is currently broken.

I will have to see in the future if it works again, and if it does, I will update the gif.

Fix CLI Doku: make order of arguments more useable

Fix CLI Doku: Sometimes misses reference to index memory cells

The CLI documentation of --disable-memory-detection and --memory-config-file currently doesn't include index memory cells, although they are affected by these options.
Also, some memory related cli flags may benefit from additional descriptions.

Add support for index memory cells

Index memory cells should be supported. For that a new section named "Index Memory Cells" should be added below the current "Memory Cells" section.

It would be nice if the tui section could somehow be merged with the memory cells section (so that booth lists are surrounded with the same line).

How it works

p(6) := 42
a1 := 30
 y := 5
 loop:
 p(y) := 5
 if y = a1 goto end
 y := y + 1
 goto loop
 end:

Nach Zeile 1
 x |  p(x)
---|------
 5 |     
 6 |   42
 7 |     
 8 |     
.. |  ....
30 |     

Nach Programm Ende 
 x |  p(x)
---|------
 5 |     5
 6 |     5
 7 |     5
 8 |     5
.. |  ....
30 |     5

Tasks

• Add documentation for how index memory cells work
• Parsing
• Runtime: target type support - implement that value can be assigned to index memory cell
• Runtime: value type support - implement that value can be read from index memory cell
• Value struct - add IndexMemoryCell variant
• Add support for alpha accumualtors
• Add support for gamma (y or $\gamma$) accumulator, gamma will just be a specially named accumulator. Gamma register should only be present in the accumulator ui list, when it is actually used, related to #10
• Add tests
• Add ui support
• Implement automatic recognition for gamma, accumulators and memory cells in index memory cell instructions
• Modify flag with which values can be loaded into memory cells to support loading values into index memory cells

Better formatting for main instructions

Add optional mode (or make it default and it can be disabled) that the instructions are better formatted.

Labels, code and comments should be aligned to each other.
Example:

loop:           a0 := 5               // Assign value 5 to accumulator a0
another_label:  p(h) := 10            // ...

Tasks

• Implement base formatting
• Add cli parameter to disable new formatting
• Add cli parameter with which the new formatting can be written to the source file
• Check if full line comments are still working

Allow manipulation of accumulator/memorycell values

It should be possible for debugging purposes to modify the value of specific accumulators or memory cells.

This can be done like this:

A new keybind that opens an overlay window where something like this can be entered:

a1=VALUE
h1=VALUE

(only one such line per operation)

Upon pressing enter, the value should be updated.

Too many spaces when selecting instruction with tab that contains non alphabetic characters

When an instruction is filled into the text area, that contains $\alpha$, the amount of spaces added behind that filled in word is incorrect, there are too many. This should be fixed, that the cursor position correctly alignes with the last character in the text field.

This is probably caused by a function that counts the length of strings incorrectly, maybe there is a function that counts the actual characters and not the bytes.

Add stackoverflow error

A new error message should be added that catches recursions that don't return.
Currently the program just freezes when such function is called and the program is run.
A way to implement it would be do limit the max number of the stack and then check if this number is exceeded.

Add option to limit the available comparisons

It would be nice to have the option --comparisons that specifies which operations should be allowed.

Tasks

• Update documentation
• Write tests

Panic when jump to line is used in first line

When jump to line is used to try and jump to the first line the program panics.

Add `-i` as short form for `--index-memory-cells` and `-g` as short form for `--enable-gamma-accumulator`

Refactoring of `Runtime`-related `Settings` and the memory state

Currently, Settings are in RuntimeArgs, they should be moved into Runtime.
RuntimeArgs should be renamed to RuntimeMemory.

Rename tooltip "Next breakpoint" to "Run to finish" when to no breakpoint is set

The tooltip "[n] Next breakpoint" should be renamed to "[n] Finish" (or something similar) when no breakpoint is set to make the interface more clear.

It might also be a good idea to change the keybind (more make booth keybinds (n and f) do the same thing, because internally this is the same thing).

Fix stack op

The way stack op is currently implemented is not quite how it should work, because the alpha accumulator is internally used to calculate the value, so the value that was previously in it should be overwritten with the result of the calculation.