Add Cursor documentation #721
Conversation
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #721 +/- ##
=======================================
Coverage 87.95% 87.95%
=======================================
Files 86 86
Lines 20922 20922
=======================================
Hits 18402 18402
Misses 2520 2520 ☔ View full report in Codecov by Sentry. |
docs/Cursors.md
Outdated
|
|
||
| All `Cursor` types provide these common methods: | ||
|
|
||
| - `c.parents()`: Returns cursor to parent node in Exo IR |
There was a problem hiding this comment.
Should be c.parent()? Also, per-cursor-type semantics should be defined. For example, that the parent of a gap cursor is not the anchor statement.
There was a problem hiding this comment.
Good catch, thanks!!
| - `delta_lo`/`delta_hi` specify statements to add at start/end; `None` means expand fully | ||
| - Ex. in `s1; s2; s3`, if `c` is a `BlockCursor` pointing `s1; s2`, then `c.expand(0, 1)` returns a new `BlockCursor` pointing `s1; s2; s3` | ||
| - `BlockCursor.before()`: Returns `GapCursor` before block's first statement | ||
| - `BlockCursor.after()`: Returns `GapCursor` after block's last statement |
There was a problem hiding this comment.
Also c.body(), c.orelse(), and indexing and slicing BlockCursor. (I know the body and orelse are described later but I feel it logically should be repeated here as at least for me the navigation section is where I'd intuitively first look, not the specific per-subclass documentation).
There was a problem hiding this comment.
c.body(), c.orelse() are navigations on ForCursor not on BlockCursor though? Index slicing is a great point!
There was a problem hiding this comment.
Right this could go in the StmtCursor documentation. Ideal level-of-detail is probably to mention c.body() works for for and if statements, c.orelse() only works for if statements with an else clause. And defer the detail about subtypes and the InvalidCursor for c.orelse() until later.
docs/Cursors.md
Outdated
| else: | ||
| orelse | ||
| ``` | ||
| Returns an invalid cursor if `orelse` isn't present. |
There was a problem hiding this comment.
This is specific to the orelse() method, I'd cut this sentence and explain this in the orelse documentation
docs/Cursors.md
Outdated
|
|
||
| To forward a cursor `c` from `p` to `p'`, you can use the `forward` method on the new procedure: | ||
| ```python | ||
| c' = p'.forward(c) |
There was a problem hiding this comment.
I'm not sure if the c-prime, p-prime notation is required by convention, but it causes weird syntax highlighting for me (the assignment is highlighted in the string literal color).
| - `c.before()`: Returns `GapCursor` to space immediately before this statement | ||
| - `c.after()`: Returns `GapCursor` to space immediately after this statement | ||
| - `c.as_block()`: Returns a `BlockCursor` containing only this one statement | ||
|
|
There was a problem hiding this comment.
I would also advertise the StmtCursor.expand() shorthand here. It's actually quite useful for correctly handling the else case (when learning cursors I didn't know about expand and hacked together StmtCursor.parent().body() which is incorrect when the StmtCursor points inside an orelse).
| - `cond() -> ExprCursor`: Returns a cursor to the if condition expression. | ||
| - `body() -> BlockCursor`: Returns a cursor to the if body block. | ||
| - `orelse() -> Cursor`: Returns a cursor to the else block (if present). | ||
|
|
There was a problem hiding this comment.
orelse() -> BlockCursor | InvalidCursor: Returns a cursor to the else block if present, otherwise returns an invalid cursor.
|
|
||
| So in summary, `p.forward(c)` computes and applies the composite forwarding function to map cursor `c` from its original procedure to the corresponding location in procedure `p`. | ||
|
|
||
|
|
There was a problem hiding this comment.
This is overall really clear documentation, thank you!
|
@akeley98 I addressed your comments and also added more texts, can you take a look again? |
docs/Cursors.md
Outdated
| Methods: | ||
| - `cond() -> ExprCursor`: Returns a cursor to the if condition expression. | ||
| - `body() -> BlockCursor`: Returns a cursor to the if body block. | ||
| - `orelse() -> BlockCursor | InvalidCurso`: Returns a cursor to the else block if present, otherwise returns an invalid cursor. |
No description provided.