run: UX notes

[simonmichael]

Here are some UX issues and open questions for the new run command.

General notes

run modes

This command provides multiple new modes of using hledger:

A. Run scripts: files containing multiple hledger commands or echo commands or lines of output, separated by newlines.

B. Run scripts from stdin: you can also pipe a run script into hledger run with no arguments.

C. Multi-command lines: Command lines containing multiple hledger commands or echo commands or lines of output, separated by --.

D. REPL: An interactive prompt accepting hledger commands or echo commands or lines of output.

This will be a lot to understand and explain.
Even if they all mostly share the same implementation for now (I expect the REPL will grow),
I wonder if it would be easier on users to provide separate commands,
"run" for scripts and multi-commands and "repl" for interactive prompt.

Flag/command order

Flags before a command
(general or command specific, like -I print or --invert print)
work in the normal hledger cli.
With the run command (all modes) they are treated as lines of output instead.
If making this consistent is infeasible we should mention it in docs.

-NUM

The new support for the -NUM form of --depth NUM not yet as consistent we'd like:

• hledger run bal -1 - depth limit is ignored
• hledger run -- bal -1 - works
• hledger run files -- bal -1 - "unknown flag: --depth" error
• hledger run -- files -- bal -1 - both commands work
• in the repl - "unknown flag: -1" error

Command separator

It might not be always obvious which separator works in which modes.
Eg:

• printf "files \n stats" | hledger run - works, runs both commands
• echo "files -- stats" | hledger run - prints two % signs (does not run the commands or report an error)

Mode-specific

Run scripts

I think mode A is selected if the first argument is the path of a file that exists.
This kind of heuristic can be risky, eg it makes error messages less informative and it may vary depending on filesystem state, your working directory, etc.
At least, we should spell out this mode selection logic precisely in the doc.

Run scripts from stdin

We should mention this mode in the doc.

People sometimes might think it needs - as in ... | hledger run -. It's not required or supported (it's treated as a line of output, currently).

Multi-command lines

In mode C, a leading -- is required, only when there are multiple commands.
Eg hledger run stats works but hledger run stats -- stats runs stats only once, which is surprising.
Hopefully this can be fixed.

REPL

Premature exit

I think most or all errors exit the repl instead of returning to the prompt.
Also the test command (and maybe some other builtin, addon commands) exit the repl on successful completion.

REPL modes, parsing

Within the repl, there are several modes of command processing, based on the first word of input:

a. A hledger builtin command name or official abbreviation: eg balance or bal (but not ba).
b. A repl command: currently just echo.
c. A line of output: anything else.

This is another heuristic, with resulting problems like

• You can't easily generate output that happens to look like a command. Eg wrapping it in quotes, doesn't work ("test", "echo").
• Error reporting is worse.
• Useful auto completion isn't possible.

Should we require the echo command, or quotes, or a leading space or >, for lines of output ?

Separately, should we distinguish repl-specific commands with a prefix ? I think slash is a bit of a standard and would be ideal (/echo).

Then we could accept or respond to non-official abbreviations the same way hledger does.
Or provide nicer TUI autocompletion in future.

Ideally addon command names will also be supported.

At the repl prompt, should command-like flags (like --version, --help, -h) work ?

What should happen if we type a non-command-like flag (-I or --invert) ?

Help

The commands list is more needed than the hledger manual. What would be a good way to make it accessible in the repl ?

Should there be repl-specific help ? (/help)

[adept]

Thank you for extensive review!

I wonder if it would be easier on users to provide separate commands,
"run" for scripts and multi-commands and "repl" for interactive prompt.

Given that they share most of the implementation, what's the best way to structure this? I can make Commands/Run.hs and
Commands/Repl.hs , which both call a function out of RunOrRepl.hs. Is is ok for RunOrRepl.hs to live in the Commands as well?

Flags before a command

I think flags before run work, and get passed to run in a usual way. Do you have counterexample perchance?

The new support for the -NUM form of --depth NUM not yet as consistent we'd like:

I missed a spot to apply replaceNumericFlags :( Should be fixed now. Perhaps a call to replaceNumericFlags and expandAtArgs should just be added into getHledgerCliOpts ?

echo "files -- stats" | hledger run - prints two % signs (does not run the commands or report an error)

It is parsed as "run files with -- stats as arguments". When I run hledger files -- stats it does nothing for me as well (nor does it return an error). So I blame implementation of files here :)

I think mode A is selected if the first argument is the path of a file that exists.
This kind of heuristic can be risky, eg it makes error messages less informative and it may vary depending on filesystem state, your working directory, etc.
At least, we should spell out this mode selection logic precisely in the doc.

I've changed it to "if all positional args are files, run in file mode"

Run scripts from stdin
We should mention this mode in the doc.

Done!

Eg hledger run stats works but hledger run stats -- stats runs stats only once, which is surprising.
Hopefully this can be fixed.

This happens because first -- is consumed by Cli.hs. I dont know how to fix right now :(

I think most or all errors exit the repl instead of returning to the prompt.

Correct. I am happy to leave it as it is for now.

Also the test command (and maybe some other builtin, addon commands) exit the repl on successful completion.

That because test calls Test.Tasty, which, I think, does System.exit internally :(

REPL modes, parsing

I agree with most of these points, but they would require a cool minute to implement and flesh out. Perhaps controversially, if the current form could not stay as it is (marked as EXPERIMENTAL) I would rather rip out REPL completely that try to make it better.

Ideally addon command names will also be supported.

For addons, you need to shell out, which defeats the whole purpose of run. Addons you could just run in a regular way, IMO

Should there be repl-specific help ? (/help)

Typing "help" in repl prompt works and displays hledger help. We could advertise this. Would this be enough?

[simonmichael]

Just the quick replies for now:

Given that they share most of the implementation, what's the best way to structure this? I can make Commands/Run.hs and Commands/Repl.hs , which both call a function out of RunOrRepl.hs. Is is ok for RunOrRepl.hs to live in the Commands as well?

I'm fine with that, if it doesn't make life harder in other ways (docs, cli help, etc.)

echo "files -- stats" | hledger run - prints two % signs (does not run the commands or report an error) It is parsed as "run `files` with `-- stats` as arguments". When I run `hledger files -- stats` it does nothing for me as well (nor does it return an error). So I blame implementation of `files` here :)

Ok. Yes files takes a REGEX argument. Why does it print two %'s though ? Possibly it should suppress printing the prompt when reading from stdin ?

At least, we should spell out this mode selection logic precisely in the doc. I've changed it to "if all positional args are files, run in file mode"

Changed what - the doc ? If so it should say what "are files" means. Eg "if each argument is the path of a file that exists".

I think most or all errors exit the repl instead of returning to the prompt. Correct. I am happy to leave it as it is for now.

Ok, I don't think that's a good REPL experience though, hopefully someone will fix that in future.

REPL modes, parsing I agree with most of these points, but they would require a cool minute to implement and flesh out. Perhaps controversially, if the current form could not stay as it is (marked as EXPERIMENTAL) I would rather rip out REPL completely that try to make it better.

Haha that's a sensible option but now that you've given us a REPL we'll never give it up :) None of these wishes need be done by you, others can help, but it's good to hash out some plans at least. Also next release deadline is approaching so we may not get much more done in time for 1.42. None of these are release blockers, it's marked experimental, as you say.

Ideally addon command names will also be supported. For addons, you need to shell out, which defeats the whole purpose of run. Addons you could just run in a regular way, IMO

I don't quite follow. Won't REPL users expect to have all the same hledger commands available that are available at the CLI and in the commands list ?

Should there be repl-specific help ? (/help) Typing "help" in repl prompt works and displays hledger help. We could advertise this. Would this be enough?

No it's not (I tried it). For me it shows the top Info node of the huge hledger manual; on other systems it might run `man hledger`, or show the same text in a pager, or (eg on windows) it might dump the whole manual to stdout with no pager. Some compact help specific to the REPL will be useful (if not now, I imagine we'll add it later).

[simonmichael]

(We could change the meaning of help when in the REPL, but I figure it's better not to introduce inconsistencies like that.)