#############################################################################
##
#W  utils.xml
#Y  Copyright (C) 2011-14                                James D. Mitchell
##
##  Licensing information can be found in the README file of this package.
##
#############################################################################
##

<#GAPDoc Label="SemigroupsDir">
  <ManSection>
    <Func Name="SemigroupsDir" Arg=""/>
    <Returns>A string.</Returns>    
    <Description>
      This function returns the absolute path to the &Semigroups; package
      directory as a string. The same result can be obtained typing:

      <Log>PackageInfo("semigroups")[1]!.InstallationPath;</Log>

      at the &GAP; prompt. 
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="SemigroupsMakeDoc">
  <ManSection>
    <Func Name="SemigroupsMakeDoc" Arg=""/>
    <Returns>Nothing.</Returns>    
    <Description>
      This function should be called with no argument to compile the 
      &Semigroups; documentation. 
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="SemigroupsOptionsRec">
  <ManSection>    
     <Var Name="SemigroupsOptionsRec"/>    
     <Description>
       This global variable is a record whose components contain the default
       values of certain options for transformation semigroups created after
       &Semigroups; has been loaded. A description of these options is given
       above in Section <Ref Sect="opts"/>. <P/>

       The value of <C>SemigroupsOptionsRec</C> is defined in the file
       <C>semigroups/gap/options.g</C> as: 
       <Log>rec( acting := true, hashlen := rec( L := 25013, M := 6257, S :=
         251 ), regular := false, small := false )</Log>
     </Description> 
   </ManSection>
<#/GAPDoc>

<#GAPDoc Label="SemigroupsTestAll">
  <ManSection>
    <Func Name="SemigroupsTestAll" Arg=""/>
    <Returns>Nothing.</Returns> 
    <Description>
      This function should be called with no argument to comprehensively
      test that &Semigroups; is working correctly. These tests
      should take no more than a few minutes to complete. 
      To quickly test that &Semigroups; is installed correctly
      use <Ref Func="SemigroupsTestInstall"/>. 
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="SemigroupsTestManualExamples">
  <ManSection>
    <Func Name="SemigroupsTestManualExamples" Arg=""/>
    <Returns>Nothing.</Returns> 
    <Description>
      This function should be called with no argument to test the examples in
      the &Semigroups; manual. These tests should take no more than a few
      minutes to complete.  To more comprehensively test that &Semigroups; is
      installed correctly use <Ref Func="SemigroupsTestAll"/>. See also <Ref
      Func="SemigroupsTestInstall"/>.
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="SemigroupsTestInstall">
  <ManSection>
    <Func Name="SemigroupsTestInstall" Arg=""/>
    <Returns>Nothing.</Returns> 
    <Description>
      This function should be called with no argument to test your installation
      of &Semigroups; is working correctly. These tests should take no more
      than a fraction of a second to complete.  To more comprehensively test
      that &Semigroups; is installed correctly use 
      <Ref Func="SemigroupsTestAll"/>. 
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="InfoSemigroups">
  <ManSection>
    <InfoClass Name="InfoSemigroups"/>
    <Description>
    <C>InfoSemigroups</C> is the info class of the &Semigroups; package. 
    The info level is initially set to 0 and no info messages are displayed. 
    We recommend that you set the level to 1 so that basic info messages
    are displayed. To increase the amount of information displayed during a
    computation increase the info level to 2 or 3. To stop all info messages
    from being displayed, set the info level to 0.  See also
    <Ref Subsect="Info Functions" BookName="ref"/> and 
    <Ref Func="SetInfoLevel" BookName="ref"/>. 
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="ReadGenerators">
  <ManSection> 
    <Func Name="ReadGenerators" Arg="filename[, nr]"/>
    <Returns>A list of lists of semigroup elements.</Returns>
    <Description>
      If <A>filename</A> is the name of a file created using 
      <Ref Func="WriteGenerators"/>, then <C>ReadGenerators</C> returns the
      contents of this file as a list of lists of transformations, partial
      permutations, or bipartitions. <P/>
      
      If the optional second argument <A>nr</A> is present, then
      <C>ReadGenerators</C> returns the elements stored in the <A>nr</A>th line
      of <A>filename</A>.

      <Example>
gap> file:=Concatenation(SemigroupsDir(), "/tst/test.gz");;
gap> ReadGenerators(file, 1378);
[ Transformation( [ 1, 2, 2 ] ), IdentityTransformation, 
  Transformation( [ 1, 2, 3, 4, 5, 7, 7 ] ), 
  Transformation( [ 1, 3, 2, 4, 7, 6, 7 ] ), 
  Transformation( [ 4, 2, 1, 1, 6, 5 ] ), 
  Transformation( [ 4, 3, 2, 1, 6, 7, 7 ] ), 
  Transformation( [ 4, 4, 5, 7, 6, 1, 1 ] ), 
  Transformation( [ 7, 6, 6, 1, 2, 4, 4 ] ), 
  Transformation( [ 7, 7, 5, 4, 3, 1, 1 ] ) ]</Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="IteratorFromGeneratorsFile">
  <ManSection> 
    <Func Name="IteratorFromGeneratorsFile" Arg="filename"/>
    <Returns>An iterator.</Returns>
    <Description>
      If <A>filename</A> is a string containing the name of a file created using 
      <Ref Func="WriteGenerators"/>, then <C>IteratorFromGeneratorsFile</C>
      returns an iterator <C>iter</C> such that <C>NextIterator(iter)</C>
      returns the next collection of generators stored in the file <A>filename</A>. 
      <P/>

      This function is a convenient way of, for example, looping over a
      collection of generators in a file without loading every object in the
      file into memory. This might be useful if the file contains more
      information than there is available memory. 
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="WriteGenerators">
  <ManSection> 
    <Func Name="WriteGenerators" Arg="filename, list[, append]"/>
    <Returns><K>true</K> or <K>fail</K>.</Returns>
    <Description>
      This function provides a method for writing transformations, partial
      permutations, and bipartitions to a file, that uses a relatively small
      amount of disk space.  The resulting file can be further compressed using
      <C>gzip</C> or <C>xz</C>.<P/>
      
      The argument <A>list</A> should be a list of elements, a semigroup, or a
      list of lists of elements, or semigroups. The types of elements and
      semigroups supported are: transformations, partial permutations, and
      bipartitions. <P/>
     
      The argument <A>filename</A> should be a string containing the name of a
      file where the entries in <A>list</A> will be written or an
      <Package>IO</Package> package file object.<P/>

      If  the  optional  third argument <A>append</A> is given and
      equals  <C>"w"</C>,  then the previous content of the file is deleted. 
      If the optional third argument is <C>"a"</C> or is not present, then
      <C>list</C> is appended to the file.  This function returns <K>true</K>
      if everything went well or <K>fail</K> if something went wrong.<P/> 

      <C>WriteGenerators</C> appends a line to the file <A>filename</A>
      for every entry in <A>list</A>. If any element of <A>list</A> is a
      semigroup, then the generators of that semigroup are written to
      <A>filename</A>. <P/>
      
      The first character of the appended line indicates which type of element
      is contained in that line, the second character <C>m</C> is the number of
      characters in the degree of the elements to be written, the next <C>m</C>
      characters are the degree <C>n</C> of the elements to be written, and the
      internal representation of the elements themselves are written in blocks
      of <C>m*n</C> in the remainder of the line. For example, the
      transformations: 
      <Log>
[ Transformation( [ 2, 6, 7, 2, 6, 9, 9, 1, 1, 5 ] ), 
  Transformation( [ 3, 8, 1, 9, 9, 4, 10, 5, 10, 6 ] )]</Log>
      are written as:
      <Log>
t210 2 2 6 7 2 6 9 9 1 1 5 3 8 1 9 9 410 510 6</Log>
     
      The file <A>filename</A> can be read using <Ref Func="ReadGenerators"/>.
    </Description>
  </ManSection>
<#/GAPDoc>



#EOF
