tool, feat: peek through

[AmaiKinono]

Go down the rabbit hole without leaving current buffer!

When in a peek session, call M-x peek-through or M-o t (the key binding may change), then an "ace" string will be attached to each symbol in the peek window, type it to peek the definition of that symbol.

This is really powerful, we can chase a definition/call chain without even moving the cursor!

@masatake please give me flowers, I bet you'll like it ;)

TODO:

• [x] Browse the peek-through history.
• [x] Refactor/rearrange the code to make it clearer

Update: I found this gives an elegant solution to cross reading.

• When start a peek session, let's push the current location to the chain first (maybe display it with a .).
• And, let's add a "restore recent peek session" command, so wherever you are, you could restore the recent session, and browse from the very entry point to the deepest node in it.
• And, let's automatically restore the session after citre-jump (we can have a user option for it). In other words, you always have the complete chain when you are jumping on the chain ;)

So, let's also implement cross reading in this PR.

[masatake]

I'm sorry that I don't respond to your calls. It will be nice.

I would like you to ask one thing; when making a screencast(?), could you use emacs started with -q option? (Of course, the extension your code requires must be enabled. I'm talking about the rest extensions.) Your emacs is so different from mine. So it is hard for me to recognize which parts you wrote.

[AmaiKinono]

Here you go:

I do changed the font, and set suggest-key-bindings to nil (the "you can press some key to run some command" defers the peek window to show up).

[masatake]

I understand it well. ~This looks very powerful.~ This makes code-reading more predictable (or deterministic); this reduces unwanted-jumps. How do I say... this change provides the way to do pre-fetching or speculative-execution in code reading.

The most impressive one is the last line: stringList -> ptrArray -> sPtrArray. I'm feeling something important is in the line.

How do you call A -> B -> C? Privately, I call it a chain. If citre records the chains a user has built, citre can calculate hot-subchains.

• A->B->C->D
• X->B->C->Y From this history, we can say B->C is a hot subchain.

I must try this one.

[AmaiKinono]

this reduces unwanted-jumps.

Yes. Even citre-peek already saves many of them, it's still a pain to peek - jump - peek - jump... then clean up unwanted buffers afterwards.

How do you call A -> B -> C? Privately, I call it a chain.

In my code I call it "symbol history". Chain is definitely a better name, let me think about it...

If citre records the chains a user has built...

This is a planned feature. It will save all your peek sessions, and the chain of each session. I expect people to use clue to arrange them later.

citre can calculate hot-subchains.

Looks like a fancy idea. I was thinking of presenting history in the order of time, but with this concept we could presenting them in the order of frequency (but that may become "hot-locations" and not "hot-subchains"). Anyway, this is to be explored after we support history in citre-peek. Do you have more ideas on this?

[AmaiKinono]

Actually I've thought about something like grep-peek. The "peeking" approach in Citre seems to be a general mechanism to offer convenient filtering/reading experience on locations. But that's out the scope of Citre, and unrealistic for me to write another package now...

[AmaiKinono]

I am thinking should we allow the chain to branch. I don't have much experience in code reading, but I'm learning and hacking C recently, and sometimes I was peeking a struct, and more than 1 fields in it have custom types, and I want to know all of them.

We could:

• Allow only linear history. When we go to a previous node in the chain, and peeked another symbol, the original history after this node is deprecated. On each node, the symbol that we peeked through is highlighted to give a hint to the user.

• Allow branched history (tree). I don't feel this is that hard to implement, but designing a good UI is the real challenge. I think I can:

  • In the symbol chain, use a special color/icon in the branch point to tell the user "you branched from here".
  • On these nodes, offer a pair of commands to switch between the subtrees after the branch point. We should also scroll the peek window accordingly and highlight the symbol that leads to the corresponding subtree.
  • Offer a command to delete the subtree after a node.

The real question is whether we really need a tree for history. Ideally we should give the answer based on how people read code in real life. But if we can't get relevant facts or testimonies, I may have to do what I prefer.

To keep the chain useable even after some editing, we could reuse the technique of locating a tag in Citre.

This is just the history of one peek session. How to deal with the whole peek history (with all the sessions) is another problem, but we could consider it later.

[masatake]

codetour uses a term "tour".

[masatake]

The result of reading may be linear. However, the process for reading requires a tree. At the start of the reading, the reader may build a tree. At the end of the reading, the reader finds the best path from the root to a leaf.

[AmaiKinono]

codetour uses a term "tour".

That plugin looks very interesting. Maybe it's possible to bring some of its idea to clue.

About the name...

• "tour" does not reflect the concept of our tool. I think it sounds more like a "guided tour" or "walk around" or something.
• "tree" is conceptually perfect, but not very intuitive. For example, It's weird to say "go forward in the tree".
• "chain" is what I'm into now. After all the UI only shows one chain in the tree, and the command that goes forward/backward suits the name well. Some subtlely may happen on the branch node, but we can use some term like "switching between sub-chains".
• I thought about "session history". It's not a bad choice to ignore the data model in the name, but the problem is it can represent "history in a session" and "history of seesions".

Btw, I have to say you have the talent to name things. Although you always says you are not good at English, I feel at least you are very good at technical terms, and they seem to be your inspiration on naming things...

The result of reading may be linear. However, the process for reading requires a tree. At the start of the reading, the reader may build a tree. At the end of the reading, the reader finds the best path from the root to a leaf.

Thanks for this good summary! I also tend to let citre-peek to support tree history. I do want to say:

• With the peek functionality, we could already cut some of the sub-chains beforehand. I consider it a big improvement on the "traditional" way to read code (or, build a tree).
• I don't know if we need to finish solving a problem in one peek session. It is definitely possible with the "chain" and "restore session" functionalities, but I think the problem depends on how long the chain may grow into, and how complex the code is. For anything that's complex enough, I think people should use the power of natural language (i.e., use clue) to express it.

[AmaiKinono]

I've finished most of the works. Some ideas of further improving citre-peek will be put in #18.

Now it's able to browse through the tree history:

Notice the bottom line, where it shows the symbol chain. It uses < to show a branch, and you could switch between branches. I've set the keymap to use meta+up/down/left/right to browse the tree.

Another goodie is the command citre-peek-restore. After citre-abort, it restores the aborted session. This allows you to pause a code reading session and continue it later.