/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"> <a href="chap0.html">[Top of Book]</a> <a href="chap0.html#contents">[Contents]</a> <a href="chap75.html">[Previous Chapter]</a> <a href="chap77.html">[Next Chapter]</a> </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"> </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"> </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"> </span><a href="chap76.html#X79B373A77B29D1F5">76.2-1 LoadPackage</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap76.html#X858E8985840BFA72">76.2-2 SetPackagePath</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap76.html#X7CD0A2F27D19BA03">76.2-3 ExtendRootDirectories</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap76.html#X7D162DDF813D2BBA">76.2-4 DisplayPackageLoadingLog</a></span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </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"> </span><a href="chap76.html#X870954577B27DCAB">76.3-1 ReadPackage</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap76.html#X8580DF257E4D7046">76.3-2 TestPackageAvailability</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap76.html#X7B79FEE57DBDBD71">76.3-3 InstalledPackageVersion</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap76.html#X807D835C7B032D4E">76.3-4 DirectoriesPackageLibrary</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap76.html#X794508E5811D3BC9">76.3-5 DirectoriesPackagePrograms</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap76.html#X787DFEB383545A49">76.3-6 CompareVersionNumbers</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap76.html#X8067348B836BAF37">76.3-7 IsPackageMarkedForLoading</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap76.html#X8495E5327D563AC3">76.3-8 DeclareAutoreadableVariables</a></span>
<span class="ContSS"><br /><span class="nocss"> </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"> </span><a href="chap76.html#X7C99782886B18C77">76.3-10 LoadDynamicModule</a></span>
<span class="ContSS"><br /><span class="nocss"> </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"> </span><a href="chap76.html#X79767C2482FF6F55">76.3-12 ValidatePackageInfo</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap76.html#X7D34AC3287611B15">76.3-13 ShowPackageVariables</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap76.html#X79EA4BD37940AD25">76.3-14 BibEntry</a></span>
<span class="ContSS"><br /><span class="nocss"> </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">‣ 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">‣ 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">‣ 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">‣ 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">‣ 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">‣ 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">‣ 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">‣ 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">‣ 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">‣ 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">‣ 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">‣ 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">‣ 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">‣ 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">‣ 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></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></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">‣ 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></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">‣ 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">‣ 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">‣ 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">‣ 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></span> <span class="GAPinput">LoadDynamicModule("./test.so");</span>
<span class="GAPprompt">gap></span> <span class="GAPinput">CrcFile("test.so");</span>
2906458206
<span class="GAPprompt">gap></span> <span class="GAPinput">LoadDynamicModule("./test.so",1);</span>
Error, <crc> mismatch (or no support for dynamic loading) called from
<function>( <arguments> ) 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></span> <span class="GAPinput">quit;</span>
<span class="GAPprompt">gap></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">‣ 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">‣ 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">‣ 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">‣ 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></span> <span class="GAPinput">bib:= BibEntry( "GAP", "GAP4.5" );;</span>
<span class="GAPprompt">gap></span> <span class="GAPinput">Print( bib, "\n" );</span>
<entry id="GAP4.5"><misc>
<title><C>GAP</C> &ndash; <C>G</C>roups, <C>A</C>lgorithms,
and <C>P</C>rogramming, <C>V</C>ersion 4.5.1</title>
<howpublished><URL>http://www.gap-system.org</URL></howpublished>
<key>GAP</key>
<keywords>groups; *; gap; manual</keywords>
<other type="organization">The GAP <C>G</C>roup</other>
</misc></entry>
<span class="GAPprompt">gap></span> <span class="GAPinput">parse:= ParseBibXMLextString( bib );;</span>
<span class="GAPprompt">gap></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">‣ 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"> <a href="chap0.html">[Top of Book]</a> <a href="chap0.html#contents">[Contents]</a> <a href="chap75.html">[Previous Chapter]</a> <a href="chap77.html">[Next Chapter]</a> </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>
|