-
Notifications
You must be signed in to change notification settings - Fork 154
Expand file tree
/
Copy pathChatScript-Debugger.html
More file actions
390 lines (390 loc) · 15.7 KB
/
ChatScript-Debugger.html
File metadata and controls
390 lines (390 loc) · 15.7 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
<head>
<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
<title>ChatScript-Debugger</title>
<style>
html {
color: #1a1a1a;
background-color: #fdfdfd;
}
body {
margin: 0 auto;
max-width: 36em;
padding-left: 50px;
padding-right: 50px;
padding-top: 50px;
padding-bottom: 50px;
hyphens: auto;
overflow-wrap: break-word;
text-rendering: optimizeLegibility;
font-kerning: normal;
}
@media (max-width: 600px) {
body {
font-size: 0.9em;
padding: 12px;
}
h1 {
font-size: 1.8em;
}
}
@media print {
html {
background-color: white;
}
body {
background-color: transparent;
color: black;
font-size: 12pt;
}
p, h2, h3 {
orphans: 3;
widows: 3;
}
h2, h3, h4 {
page-break-after: avoid;
}
}
p {
margin: 1em 0;
}
a {
color: #1a1a1a;
}
a:visited {
color: #1a1a1a;
}
img {
max-width: 100%;
}
svg {
height; auto;
max-width: 100%;
}
h1, h2, h3, h4, h5, h6 {
margin-top: 1.4em;
}
h5, h6 {
font-size: 1em;
font-style: italic;
}
h6 {
font-weight: normal;
}
ol, ul {
padding-left: 1.7em;
margin-top: 1em;
}
li > ol, li > ul {
margin-top: 0;
}
blockquote {
margin: 1em 0 1em 1.7em;
padding-left: 1em;
border-left: 2px solid #e6e6e6;
color: #606060;
}
code {
font-family: Menlo, Monaco, Consolas, 'Lucida Console', monospace;
font-size: 85%;
margin: 0;
hyphens: manual;
}
pre {
margin: 1em 0;
overflow: auto;
}
pre code {
padding: 0;
overflow: visible;
overflow-wrap: normal;
}
.sourceCode {
background-color: transparent;
overflow: visible;
}
hr {
background-color: #1a1a1a;
border: none;
height: 1px;
margin: 1em 0;
}
table {
margin: 1em 0;
border-collapse: collapse;
width: 100%;
overflow-x: auto;
display: block;
font-variant-numeric: lining-nums tabular-nums;
}
table caption {
margin-bottom: 0.75em;
}
tbody {
margin-top: 0.5em;
border-top: 1px solid #1a1a1a;
border-bottom: 1px solid #1a1a1a;
}
th {
border-top: 1px solid #1a1a1a;
padding: 0.25em 0.5em 0.25em 0.5em;
}
td {
padding: 0.125em 0.5em 0.25em 0.5em;
}
header {
margin-bottom: 4em;
text-align: center;
}
#TOC li {
list-style: none;
}
#TOC ul {
padding-left: 1.3em;
}
#TOC > ul {
padding-left: 0;
}
#TOC a:not(:hover) {
text-decoration: none;
}
code{white-space: pre-wrap;}
span.smallcaps{font-variant: small-caps;}
div.columns{display: flex; gap: min(4vw, 1.5em);}
div.column{flex: auto; overflow-x: auto;}
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
/* The extra [class] is a hack that increases specificity enough to
override a similar rule in reveal.js */
ul.task-list[class]{list-style: none;}
ul.task-list li input[type="checkbox"] {
font-size: inherit;
width: 0.8em;
margin: 0 0.8em 0.2em -1.6em;
vertical-align: middle;
}
.display.math{display: block; text-align: center; margin: 0.5rem auto;}
</style>
<!--[if lt IE 9]>
<script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
<![endif]-->
</head>
<body>
<h1 id="chatscript-debugger-manual">ChatScript Debugger Manual</h1>
<p>Copyright Bruce Wilcox, mailto:gowilcox@gmail.com
www.brilligunderstanding.com <br>Revision 2/18/2018 cs8.1</p>
<p>You can run an interactive debugger environment (IDE) if you have
Windows. You launch it by going to BINARIES and double clicking on
ChatScript IDE. It will load your bot, just as running ChatScript will.
And you can type input into the input window and see output in the
output window just like normal ChatScript. But you can do so much
more…</p>
<p>You can set breakpoints on lines of code, be they actions in a macro,
rules in a topic, or the topic itself. You can break on when CS will
output a message to the user (to see where it comes from). You can break
on change in value of a variable. You can single step in, over, out. You
can display values of user, system, and match variables.</p>
<h1 id="running-the-ide">Running the IDE</h1>
<p>Before you can run the IDE you should compile your scripts under CS
8.0 or higher. You can actually do that from the IDE itself.</p>
<p>The IDE is a wrapper around the CS engine. Instead of launching
<code>ChatScript.exe</code> from BINARIES you launch
<code>ChatScriptIDE.exe</code>. This will load your project just as the
main engine does and then come to rest in the IDE, awaiting your
commands.</p>
<h1 id="the-display">The display</h1>
<figure>
<img src="debuggerdisplay.png" alt="Debugger Screen Image" />
<figcaption aria-hidden="true">Debugger Screen Image</figcaption>
</figure>
<h2 id="script-window">Script window</h2>
<p>The script window displays your source file, information on the
debugger commands, debugging commands (:xxx), IDE commands, and system
variables (and important CS interchange variables).</p>
<p>Your script files will also be displayed when you request it (:i
filename) or when some breakpoint requires it to show you where you
are.</p>
<p>The script window has your code. To the left of that are line numbers
from the file. And to the left of the line numbers are CS tag id’s of
rules. IF you have a breakpoint set, you will see a B between the line
number and your script. The entire area of of tags and line numbers is
clickable to enable and disable a breakpoint at that line.</p>
<p>The window is also sensitive to having parts of your script clicked
upon. If you click on a variable, be it $var, _var, %var, ^var, or <span
class="citation" data-cites="nvar">@nvar</span>, the current value will
get added to the variables window and the value constantly displayed
there. An <span class="citation" data-cites="n">@n</span> variable shows
the count of how many facts it has. You can remove an entry from the
variables window by clicking on it.</p>
<p>Clicking on a function name will change the script window to display
that function. The debugger will highlight where it is in blue. When you
are executing your code and the debugger enters a breakpoint of some
kind, the script window will show you where you currently are,
displaying your script and highlighting in blue where you are. It will
also put << to the left of rule tags/line numbers to indicate this
is where you actually are. The callstack of where you are will be
displayed in the stack window.</p>
<p>If you click on a rule label (like that in a ^reuse) then the system
will take you to that label.</p>
<p>Clicking on a concept or topic name will change the script window to
that’s definition.</p>
<h3 id="file-names-title-bar">File names title bar</h3>
<p>The first line is a list of “windows” you can see. The first name in
the list is always the current windows, and if you left-click on
something else in that list, it is moved to first position and
displayed.</p>
<p>If the bar gets too crowded, right-click on a name and the name is
removed from the bar.</p>
<h3 id="who-talking-to-whom">Who talking to whom</h3>
<p>Above the file names title bar is text that shows you the current
username and the current bot name and botid. `bob=>rose(0)</p>
<h3 id="breakpoints">Breakpoints</h3>
<p>Left-click before a script line (in the number or tag area) and the
system will establish a breakpoint (and put a B after the line number).
If your code executes to that point, it will stop and give you control.
Click again in the same area and the breakpoint is removed.</p>
<p>If you Right-click before a script line, the system create a
transient breakpoint there and run code. The breakpoint will be removed
when execution is stopped by some breakpoint (that one or a different
one).</p>
<h1 id="input-window">Input window</h1>
<p>Here is where you type input for CS or for the IDE.</p>
<p>IDE input is prefixed with <code>:i</code>. Naming a function or
variable or concept set is just like clicking on it in the script
window. It will put the variable in the variables window or display the
code in the script window. You can also name a rule label and code
display will jump to there. Not the full topic label, just what you put
as the label in <code>u: MYLABEL () ...</code>, i.e., MYLABEL.</p>
<pre><code>:i ~control</code></pre>
<p>Above is the classic way to bring up the control script whereby you
can then set a breakpoint. And if you type in a rule label as argument,
it will take you to that label. Handy when you know where you want to
debug in particular.</p>
<p>If the engine is currently running, you can give IDE commands but the
IDE will refuse input for the engine.</p>
<h1 id="output-window">Output window</h1>
<p>Messages from the IDE as well as results or tracing from the engine
are displayed here. While it is scrollable, if too much information is
in the buffer it will truncate the older output.</p>
<h1 id="callstack-window">Callstack window</h1>
<p>When you are in the IDE at a breakpoint, this shows you the calling
hierarchy of where you are. Each scope is numbered (low is deepest, high
is most recent). The possible scopes are a topic, a rule, a function, an
if, or a while. Scopes that have output actions (rules, if, while,
function), will display that you are at that scope by displaying it with
<code>()</code>. You cannot walk in and execute code within a pattern or
an if test or a loop count evaluation, so when the scope is within
executable output, it will display it with <code>{n}</code>, where
<code>n</code> is the internal code offset of where you are, and it will
show you the upcoming code it is about to execute. There is also
<code>lvl:n</code> data, which is internal data about what recursive
level the output interpreter is at (mostly irrelevant to you).</p>
<p>If you click on one of these scope lines, the system will display the
code of that scope in the script window and any local variables ($_xxx
and ^xxx) in the variables window. It will have a title of
<code>local variables</code>.</p>
<h1 id="variables-window">Variables window</h1>
<p>This window shows current values of global variables you have
requested (updated whenever you end up in the IDE). If you clicked on a
scope line, it shows the values of local variables for that scope. You
can flip back to viewing globals by pressing the <code>globals</code>
button.</p>
<p>When variables are displayed, after the variable it tells you how
many characters the value has.</p>
<p>If you click to the left of a global variable, it will set a
breakpoint for when the value of that variable changes and will put a B
before it. Click again in that area and it removes the breakpoint. You
can request a break when the value becomes =, <, or > some value
using</p>
<pre><code>:i varname = test
:i varname > 5 -- integer values only
:i varname < 5 -- integer values only</code></pre>
<p>You can also use various engine debug commands while at a break,
including <code>:trace</code> and <code>:word</code>. Just dont try to
use things that have massive impact, like</p>
<pre><code>:document, :source, :reset, :bot, :user, :restart</code></pre>
<h1 id="system-resource-information">System resource information</h1>
<p>At the bottom of the main window the system prints out useful
statistics about resource usage. It shows you how much of a resource is
currently in use, and what the least amount available has ever been
seen.</p>
<p>‘Memory’ is the available space for stack + heap. If this gets down
toward 10M, you might want to allocate more text space to the
program.</p>
<p>‘Buffer’ is how many preallocated large buffers (typically 80K) are
in use. If it gets to be <10, you might want to allocate more.</p>
<p><code>DICT</code> is how many dictionary entries are available. Less
than 5K probably indicates you want to allocate more.</p>
<p><code>FACT</code> is how many facts are available to be created. Less
than 5K probably indicates you want to allocate more.</p>
<h1 id="sentence-window">Sentence window</h1>
<p>The window above the script window tells you information about the
current user input. By default it shows you the <code>adjusted</code>
input, what the tokenizer and various NLP corrections have been made to
result in the input the system is actually processing at present.</p>
<p>L-click anywhere in the sentence box and it changes to show you the
<code>raw</code> input, what the user provided (after tokenization).</p>
<p>L-click again and it shows you the <code>canonical</code> form of the
input.</p>
<p>L-click again and it returns to the <code>adjusted</code> form of the
input.</p>
<p>If you R-click on a word, it will show you the concepts it is
involved in in the output window.</p>
<h1 id="buttons">Buttons</h1>
<h2 id="go">Go</h2>
<p>Resume execution until complete or a new breakpoint is hit.</p>
<h2 id="in">In</h2>
<p>Try to go in deeper into the current thing. For a topic that will be
its first rule. For a rule, if the pattern matches, it will be the
output of it. For a function it will be the code of the function.</p>
<p>If the system cannot go in, it will stop at the next available
opportunity. Ie., the next action, rule, pass out of the function or
topic.</p>
<h2 id="out">Out</h2>
<p>Leave the current level of behavior and stop as soon thereafter. For
a topic, it leaves the topic, for a rule it leaves the topic. If within
actions of a rule, it leaves that rule. For a function it leaves that
function.</p>
<h2 id="next">Next</h2>
<p>Stay at the current level of behavior. If at a topic, move on to the
next topic (having executed all its rules). If a rule, move on to the
next rule (possibly having executed all its actions). If a function,
step over the function (executing all its actions) and return to caller.
If withing actions of a function then execute the current action and
move to the next one. If inside a rule, do the current action and move
to the next.</p>
<h2 id="stop">Stop</h2>
<p>If the engine is currently executing script, stop that execution as
soon as possible and enter the IDE. Otherwise note that you want to
stop, so that on the next user input the IDE takes control
immediately.</p>
<h2 id="msg">Msg</h2>
<p>Breakpoint when the system wants to print output to the user. This is
useful to see why you are getting the output you get.</p>
<h2 id="fail">Fail</h2>
<p>Breakpoint if any system function return a failure code. These
typically suggest you passed it bad arguments. With this, you can see
when this happens.</p>
<p>Cntrl-lclick tells the debugger to terminate current input and return
to top level.</p>
<h2 id="clear">Clear</h2>
<p>L-click removes all breakpoints currently set (not including variable
breaks). R-click temporarily disables all breakpoints set (including
variable breaks and msg break and fail break). R-click again to
re-enable.</p>
<h2 id="global">Global</h2>
<p>Restore variable window to showing global variables if it is
currently showing locals of some callframe.</p>
<h2 id="back">Back</h2>
<p>As you move from location to location in the stack window, you create
a breadcrumb trail, and <code>Back</code> will take you back from where
you were. If you need to rapidly return to where you are currently
executing code, just click on the last callframe in the stack
window.</p>
<h2 id="font">-Font+</h2>
<p>Changes the font size. Left click for smaller. Right click for
bigger.</p>
</body>
</html>