<p>The normal interaction with <strong class="pkg">GAP</strong> happens in the so-called <em>read-eval-print</em> loop. This means that you type an input, <strong class="pkg">GAP</strong> first reads it, evaluates it, and then shows the result. Note that the term <em>print</em> may be confusing since there is a <strong class="pkg">GAP</strong> function called <code class="func">Print</code> (<a href="chap6.html#X7AFA64D97A1F39A3"><span class="RefLink">6.3-4</span></a>) (see <a href="chap6.html#X8074A8387C9DB9A8"><span class="RefLink">6.3</span></a>) which is in fact <em>not</em> used in the read-eval-print loop, but traditions are hard to break. In the following, whenever we want to express that <strong class="pkg">GAP</strong> places some characters on the standard output, we will say that <strong class="pkg">GAP</strong> <em>shows</em> something.</p>
<p>The exact sequence in the read-eval-print loop is as follows.</p>
<p>To signal that it is ready to accept your input, <strong class="pkg">GAP</strong> shows the <em>prompt</em> <code class="code">gap></code>. When you see this, you know that <strong class="pkg">GAP</strong> is waiting for your input.</p>
<p>Note that every statement must be terminated by a semicolon. You must also enter <strong class="button">Return</strong> (i.e., strike the <strong class="button">Return</strong> key) before <strong class="pkg">GAP</strong> starts to read and evaluate your input. (The <strong class="button">Return</strong> key may actually be marked with the word <strong class="button">Enter</strong> and a returning arrow on your terminal.) Because <strong class="pkg">GAP</strong> does not do anything until you enter <strong class="button">Return</strong>, you can edit your input to fix typos and only when everything is correct enter <strong class="button">Return</strong> and have <strong class="pkg">GAP</strong> take a look at it (see <a href="chap6.html#X82234FD181899530"><span class="RefLink">6.8</span></a>). It is also possible to enter several statements as input on a single line. Of course each statement must be terminated by a semicolon.</p>
<p>It is absolutely acceptable to enter a single statement on several lines. When you have entered the beginning of a statement, but the statement is not yet complete, and you enter <strong class="button">Return</strong>, <strong class="pkg">GAP</strong> will show the <em>partial prompt</em> <code class="code">></code>. When you see this, you know that <strong class="pkg">GAP</strong> is waiting for the rest of the statement. This happens also when you forget the semicolon <code class="code">;</code> that terminates every <strong class="pkg">GAP</strong> statement. Note that when <strong class="button">Return</strong> has been entered and the current statement is not yet complete, <strong class="pkg">GAP</strong> will already evaluate those parts of the input that are complete, for example function calls that appear as arguments in another function call which needs several input lines. So it may happen that one has to wait some time for the partial prompt.</p>
<p>When you enter <strong class="button">Return</strong>, <strong class="pkg">GAP</strong> first checks your input to see if it is syntactically correct (see Chapter <a href="chap4.html#X7FE7C0C17E1ED118"><span class="RefLink">4</span></a> for the definition of syntactically correct). If it is not, <strong class="pkg">GAP</strong> prints an error message of the following form</p>
<p>The first line tells you what is wrong about the input, in this case the <code class="code">*</code> operator takes two expressions as operands, so obviously the right one is missing. If the inputcame from a file (see <code class="func">Read</code> (<a href="chap9.html#X8373AC6B7D5F9167"><span class="RefLink">9.8-1</span></a>)), this line will also contain the filename and the line number. The second line is a copy of the input. And the third line contains a caret pointing to the place in the previous line where <strong class="pkg">GAP</strong> realized that something is wrong. This need not be the exact place where the error is, but it is usually quite close.</p>
<p>Sometimes, you will also see a partial prompt after you have entered an input that is syntactically incorrect. This is because <strong class="pkg">GAP</strong> is so confused by your input, that it thinks that there is still something to follow. In this case you should enter <code class="code">;</code><strong class="button">Return</strong> repeatedly, ignoring further error messages, until you see the full prompt again. When you see the full prompt, you know that <strong class="pkg">GAP</strong> forgave you and is now ready to accept your next –hopefully correct– input.</p>
<p>If your input is syntactically correct, <strong class="pkg">GAP</strong> evaluates or executes it, i.e., performs the required computations (see Chapter <a href="chap4.html#X7FE7C0C17E1ED118"><span class="RefLink">4</span></a> for the definition of the evaluation).</p>
<p>If you do not see a prompt, you know that <strong class="pkg">GAP</strong> is still working on your last input. Of course, you can <em>type ahead</em>, i.e., already start entering new input, but it will not be accepted by <strong class="pkg">GAP</strong> until <strong class="pkg">GAP</strong> has completed the ongoing computation.</p>
<p>When <strong class="pkg">GAP</strong> is ready it will usually show the result of the computation, i.e., the value computed. Note that not all statements produce a value, for example, if you enter a <code class="keyw">for</code> loop, nothing will be printed, because the <code class="keyw">for</code> loop does not produce a value that could be shown.</p>
<p>Also sometimes you do not want to see the result. For example if you have computed a value and now want to assign the result to a variable, you probably do not want to see the value again. You can terminate statements by <em>two semicolons</em> to suppress showing the result.</p>
<p>If you have entered several statements on a single line <strong class="pkg">GAP</strong> will first read, evaluate, and show the first one, then read, evaluate, and show the second one, and so on. This means that the second statement will not even be checked for syntactical correctness until <strong class="pkg">GAP</strong> has completed the first computation.</p>
<p>After the result has been shown <strong class="pkg">GAP</strong> will display another prompt, and wait for your next input. And the whole process starts all over again. Note that if you have entered several statements on a single line, a new prompt will only be printed after <strong class="pkg">GAP</strong> has read, evaluated, and shown the last statement.</p>
<p>In each statement that you enter, the result of the previous statement that produced a value is available in the variable <code class="code">last</code>. The next to previous result is available in <code class="code">last2</code> and the result produced before that is available in <code class="code">last3</code>.</p>
<p>Also in each statement the time spent by the last statement, whether it produced a value or not, is available in the variable <code class="func">time</code> (<a href="chap7.html#X7C0F91F982189624"><span class="RefLink">7.6-4</span></a>). This is an integer that holds the number of milliseconds. Similarly the amount of memory allocated during that statement (in bytes) is stored in the variable <code class="func">memory_allocated</code> (<a href="chap7.html#X8156D7208591460F"><span class="RefLink">7.7-2</span></a>). The variables <code class="code">last</code>, <code class="code">last2</code>, <code class="code">last3</code>, <code class="func">time</code> (<a href="chap7.html#X7C0F91F982189624"><span class="RefLink">7.6-4</span></a>) and <code class="func">memory_allocated</code> (<a href="chap7.html#X8156D7208591460F"><span class="RefLink">7.7-2</span></a>) are all write-protected.</p>
<h4>6.2 <span class="Heading">Special Rules for Input Lines</span></h4>
<p>The input for some <strong class="pkg">GAP</strong> objects may not fit on one line, in particular big integers, long strings or long identifiers. In these cases you can still type or paste them in long single lines. For nicer display you can also specify the input on several lines. This is achieved by ending a line by a backslash or by a backslash and a carriage return character, then continue the input on the beginning of the next line. When reading this <strong class="pkg">GAP</strong> will ignore such continuation backslashes, carriage return characters and newline characters. <strong class="pkg">GAP</strong> also prints long strings and integers this way.</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">n := 1234\</span>
<span class="GAPprompt">></span> <span class="GAPinput">567890;</span>
1234567890
<span class="GAPprompt">gap></span> <span class="GAPinput">"This is a very long string that does not fit on a line \
<span class="GAPprompt">></span> <span class="GAPinput">and is therefore continued on the next line."; "This is a very long string that does not fit on a line and is therefo\
re continued on the next line."
<span class="GAPprompt">gap></span> <span class="GAPinput">bla\</span>
<span class="GAPprompt">></span> <span class="GAPinput">bla := 5;; blabla;</span>
5
</pre></div>
<p>There is a special rule about <strong class="pkg">GAP</strong> prompts in input lines: In line editing mode (usual user input and <strong class="pkg">GAP</strong> started without <code class="code">-n</code>) in lines starting with whitespace following <code class="code">gap> </code>, <code class="code">> </code> or <code class="code">brk> </code> this beginning part is removed. This rule is very convenient because it allows to cut and paste input from other <strong class="pkg">GAP</strong> sessions or manual examples easily into your current session.</p>
<h4>6.3 <span class="Heading">View and Print</span></h4>
<p><strong class="pkg">GAP</strong> has three different operations to display or print objects: <code class="func">Display</code> (<a href="chap6.html#X83A5C59278E13248"><span class="RefLink">6.3-6</span></a>), <code class="func">ViewObj</code> (<a href="chap6.html#X815BF22186FD43C9"><span class="RefLink">6.3-5</span></a>) and <code class="func">PrintObj</code> (<a href="chap6.html#X815BF22186FD43C9"><span class="RefLink">6.3-5</span></a>), and these three have different purposes as follows. The first, <code class="func">Display</code> (<a href="chap6.html#X83A5C59278E13248"><span class="RefLink">6.3-6</span></a>), should print the object to the standard outputin a human-readable relatively complete and verbose form. The second, <code class="func">ViewObj</code> (<a href="chap6.html#X815BF22186FD43C9"><span class="RefLink">6.3-5</span></a>), should print the object to the standard output in a short and concise form, it is used in the main read-eval-print loop to display the resulting object of a computation. The third, <code class="func">PrintObj</code> (<a href="chap6.html#X815BF22186FD43C9"><span class="RefLink">6.3-5</span></a>), should print the object to the standard output in a complete form which is <strong class="pkg">GAP</strong>-readable if at all possible, such that reading the output into <strong class="pkg">GAP</strong> produces an object which is equal to the original one.</p>
<p>All three operations have corresponding operations which do not print anything to standard output but return the output as a string. These are <code class="func">DisplayString</code> (<a href="chap27.html#X792FB3A1849FD739"><span class="RefLink">27.7-1</span></a>), <code class="func">ViewString</code> (<a href="chap27.html#X7803FBCA79DB5529"><span class="RefLink">27.7-3</span></a>) and <code class="func">PrintString</code> (<a href="chap27.html#X7B3CC87285DEC23D"><span class="RefLink">27.7-5</span></a>) (corresponding to <code class="func">PrintObj</code> (<a href="chap6.html#X815BF22186FD43C9"><span class="RefLink">6.3-5</span></a>)). Additionally, there is <code class="func">String</code> (<a href="chap27.html#X81FB5BE27903EC32"><span class="RefLink">27.7-6</span></a>) which is very similar to <code class="func">PrintString</code> (<a href="chap27.html#X7B3CC87285DEC23D"><span class="RefLink">27.7-5</span></a>) but does not insert control characters for line breaks.</p>
<p>For implementation convenience it is allowed that some of these operations have methods which delegate to some other of these operations. However, the rules for this are that a method may only delegate to another operation which appears further down in the following table:</p>
<p>Note in particular that none of the methods of the string producing operations may delegate to the corresponding printing operations. Note also that the above mentioned purposes of the different operations suggest that delegations between different operations will be sub-optimal in most scenarios.</p>
<h5>6.3-1 <span class="Heading">Default delegations in the library</span></h5>
<p>The library contains the following low ranked default methods:</p>
<ul>
<li><p>A method for <code class="func">DisplayString</code> (<a href="chap27.html#X792FB3A1849FD739"><span class="RefLink">27.7-1</span></a>) which returns the constant value of the global variable <code class="func">DEFAULTDISPLAYSTRING</code> (<a href="chap27.html#X8482132779EA7A23"><span class="RefLink">27.7-2</span></a>).</p>
</li>
<li><p>A method for <code class="func">ViewString</code> (<a href="chap27.html#X7803FBCA79DB5529"><span class="RefLink">27.7-3</span></a>) which returns the constant value of the global variable <code class="func">DEFAULTVIEWSTRING</code> (<a href="chap27.html#X7BBDF9D383595425"><spanclass="RefLink">27.7-4</span></a>).</p>
</li>
<li><p>A method for <code class="func">Display</code> (<a href="chap6.html#X83A5C59278E13248"><span class="RefLink">6.3-6</span></a>) which first calls <code class="func">DisplayString</code> (<a href="chap27.html#X792FB3A1849FD739"><span class="RefLink">27.7-1</span></a>) and prints the result, if it is a different object than <code class="func">DEFAULTDISPLAYSTRING</code> (<a href="chap27.html#X8482132779EA7A23"><span class="RefLink">27.7-2</span></a>). Otherwise the method delegates to <code class="func">PrintObj</code> (<a href="chap6.html#X815BF22186FD43C9"><span class="RefLink">6.3-5</span></a>).</p>
</li>
<li><p>A method for <code class="func">ViewObj</code> (<a href="chap6.html#X815BF22186FD43C9"><span class="RefLink">6.3-5</span></a>) which first calls <code class="func">ViewString</code> (<a href="chap27.html#X7803FBCA79DB5529"><span class="RefLink">27.7-3</span></a>) and prints the result, if it is a different object than <code class="func">DEFAULTVIEWSTRING</code> (<a href="chap27.html#X7BBDF9D383595425"><span class="RefLink">27.7-4</span></a>). Otherwise the method delegates to <code class="func">PrintObj</code> (<a href="chap6.html#X815BF22186FD43C9"><span class="RefLink">6.3-5</span></a>).</p>
</li>
<li><p>A method for <code class="func">PrintObj</code> (<a href="chap6.html#X815BF22186FD43C9"><span class="RefLink">6.3-5</span></a>) which prints the result of <code class="func">PrintString</code> (<a href="chap27.html#X7B3CC87285DEC23D"><span class="RefLink">27.7-5</span></a>).</p>
</li>
<li><p>A method for <code class="func">PrintString</code> (<a href="chap27.html#X7B3CC87285DEC23D"><span class="RefLink">27.7-5</span></a>) which returns the result of <code class="func">String</code> (<a href="chap27.html#X81FB5BE27903EC32"><span class="RefLink">27.7-6</span></a>)</p>
<h5>6.3-2 <span class="Heading">Recommendations for the implementation</span></h5>
<p>This subsection describes what methods for printing and viewing one should implement for new <strong class="pkg">GAP</strong> objects.</p>
<p>One should at the very least install a <code class="func">String</code> (<a href="chap27.html#X81FB5BE27903EC32"><span class="RefLink">27.7-6</span></a>) method to allow printing. Using the standard delegations this enables a limited form of viewing, displaying and printing.</p>
<p>If, for larger objects, nicer line breaks are needed, one should install a separate <code class="func">PrintString</code> (<a href="chap27.html#X7B3CC87285DEC23D"><span class="RefLink">27.7-5</span></a>) method which puts in positions for good line breaks using the control characters <code class="code">\<</code> (ASCII 1) and <code class="code">\></code> (ASCII 2).</p>
<p>If, for even larger objects, output performance and memory usage matters, one should install a separate <code class="func">PrintObj</code> (<a href="chap6.html#X815BF22186FD43C9"><span class="RefLink">6.3-5</span></a>) method.</p>
<p>One should usually install a <code class="func">ViewString</code> (<a href="chap27.html#X7803FBCA79DB5529"><span class="RefLink">27.7-3</span></a>) method, unless the above <code class="func">String</code> (<a href="chap27.html#X81FB5BE27903EC32"><span class="RefLink">27.7-6</span></a>) method is good enough for <code class="func">ViewObj</code> (<a href="chap6.html#X815BF22186FD43C9"><span class="RefLink">6.3-5</span></a>) purposes. Performance and memory should never matter here, so it is usually unnecessary to install a separate <code class="func">ViewObj</code> (<a href="chap6.html#X815BF22186FD43C9"><span class="RefLink">6.3-5</span></a>) method.</p>
<p>If the type of object calls for it one should install a <code class="func">DisplayString</code> (<a href="chap27.html#X792FB3A1849FD739"><span class="RefLink">27.7-1</span></a>) method. This is the case if a human readable verbose form is required.</p>
<p>If the performance and memory usage for <code class="func">Display</code> (<a href="chap6.html#X83A5C59278E13248"><span class="RefLink">6.3-6</span></a>) matters, one should install a separate <code class="func">Display</code> (<a href="chap6.html#X83A5C59278E13248"><span class="RefLink">6.3-6</span></a>) method.</p>
<p>Note that if only a <code class="func">String</code> (<a href="chap27.html#X81FB5BE27903EC32"><span class="RefLink">27.7-6</span></a>) method is installed, then <code class="func">ViewObj</code> (<a href="chap6.html#X815BF22186FD43C9"><span class="RefLink">6.3-5</span></a>) works and <code class="func">ViewString</code> (<a href="chap27.html#X7803FBCA79DB5529"><span class="RefLink">27.7-3</span></a>) returns <code class="func">DEFAULTVIEWSTRING</code> (<a href="chap27.html#X7BBDF9D383595425"><span class="RefLink">27.7-4</span></a>). Likewise, <code class="func">Display</code> (<a href="chap6.html#X83A5C59278E13248"><span class="RefLink">6.3-6</span></a>) works and <code class="func">DisplayString</code> (<a href="chap27.html#X792FB3A1849FD739"><span class="RefLink">27.7-1</span></a>) returns <code class="func">DEFAULTDISPLAYSTRING</code> (<a href="chap27.html#X8482132779EA7A23"><span class="RefLink">27.7-2</span></a>). If you want to avoid this then install methods for these operations as well.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ View</code>( <var class="Arg">obj1</var>, <var class="Arg">obj2...</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">View</code> shows the objects <var class="Arg">obj1</var>, <var class="Arg">obj2</var>... etc. <em>in a short form</em> on the standard output by calling the <code class="func">ViewObj</code> (<a href="chap6.html#X815BF22186FD43C9"><span class="RefLink">6.3-5</span></a>) operation on each of them. <code class="func">View</code> is called in the read-eval-print loop, thus the output looks exactly like the representation of the objects shown by the main loop. Note that no space or newline is printed between the objects.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ Print</code>( <var class="Arg">obj1</var>, <var class="Arg">obj2</var>, <var class="Arg">...</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>Also <code class="func">Print</code> shows the objects <var class="Arg">obj1</var>, <var class="Arg">obj2</var>... etc. on the standard output. The difference compared to <code class="func">View</code> (<a href="chap6.html#X851902C583B84CDC"><span class="RefLink">6.3-3</span></a>) is in general that the shown form is not required to be short, and that in many cases the form shown by <code class="func">Print</code> is <strong class="pkg">GAP</strong> readable.</p>
<p>Another difference is that <code class="func">Print</code> shows strings without the enclosing quotes, so <code class="func">Print</code> can be used to produce formatted text on the standard output (see also chapter <a href="chap27.html#X7D28329B7EDB8F47"><span class="RefLink">27</span></a>). Some characters preceded by a backslash, such as <code class="code">\n</code>, are processed specially (see chapter <a href="chap27.html#X82E5F5AB818F32DB"><span class="RefLink">27.2</span></a>). <code class="func">PrintTo</code> (<a href="chap9.html#X86956C577FFEE1F9"><span class="RefLink">9.8-3</span></a>) can be used to print to a file.</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">for i in [1..5] do</span>
<span class="GAPprompt">></span> <span class="GAPinput"> Print( i, " ", i^2, " ", i^3, "\n" );</span>
<span class="GAPprompt">></span> <span class="GAPinput"> od;</span>
1 1 1
2 4 8
3 9 27
4 16 64
5 25 125
<span class="GAPprompt">gap></span> <span class="GAPinput">g:= SmallGroup(12,5);</span>
<pc group of size 12 with 3 generators>
<span class="GAPprompt">gap></span> <span class="GAPinput">Print( g, "\n" );</span>
Group( [ f1, f2, f3 ] )
<span class="GAPprompt">gap></span> <span class="GAPinput">View( g ); Print( "\n" );</span>
<pc group of size 12 with 3 generators>
</pre></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ ViewObj</code>( <var class="Arg">obj</var> )</td><td class="tdright">( operation )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ PrintObj</code>( <var class="Arg">obj</var> )</td><td class="tdright">( operation )</td></tr></table></div>
<p>The functions <code class="func">View</code> (<a href="chap6.html#X851902C583B84CDC"><span class="RefLink">6.3-3</span></a>) and <code class="func">Print</code> (<a href="chap6.html#X7AFA64D97A1F39A3"><span class="RefLink">6.3-4</span></a>) actually call the operations <code class="func">ViewObj</code> and <code class="func">PrintObj</code>, respectively, for each argument. By installing special methods for these operations, it is possible to achieve special printing behavior for certain objects (see chapter <a href="chap78.html#X8058CC8187162644"><span class="RefLink">78</span></a>). The only exceptions are strings (see Chapter <a href="chap27.html#X7D28329B7EDB8F47"><span class="RefLink">27</span></a>), for which the default <code class="func">PrintObj</code> and <code class="func">ViewObj</code> methods as well as the function <code class="func">View</code> (<a href="chap6.html#X851902C583B84CDC"><span class="RefLink">6.3-3</span></a>) print also the enclosing doublequotes, whereas <code class="func">Print</code> (<a href="chap6.html#X7AFA64D97A1F39A3"><span class="RefLink">6.3-4</span></a>) strips the doublequotes.</p>
<p>The default method for <code class="func">ViewObj</code> is to call <code class="func">PrintObj</code>. So it is sufficient to have a <code class="func">PrintObj</code> method for an object in order to <code class="func">View</code> (<a href="chap6.html#X851902C583B84CDC"><span class="RefLink">6.3-3</span></a>) it. If one wants to supply a <q>short form</q> for <code class="func">View</code> (<a href="chap6.html#X851902C583B84CDC"><span class="RefLink">6.3-3</span></a>), one can install additionally a method for <code class="func">ViewObj</code>.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ Display</code>( <var class="Arg">obj</var> )</td><td class="tdright">( operation )</td></tr></table></div>
<p>Displays the object <var class="Arg">obj</var> in a nice, formatted way which is easy to read (but might be difficult for machines to understand). The actual format used for this depends on the type of <var class="Arg">obj</var>. Each method should print a newline character as last character.</p>
<p>One can assign a string to an object that <code class="func">Print</code> (<a href="chap6.html#X7AFA64D97A1F39A3"><span class="RefLink">6.3-4</span></a>) will use instead of the default used by <code class="func">Print</code> (<a href="chap6.html#X7AFA64D97A1F39A3"><span class="RefLink">6.3-4</span></a>), via <code class="func">SetName</code> (<a href="chap12.html#X85D6D47B83BD02A1"><span class="RefLink">12.8-1</span></a>). Also, <code class="func">Name</code> (<a href="chap12.html#X7F14EF9D81432113"><span class="RefLink">12.8-2</span></a>) returns the string previously assigned to the object for printing, via <code class="func">SetName</code> (<a href="chap12.html#X85D6D47B83BD02A1"><span class="RefLink">12.8-1</span></a>). The following is an example in the context of domains.</p>
<p>When setting up examples, in particular if for beginning users, it sometimes can be convenient to hide the structure behind a printing name. For many objects, such as groups, this can be done using <code class="func">SetName</code> (<a href="chap12.html#X85D6D47B83BD02A1"><span class="RefLink">12.8-1</span></a>). If the objects however is represented internally, for example permutations representing group elements, this function is not applicable. Instead the function <code class="func">SetNameObject</code> (<a href="chap6.html#X87E546E27A1F1FAB"><span class="RefLink">6.3-7</span></a>) can be used to interface with the display routines on a lower level.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ SetNameObject</code>( <var class="Arg">o</var>, <var class="Arg">s</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">SetNameObject</code> sets the string <var class="Arg">s</var> as display name for object <var class="Arg">o</var> in an interactive session. When applying <code class="func">View</code> (<a href="chap6.html#X851902C583B84CDC"><span class="RefLink">6.3-3</span></a>) to object <var class="Arg">o</var>, for example in the system's main loop, GAP will print the string s. Calling SetNameObject for the same object o with s set to fail (20.2-1) deletes the special viewing setup. Since use of this features potentially slows down the whole print process, this function should be used sparingly.
<p>When an error has occurred or when you interrupt <strong class="pkg">GAP</strong> (usually by hitting <strong class="button">Ctrl-C</strong>) <strong class="pkg">GAP</strong> enters a break loop, that is in most respects like the main read eval print loop (see <a href="chap6.html#X81667F568237B232"><span class="RefLink">6.1</span></a>). That is, you can enter statements, <strong class="pkg">GAP</strong> reads them, evaluates them, and shows the result if any. However those evaluations happen within the context in which the error occurred. So you can look at the arguments and local variables of the functions that were active when the error happened and even change them. The prompt is changed from <code class="code">gap></code> to <code class="code">brk></code> to indicate that you are in a break loop.</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">1/0;</span>
Rational operations: <divisor> must not be zero
not in any function
Entering break read-eval-print loop ...
you can 'quit;' to quit to outer loop, or
you can replace <divisor> via 'return <divisor>;' to continue
</pre></div>
<p>If errors occur within a break loop <strong class="pkg">GAP</strong> enters another break loop at a <em>deeper level</em>. This is indicated by a number appended to <code class="code">brk</code>:</p>
<div class="example"><pre>
<span class="GAPbrkprompt">brk></span> <span class="GAPinput">1/0;</span>
Rational operations: <divisor> must not be zero
not in any function
Entering break read-eval-print loop ...
you can 'quit;' to quit to outer loop, or
you can replace <divisor> via 'return <divisor>;' to continue
<span class="GAPbrkprompt">brk_02></span>
</pre></div>
<p>There are two ways to leave a break loop, see <a href="chap6.html#X83033EEB81CF4F49"><span class="RefLink">6.4-1</span></a> and <a href="chap6.html#X7A388B808167FE09"><span class="RefLink">6.4-2</span></a>.</p>
<h5>6.4-1 <span class="Heading">quit from a break loop</span></h5>
<p>The first way to leave a break loop is to <em>quit</em> the break loop. To do this you enter <code class="code">quit;</code> or type the <em>eof</em> (<em>e</em>nd <em>o</em>f <em>f</em>ile) character, which is usually <strong class="button">Ctrl-D</strong> except when using the <code class="code">-e</code> option (see Section <a href="chap3.html#X782751D5858A6EAF"><span class="RefLink">3.1</span></a>). Note that <strong class="pkg">GAP</strong> code between <code class="code">quit;</code> and the end of the input line is ignored.</p>
<p>In this case control returns to the break loop one level above or to the main loop, respectively. So iterated break loops must be left iteratively. Note also that if you type <code class="code">quit;</code> from a <code class="code">gap></code> prompt, <strong class="pkg">GAP</strong> will exit (see <a href="chap6.html#X83704B1080FD9B40"><span class="RefLink">6.7</span></a>).</p>
<p><em>Note:</em> If you leave a break loop with <code class="keyw">quit</code> without completing a command it is possible (though not very likely) that data structures will be corrupted or incomplete data have been stored in objects. Therefore no guarantee can be given that calculations afterwards will return correct results! If you have been using options <code class="keyw">quit</code>ting a break loop generally leaves the options stack with options you no longer want. The function <code class="func">ResetOptionsStack</code> (<a href="chap8.html#X83D1190984DA3B85"><span class="RefLink">8.1-3</span></a>) removes all options on the options stack, and this is the sole intended purpose of this function.</p>
<h5>6.4-2 <span class="Heading">return from a break loop</span></h5>
<p>The other way to leave a break loop is to <em>return</em> from a break loop. To do this you type <code class="code">return;</code> or <code class="code">return <var class="Arg">obj</var>;</code>. If the break loop was entered because you interrupted <strong class="pkg">GAP</strong>, then you can continue by typing <code class="code">return;</code>. If the break loop was entered due to an error, you may have to modify the value of a variable before typing <code class="code">return;</code> (see the example for <code class="func">IsDenseList</code> (<a href="chap21.html#X870AA9D8798C93DD"><span class="RefLink">21.1-2</span></a>)) or you may have to return an object <var class="Arg">obj</var> (by typing: <code class="code">return <var class="Arg">obj</var>;</code>) to continue the computation; in any case, the message printed on entering the break loop will tell you which of these alternatives is possible. For example, if the break loop was entered because a variable had no assigned value, the value to be returned is often a value that this variable should have to continue the computation.</p>
<div class="example"><pre>
<span class="GAPbrkprompt">brk></span> <span class="GAPinput">return 9; # we had tried to enter the divisor 9 but typed 0 ...</span>
1/9
<span class="GAPprompt">gap></span> <span class="GAPinput"></span>
</pre></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ OnBreak</code>( )</td><td class="tdright">( function )</td></tr></table></div>
<p>By default, when a break loop is entered, <strong class="pkg">GAP</strong> prints a trace of the innermost 5 commands currently being executed. This behaviour can be configured by changing the value of the global variable <code class="func">OnBreak</code>. When a break loop is entered, the value of <code class="func">OnBreak</code> is checked. If it is a function, then it is called with no arguments. By default, the value of <code class="func">OnBreak</code> is <code class="func">Where</code> (<a href="chap6.html#X7A7FFA2B7C1EF5A3"><span class="RefLink">6.4-5</span></a>).</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">Error("!\n");</span>
Error, !
Hello
Entering break read-eval-print loop ...
you can 'quit;' to quit to outer loop, or
you can 'return;' to continue
<span class="GAPbrkprompt">brk></span> <span class="GAPinput">quit;</span>
</pre></div>
<p>In cases where a break loop is entered during a function that was called with options (see Chapter <a href="chap8.html#X7FD84061873F72A2"><span class="RefLink">8</span></a>), a <code class="code">quit;</code> will also cause the options stack to be reset and an <code class="code">Info</code>-ed warning stating this is emitted at <code class="func">InfoWarning</code> (<a href="chap7.html#X7A28F77C82D6A3E0"><span class="RefLink">7.4-8</span></a>) level 1 (see Chapter <a href="chap7.html#X7A9C902479CB6F7C"><span class="RefLink">7.4</span></a>).</p>
<p>Note that for break loops entered by a call to <code class="func">Error</code> (<a href="chap6.html#X7E7AD8D87EBA1A08"><span class="RefLink">6.6-1</span></a>), the lines after <q><code class="code">Entering break read-eval-print loop ...</code></q> and before the <code class="code">brk></code> prompt can also be customised, namely by redefining <code class="func">OnBreakMessage</code> (<a href="chap6.html#X80711C807C99C220"><span class="RefLink">6.4-4</span></a>).</p>
<p>Also, note that one can achieve the effect of changing <code class="func">OnBreak</code> <em>locally</em>. As mentioned above, the default value of <code class="func">OnBreak</code> is <code class="func">Where</code> (<a href="chap6.html#X7A7FFA2B7C1EF5A3"><span class="RefLink">6.4-5</span></a>). Thus, a call to <code class="func">Error</code> (<a href="chap6.html#X7E7AD8D87EBA1A08"><span class="RefLink">6.6-1</span></a>) generally gives a trace back up to five levels of calling functions. Conceivably, we might like to have a function like <code class="func">Error</code> (<a href="chap6.html#X7E7AD8D87EBA1A08"><span class="RefLink">6.6-1</span></a>) that does not trace back without globally changing <code class="func">OnBreak</code>. Such a function we might call <code class="code">ErrorNoTraceBack</code> and here is how we might define it. (Note <code class="code">ErrorNoTraceBack</code> is <em>not</em> a <strong class="pkg">GAP</strong> function.)</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">ErrorNoTraceBack := function(arg) # arg is special variable that GAP</span>
<span class="GAPprompt">></span> <span class="GAPinput"> # knows to treat as list of arg's
<span class="GAPprompt">></span> <span class="GAPinput"> local SavedOnBreak, ENTBOnBreak;</span>
<span class="GAPprompt">></span> <span class="GAPinput"> SavedOnBreak := OnBreak; # save current value of OnBreak</span>
<span class="GAPprompt">></span> <span class="GAPinput"></span>
<span class="GAPprompt">></span> <span class="GAPinput"> ENTBOnBreak := function() # our `local' OnBreak
<span class="GAPprompt">></span> <span class="GAPinput"> local s;</span>
<span class="GAPprompt">></span> <span class="GAPinput"> for s in arg do</span>
<span class="GAPprompt">></span> <span class="GAPinput"> Print(s);</span>
<span class="GAPprompt">></span> <span class="GAPinput"> od;</span>
<span class="GAPprompt">></span> <span class="GAPinput"> OnBreak := SavedOnBreak; # restore OnBreak afterwards</span>
<span class="GAPprompt">></span> <span class="GAPinput"> end;</span>
<span class="GAPprompt">></span> <span class="GAPinput"></span>
<span class="GAPprompt">></span> <span class="GAPinput"> OnBreak := ENTBOnBreak;</span>
<span class="GAPprompt">></span> <span class="GAPinput"> Error();</span>
<span class="GAPprompt">></span> <span class="GAPinput"> end;</span>
function( arg... ) ... end
</pre></div>
<p>Here is a somewhat trivial demonstration of the use of <code class="code">ErrorNoTraceBack</code>.</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">ErrorNoTraceBack("Gidday!", " How's", " it", " going?\n");</span>
Error, Gidday! How's it going?
Entering break read-eval-print loop ...
you can 'quit;' to quit to outer loop, or
you can 'return;' to continue
<span class="GAPbrkprompt">brk></span> <span class="GAPinput">quit;</span>
</pre></div>
<p>Now we call <code class="func">Error</code> (<a href="chap6.html#X7E7AD8D87EBA1A08"><span class="RefLink">6.6-1</span></a>) with the same arguments to show the difference.</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">Error("Gidday!", " How's", " it", " going?\n");</span>
Error, Gidday! How's it going?
Hello
Entering break read-eval-print loop ...
you can 'quit;' to quit to outer loop, or
you can 'return;' to continue
<span class="GAPbrkprompt">brk></span> <span class="GAPinput">quit;</span>
</pre></div>
<p>Observe that the value of <code class="func">OnBreak</code> before the <code class="code">ErrorNoTraceBack</code> call was restored. However, we had changed <code class="func">OnBreak</code> from its default value; to restore <code class="func">OnBreak</code> to its default value, we should do the following.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ OnBreakMessage</code>( )</td><td class="tdright">( function )</td></tr></table></div>
<p>When a break loop is entered by a call to <code class="func">Error</code> (<a href="chap6.html#X7E7AD8D87EBA1A08"><span class="RefLink">6.6-1</span></a>) the message after the <q><code class="code">Entering break read-eval-print loop ...</code></q> line is produced by the function <code class="code">OnBreakMessage</code>, which just like <code class="func">OnBreak</code> (<a href="chap6.html#X82EBF01181C3C859"><span class="RefLink">6.4-3</span></a>) is a user-configurable global variable that is a <em>function</em> with <em>no arguments</em>.</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">OnBreakMessage(); # By default, OnBreakMessage prints the following</span>
you can 'quit;' to quit to outer loop, or
you can 'return;' to continue
</pre></div>
<p>Perhaps you are familiar with what's possible in a break loop, and so don't need to be reminded. In this case, you might wish to do the following (the first line just makes it easy to restore the default value later).</p>
<p>With <code class="func">OnBreak</code> (<a href="chap6.html#X82EBF01181C3C859"><span class="RefLink">6.4-3</span></a>) still set away from its default value, calling <code class="func">Error</code> (<a href="chap6.html#X7E7AD8D87EBA1A08"><span class="RefLink">6.6-1</span></a>) as we did above, now produces:</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">Error("!\n");</span>
Error, !
Hello
Entering break read-eval-print loop ...
<span class="GAPbrkprompt">brk></span> <span class="GAPinput">quit; # to get back to outer loop</span>
</pre></div>
<p>However, suppose you are writing a function which detects an error condition and <code class="code">OnBreakMessage</code> needs to be changed only <em>locally</em>, i.e., the instructions on how to recover from the break loop need to be specific to that function. The same idea used to define <code class="code">ErrorNoTraceBack</code> (see <code class="func">OnBreak</code> (<a href="chap6.html#X82EBF01181C3C859"><span class="RefLink">6.4-3</span></a>)) can be adapted to achieve this. The function <code class="func">CosetTableFromGensAndRels</code> (<a href="chap47.html#X7DE601F179E6FD09"><span class="RefLink">47.6-5</span></a>) is an example in the <strong class="pkg">GAP</strong> code where the idea is actually used.</p>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ Where</code>( <var class="Arg">nr</var> )</td><td class="tdright">( function )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ WhereWithVars</code>( <var class="Arg">nr</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>shows the last <var class="Arg">nr</var> commands on the execution stack during whose execution the error occurred. If not given, <var class="Arg">nr</var> defaults to 5. (Assume, for the following example, that after the last example <code class="func">OnBreak</code> (<a href="chap6.html#X82EBF01181C3C859"><span class="RefLink">6.4-3</span></a>) has been set back to its default value.). <code class="func">WhereWithVars</code> acts the same as <code class="func">Where</code> while also showing the arguments and local variables of each function.</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">StabChain(SymmetricGroup(100)); # After this we typed ^C</span>
user interrupt at
bpt := S.orbit[1];
called from
SiftedPermutation( S, (g * rep) ^ -1 ) called from
StabChainStrong( S.stabilizer, [ sch ], options ); called from
StabChainStrong( S.stabilizer, [ sch ], options ); called from
StabChainStrong( S, GeneratorsOfGroup( G ), options ); called from
StabChainOp( G, rec(
) ) called from
...
Entering break read-eval-print loop ...
you can 'quit;' to quit to outer loop, or
you can 'return;' to continue
<span class="GAPbrkprompt">brk></span> <span class="GAPinput">Where(2);</span>
called from
SiftedPermutation( S, (g * rep) ^ -1 ) called from
StabChainStrong( S.stabilizer, [ sch ], options ); called from
...
</pre></div>
<p>Note that the variables displayed even in the first line of the <code class="func">Where</code> list (after the <code class="code">called from</code> line) may be already one environment level higher and <code class="func">DownEnv</code> (<a href="chap6.html#X79E66DA2875303B0"><span class="RefLink">6.5-1</span></a>) may be necessary to access them.</p>
<p>At the moment this backtrace does not work from within compiled code (this includes the method selection which by default is compiled into the kernel). If this creates problems for debugging, call <strong class="pkg">GAP</strong> with the <code class="code">-M</code> option (see <a href="chap3.html#X782751D5858A6EAF"><span class="RefLink">3.1</span></a>) to avoid loading compiled code.</p>
<p>(Function calls to <code class="func">Info</code> (<a href="chap7.html#X864E4B6886E2697D"><span class="RefLink">7.4-6</span></a>) and methods installed for binary operations are handled in a special way. In rare circumstances it is possible therefore that they do not show up in a <code class="func">Where</code> log but the log refers to the <em>last</em> proper function call that happened before.)</p>
<p>The command line option <code class="code">-T</code> to <strong class="pkg">GAP</strong> disables the break loop. This is mainly intended for testing purposes and for special applications. If this option is given then errors simply cause <strong class="pkg">GAP</strong> to return to the main loop.</p>
<h4>6.5 <span class="Heading">Variable Access in a Break Loop</span></h4>
<p>In a break loop access to variables of the current break level and higher levels is possible, but if the same variable name is used for different objects or if a function calls itself recursively, of course only the variable at the lowest level can be accessed.</p>
<h5>6.5-1 <span class="Heading">DownEnv and UpEnv</span></h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ DownEnv</code>( <var class="Arg">nr</var> )</td><td class="tdright">( function )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ UpEnv</code>( <var class="Arg">nr</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p><code class="func">DownEnv</code> moves down <var class="Arg">nr</var> steps in the environment and allows one to inspect variables on this level; if <var class="Arg">nr</var> is negative it steps up in the environment again; <var class="Arg">nr</var> defaults to 1 if not given. <code class="func">UpEnv</code> acts similarly to <code class="func">DownEnv</code> but in the reverse direction (the mnemonic rule to remember the difference between <code class="func">DownEnv</code> and <code class="func">UpEnv</code> is the order in which commands on the execution stack are displayed by <code class="func">Where</code> (<a href="chap6.html#X7A7FFA2B7C1EF5A3"><span class="RefLink">6.4-5</span></a>)).</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">OnBreak := function() Where(0); end;; # eliminate back-tracing on</span>
<span class="GAPprompt">gap></span> <span class="GAPinput"> # entry to break loop</span>
<span class="GAPprompt">gap></span> <span class="GAPinput">test:= function( n )</span>
<span class="GAPprompt">></span> <span class="GAPinput"> if n > 3 then Error( "!\n" ); fi; test( n+1 ); end;;</span>
<span class="GAPprompt">gap></span> <span class="GAPinput">test( 1 );</span>
Error, !
Entering break read-eval-print loop ...
you can 'quit;' to quit to outer loop, or
you can 'return;' to continue
<span class="GAPbrkprompt">brk></span> <span class="GAPinput">Where();</span>
called from
test( n + 1 ); called from
test( n + 1 ); called from
test( n + 1 ); called from
<function>( <arguments> ) called from read-eval-loop
<span class="GAPbrkprompt">brk></span> <span class="GAPinput">n;</span>
4
<span class="GAPbrkprompt">brk></span> <span class="GAPinput">DownEnv();</span>
<span class="GAPbrkprompt">brk></span> <span class="GAPinput">n;</span>
3
<span class="GAPbrkprompt">brk></span> <span class="GAPinput">Where();</span>
called from
test( n + 1 ); called from
test( n + 1 ); called from
<function>( <arguments> ) called from read-eval-loop
<span class="GAPbrkprompt">brk></span> <span class="GAPinput">DownEnv( 2 );</span>
<span class="GAPbrkprompt">brk></span> <span class="GAPinput">n;</span>
1
<span class="GAPbrkprompt">brk></span> <span class="GAPinput">Where();</span>
called from
<function>( <arguments> ) called from read-eval-loop
<span class="GAPbrkprompt">brk></span> <span class="GAPinput">DownEnv( -2 );</span>
<span class="GAPbrkprompt">brk></span> <span class="GAPinput">n;</span>
3
<span class="GAPbrkprompt">brk></span> <span class="GAPinput">quit;</span>
<span class="GAPprompt">gap></span> <span class="GAPinput">OnBreak := Where;; # restore OnBreak to its default value</span>
</pre></div>
<p>Note that the change of the environment caused by <code class="func">DownEnv</code> only affects variable access in the break loop. If you use <code class="keyw">return</code> to continue a calculation <strong class="pkg">GAP</strong> automatically jumps to the right environment level again.</p>
<p>Note also that search for variables looks first in the chain of outer functions which enclosed the definition of a currently executing function, before it looks at the chain of calling functions which led to the current invocation of the function.</p>
¤ Die Informationen auf dieser Webseite wurden
nach bestem Wissen sorgfältig zusammengestellt. Es wird jedoch weder Vollständigkeit, noch Richtigkeit,
noch Qualität der bereit gestellten Informationen zugesichert.0.78Bemerkung:
(vorverarbeitet)
¤
Die Informationen auf dieser Webseite wurden
nach bestem Wissen sorgfältig zusammengestellt. Es wird jedoch weder Vollständigkeit, noch Richtigkeit,
noch Qualität der bereit gestellten Informationen zugesichert.
Bemerkung:
Die farbliche Syntaxdarstellung ist noch experimentell.
