search

joaotavora / sly

Sylvester the Cat's Common Lisp IDE
1.26k stars 142 forks source link

Detail stickers documentation, maybe add tutorial? #398

Open Ambrevar opened 3 years ago

Ambrevar commented 3 years ago

I'm ashamed to admit that I got frustrated for much too long with stickers because I thought I could only display their values with sly-stickers-replay and I wasn't able to interact with these values, in particular, not able to inspect them.

Being so frustratingly close to be able to manipulate the stickers value, and being Emacs/Lisp, it so happened that, of course, I was wrong. Here are the steps to inspect sticker values:

Turns out that inspection is bound to RET (when point is on the sticker), but it's not mentioned.

It's easy, but it does not seem documented, and right-clicking is something I never do in Emacs. Since Emacs is so keyboard-oriented, I assume I'm not the only one with this habbit :)

So I suggest documenting the above in the manual ;) It's so useful (essential, even), that I would include it in the tour.

Thoughts?

joaotavora commented 3 years ago

Thoughts?

I agree that the documentation in the manual and in source code sucks.

I'm ashamed to admit that I got frustrated for much too long with stickers because I thought I could only display their values with sly-stickers-replay and I wasn't able to interact with these values, in particular, not able to inspect them.

I don't understand what you mean exactly, but even in the sly-stickers-replay interface, you can of course inspect and return those values to the REPL. So it seems you are still somewhat confused?

Anyway, there are three ways of interacting with stickers recordings:

1- Replaying them post-mortem, M-x sly-stickers-replay 2- Toggling "breaking stickers" on, which enables the familiar "step-by-step" interface. For this there is currently no Elisp-side control (there could be some M-x toggle-breaking-stickers), so one currently does this by setting (setq slynk-stickers:*break-on-stickers* '(:after)) in Common Lisp. 3- Fetching stickers, or M-x sly-stickers-fetch.

You seem to have discovered way number 3 recently. I recommend 1 and 2. Why? Because 3 one can be confusing (I almost never use it). That's due to the fact that a sticker may have been evaluated multiple times, with different results, or even non-local exits. The number 3 "fetch" interface only shows you the last such occurance, I believe, and this can lead an inexperienced programmer to conclude wrong things about how core was executed.

Now, if you read the header of the file sly-stickers.el, you'll find some technical information. Then, if you are good and experienced at writing technical documentation (or know someone with these abilities) and would like to draft a pull request to the documentation, I'd be very happy to take it. Before writing this, to avoid more confusion, one must have a very clear grasp of the difference between a sticker and a sticker recording.

Ambrevar commented 3 years ago

I don't understand what you mean exactly, but even in the sly-stickers-replay interface, you can of course inspect and return those values to the REPL.

Indeed, this is something I realized only recently, I never thought of pressing RET on a sticker recording :p It wasn't obvious to me; maybe it's just me, but I guess it would not cost much to mention it in the tutorial for instance.

So it seems you are still somewhat confused?

No, I think it's pretty clear now.

Anyway, there are three ways of interacting with stickers recordings:

1- Replaying them post-mortem, M-x sly-stickers-replay 2- Toggling "breaking stickers" on, which enables the familiar "step-by-step" interface. For this there is currently no Elisp-side control (there could be some M-x toggle-breaking-stickers), so one currently does this by setting (setq slynk-stickers:*break-on-stickers* '(:after)) in Common Lisp. 3- Fetching stickers, or M-x sly-stickers-fetch.

You seem to have discovered way number 3 recently. I recommend 1 and

  1. Why? Because 3 one can be confusing (I almost never use it). That's due to the fact that a sticker may have been evaluated multiple times, with different results, or even non-local exits. The number 3 "fetch" interface only shows you the last such occurance, I believe, and this can lead an inexperienced programmer to conclude wrong things about how core was executed.

I actually use "3" the most:

In functional programming style, symbols should not be reassigned, so the problem of the last occurrence is not there.

That said, I think it'd be fantastic (and probably easy) to add a command to list all the recordings of a green sticker. Thoughts?

Now, if you read the header of the file sly-stickers.el, you'll find some technical information. Then, if you are good and experienced at writing technical documentation (or know someone with these abilities) and would like to draft a pull request to the documentation, I'd be very happy to take it.

If I find the time I'll give it a shot.

Before writing this, to avoid more confusion, one must have a very clear grasp of the difference between a sticker and a sticker recording.

Yup, this I think I've understood at this point :)

joaotavora commented 3 years ago

In functional programming style, symbols should not be reassigned, so the problem of the last occurrence is not there.

It's not related to symbol reassignment at all. In this code:

(loop repeat 10 (ignore-errors (sometimes-returns-42-sometimes-errors)))

If you place a sticker in (sometimes-returns-42-sometimes-errors) and then fetch recordings you might get a green or a strikethough face, and it doesn't inform you on how your code progressed.

So this "overarching" view is very useless in the face of loops. It is moderately useful in some situations where you already know in advance how many times each stickers is evaluated. But there are many situations where you don't.

Ambrevar commented 3 years ago

Good point! That said, recursion often replaces loops in functional programming style, which is why in my experience I run into this problem quite rarely.

joaotavora commented 3 years ago

That said, recursion often replaces loops in functional programming style, which is why in my experience I run into this problem quite rarely.

Heh, I'm sorry for beating this worse but even without loops this can happen. All that's needed is for a form to be evaluated more than once. And that happens also with recursion obviously.

Anyway, if you know what you're doing, go ahead and use sly-stickers-fetch.

Ambrevar commented 3 years ago

Huhu, no worries ;)