forked from arnaudsj/ChatScript
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathChatScript-Debugger.html
More file actions
98 lines (98 loc) · 7.47 KB
/
ChatScript-Debugger.html
File metadata and controls
98 lines (98 loc) · 7.47 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
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<meta name="generator" content="pandoc" />
<title></title>
<style type="text/css">code{white-space: pre;}</style>
</head>
<body>
<h1 id="chatscript-debugger-manual">ChatScript Debugger Manual</h1>
<p>© Bruce Wilcox, mailto:[email protected] www.brilligunderstanding.com <br>Revision 4/8/2017 cs7.31</p>
<h1 id="debugging-in-and-out">Debugging in and out</h1>
<p>While it is possible to connect ChatScript to a GUI IDE for debugging (if you create one because CS does not come with one natively), CS also has a text command debugger analogous to GDB in LINUX.</p>
<p>You enter the debugger via</p>
<pre><code>:debug</code></pre>
<p>which begins a local command loop. Resume normal execution via</p>
<pre><code>go </code></pre>
<p>or</p>
<pre><code>g</code></pre>
<p>The debug command can also have one of the debug commands after it, e.g.</p>
<pre><code>:debug break ^fn1 ~topic1 ^fn2</code></pre>
<h2 id="variable-and-json-displays">Variable and JSON displays</h2>
<p>While in the debugger, you can display $variables just by typing in their name(s).</p>
<pre><code>$myvar $_yourvar</code></pre>
<p>If you know the name of a JSON unit, you can just type that and get a display of the array or object.</p>
<pre><code>jo-44</code></pre>
<h2 id="source-locations">Source locations</h2>
<p>Typing the name of a function or topic will tell you the file and line number of it.</p>
<h2 id="breakpoints">Breakpoints</h2>
<p>You can set breakpoints that will trigger the debugger on a variety of conditions. And you can name multiple conditions at once. E.g.,</p>
<pre><code>break ^myfunction ~mytopic ~mytopic.myrule</code></pre>
<h2 id="function-breakpoints">Function breakpoints</h2>
<p>A function breakpoint will, by default, break on entry and break on exit. On entry it shows the function and its arguments. On exit it shows the value being returned and any error status.</p>
<p>You can restrict a function to only breaking on entry or exit by suffixing the name with <span class="citation">@i</span> or <span class="citation">@o</span>. Like</p>
<pre><code>break ^myfunc@i</code></pre>
<p>You can delete a breakpoint by putting <code>!</code> in front of the base name. E.g.</p>
<pre><code>break ^myfunc !^otherfunc</code></pre>
<p>Every time you call break, it prints out a summary of the breakpoints still set. So if you call break with no names, it just lists what you have.</p>
<h2 id="topic-breakpoints">Topic breakpoints</h2>
<p>A topic breakpoint will break on entry and exit of topic by whatever manner (normal, <code>^gambit</code>, <code>^rejoinder</code>, <code>^reuse</code>, etc).</p>
<h2 id="rule-breakpoints">Rule breakpoints</h2>
<p>A rule can broken upon by doing</p>
<pre><code> break ~mytopic.label
</code></pre>
<p>where label is either the label of a rule or its tag (e.g., <code>1.0</code> for the 2nd top level rule of the topic).</p>
<h2 id="abnormal-breakpoints">Abnormal breakpoints</h2>
<p>You can name</p>
<pre><code>abort </code></pre>
<p>to request a breakpoint if the system is about to exit due to abnormal conditions.</p>
<h2 id="variable-assigns">Variable Assigns</h2>
<p>A different kind of breakpoint is a variable assign, that is, when a variable has its value changed. You can list multiple variables in a single request.</p>
<pre><code>= $myvar $_hisvar</code></pre>
<p>The breakpoint will tell you the new value it is taking on. Be aware that if you break on a local variable like <code>$_myvar</code> then you break on the next change to it in whatever topic or function it is within. You may, if you want, create a restricted breakpoint for $_vars like this:</p>
<pre><code>^myfunc.$_myvar</code></pre>
<p>or</p>
<pre><code>~mytopic.$_myvar</code></pre>
<h2 id="clearing-breakpoints">Clearing Breakpoints</h2>
<pre><code>clear </code></pre>
<p>will remove all breakpoints including variable assigns.</p>
<h2 id="backtrace">Backtrace</h2>
<pre><code>where </code></pre>
<p>will print out a backtrace of where you are in terms of topics, rules, and functions.</p>
<h2 id="controlled-execution">Controlled execution</h2>
<p>You can step from action to action in your code by typing</p>
<pre><code>s </code></pre>
<p>or</p>
<pre><code>step
</code></pre>
<p>Which is equivalent to <code>step across</code>. This will execute the next thing at the current level (maybe a function call, rule test, assignment or whatever). It will then display what code it executed, what value was returned, and what code would be executed next.</p>
<p>When you are at a rule, <code>s</code> moves to the next rule. Alternatively, you can ask the system to execute rules in a topic until it comes to one that would match by saying</p>
<pre><code>step match</code></pre>
<p>It will stop before entering the output of the rule or until it leaves the topic.</p>
<p>If you discover that the executed code called a function that did something wrong and you want to watch it, you can type</p>
<pre><code>redo in</code></pre>
<p>which will retry that same piece of code, but this time going in instead of stepping over.</p>
<p>You can step out from a function or topic by typing</p>
<pre><code>out</code></pre>
<p>which will execute code until it leaves the current function or topic or rule. topic is confusing when you have rules. If stepping out returns to code which has nothing left to do, that code will also complete and the system will pop out to the next level.</p>
<p>You can step in from an action in your code by typing</p>
<pre><code>in</code></pre>
<p>This will execute one or more bits of code until it calls into some function or exits the current scope entirely.</p>
<h2 id="executing-script-and-other-debug-commands">Executing script and other debug commands</h2>
<p>You can type in a</p>
<pre><code>do</code></pre>
<p>command, which is analogous to <code>:do</code>, which allows you to set variables, execute script functions, etc.</p>
<h2 id="sourcing-a-file-of-debug-commands">Sourcing a file of debug commands</h2>
<p>The command</p>
<pre><code>source filename</code></pre>
<p>will take debugger input from the named file (with a .txt suffix added to the name) where the file is in a top level folder called <code>debug</code>. Any command that resumes execution (like <code>go</code>, <code>in</code>, <code>out</code>, <code>s</code>) will terminate reading from the file.</p>
<p>In addition, you can create a file to automatically execute on a breakpoint. The name of the breakpoint should be the name of the file in the debug directory (with .txt added). When a function named the same as such a file has a breakpoint on entry, it will execute the commands. Similarly whenever a topic has a breakpoint on entry, it will execute its commands.</p>
<h2 id="hooking-up-to-a-gui-ide">Hooking up to a GUI IDE</h2>
<p>The debugger can swap out its stdin and stdout interactions with the user with functions supplied on the <code>InitSystem</code> interface. The functions take a single argument <code>char*</code> and either get a line of input or write out a line of outout.</p>
<h2 id="map-file">MAP file</h2>
<p>The compiler builds a map file used by the debugger to know what files have what and what lines have what.</p>
<p>In addition, for every rule and function at the end of their data, the system prints out the <code>cyclomatic complexity</code> of the output code.</p>
</body>
</html>