This file is indexed.

/usr/share/gap/doc/ref/chap8.html is in gap-doc 4r8p8-3.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
         "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<title>GAP (ref) - Chapter 8: Options Stack</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
<meta name="generator" content="GAPDoc2HTML" />
<link rel="stylesheet" type="text/css" href="manual.css" />
<script src="manual.js" type="text/javascript"></script>
<script type="text/javascript">overwriteStyle();</script>
</head>
<body class="chap8"  onload="jscontent()">


<div class="chlinktop"><span class="chlink1">Goto Chapter: </span><a href="chap0.html">Top</a>  <a href="chap1.html">1</a>  <a href="chap2.html">2</a>  <a href="chap3.html">3</a>  <a href="chap4.html">4</a>  <a href="chap5.html">5</a>  <a href="chap6.html">6</a>  <a href="chap7.html">7</a>  <a href="chap8.html">8</a>  <a href="chap9.html">9</a>  <a href="chap10.html">10</a>  <a href="chap11.html">11</a>  <a href="chap12.html">12</a>  <a href="chap13.html">13</a>  <a href="chap14.html">14</a>  <a href="chap15.html">15</a>  <a href="chap16.html">16</a>  <a href="chap17.html">17</a>  <a href="chap18.html">18</a>  <a href="chap19.html">19</a>  <a href="chap20.html">20</a>  <a href="chap21.html">21</a>  <a href="chap22.html">22</a>  <a href="chap23.html">23</a>  <a href="chap24.html">24</a>  <a href="chap25.html">25</a>  <a href="chap26.html">26</a>  <a href="chap27.html">27</a>  <a href="chap28.html">28</a>  <a href="chap29.html">29</a>  <a href="chap30.html">30</a>  <a href="chap31.html">31</a>  <a href="chap32.html">32</a>  <a href="chap33.html">33</a>  <a href="chap34.html">34</a>  <a href="chap35.html">35</a>  <a href="chap36.html">36</a>  <a href="chap37.html">37</a>  <a href="chap38.html">38</a>  <a href="chap39.html">39</a>  <a href="chap40.html">40</a>  <a href="chap41.html">41</a>  <a href="chap42.html">42</a>  <a href="chap43.html">43</a>  <a href="chap44.html">44</a>  <a href="chap45.html">45</a>  <a href="chap46.html">46</a>  <a href="chap47.html">47</a>  <a href="chap48.html">48</a>  <a href="chap49.html">49</a>  <a href="chap50.html">50</a>  <a href="chap51.html">51</a>  <a href="chap52.html">52</a>  <a href="chap53.html">53</a>  <a href="chap54.html">54</a>  <a href="chap55.html">55</a>  <a href="chap56.html">56</a>  <a href="chap57.html">57</a>  <a href="chap58.html">58</a>  <a href="chap59.html">59</a>  <a href="chap60.html">60</a>  <a href="chap61.html">61</a>  <a href="chap62.html">62</a>  <a href="chap63.html">63</a>  <a href="chap64.html">64</a>  <a href="chap65.html">65</a>  <a href="chap66.html">66</a>  <a href="chap67.html">67</a>  <a href="chap68.html">68</a>  <a href="chap69.html">69</a>  <a href="chap70.html">70</a>  <a href="chap71.html">71</a>  <a href="chap72.html">72</a>  <a href="chap73.html">73</a>  <a href="chap74.html">74</a>  <a href="chap75.html">75</a>  <a href="chap76.html">76</a>  <a href="chap77.html">77</a>  <a href="chap78.html">78</a>  <a href="chap79.html">79</a>  <a href="chap80.html">80</a>  <a href="chap81.html">81</a>  <a href="chap82.html">82</a>  <a href="chap83.html">83</a>  <a href="chap84.html">84</a>  <a href="chap85.html">85</a>  <a href="chap86.html">86</a>  <a href="chap87.html">87</a>  <a href="chapBib.html">Bib</a>  <a href="chapInd.html">Ind</a>  </div>

<div class="chlinkprevnexttop">&nbsp;<a href="chap0.html">[Top of Book]</a>&nbsp;  <a href="chap0.html#contents">[Contents]</a>&nbsp;  &nbsp;<a href="chap7.html">[Previous Chapter]</a>&nbsp;  &nbsp;<a href="chap9.html">[Next Chapter]</a>&nbsp;  </div>

<p id="mathjaxlink" class="pcenter"><a href="chap8_mj.html">[MathJax on]</a></p>
<p><a id="X7FD84061873F72A2" name="X7FD84061873F72A2"></a></p>
<div class="ChapSects"><a href="chap8.html#X7FD84061873F72A2">8 <span class="Heading">Options Stack</span></a>
<div class="ContSect"><span class="tocline"><span class="nocss">&nbsp;</span><a href="chap8.html#X794C5B5A80203CF9">8.1 <span class="Heading">Functions Dealing with the Options Stack</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap8.html#X7D4939FF7FB37FBE">8.1-1 PushOptions</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap8.html#X7818A5278679FD43">8.1-2 PopOptions</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap8.html#X83D1190984DA3B85">8.1-3 ResetOptionsStack</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap8.html#X78D87D1081BF99FE">8.1-4 OnQuit</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap8.html#X7F9373AD7DB88D1F">8.1-5 ValueOption</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap8.html#X7EDA4EB67D43FE33">8.1-6 DisplayOptionsStack</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap8.html#X832F41187B150C19">8.1-7 InfoOptions</a></span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss">&nbsp;</span><a href="chap8.html#X7BB781647CAAE9B4">8.2 <span class="Heading">Options Stack – an Example</span></a>
</span>
</div>
</div>

<h3>8 <span class="Heading">Options Stack</span></h3>

<p><strong class="pkg">GAP</strong> supports a <em>global options system</em>. This is intended as a way for the user to provide guidance to various algorithms that might be used in a computation. Such guidance should not change mathematically the specification of the computation to be performed, although it may change the algorithm used. A typical example is the selection of a strategy for the Todd-Coxeter coset enumeration procedure. An example of something not suited to the options mechanism is the imposition of exponent laws in the <span class="SimpleMath">p</span>-Quotient algorithm.</p>

<p>The basis of this system is a global stack of records. All the entries of each record are thought of as options settings, and the effective setting of an option is given by the topmost record in which the relevant field is bound.</p>

<p>The reason for the choice of a stack is the intended pattern of use:</p>

<p><code class="code">PushOptions( rec( <var class="Arg">stuff</var> ) );</code></p>

<p><code class="code">DoSomething( <var class="Arg">args</var> );</code></p>

<p><code class="code">PopOptions();</code></p>

<p>This can be abbreviated, to <code class="code">DoSomething( <var class="Arg">args</var> : <var class="Arg">stuff</var> );</code> with a small additional abbreviation of <var class="Arg">stuff</var> permitted. See <a href="chap4.html#X867D54987EF86D1D"><span class="RefLink">4.11-2</span></a> for details. The full form can be used where the same options are to run across several calls, or where the <code class="code">DoSomething</code> procedure is actually an infix operator, or other function with special syntax.</p>

<p>An alternative to this system is the use of additional optional arguments in procedure calls. This is not felt to be sufficient because many procedure calls might cause, for example, a coset enumeration and each would need to make provision for the possibility of extra arguments. In this system the options are pushed when the user-level procedure is called, and remain in effect (unless altered) for all procedures called by it.</p>

<p>Note that in some places in the system optional records containing options which are valid only for the immediate function or method call are in fact used.</p>

<p><a id="X794C5B5A80203CF9" name="X794C5B5A80203CF9"></a></p>

<h4>8.1 <span class="Heading">Functions Dealing with the Options Stack</span></h4>

<p><a id="X7D4939FF7FB37FBE" name="X7D4939FF7FB37FBE"></a></p>

<h5>8.1-1 PushOptions</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; PushOptions</code>( <var class="Arg">options</var>, <var class="Arg">record</var> )</td><td class="tdright">(&nbsp;function&nbsp;)</td></tr></table></div>
<p>This function pushes a record of options onto the global option stack. Note that <code class="code">PushOptions( rec( <var class="Arg">opt</var>:= fail ) )</code> has the effect of resetting the option <var class="Arg">opt</var>, since an option that has never been set has the value <code class="keyw">fail</code> returned by <code class="func">ValueOption</code> (<a href="chap8.html#X7F9373AD7DB88D1F"><span class="RefLink">8.1-5</span></a>).</p>

<p>Note that there is no check for misspelt or undefined options.</p>

<p><a id="X7818A5278679FD43" name="X7818A5278679FD43"></a></p>

<h5>8.1-2 PopOptions</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; PopOptions</code>(  )</td><td class="tdright">(&nbsp;function&nbsp;)</td></tr></table></div>
<p>This function removes the top-most options record from the options stack if there is one.</p>

<p><a id="X83D1190984DA3B85" name="X83D1190984DA3B85"></a></p>

<h5>8.1-3 ResetOptionsStack</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; ResetOptionsStack</code>(  )</td><td class="tdright">(&nbsp;function&nbsp;)</td></tr></table></div>
<p>unbinds (i.e. removes) all the options records from the options stack.</p>

<p><em>Note:</em> <code class="func">ResetOptionsStack</code> should <em>not</em> be used within a function. Its intended use is to clean up the options stack in the event that the user has <code class="keyw">quit</code> from a <code class="keyw">break</code> loop, so leaving a stack of no-longer-needed options (see <a href="chap6.html#X83033EEB81CF4F49"><span class="RefLink">6.4-1</span></a>).</p>

<p><a id="X78D87D1081BF99FE" name="X78D87D1081BF99FE"></a></p>

<h5>8.1-4 OnQuit</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; OnQuit</code>(  )</td><td class="tdright">(&nbsp;function&nbsp;)</td></tr></table></div>
<p>called when a user selects to <code class="code">quit;</code> a break loop entered via execution of <code class="func">Error</code> (<a href="chap6.html#X7E7AD8D87EBA1A08"><span class="RefLink">6.6-1</span></a>). As <strong class="pkg">GAP</strong> starts up, <code class="func">OnQuit</code> is defined to do nothing, in case an error is encountered during <strong class="pkg">GAP</strong> start-up. Later in the loading process we redefine <code class="func">OnQuit</code> to do a variant of <code class="func">ResetOptionsStack</code> (<a href="chap8.html#X83D1190984DA3B85"><span class="RefLink">8.1-3</span></a>) to ensure the options stack is empty after a user quits an <code class="func">Error</code> (<a href="chap6.html#X7E7AD8D87EBA1A08"><span class="RefLink">6.6-1</span></a>)-induced break loop. (<code class="func">OnQuit</code> differs from <code class="func">ResetOptionsStack</code> (<a href="chap8.html#X83D1190984DA3B85"><span class="RefLink">8.1-3</span></a>) in that it warns when it does something rather than the other way round.) Currently, <code class="func">OnQuit</code> is not advertised, since exception handling may make it obsolete.</p>

<p><a id="X7F9373AD7DB88D1F" name="X7F9373AD7DB88D1F"></a></p>

<h5>8.1-5 ValueOption</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; ValueOption</code>( <var class="Arg">opt</var> )</td><td class="tdright">(&nbsp;function&nbsp;)</td></tr></table></div>
<p>This function is a method for accessing the options stack without changing it; <var class="Arg">opt</var> should be the name of an option, i.e. a string. A function which makes decisions that might be affected by options should examine the result of <code class="func">ValueOption</code>. If <var class="Arg">opt</var> is currently not set then <code class="keyw">fail</code> is returned.</p>

<p><a id="X7EDA4EB67D43FE33" name="X7EDA4EB67D43FE33"></a></p>

<h5>8.1-6 DisplayOptionsStack</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; DisplayOptionsStack</code>(  )</td><td class="tdright">(&nbsp;function&nbsp;)</td></tr></table></div>
<p>This function prints a human-readable display of the complete options stack.</p>

<p><a id="X832F41187B150C19" name="X832F41187B150C19"></a></p>

<h5>8.1-7 InfoOptions</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; InfoOptions</code></td><td class="tdright">(&nbsp;info class&nbsp;)</td></tr></table></div>
<p>This info class can be used to enable messages about options being changed (level 1) or accessed (level 2).</p>

<p><a id="X7BB781647CAAE9B4" name="X7BB781647CAAE9B4"></a></p>

<h4>8.2 <span class="Heading">Options Stack – an Example</span></h4>

<p>The example below shows simple manipulation of the Options Stack, first using <code class="func">PushOptions</code> (<a href="chap8.html#X7D4939FF7FB37FBE"><span class="RefLink">8.1-1</span></a>) and <code class="func">PopOptions</code> (<a href="chap8.html#X7818A5278679FD43"><span class="RefLink">8.1-2</span></a>) and then using the special function calling syntax.</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">foo := function()</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">Print("myopt1 = ", ValueOption("myopt1"),</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">      " myopt2 = ",ValueOption("myopt2"),"\n");</span>
<span class="GAPprompt">&gt;</span> <span class="GAPinput">end;</span>
function(  ) ... end
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">foo();</span>
myopt1 = fail myopt2 = fail
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">PushOptions(rec(myopt1 := 17));</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">foo();</span>
myopt1 = 17 myopt2 = fail
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">DisplayOptionsStack();</span>
[ rec(
      myopt1 := 17 ) ]
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">PopOptions();</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">foo();</span>
myopt1 = fail myopt2 = fail
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">foo( : myopt1, myopt2 := [Z(3),"aardvark"]);</span>
myopt1 = true myopt2 = [ Z(3), "aardvark" ]
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">DisplayOptionsStack();</span>
[  ]
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput"></span>
</pre></div>


<div class="chlinkprevnextbot">&nbsp;<a href="chap0.html">[Top of Book]</a>&nbsp;  <a href="chap0.html#contents">[Contents]</a>&nbsp;  &nbsp;<a href="chap7.html">[Previous Chapter]</a>&nbsp;  &nbsp;<a href="chap9.html">[Next Chapter]</a>&nbsp;  </div>


<div class="chlinkbot"><span class="chlink1">Goto Chapter: </span><a href="chap0.html">Top</a>  <a href="chap1.html">1</a>  <a href="chap2.html">2</a>  <a href="chap3.html">3</a>  <a href="chap4.html">4</a>  <a href="chap5.html">5</a>  <a href="chap6.html">6</a>  <a href="chap7.html">7</a>  <a href="chap8.html">8</a>  <a href="chap9.html">9</a>  <a href="chap10.html">10</a>  <a href="chap11.html">11</a>  <a href="chap12.html">12</a>  <a href="chap13.html">13</a>  <a href="chap14.html">14</a>  <a href="chap15.html">15</a>  <a href="chap16.html">16</a>  <a href="chap17.html">17</a>  <a href="chap18.html">18</a>  <a href="chap19.html">19</a>  <a href="chap20.html">20</a>  <a href="chap21.html">21</a>  <a href="chap22.html">22</a>  <a href="chap23.html">23</a>  <a href="chap24.html">24</a>  <a href="chap25.html">25</a>  <a href="chap26.html">26</a>  <a href="chap27.html">27</a>  <a href="chap28.html">28</a>  <a href="chap29.html">29</a>  <a href="chap30.html">30</a>  <a href="chap31.html">31</a>  <a href="chap32.html">32</a>  <a href="chap33.html">33</a>  <a href="chap34.html">34</a>  <a href="chap35.html">35</a>  <a href="chap36.html">36</a>  <a href="chap37.html">37</a>  <a href="chap38.html">38</a>  <a href="chap39.html">39</a>  <a href="chap40.html">40</a>  <a href="chap41.html">41</a>  <a href="chap42.html">42</a>  <a href="chap43.html">43</a>  <a href="chap44.html">44</a>  <a href="chap45.html">45</a>  <a href="chap46.html">46</a>  <a href="chap47.html">47</a>  <a href="chap48.html">48</a>  <a href="chap49.html">49</a>  <a href="chap50.html">50</a>  <a href="chap51.html">51</a>  <a href="chap52.html">52</a>  <a href="chap53.html">53</a>  <a href="chap54.html">54</a>  <a href="chap55.html">55</a>  <a href="chap56.html">56</a>  <a href="chap57.html">57</a>  <a href="chap58.html">58</a>  <a href="chap59.html">59</a>  <a href="chap60.html">60</a>  <a href="chap61.html">61</a>  <a href="chap62.html">62</a>  <a href="chap63.html">63</a>  <a href="chap64.html">64</a>  <a href="chap65.html">65</a>  <a href="chap66.html">66</a>  <a href="chap67.html">67</a>  <a href="chap68.html">68</a>  <a href="chap69.html">69</a>  <a href="chap70.html">70</a>  <a href="chap71.html">71</a>  <a href="chap72.html">72</a>  <a href="chap73.html">73</a>  <a href="chap74.html">74</a>  <a href="chap75.html">75</a>  <a href="chap76.html">76</a>  <a href="chap77.html">77</a>  <a href="chap78.html">78</a>  <a href="chap79.html">79</a>  <a href="chap80.html">80</a>  <a href="chap81.html">81</a>  <a href="chap82.html">82</a>  <a href="chap83.html">83</a>  <a href="chap84.html">84</a>  <a href="chap85.html">85</a>  <a href="chap86.html">86</a>  <a href="chap87.html">87</a>  <a href="chapBib.html">Bib</a>  <a href="chapInd.html">Ind</a>  </div>

<hr />
<p class="foot">generated by <a href="http://www.math.rwth-aachen.de/~Frank.Luebeck/GAPDoc">GAPDoc2HTML</a></p>
</body>
</html>