-
Notifications
You must be signed in to change notification settings - Fork 12
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #84 from adri09070/writing-doc
Adding quick doc for jump to caret
- Loading branch information
Showing
3 changed files
with
201 additions
and
2 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,167 @@ | ||
| # JumpToCaret command | ||
|
|
||
| This PR introduces a new JumpToCaret command that allows to move the program execution to the first PC associated to the specific AST node associated to where the caret has been placed. | ||
|
|
||
| The command itself can be accessed via the advanced steps menu in the debugger toolbar: | ||
|
|
||
|  | ||
|
|
||
| You should put your caret somewhere in the code before using this command, otherwise it will go back to the beginning of the method (even before the creation of temporaries). | ||
|
|
||
| ## Tutorial: What you can do with JumpToCaret | ||
|
|
||
| ### Everything that you can do with `SkipUpTo`: | ||
|
|
||
| * Jump to caret forward to skip instructions to caret: | ||
|
|
||
| In the screnshot below, `a` is equal to 1 and we jump to caret that is on the `a * 42` message node: | ||
|
|
||
|  | ||
|
|
||
| After jumping to caret, the next instruction that will be executed is the `a * 42` message node. You can also see that `a` is still equal to 1 as the assignment `a := a +2` has been skipped: | ||
|
|
||
|  | ||
|
|
||
| * Jump to caret inside an inlined block (such as an ifTrue: or ifFalse: block) | ||
|
|
||
| In the screenshot below, we put our caret inside the ifFalse: block: | ||
|
|
||
|  | ||
|
|
||
| After jumping to caret, we have entered the ifFalse: block and `a` is still nil, as the assignment `a := true` has been skipped. | ||
|
|
||
|  | ||
|
|
||
| Then, you can enter the ifTrue: block if you want too: | ||
|
|
||
|  | ||
|
|
||
|  | ||
|
|
||
| ### You can also do other things that you cannot do with the SkipUpTo command: | ||
|
|
||
| * JumpToCaret allows to go backward in the execution, while keeping the state of the program before jumping to caret. | ||
|
|
||
| In this screenshot below, `a` is equal to 1, and we want to jump to caret on the message node `a + 2`: | ||
|
|
||
|  | ||
|
|
||
| After jumping to caret, as you'd expect, the next instruction that will be executed is the message node: | ||
|
|
||
|  | ||
|
|
||
| If you step twice, the message node `a + 2` and the assignment node `a := a +2` will be executed and `a` will be equal to 3: | ||
|
|
||
|  | ||
|
|
||
| Now, what you can do with jumpToCaret and that you can't do with skipUpTo is jumping back to caret on the `a + 2` message node: | ||
|
|
||
|  | ||
|
|
||
| Then you can step twice again to execute the message node and the assignment node and `a` will be equal to 5: | ||
|
|
||
|  | ||
|
|
||
| So, jumpToCaret is very useful if you want to see and debug what happens when a piece of code is executed several times. | ||
|
|
||
| * JumpToCaret allows to jump inside a non-inlined (embedded or not) block (= that needs to be evalued and that creates their own context) | ||
|
|
||
| In the screenshot below, `a` is equal to 1 and the next instruction that will be executed is the message node `a + 2`, whose receiver value 1 has already been pushed on the stack: | ||
|
|
||
|  | ||
|
|
||
| If we move to caret, inside the block, on the `a + 1` message node, then, as you'd expect, the next instruction that will be executed is the `a + 1` message node inside the block. However, as the block is not inlined, a context has been created for it and it has become the suspended context: | ||
|
|
||
|  | ||
|
|
||
| Now, stepping twice will execute the `a + 1` message node and the ` a := a + 1` assignment node AND the block return. So the result of the block is put on the stack. After exiting the block context via these steps, you go back in the parent context right after the block creation: | ||
|
|
||
|  | ||
|
|
||
| You should be really careful when exiting a block via steps if you have entered this block via the jumpToCaret command, as the result of the block is pushed on the stack and becomes the argument of the next bytecode that should be executed (as its real argument had already been pushed on the stack before jumping to caret). If this is not intended, you should reexecute the jumpToCaret command to jump to where you are in order to clean the stack: | ||
|
|
||
|  | ||
|
|
||
| After jumping to caret, the stack has been cleaned (stackTop is not 2 that was the result of the block anymore). | ||
|
|
||
| Note that you can enter embedded blocks. In this case, as many contexts as there are embedding levels are created: | ||
|
|
||
|  | ||
|
|
||
|  | ||
|
|
||
| So, jumpToCaret is useful to see and debug what happens when a block that is never evaluated is actually evaluated. | ||
|
|
||
| * jumpToCaret allows to jump outside a block (whether it's embedded or not) | ||
|
|
||
| In the screenshot below, we have entered an embedded block thanks to the `jumpToCaret` command and the next instruction that is going to be executed is the `a + 1` message node: | ||
|
|
||
|  | ||
|
|
||
| After jumping to caret outside the block, on the `a + 2` message node, then as this message node is in the home context method node, all contexts above the suspended context are discarded and, as you'd expect, the next instruction that is going to be executed is the `a + 2` message node: | ||
|
|
||
|  | ||
|
|
||
| Note that if the aimed node was outside the suspended context block node, but inside another context (let's call it C) block node whose context is between the suspended context and its home context, then only the contexts above the context C are discarded: | ||
|
|
||
|  | ||
|
|
||
|  | ||
|
|
||
| So, jumpToCaret is useful to exit non-inlined blocks, in order to go back to a context between its sender context and its home context, without executing the rest of the block closure. | ||
|
|
||
| ### What you cannot do with jumpToCaret: | ||
|
|
||
| * As skipUpTo, jumpToCaret does not allow to skip return nodes **yet**. | ||
|
|
||
| Except when the return node is in a non-inlined block (non-local return) as jumping outside non-inlined block discards the entire context, it is not possible to jump over a return bytecode. | ||
|
|
||
| This is a problem inherited from skipUpTo, as we didn't allow skipUpTo to skip return bytecodes because a context needs to return something. | ||
|
|
||
| Of course, you will never see any code after a return node that is not in a block because Pharo does not allow to write unreachable code (except in DoIts and unreachable code after ifTrue: ifFalse: blocks that contain returns , but we don't take these cases into account, as anyway this code is never executed normally). | ||
|
|
||
| However, this can become a problem in the case below: | ||
|
|
||
|  | ||
|
|
||
| Here, we want to jump to caret on the `a := 3` assignment node, after an ifFalse: ifTrue: message. However, jumping to caret does not stop on the assignment but it stops on the return node in the `ifTrue:` block because it has a return node and this block is inlined in the method bytecode, before the aimed node: | ||
|
|
||
|  | ||
|
|
||
| The bug also appears with skipUpTo and this is a problem as the assignment `a := 3` is reachable so this should be possible to jump to it. | ||
|
|
||
| Here, it is possible to go there without executing anything by: | ||
| ° jump to caret at the end of the ifFalse: block : | ||
|
|
||
|  | ||
|
|
||
| ° skipping the last instruction of the ifFalse: block that doesn't return: | ||
|
|
||
|  | ||
|
|
||
|  | ||
|
|
||
| ° stepping over (that keeps the program state as it is. Here, it just jumps after the ifTrue: block as it considers that the ifFalse: block has been executed): | ||
|
|
||
|  | ||
|
|
||
| However this is really tedious and we have to think about a way to make it work. Furthermore, there are some cases for which no easy workaround exists. In the screenshot below, we want to enter the inlined ifTrue: block in the ifTrue:ifFalse: message: | ||
|
|
||
|  | ||
|
|
||
| After jumping to caret, we stop on the return node in the inlined ifFalse: block because it is before the inlined ifTrue: block: | ||
|
|
||
|  | ||
|
|
||
| * It is not possible to jump to caret within a context that is not the top context yet | ||
|
|
||
| ## Implementation notes: | ||
| - | ||
| * We get the AST node associated to the caret and get the first PC in the method associated to the AST node. If it is nil, then we check if the node is actually in the method (or block) node. If it is not in the method node and if it is not in the home context method node, we signal an error. If it is not in the method node but if it is in the home context method node, that means we want to exit a block and we discard the contexts above to exit the block and jump to the aimed node in this context. | ||
| * If the aimedPC for the aimed node is nil and if the aimed node is a recursive child of the method node (this is the case for variable nodes in assignments for example), then we get the first node that is executed after the aimed node and that has a PC associated to it and then we move to the first PC associated to this node instead. If this node is a block node, then this means that we want to enter a block. Then after having jumped to the block creation, we step the block creation bytecode to get the block closure and create a new context for it. We set this new block context as the suspended context in the process and the debug session and we recursively `moveToNode:` to jump to the aimed node in the new context. | ||
| - In the implementation, I work with AST node identity, because, for instance if we want to jump to an RBLiteralValueNode 1, we want to jump to this specific node and not any other RBLiteralValueNode 1 that could be anywhere else in the method node. | ||
|
|
||
| ## Known related issues: | ||
| - #55 (minor issue, will be fixed shortly) | ||
| - return node in inlined block issue (annoying issue that prevents to use this command at full power but does not induce any crash), will be fixed shortly | ||
| - It is not possible to jump to caret within a context that is not the top context |