You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: docs/src/usage.md
+70-31
Original file line number
Diff line number
Diff line change
@@ -19,15 +19,21 @@ Select the expression you want to step into by positioning "point" (your cursor)
19
19
at the desired location in the command line:
20
20
21
21
```@raw html
22
-
<img src="images/stepin1.png" width="200px"/>
22
+
<img src="images/stepin1.png" width="160px"/>
23
23
```
24
24
25
25
It's essential that point is at the very first character of the expression, in this case on
26
26
the `s` in `show`.
27
+
28
+
!!! note
29
+
Don't confuse the REPL's cursor with your mouse pointer.
30
+
Your mouse is essentially irrelevant on the REPL; use arrow keys or the other
31
+
[navigation features of Julia's REPL](https://docs.julialang.org/en/latest/stdlib/REPL/).
32
+
27
33
Now if you hit Meta-e, you should see something like this:
28
34
29
35
```@raw html
30
-
<img src="images/stepin2.png" width="822px"/>
36
+
<img src="images/stepin2.png" width="660px"/>
31
37
```
32
38
33
39
(If not, check [Keyboard shortcuts](@ref) and [Customize keybindings](@ref).)
@@ -42,22 +48,36 @@ Indented blue line(s) show the value(s) of any input arguments or type parameter
42
48
If you're following along, move your cursor to the next `show` call as illustrated above.
43
49
Hit Meta-e again. You should see a new `show` method, this time with two input arguments.
44
50
45
-
Now let's demonstrate another important display item: position your cursor at the
51
+
Now let's demonstrate another important display item: position point at the
46
52
beginning of the `_show_empty` call and hit Meta-e.
47
53
The display should now look like this:
48
54
49
55
```@raw html
50
-
<img src="images/stepin3.png" width="859px"/>
56
+
<img src="images/stepin3.png" width="690px"/>
51
57
```
52
58
53
59
This time, note the yellow/orange line: this is a warning message, and you should pay attention to these.
54
60
(You might also see red lines, which are generally more serious "errors.")
55
61
In this case execution never reached `_show_empty`, because it enters `show_vector` instead;
56
62
if you moved your cursor there, you could trace execution more completely.
57
63
64
+
You can edit these expressions to insert code to display variables or test
65
+
changes to the code.
66
+
As an experiment, try stepping into the `show_vector` call from the example above
67
+
and adding `@show limited` to display a local variable's value:
68
+
69
+
```@raw html
70
+
<img src="images/stepin4.png" width="800px"/>
71
+
```
72
+
73
+
!!! note
74
+
When editing expressions, you can insert a blank line with Meta-Enter (i.e., Esc-Enter, Alt-Enter, or Option-Enter).
75
+
See the many [advanced features of Julia's REPL](https://docs.julialang.org/en/latest/stdlib/REPL/#Key-bindings-1) that allow you to efficiently edit these `let`-blocks.
76
+
58
77
Having illustrated the importance of "point" and the various colors used for messages from Rebugger,
59
78
to ensure readability the remaining examples will be rendered as text.
60
79
80
+
61
81
## Capturing stacktraces
62
82
63
83
For a quick demo, we'll use the `Colors` package (`add` it if you don't have it)
@@ -81,19 +101,21 @@ in expression starting at REPL[3]:1
81
101
```
82
102
83
103
To capture the stacktrace, type the last line again or hit the up arrow, but instead of
84
-
pressing enter type Meta-s.
104
+
pressing Enter, type Meta-s.
85
105
After a short delay, you should see something like this:
106
+
86
107
```julia
87
108
julia>colorant"hsl(80%, 20%, 15%)"
88
109
┌ Warning: Tuple{getfield(Colors, Symbol("#@colorant_str")),LineNumberNode,Module,Any} was not found, perhaps it was generated by code
89
-
└ @ Revise ~/.julia/dev/Revise/src/Revise.jl:614
110
+
└ @ Revise ~/.julia/dev/Revise/src/Revise.jl:659
90
111
Captured elements of stacktrace:
91
-
[1] parse_hsl_hue(num::AbstractString) in Colors at /home/tim/.julia/dev/Colors/src/parse.jl:25
92
-
[2] _parse_colorant(desc::AbstractString) in Colors at /home/tim/.julia/dev/Colors/src/parse.jl:51
93
-
[3] parse(::Type{C}, desc::AbstractString) where C<:Colorantin Colors at /home/tim/.julia/dev/Colors/src/parse.jl:140
94
-
parse_hsl_hue(num::AbstractString) in Colors at /home/tim/.julia/dev/Colors/src/parse.jl:25
112
+
[1] parse_hsl_hue(num::AbstractString) in Colors at /home/tim/.julia/packages/Colors/4hvzi/src/parse.jl:25
113
+
[2] _parse_colorant(desc::AbstractString) in Colors at /home/tim/.julia/packages/Colors/4hvzi/src/parse.jl:51
114
+
[3] _parse_colorant(::Type{C}, ::Type{SUP}, desc::AbstractString) where {C<:Colorant, SUP} in Colors at /home/tim/.julia/packages/Colors/4hvzi/src/parse.jl:112
115
+
[4] parse(::Type{C}, desc::AbstractString) where C<:Colorantin Colors at /home/tim/.julia/packages/Colors/4hvzi/src/parse.jl:140
116
+
parse_hsl_hue(num::AbstractString) in Colors at /home/tim/.julia/packages/Colors/4hvzi/src/parse.jl:25
95
117
num =80%
96
-
rebug>@eval Colors let (num,) = Main.Rebugger.getstored("c592f0a4-a226-11e8-1002-fd2731558606")
118
+
rebug>@eval Colors let (num,) = Main.Rebugger.getstored("57dbc76a-0def-11e9-1dbf-ef97d29d2e25")
(Again, if this doesn't happen check [Keyboard shortcuts](@ref) and [Customize keybindings](@ref).)
130
+
You are in the method corresponding to `[1]` in the stacktrace.
108
131
Now you can navigate with your up and down arrows to browse the captured stacktrace.
109
-
You can pick any of these expressions to execute (hit Enter) or edit before execution.
110
-
For example you could add `@show` commands to examine intermediate variables or test
111
-
out different ways to fix a bug.
132
+
For example, if you hit the up arrow twice, you will be in the method corresponding to `[3]`:
133
+
134
+
```julia
135
+
julia>colorant"hsl(80%, 20%, 15%)"
136
+
┌ Warning: Tuple{getfield(Colors, Symbol("#@colorant_str")),LineNumberNode,Module,Any} was not found, perhaps it was generated by code
137
+
└ @ Revise ~/.julia/dev/Revise/src/Revise.jl:659
138
+
Captured elements of stacktrace:
139
+
[1] parse_hsl_hue(num::AbstractString) in Colors at /home/tim/.julia/packages/Colors/4hvzi/src/parse.jl:25
140
+
[2] _parse_colorant(desc::AbstractString) in Colors at /home/tim/.julia/packages/Colors/4hvzi/src/parse.jl:51
141
+
[3] _parse_colorant(::Type{C}, ::Type{SUP}, desc::AbstractString) where {C<:Colorant, SUP} in Colors at /home/tim/.julia/packages/Colors/4hvzi/src/parse.jl:112
142
+
[4] parse(::Type{C}, desc::AbstractString) where C<:Colorantin Colors at /home/tim/.julia/packages/Colors/4hvzi/src/parse.jl:140
143
+
_parse_colorant(::Type{C}, ::Type{SUP}, desc::AbstractString) where {C<:Colorant, SUP} in Colors at /home/tim/.julia/packages/Colors/4hvzi/src/parse.jl:112
144
+
C = Colorant
145
+
SUP = Any
146
+
desc =hsl(80%, 20%, 15%)
147
+
rebug>@eval Colors let (C, SUP, desc) = Main.Rebugger.getstored("57d9ebc0-0def-11e9-2ab0-e5d1e4c6e82d")
148
+
begin
149
+
_parse_colorant(desc)
150
+
end
151
+
end
152
+
```
153
+
154
+
You can hit the down arrow and go back to earlier entries in the trace.
155
+
Alternatively, you can pick any of these expressions to execute (hit Enter) or edit before execution.
112
156
You can use the REPL history to test the results of many different changes to the same "method";
113
157
the "method" will be run with the same inputs each time.
114
158
159
+
!!! note
160
+
When point is at the end of the input, the up and down arrows step through the history.
161
+
But if you move point into the method body (e.g., by using left-arrow),
162
+
the up and down arrows move within the method body.
163
+
If you've entered edit mode, you can go back to history mode using PgUp and PgDn.
164
+
115
165
## Important notes
116
166
117
167
### "Missing" methods from stacktraces
118
168
119
169
In the example above, you may have noticed the warning about the `@colorant_str` macro
120
170
being omitted from the "captured" (interactive) expressions comprising the stacktrace.
121
171
Macros are not traced.
122
-
Also notice that the inlined method does not appear in the captured stacktrace.
123
-
However, you can enter an inlined method using "step in," starting from the method
124
-
above it in the stacktrace.
125
172
126
173
When many methods use keyword arguments, the apparent difference between the
127
174
"real" stacktrace and the "captured" stacktrace can be quite dramatic:
@@ -154,29 +201,21 @@ Stacktrace:
154
201
julia> Pkg.add("NoPkg") # hit Meta-s here
155
202
Captured elements of stacktrace:
156
203
[1] pkgerror(msg::String...) in Pkg.Types at /home/tim/src/julia-1.0/usr/share/julia/stdlib/v1.0/Pkg/src/Types.jl:120
157
-
[2] ensure_resolved(env::Pkg.Types.EnvCache, pkgs::AbstractArray{Pkg.Types.PackageSpec,1}) in Pkg.Types at /home/tim/src/julia-1.0/usr/share/julia/stdlib/v1.0/Pkg/src/Types.jl:860
158
-
[3] add_or_develop(ctx::Pkg.Types.Context, pkgs::Array{Pkg.Types.PackageSpec,1}) in Pkg.API at /home/tim/src/julia-1.0/usr/share/julia/stdlib/v1.0/Pkg/src/API.jl:32
159
-
[4] add_or_develop(pkgs::Array{String,1}) in Pkg.API at /home/tim/src/julia-1.0/usr/share/julia/stdlib/v1.0/Pkg/src/API.jl:28
160
-
[5] add(args...) in Pkg.API at /home/tim/src/julia-1.0/usr/share/julia/stdlib/v1.0/Pkg/src/API.jl:69
204
+
[2] add(args...) in Pkg.API at /home/tim/src/julia-1.0/usr/share/julia/stdlib/v1.0/Pkg/src/API.jl:69
161
205
pkgerror(msg::String...) in Pkg.Types at /home/tim/src/julia-1.0/usr/share/julia/stdlib/v1.0/Pkg/src/Types.jl:120
162
206
msg = ("The following package names could not be resolved:\n * NoPkg (not found in project, manifest or registry)\nPlease specify by known `name=uuid`.",)
163
-
rebug>@eval Pkg.Types let (msg,) = Main.Rebugger.getstored("b5c899c2-a228-11e8-0877-d102334a9f65")
207
+
rebug>@eval Pkg.Types let (msg,) = Main.Rebugger.getstored("161c53ba-0dfe-11e9-0f8f-59f468aec692")
164
208
begin
165
209
throw(PkgError(join(msg)))
166
210
end
167
211
end
168
212
```
169
213
170
-
Note that only five methods got captured but the stacktrace is much longer.
214
+
Note that only two methods got captured but the stacktrace is much longer.
171
215
Most of these methods, however, start with `#`, an indication that they are
172
-
generated methods rather than ones that appear in the source code.
173
-
The interactive stacktrace visits only those methods that appear in the original source code.
174
-
175
-
!!! note
176
-
`Pkg` is one of Julia's standard libraries, and to step into or trace Julia's stdlibs
177
-
you must build Julia from source.
178
-
179
-
216
+
generated (keyword-handling) methods rather than ones that appear directly in the source code.
217
+
For now, Rebugger omits these entries.
218
+
However, you can enter (i.e., Meta-e) such methods from one that is higher in the stack trace.
0 commit comments