| blob | e0d2246953e53b5a2bb8ab8f890b67fb3094b715 |
1 <!-- This file is part of Shapes. -->
2 <!-- -->
3 <!-- Shapes is free software: you can redistribute it and/or modify -->
4 <!-- it under the terms of the GNU General Public License as published by -->
5 <!-- the Free Software Foundation, either version 3 of the License, or -->
6 <!-- any later version. -->
7 <!-- -->
8 <!-- Shapes is distributed in the hope that it will be useful, -->
9 <!-- but WITHOUT ANY WARRANTY; without even the implied warranty of -->
10 <!-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -->
11 <!-- GNU General Public License for more details. -->
12 <!-- -->
13 <!-- You should have received a copy of the GNU General Public License -->
14 <!-- along with Shapes. If not, see <http://www.gnu.org/licenses/>. -->
15 <!-- -->
16 <!-- Copyright 2008, 2009 Henrik Tidefelt -->
18 <section id="state-types/misc">
19 <title>Miscellaneous</title>
20 <top>
21 <p>All the rest…</p>
22 </top>
24 <core-state-type name="Ignore">
25 <abstraction>
26 <p>States of type <self /> just ignores everything tacked onto them.</p>
27 </abstraction>
28 <see-also>
29 <value namespace="..Shapes" name="newIgnore" /> <state namespace="..Shapes" name="ignore" />
30 </see-also>
31 <mutator op="tack-on">
32 <function>
33 <case>
34 <arguments>
35 <arg>
36 <type><named-type name="Object" /></type>
37 </arg>
38 </arguments>
39 <side-effect>
40 <p>Nothing.</p>
41 </side-effect>
42 </case>
43 </function>
44 </mutator>
45 </core-state-type>
47 <core-state-type name="Time">
48 <abstraction>
49 <p>States of type <self /> represent the ever-changing time.</p>
50 </abstraction>
51 <see-also>
52 <state namespace="..Shapes" name="time" />
53 </see-also>
54 <mutator op="peek">
55 <function>
56 <case>
57 <result>
58 <type><named-type name="ChronologicalTime" /></type>
59 </result>
60 <dynamic-references></dynamic-references>
61 <description>
62 <p>Get current time.</p>
63 </description>
64 </case>
65 </function>
66 </mutator>
67 </core-state-type>
69 <core-state-type name="Random">
70 <abstraction>
71 <p>Random number generator state.</p>
72 </abstraction>
73 <description>
74 <p>A random number generator state gives direct access to the random integers generated by the generator. Sampling from other distributions is implemented as non-pure functions, such as <value namespace="..Shapes..Numeric..Random" name="ball3D" />, acting on the state.</p>
75 </description>
76 <mutator op="peek">
77 <function>
78 <case>
79 <result>
80 <type><named-type name="Integer" /></type>
81 </result>
82 <dynamic-references></dynamic-references>
83 <description>
84 <p>Get raw sample from the random number generator.</p>
85 </description>
86 <see-also>
87 <value namespace="..Shapes..Numeric..Random" name="ball1D" />
88 <value namespace="..Shapes..Numeric..Random" name="ball2D" />
89 <value namespace="..Shapes..Numeric..Random" name="ball3D" />
90 </see-also>
91 </case>
92 </function>
93 </mutator>
94 </core-state-type>
96 <core-state-type name="Debugger">
97 <abstraction>
98 <p>States of type <self /> let the user interact with the compiler.</p>
99 </abstraction>
100 <description>
101 <p>In the interactive mode of the compiler, a state of type <self /> is present in every environment for interactive evaluation. This state is always named <db-state />, and there is no way to create other <selv /> states. See <a part="interactive" /> for a more pedagogical treatment of the actual use of <self /> states.</p>
102 </description>
103 <mutator identifier="resume">
104 <alias identifier="r" />
105 <function>
106 <case>
107 <arguments>
108 <arg identifier="result">
109 <default><user-value name="expr" /></default>
110 </arg>
111 </arguments>
112 <side-effect>
113 <p>Invokes <escape namespace="..Shapes..Debug" name="resume" />.</p>
114 </side-effect>
115 <description>
116 <p>Invokes the continuation <escape namespace="..Shapes..Debug" name="resume" /> with the argument <arg name="result"/>.</p>
117 <p>If <arg name="result" /> is not provided, the expression where evaluation was interrupted is made the next expression to evaluate (with the corresponding lexical and dynamic environments), rather than actually passing the corresponding thunk <user-value name="expr" /> to the continuation. The special treatment of the default for <arg name="result" /> also includes making sure that a breakpoint is not triggered immediately, which is very convenient if evaluation was previously interrupted at a breakpoint.</p>
118 <p>For instance,
119 <pre>
120 <![CDATA[•db.[resume void]]]>
121 </pre>
122 shall be equivalent to
123 <pre>
124 <![CDATA[(escape_continue resume void)]]>
125 </pre>
126 and
127 <pre>
128 <![CDATA[•db.[resume]]]>
129 </pre>
130 (at a breakpoint) shall be similar to
131 <pre>
132 <![CDATA[•db.[breakIgnore]
133 (escape_continue resume expr)]]>
134 </pre>
135 </p>
136 </description>
137 </case>
138 </function>
139 </mutator>
140 <mutator identifier="top_repl">
141 <function>
142 <case>
143 <arguments>
144 <arg identifier="result">
145 <default><value-the-void /></default>
146 </arg>
147 </arguments>
148 <side-effect>
149 <p>Invokes <escape namespace="..Shapes..Debug" name="top_repl" />.</p>
150 </side-effect>
151 <description>
152 <p>Invokes the continuation <escape namespace="..Shapes..Debug" name="top_repl" /> with the argument <arg name="result"/>. Note that while the default value for <arg name="result" /> in <mutator type="Debugger" name="resume" /> depends on where evaluation was interrupted, the default value here is always the same.</p>
153 </description>
154 </case>
155 </function>
156 </mutator>
157 <mutator identifier="backtrace">
158 <alias identifier="t" />
159 <function>
160 <case>
161 <arguments>
162 </arguments>
163 <result>
164 <type><named-type name="String" /></type>
165 </result>
166 <description>
167 <p>The returned string will display the backtrace when printed by the interactive continuation. Here, a <em>backtrace</em> refers to the chain of continuations starting from the current continuation. When the chain reaches an interactive continuation, it is continued at its <escape namespace="..Shapes..Debug" name="resume" />.</p>
168 </description>
169 </case>
170 </function>
171 </mutator>
172 <mutator identifier="env">
173 <alias identifier="e" />
174 <function>
175 <case>
176 <arguments>
177 </arguments>
178 <result>
179 <type><named-type name="String" /></type>
180 </result>
181 <description>
182 <p>The returned string will display the lexical environment at the point of interaction.</p>
183 </description>
184 </case>
185 </function>
186 </mutator>
187 <mutator identifier="dyn">
188 <alias identifier="d" />
189 <function>
190 <case>
191 <arguments>
192 </arguments>
193 <result>
194 <type><named-type name="String" /></type>
195 </result>
196 <description>
197 <p>The returned string will display the dynamic environment at the point of interaction.</p>
198 </description>
199 </case>
200 </function>
201 </mutator>
202 <mutator identifier="breakList">
203 <alias identifier="bl" />
204 <function>
205 <case>
206 <arguments>
207 </arguments>
208 <result>
209 <type><named-type name="String" /></type>
210 </result>
211 <description>
212 <p>The returned string displays information about the currently existing breakpoints. The first column lists the <em>current</em> index of a breakpoint, but note that this number may change over time as breakpoints are cleared or created. The second column (within parentheses) tells if the breakpoint is enabled (<em>on</em>) or not (<em>off</em>), optionally followed by other information about the breakpoint. Following a colon, each line ends with the breakpoint location.</p>
213 </description>
214 </case>
215 </function>
216 </mutator>
217 <mutator identifier="breakAt">
218 <alias identifier="ba" />
219 <function>
220 <case>
221 <arguments>
222 <arg identifier="file">
223 <type><named-type name="String" /></type>
224 </arg>
225 <arg identifier="line">
226 <type><named-type name="Integer" /></type>
227 </arg>
228 <arg identifier="column">
229 <type><named-type name="Integer" /></type>
230 <default><eq>0</eq></default>
231 </arg>
232 <arg identifier="enable">
233 <type><named-type name="Boolean" /></type>
234 </arg>
235 </arguments>
236 <side-effect>
237 <p>Enable, disable, or toggle breakpoint at a given source location.</p>
238 </side-effect>
239 <description>
240 <p>If <arg name="enable" /> is not provided, it defaults to toggle the breakpoint.</p>
241 <p>The expression pointed out is defined as the expression with the smallest source location that includes the given position.</p>
242 </description>
243 </case>
244 </function>
245 </mutator>
246 <mutator identifier="breakIn">
247 <alias identifier="bi" />
248 <function>
249 <case>
250 <arguments>
251 <arg identifier="function">
252 <type><named-type name="UserFunction" /></type>
253 </arg>
254 <arg identifier="enable">
255 <type><named-type name="Boolean" /></type>
256 </arg>
257 </arguments>
258 <side-effect>
259 <p>Enable, disable, or toggle breakpoint at the body of a function.</p>
260 </side-effect>
261 <description>
262 <p>If <arg name="enable" /> is not provided, it defaults to toggle the breakpoint.</p>
263 </description>
264 </case>
265 </function>
266 </mutator>
267 <mutator identifier="breakIgnore">
268 <alias identifier="bg" />
269 <function>
270 <case>
271 <arguments>
272 <arg identifier="index">
273 <type><named-type name="Integer" /></type>
274 <default><eq>0</eq></default>
275 </arg>
276 <arg identifier="count">
277 <type><named-type name="Integer" /></type>
278 <default><eq>1</eq></default>
279 </arg>
280 </arguments>
281 <side-effect>
282 <p>Set count for how many times a breakpoint shall be ignored.</p>
283 </side-effect>
284 <description>
285 <p>The default value for <arg name="index" /> refers to the expression where evaluation was interrupted. Any other value is interpreted by the indices listed by <mutator type="Debugger" name="breakList" />.</p>
286 </description>
287 </case>
288 </function>
289 </mutator>
290 <mutator identifier="breakClear">
291 <alias identifier="bc" />
292 <function>
293 <case>
294 <arguments>
295 <arg identifier="index">
296 <type><named-type name="Integer" /></type>
297 <default><eq>0</eq></default>
298 </arg>
299 </arguments>
300 <side-effect>
301 <p>Remove breakpoint completely.</p>
302 </side-effect>
303 <description>
304 <p>The default value for <arg name="index" /> refers to the expression where evaluation was interrupted. Any other value is interpreted by the indices listed by <mutator type="Debugger" name="breakList" />.</p>
305 </description>
306 </case>
307 </function>
308 </mutator>
309 <mutator identifier="breakClearAll">
310 <alias identifier="bC" />
311 <function>
312 <case>
313 <arguments>
314 </arguments>
315 <side-effect>
316 <p>Remove all breakpoints completely.</p>
317 </side-effect>
318 </case>
319 </function>
320 </mutator>
321 <mutator identifier="step">
322 <alias identifier="s" />
323 <function>
324 <case>
325 <arguments>
326 <arg identifier="count">
327 <type><named-type name="Integer" /></type>
328 <default><eq>1</eq></default>
329 </arg>
330 </arguments>
331 <description>
332 <p>Continue program evaluation until reaching an expression which is not lexically inside the current expression.</p>
333 <p>The argument <arg name="count" /> tells how many times to continue evaluation before actually interrupting again.</p>
334 </description>
335 <see-also>
336 <mutator type="Debugger" name="resume" />
337 </see-also>
338 </case>
339 </function>
340 </mutator>
341 <mutator identifier="stepe">
342 <alias identifier="se" />
343 <function>
344 <case>
345 <arguments>
346 <arg identifier="count">
347 <type><named-type name="Integer" /></type>
348 <default><eq>1</eq></default>
349 </arg>
350 </arguments>
351 <description>
352 <p>Step program evaluation to the next expression <arg name="count" /> times, and then interrupt evaluation.</p>
353 </description>
354 <see-also>
355 <mutator type="Debugger" name="resume" />
356 </see-also>
357 </case>
358 </function>
359 </mutator>
360 <mutator identifier="stepc">
361 <alias identifier="sc" />
362 <function>
363 <case>
364 <arguments>
365 </arguments>
366 <description>
367 <p>Step program evaluation to the next <em>child</em> expression of the current expression.</p>
368 <p>Uses temporary breakpoints internally. If no breakpoints are set, the stepping is aborted. The ignore count (see <mutator type="Debugger" name="breakIgnore" />) is not affected, which means that it can be used to avoid stopping in some of the expressions where temporary breakpoints are set.</p>
369 </description>
370 <see-also>
371 <mutator type="Debugger" name="steps" />
372 </see-also>
373 </case>
374 </function>
375 </mutator>
376 <mutator identifier="steps">
377 <alias identifier="ss" />
378 <function>
379 <case>
380 <arguments>
381 </arguments>
382 <description>
383 <p>Step program evaluation to the next <em>sibling</em> expression of the current expression.</p>
384 <p>Uses temporary breakpoints internally, compare with <mutator type="Debugger" name="stepc" />.</p>
385 </description>
386 </case>
387 </function>
388 </mutator>
389 <mutator identifier="contUp">
390 <alias identifier="cu" />
391 <function>
392 <case>
393 <arguments>
394 <arg identifier="count">
395 <type><named-type name="Integer" /></type>
396 <default><eq>1</eq></default>
397 </arg>
398 </arguments>
399 <side-effect>
400 <p>Update to be consistent with a new <escape namespace="..Shapes..Debug" name="resume" />.</p>
401 </side-effect>
402 <description>
403 <p>Replace the current interactive context with one where <escape namespace="..Shapes..Debug" name="resume" /> is found by following the backtrace <arg name="count" /> steps up.</p>
404 <p>Since this mutator has side effects on the involved state, it is not possible to go past the next interactive continuation in the backtrace. (Doing so would break the rule that only states appearing in an expression may be modified by that expression. Exactly reaching the next interactive continuation is possible since it is then possible to reuse that interactive context as is.)</p>
405 </description>
406 <see-also>
407 <mutator type="Debugger" name="resume" />
408 <mutator type="Debugger" name="backtrace" />
409 <mutator type="Debugger" name="contExit" />
410 </see-also>
411 </case>
412 </function>
413 </mutator>
414 <mutator identifier="contExit">
415 <alias identifier="ce" />
416 <function>
417 <case>
418 <arguments>
419 <arg identifier="count">
420 <type><named-type name="Integer" /></type>
421 <default><eq>1</eq></default>
422 </arg>
423 </arguments>
424 <description>
425 <p>Exit the current interactive context by replacing it with an interactive continuation higher up in the backtrace.</p>
426 <p>Unlike <mutator type="Debugger" name="contUp" /> this mutator has no side effects on the state in the new interactive context, which explains why this mutator can go past the next interactive continuation in the backtrace.</p>
427 </description>
428 <see-also>
429 <mutator type="Debugger" name="resume" />
430 <mutator type="Debugger" name="backtrace" />
431 <mutator type="Debugger" name="contUp" />
432 </see-also>
433 </case>
434 </function>
435 </mutator>
436 </core-state-type>
438 </section>