This file is indexed.

/usr/share/gap/doc/ref/chap76.html is in gap-doc 4r7p9-1.

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
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
<?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 76: Using GAP Packages</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="chap76"  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="chap75.html">[Previous Chapter]</a>&nbsp;  &nbsp;<a href="chap77.html">[Next Chapter]</a>&nbsp;  </div>

<p id="mathjaxlink" class="pcenter"><a href="chap76_mj.html">[MathJax on]</a></p>
<p><a id="X7B6CD527825945CD" name="X7B6CD527825945CD"></a></p>
<div class="ChapSects"><a href="chap76.html#X7B6CD527825945CD">76 <span class="Heading">Using GAP Packages</span></a>
<div class="ContSect"><span class="tocline"><span class="nocss">&nbsp;</span><a href="chap76.html#X82473E4B8756C6CD">76.1 <span class="Heading">Installing a GAP Package</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss">&nbsp;</span><a href="chap76.html#X825CBC5B86F8F811">76.2 <span class="Heading">Loading a GAP Package</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap76.html#X79B373A77B29D1F5">76.2-1 LoadPackage</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap76.html#X858E8985840BFA72">76.2-2 SetPackagePath</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap76.html#X7CD0A2F27D19BA03">76.2-3 ExtendRootDirectories</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap76.html#X7D162DDF813D2BBA">76.2-4 DisplayPackageLoadingLog</a></span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss">&nbsp;</span><a href="chap76.html#X7C6CE28B7E142804">76.3 <span class="Heading">Functions for GAP Packages</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap76.html#X870954577B27DCAB">76.3-1 ReadPackage</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap76.html#X8580DF257E4D7046">76.3-2 TestPackageAvailability</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap76.html#X7B79FEE57DBDBD71">76.3-3 InstalledPackageVersion</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap76.html#X807D835C7B032D4E">76.3-4 DirectoriesPackageLibrary</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap76.html#X794508E5811D3BC9">76.3-5 DirectoriesPackagePrograms</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap76.html#X787DFEB383545A49">76.3-6 CompareVersionNumbers</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap76.html#X8067348B836BAF37">76.3-7 IsPackageMarkedForLoading</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap76.html#X8495E5327D563AC3">76.3-8 DeclareAutoreadableVariables</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap76.html#X79EF67107E40A130">76.3-9 <span class="Heading">Kernel modules in <strong class="pkg">GAP</strong> packages</span></a>
</span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap76.html#X7C99782886B18C77">76.3-10 LoadDynamicModule</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap76.html#X85C8DE357EE424D8">76.3-11 <span class="Heading">The PackageInfo.g File</span></a>
</span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap76.html#X79767C2482FF6F55">76.3-12 ValidatePackageInfo</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap76.html#X7D34AC3287611B15">76.3-13 ShowPackageVariables</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap76.html#X79EA4BD37940AD25">76.3-14 BibEntry</a></span>
<span class="ContSS"><br /><span class="nocss">&nbsp;&nbsp;</span><a href="chap76.html#X79637D9A7B1AD7F7">76.3-15 Cite</a></span>
</div></div>
</div>

<h3>76 <span class="Heading">Using GAP Packages</span></h3>

<p>The functionality of <strong class="pkg">GAP</strong> can be extended by loading <strong class="pkg">GAP</strong> packages. <strong class="pkg">GAP</strong> distribution already contains all currently redistributed with <strong class="pkg">GAP</strong> packages in the <code class="file">gap4r7/pkg</code> directory.</p>

<p><strong class="pkg">GAP</strong> packages are written by (groups of) <strong class="pkg">GAP</strong> users which may not be members of the <strong class="pkg">GAP</strong> developer team. The responsibility and copyright of a <strong class="pkg">GAP</strong> package remains with the original author(s).</p>

<p><strong class="pkg">GAP</strong> packages have their own documentation which is smoothly integrated into the <strong class="pkg">GAP</strong> help system.</p>

<p>All <strong class="pkg">GAP</strong> users who develop new code are invited to share the results of their efforts with other <strong class="pkg">GAP</strong> users by making the code and its documentation available in form of a package. Information how to do this is available from the <strong class="pkg">GAP</strong> Web pages (<span class="URL"><a href="http://www.gap-system.org">http://www.gap-system.org</a></span>) and in the <strong class="pkg">GAP</strong> package <strong class="pkg">Example</strong> (see <span class="URL"><a href="http://www.gap-system.org/Packages/example.html">http://www.gap-system.org/Packages/example.html</a></span>). There are possibilities to get a package distributed together with <strong class="pkg">GAP</strong> and it is possible to submit a package to a formal refereeing process.</p>

<p>In this chapter we describe how to use existing packages.</p>

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

<h4>76.1 <span class="Heading">Installing a GAP Package</span></h4>

<p>Before a package can be used it must be installed. With a standard installation of <strong class="pkg">GAP</strong> there should be all currently redistributed with <strong class="pkg">GAP</strong> packages already available. But since <strong class="pkg">GAP</strong> packages are released independently of the main <strong class="pkg">GAP</strong> system it may be sensible to upgrade or install new packages between upgrades of your <strong class="pkg">GAP</strong> installation.</p>

<p>A package consists of a collection of files within a single directory that must be a subdirectory of the <code class="file">pkg</code> directory in one of the <strong class="pkg">GAP</strong> root directories, see <a href="chap9.html#X7A4973627A5DB27D"><span class="RefLink">9.2</span></a>. (If you don't have access to the <code class="file">pkg</code> directory in your main <strong class="pkg">GAP</strong> installation you can add private root directories as explained in that section.)</p>

<p>Whenever you get from somewhere an archive of a <strong class="pkg">GAP</strong> package it should be accompanied with a <code class="file">README</code> file that explains its installation. Some packages just consist of <strong class="pkg">GAP</strong> code and the installation is done by unpacking the archive in one of the places described above. There are also packages that need further installation steps, there may be for example some external programs which have to be compiled (this is often done by just saying <code class="code">./configure; make</code> inside the unpacked package directory, but check the individual <code class="file">README</code> files). Note that if you use Windows you may not be able to use some or all external binaries.</p>

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

<h4>76.2 <span class="Heading">Loading a GAP Package</span></h4>

<p>Some <strong class="pkg">GAP</strong> packages are prepared for <em>automatic loading</em>, that is they will be loaded automatically with <strong class="pkg">GAP</strong>, others must in each case be separately loaded by a call to <code class="func">LoadPackage</code> (<a href="chap76.html#X79B373A77B29D1F5"><span class="RefLink">76.2-1</span></a>).</p>

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

<h5>76.2-1 LoadPackage</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; LoadPackage</code>( <var class="Arg">name</var>[, <var class="Arg">version</var>][, <var class="Arg">banner</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>loads the <strong class="pkg">GAP</strong> package with name <var class="Arg">name</var>. If the optional version string <var class="Arg">version</var> is given, the package will only be loaded in a version number at least as large as <var class="Arg">version</var>, or equal to <var class="Arg">version</var> if its first character is <code class="code">=</code> (see <code class="func">CompareVersionNumbers</code> (<a href="chap76.html#X787DFEB383545A49"><span class="RefLink">76.3-6</span></a>)). The argument <var class="Arg">name</var> is case insensitive.</p>

<p><code class="func">LoadPackage</code> will return <code class="keyw">true</code> if the package has been successfully loaded and will return <code class="keyw">fail</code> if the package could not be loaded. The latter may be the case if the package is not installed, if necessary binaries have not been compiled, or if the version number of the available version is too small. If the package cannot be loaded, <code class="func">TestPackageAvailability</code> (<a href="chap76.html#X8580DF257E4D7046"><span class="RefLink">76.3-2</span></a>) can be used to find the reasons. Also, <code class="func">DisplayPackageLoadingLog</code> (<a href="chap76.html#X7D162DDF813D2BBA"><span class="RefLink">76.2-4</span></a>) can be used to find out more about the failure reasons. To see the problems directly, one can change the verbosity using the user preference <code class="code">InfoPackageLoadingLevel</code>, see <code class="func">InfoPackageLoading</code> (<a href="chap76.html#X7D162DDF813D2BBA"><span class="RefLink">76.2-4</span></a>) for details.</p>

<p>If the package <var class="Arg">name</var> has already been loaded in a version number at least or equal to <var class="Arg">version</var>, respectively, <code class="func">LoadPackage</code> returns <code class="keyw">true</code> without doing anything else.</p>

<p>The argument <var class="Arg">name</var> may be the prefix of a package name. If no package with name <var class="Arg">name</var> is installed, the behaviour is as follows. If <var class="Arg">name</var> is the prefix of exactly one name of an installed package then <code class="func">LoadPackage</code> is called with this name; if the names of several installed packages start with <var class="Arg">name</var> then the these names are printed, and <code class="func">LoadPackage</code> returns <code class="keyw">fail</code>. Thus the names of <em>all</em> installed packages can be shown by calling <code class="func">LoadPackage</code> with an empty string.</p>

<p>If the optional argument <var class="Arg">banner</var> is present then it must be either <code class="keyw">true</code> or <code class="keyw">false</code>; in the latter case, the effect is that no package banner is printed.</p>

<p>After a package has been loaded its code and documentation should be available as other parts of the <strong class="pkg">GAP</strong> library are.</p>

<p>When <strong class="pkg">GAP</strong> is started then some packages are loaded automatically. These are the packages listed in <code class="code">GAPInfo.Dependencies.NeededOtherPackages</code> and (if this is not disabled, see below) <code class="code">UserPreference( "PackagesToLoad" )</code>.</p>

<p>A <strong class="pkg">GAP</strong> package may also install only its documentation automatically but still need loading by <code class="func">LoadPackage</code>. In this situation the online help displays <code class="code">(not loaded)</code> in the header lines of the manual pages belonging to this <strong class="pkg">GAP</strong> package.</p>

<p>If for some reason you don't want certain packages to be automatically loaded, <strong class="pkg">GAP</strong> provides three levels for disabling autoloading:</p>

<p>The autoloading of specific packages can be overwritten <em>for the whole <strong class="pkg">GAP</strong> installation</em> by putting a file <code class="file">NOAUTO</code> into a <code class="file">pkg</code> directory that contains lines with the names of packages which should not be automatically loaded.</p>

<p>Furthermore, <em>individual users</em> can disable the autoloading of specific packages by putting the names of these packages into the list that is assigned to the user preference "ExcludeFromAutoload", for example in the user's <code class="file">gap.ini</code> file (see <a href="chap3.html#X87DF11C885E73583"><span class="RefLink">3.2-1</span></a>).</p>

<p>Using the <code class="code">-A</code> command line option when starting up <strong class="pkg">GAP</strong> (see <a href="chap3.html#X782751D5858A6EAF"><span class="RefLink">3.1</span></a>), automatic loading of packages is switched off <em>for this <strong class="pkg">GAP</strong> session</em>.</p>

<p>In any of the above three cases, the packages listed in <code class="code">GAPInfo.Dependencies.NeededOtherPackages</code> are still loaded automatically, and an error is signalled if not all of these packages are available.</p>

<p>See <code class="func">SetPackagePath</code> (<a href="chap76.html#X858E8985840BFA72"><span class="RefLink">76.2-2</span></a>) for a possibility to force that a prescribed package version will be loaded. See also <code class="func">ExtendRootDirectories</code> (<a href="chap76.html#X7CD0A2F27D19BA03"><span class="RefLink">76.2-3</span></a>) for a possibility to add directories containing packages after <strong class="pkg">GAP</strong> has been started.</p>

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

<h5>76.2-2 SetPackagePath</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; SetPackagePath</code>( <var class="Arg">pkgname</var>, <var class="Arg">pkgpath</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>Let <var class="Arg">pkgname</var> and <var class="Arg">pkgpath</var> be strings denoting the name of a <strong class="pkg">GAP</strong> package and the path to a directory where a version of this package can be found (i. e., calling <code class="func">Directory</code> (<a href="chap9.html#X86A71E927EEC7EAD"><span class="RefLink">9.3-2</span></a>) with the argument <var class="Arg">pkgpath</var> will yield a directory that contains the file <code class="file">PackageInfo.g</code> of the package).</p>

<p>If the package <var class="Arg">pkgname</var> is already loaded with an installation path different from <var class="Arg">pkgpath</var> then <code class="func">SetPackagePath</code> signals an error. If the package <var class="Arg">pkgname</var> is not yet loaded then <code class="func">SetPackagePath</code> erases the information about available versions of the package <var class="Arg">pkgname</var>, and stores the record that is contained in the <code class="file">PackageInfo.g</code> file at <var class="Arg">pkgpath</var> instead, such that only the version installed at <var class="Arg">pkgpath</var> can be loaded with <code class="func">LoadPackage</code> (<a href="chap76.html#X79B373A77B29D1F5"><span class="RefLink">76.2-1</span></a>).</p>

<p>This function can be used to force <strong class="pkg">GAP</strong> to load a particular version of a package, although newer versions of the package might be available.</p>

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

<h5>76.2-3 ExtendRootDirectories</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; ExtendRootDirectories</code>( <var class="Arg">paths</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>Let <var class="Arg">paths</var> be a list of strings that denote paths to intended <strong class="pkg">GAP</strong> root directories (see <a href="chap9.html#X7A4973627A5DB27D"><span class="RefLink">9.2</span></a>). The function <code class="func">ExtendRootDirectories</code> adds these paths to the global list <code class="code">GAPInfo.RootPaths</code> and calls the initialization of available <strong class="pkg">GAP</strong> packages, such that later calls to <code class="func">LoadPackage</code> (<a href="chap76.html#X79B373A77B29D1F5"><span class="RefLink">76.2-1</span></a>) will find the <strong class="pkg">GAP</strong> packages that are contained in <code class="file">pkg</code> subdirectories of the directories given by <var class="Arg">paths</var>.</p>

<p>Note that the purpose of this function is to make <strong class="pkg">GAP</strong> packages in the given directories available. It cannot be used to influence the start of <strong class="pkg">GAP</strong>, because the <strong class="pkg">GAP</strong> library is loaded before <code class="func">ExtendRootDirectories</code> can be called (and because <code class="code">GAPInfo.RootPaths</code> is not used for reading the <strong class="pkg">GAP</strong> library).</p>

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

<h5>76.2-4 DisplayPackageLoadingLog</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; DisplayPackageLoadingLog</code>( [<var class="Arg">severity</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">&#8227; InfoPackageLoading</code></td><td class="tdright">( info class )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; PACKAGE_ERROR</code></td><td class="tdright">( global variable )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; PACKAGE_WARNING</code></td><td class="tdright">( global variable )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; PACKAGE_INFO</code></td><td class="tdright">( global variable )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; PACKAGE_DEBUG</code></td><td class="tdright">( global variable )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; LogPackageLoadingMessage</code>( <var class="Arg">severity</var>, <var class="Arg">message</var>[, <var class="Arg">name</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>Whenever <strong class="pkg">GAP</strong> considers loading a package, log messages are collected in a global list. The messages for the current <strong class="pkg">GAP</strong> session can be displayed with <code class="func">DisplayPackageLoadingLog</code>. To each message, a "severity" is assigned, which is one of <code class="func">PACKAGE_ERROR</code>, <code class="func">PACKAGE_WARNING</code>, <code class="func">PACKAGE_INFO</code>, <code class="func">PACKAGE_DEBUG</code>, in increasing order. The function <code class="func">DisplayPackageLoadingLog</code> shows only the messages whose severity is at most <var class="Arg">severity</var>, the default for <var class="Arg">severity</var> is <code class="func">PACKAGE_WARNING</code>.</p>

<p>The intended meaning of the severity levels is as follows.</p>


<dl>
<dt><strong class="Mark">PACKAGE_ERROR</strong></dt>
<dd><p>should be used whenever <strong class="pkg">GAP</strong> will run into an error during package loading, where the reason of the error shall be documented in the global list.</p>

</dd>
<dt><strong class="Mark">PACKAGE_WARNING</strong></dt>
<dd><p>should be used whenever <strong class="pkg">GAP</strong> has detected a reason why a package cannot be loaded, and where the message describes how to solve this problem, for example if a package binary is missing.</p>

</dd>
<dt><strong class="Mark">PACKAGE_INFO</strong></dt>
<dd><p>should be used whenever <strong class="pkg">GAP</strong> has detected a reason why a package cannot be loaded, and where it is not clear how to solve this problem, for example if the package is not compatible with other installed packages.</p>

</dd>
<dt><strong class="Mark">PACKAGE_DEBUG</strong></dt>
<dd><p>should be used for other messages reporting what <strong class="pkg">GAP</strong> does when it loads packages (checking dependencies, reading files, etc.). One purpose is to record in which order packages have been considered for loading or have actually been loaded.</p>

</dd>
</dl>
<p>The log messages are created either by the functions of <strong class="pkg">GAP</strong>'s package loading mechanism or in the code of your package, for example in the <code class="code">AvailabilityTest</code> function of the package's <code class="file">PackageInfo.g</code> file (see <a href="chap76.html#X85C8DE357EE424D8"><span class="RefLink">76.3-11</span></a>), using <code class="func">LogPackageLoadingMessage</code>. The arguments of this function are <var class="Arg">severity</var> (which must be one of the above severity levels), <var class="Arg">message</var> (which must be either a string or a list of strings), and optionally <var class="Arg">name</var> (which must be the name of the package to which the message belongs). The argument <var class="Arg">name</var> is not needed if the function is called from a call of a package's <code class="code">AvailabilityTest</code> function (see <a href="chap76.html#X85C8DE357EE424D8"><span class="RefLink">76.3-11</span></a>) or is called from a package file that is read from <code class="file">init.g</code> or <code class="file">read.g</code>; in these cases, the name of the current package (stored in the record <code class="code">GAPInfo.PackageCurrent</code>) is taken. According to the above list, the <var class="Arg">severity</var> argument of <code class="func">LogPackageLoadingMessage</code> calls in a package's <code class="code">AvailabilityTest</code> function is either <code class="func">PACKAGE_WARNING</code> or <code class="func">PACKAGE_INFO</code>.</p>

<p>If you want to see the log messages already during the package loading process, you can set the level of the info class <code class="func">InfoPackageLoading</code> to one of the severity values listed above; afterwards the messages with at most this severity are shown immediately when they arise. In order to make this work already for autoloaded packages, you can call <code class="code">SetUserPreference("InfoPackageLoadingLevel", <var class="Arg">lev</var>);</code> to set the desired severity level <var class="Arg">lev</var>. This can for example be done in your <code class="file">gap.ini</code> file, see Section <a href="chap3.html#X87DF11C885E73583"><span class="RefLink">3.2-1</span></a>.</p>

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

<h4>76.3 <span class="Heading">Functions for GAP Packages</span></h4>

<p>The following functions are mainly used in files contained in a package and not by users of a package.</p>

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

<h5>76.3-1 ReadPackage</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; ReadPackage</code>( [<var class="Arg">name</var>, ]<var class="Arg">file</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">&#8227; RereadPackage</code>( [<var class="Arg">name</var>, ]<var class="Arg">file</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>Called with two strings <var class="Arg">name</var> and <var class="Arg">file</var>, <code class="func">ReadPackage</code> reads the file <var class="Arg">file</var> of the <strong class="pkg">GAP</strong> package <var class="Arg">name</var>, where <var class="Arg">file</var> is given as a path relative to the home directory of <var class="Arg">name</var>. Note that <var class="Arg">file</var> is read in the namespace of the package, see Section <a href="chap4.html#X875BA7C58175DEFB"><span class="RefLink">4.10</span></a> for details.</p>

<p>If only one argument <var class="Arg">file</var> is given, this should be the path of a file relative to the <code class="file">pkg</code> subdirectory of <strong class="pkg">GAP</strong> root paths (see <a href="chap9.html#X7A4973627A5DB27D"><span class="RefLink">9.2</span></a>). Note that in this case, the package name is assumed to be equal to the first part of <var class="Arg">file</var>, <em>so the one argument form is not recommended</em>.</p>

<p>The absolute path is determined as follows. If the package in question has already been loaded then the file in the directory of the loaded version is read. If the package is available but not yet loaded then the directory given by <code class="func">TestPackageAvailability</code> (<a href="chap76.html#X8580DF257E4D7046"><span class="RefLink">76.3-2</span></a>) is used, without prescribed version number. (Note that the <code class="func">ReadPackage</code> call does <em>not</em> force the package to be loaded.)</p>

<p>If the file is readable then <code class="keyw">true</code> is returned, otherwise <code class="keyw">false</code>.</p>

<p>Each of <var class="Arg">name</var> and <var class="Arg">file</var> should be a string. The <var class="Arg">name</var> argument is case insensitive.</p>

<p><code class="func">RereadPackage</code> does the same as <code class="func">ReadPackage</code>, except that also read-only global variables are overwritten (cf. <code class="func">Reread</code> (<a href="chap9.html#X79EE267A7FAF28A6"><span class="RefLink">9.7-9</span></a>)).</p>

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

<h5>76.3-2 TestPackageAvailability</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; TestPackageAvailability</code>( <var class="Arg">name</var>[, <var class="Arg">version</var>][, <var class="Arg">checkall</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>For strings <var class="Arg">name</var> and <var class="Arg">version</var>, this function tests whether the <strong class="pkg">GAP</strong> package <var class="Arg">name</var> is available for loading in a version that is at least <var class="Arg">version</var>, or equal to <var class="Arg">version</var> if the first character of <var class="Arg">version</var> is <code class="code">=</code> (see <code class="func">CompareVersionNumbers</code> (<a href="chap76.html#X787DFEB383545A49"><span class="RefLink">76.3-6</span></a>) for further details about version numbers).</p>

<p>The result is <code class="keyw">true</code> if the package is already loaded, <code class="keyw">fail</code> if it is not available, and the string denoting the <strong class="pkg">GAP</strong> root path where the package resides if it is available, but not yet loaded. So the package <var class="Arg">name</var> is available if the result of <code class="func">TestPackageAvailability</code> is not equal to <code class="keyw">fail</code>.</p>

<p>If the optional argument <var class="Arg">checkall</var> is <code class="keyw">true</code> then all dependencies are checked, even if some have turned out to be not satisfied. This is useful when one is interested in the reasons why the package <var class="Arg">name</var> cannot be loaded. In this situation, calling first <code class="func">TestPackageAvailability</code> and then <code class="func">DisplayPackageLoadingLog</code> (<a href="chap76.html#X7D162DDF813D2BBA"><span class="RefLink">76.2-4</span></a>) with argument <code class="func">PACKAGE_INFO</code> (<a href="chap76.html#X7D162DDF813D2BBA"><span class="RefLink">76.2-4</span></a>) will give an overview of these reasons.</p>

<p>You should <em>not</em> call <code class="func">TestPackageAvailability</code> in the test function of a package (the value of the component <code class="code">AvailabilityTest</code> in the <code class="file">PackageInfo.g</code> file of the package, see <a href="chap76.html#X85C8DE357EE424D8"><span class="RefLink">76.3-11</span></a>), because <code class="func">TestPackageAvailability</code> calls this test function.</p>

<p>The argument <var class="Arg">name</var> is case insensitive.</p>

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

<h5>76.3-3 InstalledPackageVersion</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; InstalledPackageVersion</code>( <var class="Arg">name</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>If the <strong class="pkg">GAP</strong> package with name <var class="Arg">name</var> has already been loaded then <code class="func">InstalledPackageVersion</code> returns the string denoting the version number of this version of the package. If the package is available but has not yet been loaded then the version number string for that version of the package that currently would be loaded. (Note that loading <em>another</em> package might force loading another version of the package <var class="Arg">name</var>, so the result of <code class="func">InstalledPackageVersion</code> will be different afterwards.) If the package is not available then <code class="keyw">fail</code> is returned.</p>

<p>The argument <var class="Arg">name</var> is case insensitive.</p>

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

<h5>76.3-4 DirectoriesPackageLibrary</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; DirectoriesPackageLibrary</code>( <var class="Arg">name</var>[, <var class="Arg">path</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>takes the string <var class="Arg">name</var>, a name of a <strong class="pkg">GAP</strong> package, and returns a list of directory objects for those sub-directory/ies containing the library functions of this <strong class="pkg">GAP</strong> package, for the version that is already loaded or is currently going to be loaded or would be the first version <strong class="pkg">GAP</strong> would try to load if no other version is explicitly prescribed. (If the package <var class="Arg">name</var> is not yet loaded then we cannot guarantee that the returned directories belong to a version that really can be loaded.)</p>

<p>The default is that the library functions are in the subdirectory <code class="file">lib</code> of the <strong class="pkg">GAP</strong> package's home directory. If this is not the case, then the second argument <var class="Arg">path</var> needs to be present and must be a string that is a path name relative to the home directory of the <strong class="pkg">GAP</strong> package with name <var class="Arg">name</var>.</p>

<p>Note that <code class="func">DirectoriesPackageLibrary</code> is likely to be called in the <code class="code">AvailabilityTest</code> function in the package's <code class="file">PackageInfo.g</code> file (see <a href="chap76.html#X85C8DE357EE424D8"><span class="RefLink">76.3-11</span></a>).</p>

<p>As an example, the following returns a directory object for the library functions of the <strong class="pkg">GAP</strong> package <strong class="pkg">Example</strong>:</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">DirectoriesPackageLibrary( "Example", "gap" );</span>
[ dir("/home/werner/gap/4.0/pkg/example/gap/") ]
</pre></div>

<p>Observe that we needed the second argument <code class="code">"gap"</code> here, since <strong class="pkg">Example</strong>'s library functions are in the subdirectory <code class="file">gap</code> rather than <code class="file">lib</code>.</p>

<p>In order to find a subdirectory deeper than one level in a package directory, the second argument is again necessary whether or not the desired subdirectory relative to the package's directory begins with <code class="file">lib</code>. The directories in <var class="Arg">path</var> should be separated by <code class="code">/</code> (even on systems, like Windows, which use <code class="code">\</code> as the directory separator). For example, suppose there is a package <code class="code">somepackage</code> with a subdirectory <code class="file">m11</code> in the directory <code class="file">data</code>, then we might expect the following:</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">DirectoriesPackageLibrary( "somepackage", "data/m11" );</span>
[ dir("/home/werner/gap/4.0/pkg/somepackage/data/m11") ]
</pre></div>

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

<h5>76.3-5 DirectoriesPackagePrograms</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; DirectoriesPackagePrograms</code>( <var class="Arg">name</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>returns a list of the <code class="code">bin/</code><var class="Arg">architecture</var> subdirectories of all packages <var class="Arg">name</var> where <var class="Arg">architecture</var> is the architecture on which <strong class="pkg">GAP</strong> has been compiled (this can be accessed as <code class="code">GAPInfo.Architecture</code>, see <code class="func">GAPInfo</code> (<a href="chap3.html#X8354754E7935F935"><span class="RefLink">3.5-1</span></a>)) and the version of the installed package coincides with the version of the package <var class="Arg">name</var> that is already loaded or is currently going to be loaded or would be the first version <strong class="pkg">GAP</strong> would try to load if no other version is explicitly prescribed. (If the package <var class="Arg">name</var> is not yet loaded then we cannot guarantee that the returned directories belong to a version that really can be loaded.)</p>

<p>Note that <code class="func">DirectoriesPackagePrograms</code> is likely to be called in the <code class="code">AvailabilityTest</code> function in the package's <code class="file">PackageInfo.g</code> file (see <a href="chap76.html#X85C8DE357EE424D8"><span class="RefLink">76.3-11</span></a>).</p>

<p>The directories returned by <code class="func">DirectoriesPackagePrograms</code> are the place where external binaries of the <strong class="pkg">GAP</strong> package <var class="Arg">name</var> for the current package version and the current architecture should be located.</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">DirectoriesPackagePrograms( "nq" );</span>
[ dir("/home/gap/4.0/pkg/nq/bin/x86_64-unknown-linux-gnu-gcc/64-bit/"),
  dir("/home/gap/4.0/pkg/nq/bin/x86_64-unknown-linux-gnu-gcc/") ]
</pre></div>

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

<h5>76.3-6 CompareVersionNumbers</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; CompareVersionNumbers</code>( <var class="Arg">supplied</var>, <var class="Arg">required</var>[, <var class="Arg">"equal"</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>A version number is a string which contains nonnegative integers separated by non-numeric characters. Examples of valid version numbers are for example:</p>


<div class="example"><pre>
"1.0"   "3.141.59"  "2-7-8.3" "5 release 2 patchlevel 666"
</pre></div>

<p><code class="func">CompareVersionNumbers</code> compares two version numbers, given as strings. They are split at non-digit characters, the resulting integer lists are compared lexicographically. The routine tests whether <var class="Arg">supplied</var> is at least as large as <var class="Arg">required</var>, and returns <code class="keyw">true</code> or <code class="keyw">false</code> accordingly. A version number ending in <code class="code">dev</code> is considered to be infinite.</p>

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

<h5>76.3-7 IsPackageMarkedForLoading</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; IsPackageMarkedForLoading</code>( <var class="Arg">name</var>, <var class="Arg">version</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>This function can be used in the code of a package <span class="SimpleMath">A</span>, say, for testing whether the package <var class="Arg">name</var> in version <var class="Arg">version</var> will be loaded after the <code class="func">LoadPackage</code> (<a href="chap76.html#X79B373A77B29D1F5"><span class="RefLink">76.2-1</span></a>) call for the package <span class="SimpleMath">A</span> has been executed. This means that the package <var class="Arg">name</var> had been loaded before, or has been (directly or indirectly) requested as a needed or suggested package of the package <span class="SimpleMath">A</span> or of a package whose loading requested that <span class="SimpleMath">A</span> was loaded.</p>

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

<h5>76.3-8 DeclareAutoreadableVariables</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; DeclareAutoreadableVariables</code>( <var class="Arg">pkgname</var>, <var class="Arg">filename</var>, <var class="Arg">varlist</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>Let <var class="Arg">pkgname</var> be the name of a package, let <var class="Arg">filename</var> be the name of a file relative to the home directory of this package, and let <var class="Arg">varlist</var> be a list of strings that are the names of global variables which get bound when the file is read. <code class="func">DeclareAutoreadableVariables</code> notifies the names in <var class="Arg">varlist</var> such that the first attempt to access one of the variables causes the file to be read.</p>

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

<h5>76.3-9 <span class="Heading">Kernel modules in <strong class="pkg">GAP</strong> packages</span></h5>

<p>If the package has a kernel module, then it can be compiled using the <strong class="pkg">gac</strong> script. A kernel module is implemented in C and follows certain conventions to comply with the <strong class="pkg">GAP</strong> kernel interface, which we plan to document later. In the meantime, we advice to get in touch with <strong class="pkg">GAP</strong> developers if you plan to develop such a package.</p>

<p>To use the <strong class="pkg">gac</strong> script to produce dynamically loadable modules, call it with the <code class="code">-d</code> option, for example:</p>


<div class="example"><pre>
$ gap4/bin/i386-ibm-linux-gcc2/gac -d test.c
</pre></div>

<p>This will produce a file <code class="file">test.so</code>, which then can be loaded into <strong class="pkg">GAP</strong> with <code class="func">LoadDynamicModule</code> (<a href="chap76.html#X7C99782886B18C77"><span class="RefLink">76.3-10</span></a>).</p>

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

<h5>76.3-10 LoadDynamicModule</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; LoadDynamicModule</code>( <var class="Arg">filename</var>[, <var class="Arg">crc</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>To load a compiled file, the command <code class="func">LoadDynamicModule</code> is used. This command loads <var class="Arg">filename</var> as module. If given, the CRC checksum <var class="Arg">crc</var> must match the value of the module (see <a href="chap9.html#X8241CEAD80415BB9"><span class="RefLink">9.7-7</span></a>).</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">LoadDynamicModule("./test.so");</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">CrcFile("test.so");</span>
2906458206
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">LoadDynamicModule("./test.so",1);</span>
Error, &lt;crc&gt; mismatch (or no support for dynamic loading) called from
&lt;function&gt;( &lt;arguments&gt; ) called from read-eval-loop
Entering break read-eval-print loop ...
you can 'quit;' to quit to outer loop, or
you can 'return;' to continue
<span class="GAPbrkprompt">brk&gt;</span> <span class="GAPinput">quit;</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">LoadDynamicModule("./test.so",2906458206);</span>
</pre></div>

<p>On some operating systems, once you have loaded a dynamic module with a certain filename, loading another with the same filename will have no effect, even if the file on disk has changed.</p>

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

<h5>76.3-11 <span class="Heading">The PackageInfo.g File</span></h5>

<p>Each package has the file <code class="file">PackageInfo.g</code> which contains meta-information about the package (package name, version, author(s), relations to other packages, homepage, download archives, banner, etc.). This file is used by the package loading mechanism and also for the distribution of a package to other users.</p>

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

<h5>76.3-12 ValidatePackageInfo</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; ValidatePackageInfo</code>( <var class="Arg">info</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>This function is intended to support package authors who create or modify <code class="file">PackageInfo.g</code> files. (It is <em>not</em> called when these files are read during the startup of <strong class="pkg">GAP</strong> or when packages are actually loaded.)</p>

<p>The argument <var class="Arg">info</var> must be either a record as is contained in a <code class="file">PackageInfo.g</code> file or a a string which describes the path to such a file. The result is <code class="keyw">true</code> if the record or the contents of the file, respectively, has correct format, and <code class="keyw">false</code> otherwise; in the latter case information about the incorrect components is printed.</p>

<p>Note that the components used for package loading are checked as well as the components that are needed for composing the package overview web page or for updating the package archives.</p>

<p>If <var class="Arg">info</var> is a string then <code class="func">ValidatePackageInfo</code> checks additionally whether those package files exist that are mentioned in the file <code class="file">info</code>, for example the <code class="file">manual.six</code> file of the package documentation.</p>

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

<h5>76.3-13 ShowPackageVariables</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; ShowPackageVariables</code>( <var class="Arg">pkgname</var>[, <var class="Arg">version</var>][, <var class="Arg">arec</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">&#8227; PackageVariablesInfo</code>( <var class="Arg">pkgname</var>, <var class="Arg">version</var> )</td><td class="tdright">( function )</td></tr></table></div>
<p>Let <var class="Arg">pkgname</var> be the name of a <strong class="pkg">GAP</strong> package. If the package <var class="Arg">pkgname</var> is available but not yet loaded then <code class="func">ShowPackageVariables</code> prints a list of global variables that become bound and of methods that become installed when the package is loaded. (For that, <strong class="pkg">GAP</strong> actually loads the package.)</p>

<p>If a version number <var class="Arg">version</var> is given (see Section <span class="RefLink">???</span>) then this version of the package is considered.</p>

<p>An error message is printed if (the given version of) the package is not available or already loaded.</p>

<p>Information is printed about new and redeclared global variables, and about names of global variables introduced in the package that differ from existing globals only by case; note that the <strong class="pkg">GAP</strong> help system is case insensitive, so it is difficult to document identifiers that differ only by case.</p>

<p>Info lines for undocumented variables are marked with an asterisk <code class="code">*</code>.</p>

<p>The following entries are omitted from the list: default setter methods for attributes and properties that are declared in the package, and <code class="code">Set<var class="Arg">attr</var></code> and <code class="code">Has<var class="Arg">attr</var></code> type variables where <var class="Arg">attr</var> is an attribute or property.</p>

<p>The output can be customized using the optional record <var class="Arg">arec</var>, the following components of this record are supported.</p>


<dl>
<dt><strong class="Mark"><code class="code">show</code></strong></dt>
<dd><p>a list of strings describing those kinds of variables which shall be shown, such as <code class="code">"new global functions"</code>; the default are all kinds that appear in the package,</p>

</dd>
<dt><strong class="Mark"><code class="code">showDocumented</code></strong></dt>
<dd><p><code class="keyw">true</code> (the default) if documented variables shall be shown, and <code class="keyw">false</code> otherwise,</p>

</dd>
<dt><strong class="Mark"><code class="code">showUndocumented</code></strong></dt>
<dd><p><code class="keyw">true</code> (the default) if undocumented variables shall be shown, and <code class="keyw">false</code> otherwise,</p>

</dd>
<dt><strong class="Mark"><code class="code">showPrivate</code></strong></dt>
<dd><p><code class="keyw">true</code> (the default) if variables from the package's name space (see Section <a href="chap4.html#X875BA7C58175DEFB"><span class="RefLink">4.10</span></a>) shall be shown, and <code class="keyw">false</code> otherwise,</p>

</dd>
<dt><strong class="Mark"><code class="code">Display</code></strong></dt>
<dd><p>a function that takes a string and shows it on the screen; the default is <code class="func">Print</code> (<a href="chap6.html#X7AFA64D97A1F39A3"><span class="RefLink">6.3-4</span></a>), another useful value is <code class="func">Pager</code> (<a href="chap2.html#X7ED03E41792C3840"><span class="RefLink">2.4-1</span></a>).</p>

</dd>
</dl>
<p>An interactive variant of <code class="func">ShowPackageVariables</code> is the function <code class="func">BrowsePackageVariables</code> (<span class="RefLink">???</span>) that is provided by the <strong class="pkg">GAP</strong> package <strong class="pkg">Browse</strong>. For this function, it is not sensible to assume that the package <var class="Arg">pkgname</var> is not yet loaded before the function call, because one might be interested in packages that must be loaded before <strong class="pkg">Browse</strong> itself can be loaded. The solution is that <code class="func">BrowsePackageVariables</code> (<span class="RefLink">???</span>) takes the output of <code class="func">PackageVariablesInfo</code> as its second argument. The function <code class="func">PackageVariablesInfo</code> is used by both <code class="func">ShowPackageVariables</code> and <code class="func">BrowsePackageVariables</code> (<span class="RefLink">???</span>) for collecting the information about the package in question, and can be called before the package <strong class="pkg">Browse</strong> is loaded.</p>

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

<h5>76.3-14 BibEntry</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; BibEntry</code>( <var class="Arg">pkgname</var>[, <var class="Arg">key</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>Returns: a string in BibXMLext format (see <a href="../../pkg/GAPDoc/doc/chap7.html#X7FB8F6BD80D859D1"><span class="RefLink">GAPDoc: The BibXMLext Format</span></a>) that can be used for referencing the <strong class="pkg">GAP</strong> system or a <strong class="pkg">GAP</strong> package.</p>

<p>If the argument <var class="Arg">pkgname</var> is the string <code class="code">"GAP"</code>, the function returns an entry for the current version of <strong class="pkg">GAP</strong>.</p>

<p>Otherwise, if a string <var class="Arg">pkgname</var> is given, which is the name of a <strong class="pkg">GAP</strong> package, an entry for this package is returned; this entry is computed from the <code class="file">PackageInfo.g</code> file of <em>the current version</em> of the package, see <code class="func">InstalledPackageVersion</code> (<a href="chap76.html#X7B79FEE57DBDBD71"><span class="RefLink">76.3-3</span></a>). If no package with name <var class="Arg">pkgname</var> is installed then the empty string is returned.</p>

<p>A string for <em>a different version</em> of <strong class="pkg">GAP</strong> or a package can be computed by entering, as the argument <var class="Arg">pkgname</var>, the desired record from the <code class="file">PackageInfo.g</code> file. (One can access these records using the function <code class="code">PackageInfo</code>.)</p>

<p>In each of the above cases, an optional argument <var class="Arg">key</var> can be given, a string which is then used as the key of the BibTeX entry instead of the default key that is generated from the system/package name and the version number.</p>

<p><code class="func">BibEntry</code> requires the functions <code class="func">FormatParagraph</code> (<a href="../../pkg/GAPDoc/doc/chap6.html#X812058CE7C8E9022"><span class="RefLink">GAPDoc: FormatParagraph</span></a>) and <code class="func">NormalizedNameAndKey</code> (<a href="../../pkg/GAPDoc/doc/chap7.html#X7C9F0C337A0A0FF0"><span class="RefLink">GAPDoc: NormalizedNameAndKey</span></a>) from the <strong class="pkg">GAP</strong> package <strong class="pkg">GAPDoc</strong>.</p>

<p>The functions <code class="func">ParseBibXMLextString</code> (<a href="../../pkg/GAPDoc/doc/chap7.html#X86BD29AE7A453721"><span class="RefLink">GAPDoc: ParseBibXMLextString</span></a>) and <code class="func">StringBibXMLEntry</code> (<a href="../../pkg/GAPDoc/doc/chap7.html#X790A295680F7CD24"><span class="RefLink">GAPDoc: StringBibXMLEntry</span></a>) can be used to create for example a BibTeX entry from the return value, as follows.</p>


<div class="example"><pre>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">bib:= BibEntry( "GAP", "GAP4.5" );;</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">Print( bib, "\n" );</span>
&lt;entry id="GAP4.5"&gt;&lt;misc&gt;
  &lt;title&gt;&lt;C&gt;GAP&lt;/C&gt; &amp;ndash; &lt;C&gt;G&lt;/C&gt;roups, &lt;C&gt;A&lt;/C&gt;lgorithms,
         and &lt;C&gt;P&lt;/C&gt;rogramming, &lt;C&gt;V&lt;/C&gt;ersion 4.5.1&lt;/title&gt;
  &lt;howpublished&gt;&lt;URL&gt;http://www.gap-system.org&lt;/URL&gt;&lt;/howpublished&gt;
  &lt;key&gt;GAP&lt;/key&gt;
  &lt;keywords&gt;groups; *; gap; manual&lt;/keywords&gt;
  &lt;other type="organization"&gt;The GAP &lt;C&gt;G&lt;/C&gt;roup&lt;/other&gt;
&lt;/misc&gt;&lt;/entry&gt;
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">parse:= ParseBibXMLextString( bib );;</span>
<span class="GAPprompt">gap&gt;</span> <span class="GAPinput">Print( StringBibXMLEntry( parse.entries[1], "BibTeX" ) );</span>
@misc{ GAP4.5,
  title =            {{GAP}   {\textendash}   {G}roups,   {A}lgorithms,  and
                      {P}rogramming, {V}ersion 4.5.1},
  organization =     {The GAP {G}roup},
  howpublished =     {\href                      {http://www.gap-system.org}
                      {\texttt{http://www.gap-system.org}}},
  key =              {GAP},
  keywords =         {groups; *; gap; manual}
}
</pre></div>

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

<h5>76.3-15 Cite</h5>

<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">&#8227; Cite</code>( [<var class="Arg">pkgname</var>[, <var class="Arg">key</var>]] )</td><td class="tdright">( function )</td></tr></table></div>
<p>Used with no arguments or with argument <code class="code">"GAP"</code> (case-insensitive), <code class="func">Cite</code> displays instructions on citing the version of <strong class="pkg">GAP</strong> that is being used. Suggestions are given in plain text, HTML, BibXML and BibTeX formats. The same instructions are also contained in the <code class="file">CITATION</code> file in the <strong class="pkg">GAP</strong> root directory.</p>

<p>If <var class="Arg">pkgname</var> is the name of a <strong class="pkg">GAP</strong> package, instructions on citing this package will be displayed. They will be produced from the <code class="file">PackageInfo.g</code> file of the working version of this package that must be available in the <strong class="pkg">GAP</strong> installation being used. Otherwise, one will get a warning that no working version of the package is available.</p>

<p>The optional 2nd argument <var class="Arg">key</var> has the same meaning as in <code class="func">BibEntry</code> (<a href="chap76.html#X79EA4BD37940AD25"><span class="RefLink">76.3-14</span></a>).</p>


<div class="chlinkprevnextbot">&nbsp;<a href="chap0.html">[Top of Book]</a>&nbsp;  <a href="chap0.html#contents">[Contents]</a>&nbsp;  &nbsp;<a href="chap75.html">[Previous Chapter]</a>&nbsp;  &nbsp;<a href="chap77.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>