Simple text CLI

[alexmojaki]

Continuing our email discussion here so that others can comment...

You're right, there isn't extra information, I was confused at first. But overall there is a lot of information in the diagram and it's hard (especially for a new user) to understand what it all means and find the relevant parts. I think it would be better to guide the user step by step, answer their questions one at a time, and not flood them with information.

Here I propose a simple text-based CLI which does this. This should be easy to implement and test, both for you and anyone who wants to contribute. I also think many users will like it better than a GUI. It can work even on a remote server via ssh, and it doesn't require dependencies like graphviz. You can still have a GUI as an option.

The idea is to explain to the user the answer to a single atomic question "how did become ?" This explanation may raise further questions of the same type, the user can ask for those explanations as well and move one step at a time through the backwards tracing, but it's always the same kind of thing showing in the interface so there's very little to learn.

A step in the interface consists of these parts:

1. The current expression/variable being explained and its value, in the form <expression/variable> = <value> or <variable>: <old value> -> <new value>.
2. The line/statement of source code which caused this value. It might be helpful to also show a few lines of context before/after that line, while highlighting the main line.
3. The values of expressions in that line (before it executed), to explain what happened in that line.
4. A way to see explanations of the values shown in 3, which leads to the next step in the backtrace which will follow a similar format. This part of the interface may be merged with 3.

For example, here's the first step when running the test simple_func.py:

y = 3
File simple_func.py, line 11:
y = f(x, f(1, 1))
    where
        1. x = 1
        2. f(1, 1) = 2
        3. f(x, f(1, 1)) = 3

Which part would you like to see explained? (1-3)
> <cursor flashing here>

If the user enters 1, the next step it shows is very simple:

x = 1
File simple_func.py, line 10:
x = 1

Here there is no way to go further. Maybe the user can be allowed to go back in general by entering '0'.

If the user had entered 2, they might see:

f(1, 1) = 2
File simple_func.py, line 8:
return x + y
    where
        1. x = 1
        2. y = 1

If they choose 1:

x = 1
File simple_func.py, line 11:
f(1, 1)
 |
 +-> def f(x, y):

You get the idea. The exact details are flexible, like how function calls are explained.

Another example from doc_example.py, at one point it might show:

ba: [1] -> [1, None, '?']
func_c(ba)
  where
    1. func_c = <function func_c>
    2. ba = [1]
    3. Step into func_c(ba)

You will need something like '3' here for cases when the return value of a function is not useful but knowing what happened inside that function is important. You may not want to show a value or explanation for func_c like in point 1, especially when it comes from a simple function definition, but in some cases it might be more useful if the value is not so obvious.

[laike9m]

This is a pretty good proposal, I think it described many things I have in mind but didn't give a deep thought of. Really appreciate it!

CLI client will eventually be a thing, that's for sure, and considering the capbility of a CLI, it would almost certainly be a lot like what you described. I decided to implement GUI first because that would help me better personally. Right now I'm exploring pyodide, as well as trying to optimize memory usage.

[laike9m]

I think to be able to generate the desired output, Flow object is not enough, for example, it cannot locate the source of a change efficiently. There needs to be some sort of abstraction on top of flow that caches all the "jump" targets. This abstraction should be univerisal, and can be used to generate output in various formats.

[TejasAvinashShetty]

I think the PDF version is ok. Only I took some time to realise what was 'ba -> baa', 'fo -> foo'

[laike9m]

I think the PDF version is ok. Only I took some time to realise what was 'ba -> baa', 'fo -> foo'

@TejasAvinashShetty Suggestions welcomed, I can understand it's a bit confusing at first glance, but I don't know how to improve it.