doc/parts/interactive/index.sxml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2
   3 <!-- This file is part of Shapes.                                           -->
   4 <!--                                                                        -->
   5 <!-- Shapes is free software: you can redistribute it and/or modify         -->
   6 <!-- it under the terms of the GNU General Public License as published by   -->
   7 <!-- the Free Software Foundation, either version 3 of the License, or      -->
   8 <!-- any later version.                                                     -->
   9 <!--                                                                        -->
  10 <!-- Shapes is distributed in the hope that it will be useful,              -->
  11 <!-- but WITHOUT ANY WARRANTY; without even the implied warranty of         -->
  12 <!-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the          -->
  13 <!-- GNU General Public License for more details.                           -->
  14 <!--                                                                        -->
  15 <!-- You should have received a copy of the GNU General Public License      -->
  16 <!-- along with Shapes.  If not, see <http://www.gnu.org/licenses/>.        -->
  17 <!--                                                                        -->
  18 <!-- Copyright 2009, 2010 Henrik Tidefelt                                   -->
  19
  20 <!--#include virtual="../formats/doctype-book.xml" meta="yes" -->
  21
  22 <book>
  23         <title>Interactive mode</title>
  24         <description>
  25                 <p>Using the <str-Shapes /> compiler interactively.</p>
  26         </description>
  27         <meta-selflink><part-href name="interactive" /></meta-selflink>
  28         <examples-home href=<!--#expand-next-string-->"$(EXAMPLES)" />
  29         <shapes-version number=<!--#expand-next-string-->"$(SHAPES_VERSION)" />
  30         <top>
  31                 <p>When learning <str-Shapes />, it may be useful to try out the language with the compiler operating in <em>interactive mode</em>.  This means that you give small chunks of code to the compiler, and the compiler replies with the value of that chunk.  This part of the documentation discusses how this mode can be useful, and explains a few differences in language semantics for this mode.</p>
  32         </top>
  33
  34         <section id="interactive/launch">
  35         <title>Launching the interactive mode</title>
  36         <body>
  37                 <p>How to start the compiler in interactive mode is explained in the <a part="man" id="interactive">man page</a>.  Here, we just give an example; try running
  38 <pre>
  39 shapes -i --xpdf
  40 </pre>
  41 and start typing!  You may exit by terminating the input stream.</p>
  42
  43     <p>To give an idea of what working with the interactive mode is like, a short sample session is included below:</p>
  44 <pre><![CDATA[<!--#include virtual="sample-session.txt" depth="0" -->]]></pre>
  45     <p>Note the error recovery which has no counter-part in non-interactive mode.  Also note that <named-type name="Drawable" /> results are output to files that are displayed automatically by a <str-PDF /> previewer.  The non-standard input <inline>:ce</inline> is used to abandon the debugging context that was set up to handle type mismatch error.  This and many other features of the interactive mode will be described in the following sections.</p>
  46         </body>
  47         </section><!-- End of interactive-launch -->
  48
  49         <section id="interactive/semantics">
  50         <title>Semantics</title>
  51         <body>
  52                 <p>The difference between interactive and non-interactive evaluation is that the list of bindings in a code bracket (environment) need not be completely known when evaluating expressions in that bracket (environment).  The ability to modify the set of bindings is restricted to certain <em>imaginary</em> code brackets, ensuring that the bindings in existing code are never affected.</p>
  53                 <p>While bindings cannot be affected, there are some things that <em>can</em> be done in the interactive mode:
  54                         <ul>
  55                                 <li>States can be mutated.</li>
  56                                 <li>Continuations may be invoked, effectively changing the value of certain expressions.</li>
  57                                 <li>Bindings may be introduced in the imaginary code bracket.</li>
  58                                 <li>Expressions may result in values although not at the end of the imaginary code bracket, and the result will be displayed.</li>
  59                         </ul>
  60                 </p>
  61                 <p>If an expression results in a <named-type name="Drawable" /> “being returned to” the imaginary code bracket, the result is written to a file, and the name of the file is given on <filename>stdout</filename>.  The details of where the file is placed, and its name, are explained in the <a part="man" id="interactive">man page</a>.  Let it just be mentioned here, that there is a default, so one does not have to specify anything on the command line.  If a previewer is opted for, it will be invoked to display the file.</p>
  62         </body>
  63         </section><!-- End of interactive-semantics -->
  64
  65         <section id="interactive/input">
  66         <title>Typing input in the interactive mode</title>
  67         <body>
  68                 <p>The interactive mode is meant to be used more or less interactively.  For the typing of input, this means that the source shall be given in chunks that can be evaluated individually, rather than as a continuous stream of characters.  Chunks consisting of just one line can be typed as is, but to enter input with more than one line one must prevent that the newline at the end of each line is interpreted as the end of the chunk.  In <str-Shapes /> non-end-of-chunk newlines must be preceded with the space character (many other language use the backslash instead of the space character for this purpose, but this is not a good option for <str-Shapes /> since the backslash is a token by itself).</p>
  69                 <p>Having to remember the space before each in-chunk newline can be very annoying, but it is even worse that once a line has been entered, there is no way to go back and change it.  The rationale is that users are not expected to type chunks that consist of more than one line directly at the <str-Shapes /> compiler prompt, but the space-newline sequence shall just be considered part of a simple protocol that can be used by external command editors (such as <a id="interactive-Emacs-shapes-mode">Emacs with <str-shapes-mode /></a>).</p>
  70                 <p>Since the interactive mode is not only used for play, but also for debugging, and many of the actions a user takes while debugging are commanded through <db-state />, the interactive mode gives fast access to the methods of this state.  The easy convention that makes this possible is that if an input begins with a colon, the rest of the input is placed within the brackets of a mutator call to <db-state />.  For instance,
  71 <pre>
  72 :bi circle
  73 </pre>
  74 is expanded to
  75 <pre>
  76 #db.[bi circle]
  77 </pre>
  78 (where <mutator type="Debugger" name="bi" /> is an alias for <mutator type="Debugger" name="breakIn" />).  Note that this convention does not interfere with normal input, since each normal chunk of input must be complete in itself, and hence cannot begin with a colon.</p>
  79         </body>
  80         </section><!-- End of interactive-launch -->
  81
  82         <section id="interactive/continuations">
  83         <title>Continuations available in the interactive mode</title>
  84         <body>
  85                 <p>There are two special continuations that are provided in the dynamic environment of the interactive evaluation.</p>
  86                 <p>One continuation is named <escape name="bye" />, and may be used to exit the interactive mode without terminating the input stream.  Unlike when exiting by terminating the input stream, no message is printed before the <str-Shapes /> compiler exits.  The value passed to this continuation determined the exit code from the <str-Shapes /> compiler.  An integer outside the reserved range <eq>[ -99, 99 ]</eq> is returned as is, and the symbols { <inline>'OK</inline> <inline>'GenericError</inline> <inline>'UserDetectedError</inline> } may be used to refer to some of the exit codes (in the reserved range) specified in the <a part="man">man page</a>.</p>
  87                 <p>The other continuation is named <escape name="top_repl" /> (read as <em>top level read-eval-print-loop</em>), and gives access to the continuation used to drive the interactive mode.  It is not clear that this can be useful, as long as continuations are limited to exist only in the dynamic environment.  For instance, a debugging tool like the following function is not possible to define as the language is defined today:</p>
  88 <pre class="bad">
  89 <![CDATA[break: \ val → (escape_continuation c (escape_continue top_repl (> cont:c result:val <)))]]>
  90 </pre>
  91     <p>The following short session illustrates the effects of invoking the two continuations discussed in this section.</p>
  92 <pre><![CDATA[<!--#include virtual="continuations-session.txt" depth="0" -->]]></pre>
  93
  94         </body>
  95         </section><!-- End of interactive-continuations -->
  96
  97         <section id="interactive/debug">
  98                 <title>Debugging using the interactive mode</title>
  99                 <top>
 100                         <p>In every environment that is set up for interactive evaluation there is a <db-state /> state, and it is through this the user can do typical debugging tasks such as setting breakpoints, stepping the program, and inspecting various aspects of the evaluation.  The state <db-state /> is of type <named-state-type name="Debugger" />, and the documentation of this type is to be considered the main reference for <db-state />.  In this section, <db-state /> is described in tutorial style, along with some additional information that is key to understanding the debugging facility.</p>
 101                         <p>Most mutators of <named-state-type name="Debugger" /> have abbreviated aliases to allow them to be typed quickly at the debug prompt.  Here, the abbreviated forms will be used in code examples, while the longer names are used in running text.  If there is an abbreviated form, it can always be found by following the link to the reference documentation for the mutator in question.</p>
 102                 </top>
 103                 <section id="interactive/debug/quick-start">
 104                         <title>Getting started</title>
 105                         <body>
 106                                 <p>A <em>breakpoint</em> is set at an <em>expression</em>.  Instead of evaluating the expression, a new code bracket is set up at the point of the expression, the expression is stored as a thunk bound to <user-value name="expr" />, the continuation for the expression is bound to <escape name="resume" />, a <db-state /> is set up with relevant parameters, and interactive mode is entered in that environment.  Now, the user may examine expressions, modify states, introduce temporary bindings, and so forth.  When happy and ready to continue, the normal action to take is to type
 107 <pre>
 108 :r
 109 </pre>
 110 but if program evaluation was interrupted because of an error, this will probably just trigger the same error again.  To recover from an error one must resume evaluation with an expression that replaces the one that caused the error, or one may just abort the debugging session by escaping to the top level interaction by means of <escape name="top_repl" />.</p>
 111                         </body>
 112                 </section>
 113                 <section id="interactive/debug/prompt">
 114                         <title>The debug prompt</title>
 115                         <body>
 116                                 <p>The prompt that asks for input will indicate that evaluation takes place in a debugging context.  If another error occurs while debugging, this may or may not set up a new debugging context — some logic is used to try to decide when setting up a new context would just be annoying.  The following sample session shows how the prompt changes, and reuse of the debugging context.
 117 <pre><![CDATA[<!--#include virtual="debug-depth-session.txt" depth="0" -->]]></pre>
 118                                 </p>
 119                         </body>
 120                 </section>
 121                 <section id="interactive/debug/examine">
 122                         <title>Examining the context</title>
 123                         <body>
 124                                 <p>Besides examining the lexical and dynamic environments by simply evaluating individual lexical or dynamic variables, <db-state /> can be used to get information about all available bindings (but the core bindings are omitted for brevity) by means of <mutator type="Debugger" name="env" /> and <mutator type="Debugger" name="dyn" />.  Similarly, a the backtrace returned by <mutator type="Debugger" name="backtrace" /> displays important information about the chain of continuations and possibly nested debugging contexts.  There is not much to say about these mutators (yes, they are mutators since they are accessed via a state), so we turn to more interesting features of the debugger.</p>
 125                         </body>
 126                 </section>
 127                 <section id="interactive/debug/breakpoints">
 128                         <title>Breakpoints</title>
 129                         <body>
 130                                 <p>Each expression may have a breakpoint, and these are the ways of referring to a breakpoint or the corresponding expression:
 131                                         <ul>
 132                                                 <li><p>By source location (<mutator type="Debugger" name="breakAt" />), that is, a filename (which will be resolved using the same search path as the <str-Shapes /> compiler uses for the <inline>##needs</inline> directive), a line number, and a column number.  This refers to the smallest expression that contains the position.</p></li>
 133                                                 <li><p>The body of a user-defined function (<mutator type="Debugger" name="breakIn" />), referenced simply by the function object itself.</p></li>
 134                                                 <li><p>Sometimes existing breakpoints are referenced by their number in the list of all breakpoints returned by <mutator type="Debugger" name="breakList" />.</p></li>
 135                                                 <li><p>Some <db-state /> mutators have the current expression (where evaluation has been interrupted) as default.</p></li>
 136                                         </ul>
 137                                         Note that not every expression may be possible to refer to by any of these methods.  For instance, two expressions may sometimes have exactly the same source locations.</p>
 138                                 <p>Once an expression is given a breakpoint, one may set an <em>ignore count</em> (using <mutator type="Debugger" name="breakIgnore" />) to inactivate the breakpoint for a given number of visits.  This can be useful, for instance, if the expression appears in a loop, and one knows that it is only after a number of iterations that the expression is interesting to stop at.</p>
 139                                 <p>To clear breakpoints, one has <mutator type="Debugger" name="breakClear" /> that clears just one expression (defaulting to the current expression), and <mutator type="Debugger" name="breakClearAll" /> that clears all breakpoints.</p>
 140                         </body>
 141                 </section>
 142                 <section id="interactive/debug/stepping">
 143                         <title>Stepping</title>
 144                         <body>
 145                                 <p>Stepping the evaluation of a lazy language is a rather strange thing to do since the way evaluation jumps from one expression to the next is often hard to predict.  On the other hand, stepping the evaluation may be a good way for someone who is not used to lazy evaluation to learn how it works.</p>
 146                                 <p>Currently, the interactive mode (for it is the mode of evaluation rather than a feature of <db-state /> that makes stepping possible) supports two modes of stepping.  The simplest way to step evaluation is to stop at every expression, <mutator type="Debugger" name="stepe" /> is the way a user may access this mode.</p>
 147                                 <p>Sometimes, stopping at every expression becomes tedious and one would like to make bigger steps.  One way to do so is to stop at the first expression which is not lexigraphically inside the current expression, and the corresponding mutator of <db-state /> is <mutator type="Debugger" name="step" />.  Just as with <mutator type="Debugger" name="stepe" />, it may be very hard to predict the destination of <mutator type="Debugger" name="step" />.</p>
 148                                 <p>One way to step in a more predictable manner is obviously to temporarily set breakpoints at the desired destinations, and this idea is supported internally by the interactive mode.  There are currently two mutators that use this mechanism; <mutator type="Debugger" name="stepc" /> sets temporary breakpoints in all <em>child</em> expressions of the current expression, while <mutator type="Debugger" name="steps" /> sets temporary breakpoints in all <em>sibling</em> expressions.</p>
 149                         </body>
 150                 </section>
 151                 <section id="interactive/debug/cont">
 152                         <title>Going up the backtrace</title>
 153                         <body>
 154                                 <p>While the mutators <mutator type="Debugger" name="resume" /> and <mutator type="Debugger" name="top_repl" /> gives convenient access to certain continuations, and other continuations in the dynamic environment may be invoked manually, there are still many anonymous continuations that can be seen in the backtrace, but which are not accessible by any of the tools described so far.  To serve this need, <mutator type="Debugger" name="contExit" /> allows an interactive context to be exited by simply picking an interactive continuation from the backtrace.  To reach a continuation between the bottom of the backtrace and the next interactive backtrace, one has to use <mutator type="Debugger" name="contUp" />.</p>
 155                                 <p>Note that a common use of <mutator type="Debugger" name="contExit" /> is to abandon an interactive context that was entered because of some unfortunate typo at the debug prompt, as the next example shows.
 156 <pre><![CDATA[<!--#include virtual="debug-contExit-session.txt" depth="0" -->]]></pre>
 157 </p>
 158                         </body>
 159                 </section>
 160         </section><!-- End of interactive-debug -->
 161
 162         <section id="interactive/Emacs-shapes-mode">
 163         <title>Support for interactive mode in Emacs</title>
 164         <body>
 165                 <p>Once you have installed <a part="edit" id="edit/shapes-mode" ><str-shapes-mode /></a> in Emacs, type <em>M-x run-shapes</em> to start the interactive mode inside an Emacs buffer.  Try producing a <named-type name="Drawable" /> value — it's fun!</p>
 166                 <figure>
 167                         <image>
 168                                 <a href=<!--#expand-next-string-->"$(BASE)img/shapes-mode-interactive-screenshot.png" target="_">
 169                                         <img class="screenshot" src=<!--#expand-next-string-->"$(BASE)img/shapes-mode-interactive-screenshot-www.jpg" />
 170                                 </a>
 171                         </image>
 172                   <caption>
 173                                 <p>Screenshot of the <str-shapes-mode /> interface to the interactive mode of the <str-Shapes /> compiler.</p>
 174                         </caption>
 175                 </figure>
 176         </body>
 177         </section><!-- End of interactive-support -->
 178
 179 </book>