Add DeclareGlobalName

With DeclareGlobalName one can mark the name of a global
variable as "will be defined". The only effect this has is that
it suppresses "Unbound Global Variable" warnings.

This can be used in many cases to replace uses of `DeclareGlobalVariable` &
`InstallValue` respectively `DeclareGlobalFunction` & `InstallGlobalFunction`
by `DeclareGlobalName` & `BindGlobal`.

doc/ref/create.xml

@@ -967,7 +967,7 @@ following:
 <Heading>Global Variables in the Library</Heading>
 
 Global variables in the &GAP; library are usually read-only in order to
-avoid their being overwritten accidentally.
+prevent them from being overwritten accidentally.
 
 See also Section <Ref Sect="More About Global Variables"/>.
 

hpcgap/lib/helpbase.gi

@@ -497,7 +497,7 @@ end);
 # in second list: for each book a list 
 #                 [short name, long name, 
 #                  directory containing the manual.six file] 
-InstallValue(HELP_KNOWN_BOOKS, [[],[]]);
+BindGlobal("HELP_KNOWN_BOOKS", [[],[]]);
 if IsHPCGAP then
   LockAndMigrateObj(HELP_KNOWN_BOOKS,HELP_REGION);
 fi;
@@ -640,7 +640,7 @@ fi;
 ##  components  in  this help  book record  depend  on  the format  of the
 ##  documentation and the corresponding handler functions.
 ##  
-InstallValue(HELP_BOOKS_INFO, rec());
+BindGlobal("HELP_BOOKS_INFO", rec());
 if IsHPCGAP then
   LockAndMigrateObj(HELP_BOOKS_INFO,HELP_REGION);
 fi;
@@ -1204,7 +1204,7 @@ if IsHPCGAP then
 fi;
 # here we store the last shown topic, initialized with 0 (leading to
 # show "Tutorial: Help", see below)
-InstallValue(HELP_LAST, AtomicRecord( rec(MATCH := 0, BOOK := 0, 
+BindGlobal("HELP_LAST", AtomicRecord( rec(MATCH := 0, BOOK := 0, 
              NEXT_VIEWER := false, TOPICS := [])));
 NAMES_SYSTEM_GVARS:= "to be defined in init.g";
 

hpcgap/lib/integer.gi

@@ -14,7 +14,7 @@
 ##
 #V  Integers  . . . . . . . . . . . . . . . . . . . . .  ring of the integers
 ##
-InstallValue( Integers, Objectify( NewType(
+BindGlobal( "Integers", Objectify( NewType(
     CollectionsFamily( CyclotomicsFamily ),
     IsIntegers and IsAttributeStoringRep ),
     rec() ) );
@@ -35,7 +35,7 @@ SetIsWholeFamily( Integers, false );
 ##
 #V  NonnegativeIntegers . . . . . . . . . .  semiring of nonnegative integers
 ##
-InstallValue( NonnegativeIntegers, Objectify( NewType(
+BindGlobal( "NonnegativeIntegers", Objectify( NewType(
     CollectionsFamily( CyclotomicsFamily ),
     IsNonnegativeIntegers and IsAttributeStoringRep ),
     rec() ) );
@@ -53,7 +53,7 @@ SetIsWholeFamily( NonnegativeIntegers, false );
 ##
 #V  PositiveIntegers  . . . . . . . . . . . . . semiring of positive integers
 ##
-InstallValue( PositiveIntegers, Objectify( NewType(
+BindGlobal( "PositiveIntegers", Objectify( NewType(
     CollectionsFamily( CyclotomicsFamily ),
     IsPositiveIntegers and IsAttributeStoringRep ),
     rec() ) );
@@ -71,7 +71,7 @@ SetIsWholeFamily( PositiveIntegers, false );
 ##
 #V  GaussianIntegers  . . . . . . . . . . . . . . . ring of Gaussian integers
 ##
-InstallValue( GaussianIntegers, Objectify( NewType(
+BindGlobal( "GaussianIntegers", Objectify( NewType(
     CollectionsFamily(CyclotomicsFamily),
     IsGaussianIntegers and IsAttributeStoringRep ),
     rec() ) );
@@ -148,7 +148,7 @@ InstallMethod( Coefficients,
 ##
 #V  Primes  . . . . . . . . . . . . . . . . . . . . . .  list of small primes
 ##
-InstallValue( Primes,
+BindGlobal( "Primes",
   [   2,  3,  5,  7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61,
      67, 71, 73, 79, 83, 89, 97,101,103,107,109,113,127,131,137,139,149,151,
     157,163,167,173,179,181,191,193,197,199,211,223,227,229,233,239,241,251,

lib/ctbl.gd

@@ -3591,7 +3591,7 @@ DeclareAttribute( "DisplayOptions", IsNearlyCharacterTable );
 ##  </Description>
 ##  </ManSection>
 ##
-DeclareGlobalVariable( "CharacterTableDisplayDefaults" );
+DeclareGlobalName( "CharacterTableDisplayDefaults" );
 
 
 #############################################################################

lib/ctbl.gi

@@ -5218,7 +5218,7 @@ fi;
 ##
 #V  CharacterTableDisplayDefaults
 ##
-InstallValue( CharacterTableDisplayDefaults, rec(
+BindGlobal( "CharacterTableDisplayDefaults", rec(
       Global:= rec(
         centralizers    := true,
 

lib/ctblsolv.gd

@@ -27,7 +27,7 @@
 ##  </Description>
 ##  </ManSection>
 ##
-DeclareGlobalVariable( "BaumClausenInfoDebug" );
+DeclareGlobalName( "BaumClausenInfoDebug" );
 
 
 #############################################################################

lib/ctblsolv.gi

@@ -849,7 +849,7 @@ InstallMethod( Irr,
 ##
 #V  BaumClausenInfoDebug  . . . . . . . . . . . . . . testing BaumClausenInfo
 ##
-InstallValue( BaumClausenInfoDebug, rec(
+BindGlobal( "BaumClausenInfoDebug", rec(
     makemat:= function( record, e )
         local dim, mat, diag, gcd, i;
         dim:= Length( record.diag );

lib/ctblsymm.gd

@@ -180,8 +180,7 @@ DeclareGlobalFunction( "CharValueSymmetric" );
 ##  </Description>
 ##  </ManSection>
 ##
-DeclareGlobalVariable( "CharTableSymmetric",
-    "generic character table of symmetric groups" );
+DeclareGlobalName( "CharTableSymmetric" );
 
 
 #############################################################################
@@ -195,8 +194,7 @@ DeclareGlobalVariable( "CharTableSymmetric",
 ##  </Description>
 ##  </ManSection>
 ##
-DeclareGlobalVariable( "CharTableAlternating",
-    "generic character table of alternating groups" );
+DeclareGlobalName( "CharTableAlternating" );
 
 
 #############################################################################
@@ -224,8 +222,7 @@ DeclareGlobalFunction( "CharValueWeylB" );
 ##  </Description>
 ##  </ManSection>
 ##
-DeclareGlobalVariable( "CharTableWeylB",
-    "generic character table of Weyl groups of type B" );
+DeclareGlobalName( "CharTableWeylB" );
 
 
 #############################################################################
@@ -239,8 +236,7 @@ DeclareGlobalVariable( "CharTableWeylB",
 ##  </Description>
 ##  </ManSection>
 ##
-DeclareGlobalVariable( "CharTableWeylD",
-    "generic character table of Weyl groups of type D" );
+DeclareGlobalName( "CharTableWeylD" );
 
 
 #############################################################################
@@ -366,8 +362,7 @@ DeclareGlobalFunction( "CharacterTableWreathSymmetric" );
 ##  </Description>
 ##  </ManSection>
 ##
-DeclareGlobalVariable( "CharTableDoubleCoverSymmetric",
-    "gen. char. table of the standard Schur double cover of symm. groups" );
+DeclareGlobalName( "CharTableDoubleCoverSymmetric" );
 
 
 #############################################################################
@@ -381,5 +376,4 @@ DeclareGlobalVariable( "CharTableDoubleCoverSymmetric",
 ##  </Description>
 ##  </ManSection>
 ##
-DeclareGlobalVariable( "CharTableDoubleCoverAlternating",
-    "generic char. table of the Schur double cover of alternating groups" );
+DeclareGlobalName( "CharTableDoubleCoverAlternating" );

lib/ctblsymm.gi

@@ -382,7 +382,7 @@ end );
 ##  Note that this record is accessed in the `Irr' method for natural
 ##  symmetric groups.
 ##
-InstallValue( CharTableSymmetric, Immutable( rec(
+BindGlobal( "CharTableSymmetric", Immutable( rec(
     isGenericTable:=
         true,
     identifier:=
@@ -486,7 +486,7 @@ InstallValue( CharTableSymmetric, Immutable( rec(
 ##
 #V  CharTableAlternating  . .  generic character table of alternating groups.
 ##
-InstallValue( CharTableAlternating, Immutable( rec(
+BindGlobal( "CharTableAlternating", Immutable( rec(
     isGenericTable:=
         true,
     identifier:=
@@ -831,7 +831,7 @@ end );
 ##
 #V  CharTableWeylB  . . . . generic character table of Weyl groups of type B.
 ##
-InstallValue( CharTableWeylB, Immutable( rec(
+BindGlobal( "CharTableWeylB", Immutable( rec(
     isGenericTable:=
         true,
     identifier:=
@@ -886,7 +886,7 @@ InstallValue( CharTableWeylB, Immutable( rec(
 ##
 #V  CharTableWeylD  . . . . generic character table of Weyl groups of type D.
 ##
-InstallValue( CharTableWeylD, rec(
+BindGlobal( "CharTableWeylD", rec(
     isGenericTable:=
         true,
     identifier:=
@@ -1742,7 +1742,7 @@ BindGlobal( "OrderOfSchurLift", function( pi )
 ##
 #V  CharTableDoubleCoverSymmetric
 ##
-InstallValue( CharTableDoubleCoverSymmetric, MakeImmutable ( rec(
+BindGlobal( "CharTableDoubleCoverSymmetric", MakeImmutable ( rec(
     isGenericTable:=
         true,
     identifier:=
@@ -1879,7 +1879,7 @@ InstallValue( CharTableDoubleCoverSymmetric, MakeImmutable ( rec(
 ##
 #V  CharTableDoubleCoverAlternating
 ##
-InstallValue( CharTableDoubleCoverAlternating, MakeImmutable( rec(
+BindGlobal( "CharTableDoubleCoverAlternating", MakeImmutable( rec(
     isGenericTable:=
         true,
     identifier:=

lib/grpfp.gd

@@ -1353,4 +1353,4 @@ DeclareGlobalFunction("StringFactorizationWord");
 DeclareGlobalFunction("CanMapFiniteAbelianInvariants");
 
 # used in homomorphisms
-DeclareGlobalVariable("TRIVIAL_FP_GROUP");
+DeclareGlobalName("TRIVIAL_FP_GROUP");

lib/grpfp.gi

@@ -5670,4 +5670,4 @@ InstallMethod( IndependentGeneratorsOfAbelianGroup,
   [ IsFpGroup and IsAbelian ],
   IndependentGeneratorsOfMaximalAbelianQuotientOfFpGroup );
 
-InstallValue(TRIVIAL_FP_GROUP,FreeGroup(0,"TrivGp")/[]);
+BindGlobal("TRIVIAL_FP_GROUP",FreeGroup(0,"TrivGp")/[]);

lib/helpbase.gd

@@ -17,10 +17,10 @@ DeclareGlobalFunction("MATCH_BEGIN");
 DeclareGlobalFunction("MATCH_BEGIN_COUNT");
 DeclareGlobalFunction("FILLED_LINE");
 DeclareGlobalFunction("SIMPLE_STRING");
-DeclareGlobalVariable("HELP_KNOWN_BOOKS");
+DeclareGlobalName("HELP_KNOWN_BOOKS");
 DeclareGlobalFunction("HELP_ADD_BOOK");
 DeclareGlobalFunction("HELP_REMOVE_BOOK");
-DeclareGlobalVariable("HELP_BOOKS_INFO");
+DeclareGlobalName("HELP_BOOKS_INFO");
 DeclareGlobalFunction("HELP_BOOK_INFO");
 DeclareGlobalFunction("HELP_SHOW_BOOKS");
 DeclareGlobalFunction("HELP_SHOW_CHAPTERS");
@@ -35,6 +35,6 @@ DeclareGlobalFunction("HELP_GET_MATCHES");
 DeclareGlobalFunction("HELP_SHOW_MATCHES");
 DeclareGlobalFunction("HELP_SHOW_FROM_LAST_TOPICS");
 DeclareGlobalFunction("HELP_LAB_FILE");
-DeclareGlobalVariable("HELP_LAST");
+DeclareGlobalName("HELP_LAST");
 DeclareGlobalFunction("HELP");
 

lib/helpbase.gi

@@ -490,7 +490,7 @@ end);
 # in second list: for each book a list 
 #                 [short name, long name, 
 #                  directory containing the manual.six file] 
-InstallValue(HELP_KNOWN_BOOKS, [[],[]]);
+BindGlobal("HELP_KNOWN_BOOKS", [[],[]]);
 if IsHPCGAP then
   LockAndMigrateObj(HELP_KNOWN_BOOKS,HELP_REGION);
 fi;
@@ -629,7 +629,7 @@ fi;
 ##  components  in  this help  book record  depend  on  the format  of the
 ##  documentation and the corresponding handler functions.
 ##  
-InstallValue(HELP_BOOKS_INFO, rec());
+BindGlobal("HELP_BOOKS_INFO", rec());
 if IsHPCGAP then
   LockAndMigrateObj(HELP_BOOKS_INFO,HELP_REGION);
 fi;
@@ -1174,7 +1174,7 @@ if IsHPCGAP then
 fi;
 # here we store the last shown topic, initialized with 0 (leading to
 # show "Tutorial: Help", see below)
-InstallValue(HELP_LAST, rec(MATCH := 0, BOOK := 0, 
+BindGlobal("HELP_LAST", rec(MATCH := 0, BOOK := 0, 
              NEXT_VIEWER := false, TOPICS := []));
 NAMES_SYSTEM_GVARS:= "to be defined in init.g";
 

lib/helpdef.gd

@@ -18,10 +18,10 @@
 ##  
 
 DeclareGlobalFunction("GapLibToc2Gap");
-DeclareGlobalVariable("HELP_CHAPTER_BEGIN");
-DeclareGlobalVariable("HELP_SECTION_BEGIN");
-DeclareGlobalVariable("HELP_FAKECHAP_BEGIN");
-DeclareGlobalVariable("HELP_PRELCHAPTER_BEGIN");
+DeclareGlobalName("HELP_CHAPTER_BEGIN");
+DeclareGlobalName("HELP_SECTION_BEGIN");
+DeclareGlobalName("HELP_FAKECHAP_BEGIN");
+DeclareGlobalName("HELP_PRELCHAPTER_BEGIN");
 DeclareGlobalFunction("HELP_CHAPTER_INFO");
 DeclareGlobalFunction("HELP_PRINT_SECTION_URL");
 DeclareGlobalFunction("HELP_PRINT_SECTION_MAC_IC_URL");

lib/helpdef.gi

@@ -112,10 +112,10 @@ end);
 #F  HELP_CHAPTER_INFO( <book>, <chapter> )  . . . .  get info about a chapter
 ##
 ##  this is a helper function for `HELP_SHOW_SECTIONS'
-InstallValue(HELP_CHAPTER_BEGIN, Immutable("\\Chapter"));
-InstallValue(HELP_SECTION_BEGIN, Immutable("\\Section"));
-InstallValue(HELP_FAKECHAP_BEGIN, Immutable("%\\FakeChapter"));
-InstallValue(HELP_PRELCHAPTER_BEGIN, Immutable("\\PreliminaryChapter"));
+BindGlobal("HELP_CHAPTER_BEGIN", Immutable("\\Chapter"));
+BindGlobal("HELP_SECTION_BEGIN", Immutable("\\Section"));
+BindGlobal("HELP_FAKECHAP_BEGIN", Immutable("%\\FakeChapter"));
+BindGlobal("HELP_PRELCHAPTER_BEGIN", Immutable("\\PreliminaryChapter"));
 
 InstallGlobalFunction(HELP_CHAPTER_INFO, function( book, chapter )
     local   info,  filename,  stream,  poss,  secnum,  pos,  line;

lib/integer.gd

@@ -74,12 +74,11 @@ DeclareCategory( "IsNonnegativeIntegers", IsSemiringWithOneAndZero );
 ##  </ManSection>
 ##  <#/GAPDoc>
 ##
-DeclareGlobalVariable( "Integers", "ring of integers" );
+DeclareGlobalName( "Integers" );
 
-DeclareGlobalVariable( "PositiveIntegers", "semiring of positive integers" );
+DeclareGlobalName( "PositiveIntegers" );
 
-DeclareGlobalVariable( "NonnegativeIntegers",
-    "semiring of nonnegative integers" );
+DeclareGlobalName( "NonnegativeIntegers" );
 
 
 #############################################################################
@@ -117,7 +116,7 @@ DeclareCategory( "IsGaussianIntegers", IsEuclideanRing and IsFLMLOR
 ##  </ManSection>
 ##  <#/GAPDoc>
 ##
-DeclareGlobalVariable( "GaussianIntegers", "ring of Gaussian integers" );
+DeclareGlobalName( "GaussianIntegers");
 
 
 #############################################################################
@@ -144,7 +143,7 @@ DeclareGlobalVariable( "GaussianIntegers", "ring of Gaussian integers" );
 ##  </ManSection>
 ##  <#/GAPDoc>
 ##
-DeclareGlobalVariable( "Primes", "list of the 168 primes less than 1000" );
+DeclareGlobalName( "Primes" );
 
 
 #############################################################################

lib/integer.gi

@@ -14,7 +14,7 @@
 ##
 #V  Integers  . . . . . . . . . . . . . . . . . . . . .  ring of the integers
 ##
-InstallValue( Integers, Objectify( NewType(
+BindGlobal( "Integers", Objectify( NewType(
     CollectionsFamily( CyclotomicsFamily ),
     IsIntegers and IsAttributeStoringRep ),
     rec() ) );
@@ -35,7 +35,7 @@ SetIsWholeFamily( Integers, false );
 ##
 #V  NonnegativeIntegers . . . . . . . . . .  semiring of nonnegative integers
 ##
-InstallValue( NonnegativeIntegers, Objectify( NewType(
+BindGlobal( "NonnegativeIntegers", Objectify( NewType(
     CollectionsFamily( CyclotomicsFamily ),
     IsNonnegativeIntegers and IsAttributeStoringRep ),
     rec() ) );
@@ -53,7 +53,7 @@ SetIsWholeFamily( NonnegativeIntegers, false );
 ##
 #V  PositiveIntegers  . . . . . . . . . . . . . semiring of positive integers
 ##
-InstallValue( PositiveIntegers, Objectify( NewType(
+BindGlobal( "PositiveIntegers", Objectify( NewType(
     CollectionsFamily( CyclotomicsFamily ),
     IsPositiveIntegers and IsAttributeStoringRep ),
     rec() ) );
@@ -71,7 +71,7 @@ SetIsWholeFamily( PositiveIntegers, false );
 ##
 #V  GaussianIntegers  . . . . . . . . . . . . . . . ring of Gaussian integers
 ##
-InstallValue( GaussianIntegers, Objectify( NewType(
+BindGlobal( "GaussianIntegers", Objectify( NewType(
     CollectionsFamily(CyclotomicsFamily),
     IsGaussianIntegers and IsAttributeStoringRep ),
     rec() ) );
@@ -148,7 +148,7 @@ InstallMethod( Coefficients,
 ##
 #V  Primes  . . . . . . . . . . . . . . . . . . . . . .  list of small primes
 ##
-InstallValue( Primes,
+BindGlobal( "Primes",
   [   2,  3,  5,  7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61,
      67, 71, 73, 79, 83, 89, 97,101,103,107,109,113,127,131,137,139,149,151,
     157,163,167,173,179,181,191,193,197,199,211,223,227,229,233,239,241,251,