Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add help (and ?) commands to numbat REPL #222

Merged
merged 16 commits into from
Nov 3, 2023

Conversation

tomeichlersmith
Copy link
Contributor

This resolves #175 .

I implemented an insect-like help command for the REPL (with ? as an alias) by writing the package description, running a few examples through the REPL itself and then printing the link to the online documentation. The examples are printed along with the prompt to show the user how it would look and then the result of the examples are printed just like any other user command to show the user how it would look on their computer.

I like this so that the output of the examples are automatically updated along with any output formatting changes in numbat, but this has the downside of potentially polluting the user namespace if any of the examples have let or use in them. For now, I just avoid using those commands in the examples.

@sharkdp
Copy link
Owner

sharkdp commented Nov 2, 2023

I implemented an insect-like help command for the REPL (with ? as an alias) by writing the package description, running a few examples through the REPL itself and then printing the link to the online documentation

Thank you very much!

The examples are printed along with the prompt to show the user how it would look and then the result of the examples are printed just like any other user command to show the user how it would look on their computer.

I like it! Maybe we could indent everything by 4 spaces to clarify what belongs to the help text and what not?

I like this so that the output of the examples are automatically updated along with any output formatting changes in numbat, but this has the downside of potentially polluting the user namespace if any of the examples have let or use in them.

This is also problematic for another reason. If you run numbat --no-prelude and then type help, you'll get something like "unknown identifier: km".

We could create a fresh Numbat Context for the purpose of running the help examples. This way, there would be a clean separation. This also leads me to a general comment/question:

It would be great if we could somehow move this functionality into the numbat crate (the library, not the CLI app). This way, we could reuse this code in the web application as well.

@tomeichlersmith
Copy link
Contributor Author

Thanks for taking a look at this so quickly 😄

  • I also like the idea of making this available to the web as well as the CLI app. (I had erroneously assumed that this code would be in the web app as well).
  • Creating a fresh context to run the help will be nice for the reason you describe (and will help me familiarize myself with the Context) - do you think the examples should change depending on if a prelude is loaded?

it is connected to the 'help' keyword and runs a few examples for the
user showing what could be typed in and the resulting printout on their
machine.

add more insect-like help printout

short description plus some examples and a link to the full
documentation online

use package description for uniformity

fixup help printout by changing Cargo description.

- Just formatting changes to the Cargo description (removing the initial
  whitepsace and adding an ending period).
- don't use `let` in example to avoid polluting the namespace of the
  user
- use keyword markup for numbat and link to documentation so they stand
  out

run cargo fmt
- need to make printing silent for 'use prelude'
- need to add it to numbat-wasm

WIP: refactor help to return markup

this way it can be used with whatever formatter is available

functional version of markup-returning help

Standing Issues
- Cannot use `print` function in examples because it gets order messed
  up
- adds an extra indent in the next line that is printed after the help
  is printed

run cargo fmt
this avoids a current _very small_ bug in the ANSI formatter which adds
the indent after all new lines which means the next time the terminal is
asked to printed a line it has the indent. We can "absorb" this indent
by simply moving one of the newlines out of the markup and into a raw
println!() call
Copy link
Contributor Author

@tomeichlersmith tomeichlersmith left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Alright, I think I've made the necessary updates to enable this help to be printed in both the CLI and the web apps. There are still two more things to do

  1. I need to actually test and see what the output looks like on the web app. I am not familiar with web-dev and so I'll need to figure out how to get wasm-pack and npm and stuff so I can do a local test and serve.
  2. I found a very minor bug in the ANSIFormatter. When indent is enabled, the indenting spaces are added after each new line character in the markup. This means that the next line that would be printed by the terminal emulator will have the indent. Instead of resolving this issue, I just moved the last newline from the markup into an extra println!() call.

numbat-cli/src/main.rs Outdated Show resolved Hide resolved
numbat/src/help.rs Outdated Show resolved Hide resolved
numbat/src/help.rs Outdated Show resolved Hide resolved
numbat/src/help.rs Outdated Show resolved Hide resolved
numbat/src/help.rs Outdated Show resolved Hide resolved
Copy link
Owner

@sharkdp sharkdp left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for the updates!

to help make the help printout more concise, we remove the
pretty-printing of the interpreted statements. This also simplifies the
help code slightly by removing some code forks.
@sharkdp
Copy link
Owner

sharkdp commented Nov 3, 2023

  • do you think the examples should change depending on if a prelude is loaded?

Hm. I think we should just show the same thing always.

I need to actually test and see what the output looks like on the web app. I am not familiar with web-dev and so I'll need to figure out how to get wasm-pack and npm and stuff so I can do a local test and serve.

I'd also be okay with doing this for you. No worries.

I found a very minor bug in the ANSIFormatter. When indent is enabled, the indenting spaces are added after each new line character in the markup. This means that the next line that would be printed by the terminal emulator will have the indent. Instead of resolving this issue, I just moved the last newline from the markup into an extra println!() call.

Okay. If you have a good idea on how to improve the situation, please let me know.

tomeichlersmith and others added 10 commits November 3, 2023 11:57
this allows the same markup translation to be shared between the cli and
web apps and the help examples running in an isolated context
- rewrite description so it can be a full sentence.
- put link to documentation in intro paragraph
- remove extra white space around examples to condense the help printout
Copy link
Owner

@sharkdp sharkdp left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you very much. I pushed a couple of updates — I hope you don't mind.

@sharkdp sharkdp merged commit f66989f into sharkdp:master Nov 3, 2023
14 checks passed
@tomeichlersmith tomeichlersmith deleted the 175-numbat-cli-help branch November 3, 2023 19:37
@sharkdp
Copy link
Owner

sharkdp commented Nov 3, 2023

It works great in the web version as well. Changes are live on https://numbat.dev/

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Add help command
2 participants