/usr/share/gap/doc/ref/chap83.html is in gap-doc 4r6p5-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 | <?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 83: Library Files</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="chap83" 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="chap82.html">[Previous Chapter]</a> <a href="chap84.html">[Next Chapter]</a> </div>
<p id="mathjaxlink" class="pcenter"><a href="chap83_mj.html">[MathJax on]</a></p>
<p><a id="X848C952A87FB36E2" name="X848C952A87FB36E2"></a></p>
<div class="ChapSects"><a href="chap83.html#X848C952A87FB36E2">83 <span class="Heading">Library Files</span></a>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap83.html#X7FF5DC397C79392C">83.1 <span class="Heading">File Types</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap83.html#X845CCBE082CDF4BB">83.2 <span class="Heading">Finding Implementations in the Library</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap83.html#X801428EB86E7113C">83.3 <span class="Heading">Undocumented Variables</span></a>
</span>
</div>
</div>
<h3>83 <span class="Heading">Library Files</span></h3>
<p>This chapter describes some of the conventions used in the <strong class="pkg">GAP</strong> library files. These conventions are intended as a help on how to read library files and how to find information in them. So everybody is recommended to follow these conventions, although they do not prescribe a compulsory programming style –<strong class="pkg">GAP</strong> itself will not bother with the formatting of files.</p>
<p>Filenames have traditionally <strong class="pkg">GAP</strong> adhered to the 8+3 convention (to make it possible to use the same filenames even on a MS-DOS file system) and been in lower case (systems that do not recognize lower case in file names will convert them automatically to upper case). It is no longer so important to adhere to these conventions, but at the very least filenames should adhere to a 16+5 convention, and be distinct even after identifying upper and lower case. Directory names of packages, however, <em>must</em> be in lower case (the <code class="func">LoadPackage</code> (<a href="chap76.html#X79B373A77B29D1F5"><span class="RefLink">76.2-1</span></a>) command assumes this).</p>
<p><a id="X7FF5DC397C79392C" name="X7FF5DC397C79392C"></a></p>
<h4>83.1 <span class="Heading">File Types</span></h4>
<p>The <strong class="pkg">GAP</strong> library consists of the following types of files, distinguished by their suffixes:</p>
<dl>
<dt><strong class="Mark"><code class="code">.g</code> </strong></dt>
<dd><p>Files which contain parts of the "inner workings" of <strong class="pkg">GAP</strong>. These files usually do not contain mathematical functionality, except for providing links to kernel functions.</p>
</dd>
<dt><strong class="Mark"><code class="code">.gd</code> </strong></dt>
<dd><p>Declaration files. These files contain declarations of all categories, attributes, operations, and global functions. These files also contain the operation definitions in comments.</p>
</dd>
<dt><strong class="Mark"><code class="code">.gi</code> </strong></dt>
<dd><p>Implementation files. These files contain all installations of methods and global functions. Usually declarations of representations are also considered to be part of the implementation and are therefore found in the <code class="code">.gi</code> files.</p>
</dd>
</dl>
<p>As a rule of thumb, all <code class="code">.gd</code> files are read in before the <code class="code">.gi</code> files are read. Therefore a <code class="code">.gi</code> file usually may use any operation or global function (it has been declared before), and no care has to be taken towards the order in which the <code class="code">.gi</code> files are read.</p>
<p><a id="X845CCBE082CDF4BB" name="X845CCBE082CDF4BB"></a></p>
<h4>83.2 <span class="Heading">Finding Implementations in the Library</span></h4>
<p>For a concretely given function, you can use <code class="func">FilenameFunc</code> (<a href="chap5.html#X80E108C57F90FAA3"><span class="RefLink">5.1-4</span></a>) and <code class="func">StartlineFunc</code> (<a href="chap5.html#X7FF7643781D2C194"><span class="RefLink">5.1-5</span></a>) for finding the file where this function is defined, and the line in this file where the definition of this function starts. This does not work for arbitrary functions, see Section <code class="func">FilenameFunc</code> (<a href="chap5.html#X80E108C57F90FAA3"><span class="RefLink">5.1-4</span></a>) for the restrictions.</p>
<p>If you are interested in getting the function which implements a method for specific arguments, you can use <a href="chap7.html#X80848FF486BD6F9F"><span class="RefLink">7.2-1</span></a>. If <code class="func">FilenameFunc</code> (<a href="chap5.html#X80E108C57F90FAA3"><span class="RefLink">5.1-4</span></a>) does not work for this method then setting the print level of <a href="chap7.html#X80848FF486BD6F9F"><span class="RefLink">7.2-1</span></a> higher will give you the installation string for this method, which can be used for searching in library files.</p>
<p>To find the occurrence of functions, methods, function names, and installation strings in the library, one can use the <code class="code">grep</code> tool under UNIX. To find a function, search for the function name in the <code class="code">.gd</code> files; as global variables are usually declared only once, only few files will show up. The function installation is likely to occur in the corresponding <code class="code">.gi</code> file.</p>
<p>To find a method from the known operation name and the installation string, search for the string "<code class="code">Method(</code>" (this catches both <code class="func">InstallMethod</code> (<a href="chap78.html#X837EFDAB7BEF290B"><span class="RefLink">78.2-1</span></a>) and <code class="func">InstallOtherMethod</code> (<a href="chap78.html#X7D2C12DB841CE539"><span class="RefLink">78.2-2</span></a>)) and the installation string or the operation name.</p>
<p>The following tools from the <strong class="pkg">GAP</strong> package <strong class="pkg">Browse</strong> can be used for accessing the code of functions.</p>
<ul>
<li><p><code class="func">BrowseGapMethods</code> (<span class="RefLink">???</span>) shows an overview of <strong class="pkg">GAP</strong>'s operations and methods, and allows one to navigate through the files that contain the implementations of the methods, using a pager.</p>
</li>
<li><p><code class="func">BrowseProfile</code> (<span class="RefLink">???</span>) shows profiling results (similar to <code class="func">DisplayProfile</code> (<a href="chap7.html#X80FEA6A08775A48E"><span class="RefLink">7.7-8</span></a>)) and allows one to navigate through the files that contain the implementations of the functions that were actually used, using a pager.</p>
</li>
</ul>
<p><a id="X801428EB86E7113C" name="X801428EB86E7113C"></a></p>
<h4>83.3 <span class="Heading">Undocumented Variables</span></h4>
<p>For several global variables in <strong class="pkg">GAP</strong>, no information is available via the help system (see Section <a href="../../doc/tut/chap2.html#X7A7EADB77FF38BC9"><span class="RefLink">Tutorial: Help</span></a>, for a quick overview of the help system, or Chapter <a href="chap2.html#X8755A2C67B197C63"><span class="RefLink">2</span></a>, for details). There are various reasons for "hiding" a variable from the user; namely, the variable may be regarded as of minor importance (for example, it may be a function called by documented <strong class="pkg">GAP</strong> functions that first compute many input parameters for the undocumented function), or it belongs to a part of <strong class="pkg">GAP</strong> that is still experimental in the sense that the meaning of the variable has not yet been fixed or even that it is not clear whether the variable will vanish in a more developed version.</p>
<p>As a consequence, it is dangerous to use undocumented variables because they are not guaranteed to exist or to behave the same in future versions of <strong class="pkg">GAP</strong>.</p>
<p>Conversely, for <em>documented</em> variables, the definitions in the <strong class="pkg">GAP</strong> manual can be relied on for future <strong class="pkg">GAP</strong> versions (unless they turn out to be erroneous); if the <strong class="pkg">GAP</strong> developers find that some piece of minor, but documented functionality is an insurmountable obstacle to important developments, they may make the smallest possible incompatible change to the functionality at the time of a major release. However, in any such case it will be announced clearly in the <strong class="pkg">GAP</strong> Forum what has been changed and why.</p>
<p>So on the one hand, the developers of <strong class="pkg">GAP</strong> want to keep the freedom of changing undocumented <strong class="pkg">GAP</strong> code. On the other hand, users may be interested in using undocumented variables.</p>
<p>In this case, whenever you write <strong class="pkg">GAP</strong> code involving undocumented variables, and want to make sure that this code will work in future versions of <strong class="pkg">GAP</strong>, you may ask at <span class="URL"><a href="mailto:support@gap-system.org">support@gap-system.org</a></span> for documentation about the variables in question. The <strong class="pkg">GAP</strong> developers then decide whether these variables shall be documented or not, and if yes, what the definitions shall be.</p>
<p>In the former case, the new documentation is added to the <strong class="pkg">GAP</strong> manual, this means that from then on, this definition is protected against changes.</p>
<p>In the latter case (which may occur for example if the variables in question are still experimental), you may add the current values of these variables to your private code if you want to be sure that nothing will be broken later due to changes in <strong class="pkg">GAP</strong>.</p>
<div class="chlinkprevnextbot"> <a href="chap0.html">[Top of Book]</a> <a href="chap0.html#contents">[Contents]</a> <a href="chap82.html">[Previous Chapter]</a> <a href="chap84.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>
|