<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">

<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

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]>

<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>

<img src="debuggerdisplay.png" alt="Debugger Screen Image" />

<figcaption aria-hidden="true">Debugger Screen Image</figcaption>

<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 &lt;&lt; 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=&gt;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 =, &lt;, or &gt; some value

using</p>

<pre><code>:i varname = test

:i varname &gt; 5 -- integer values only

:i varname &lt; 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 &lt;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>