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,10 +967,49 @@ 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"/>.
 
+
+<ManSection>
+<Func Name="DeclareGlobalName" Arg="name"/>
+
+<Description>
+For global variables, sometimes code needs to reference them before
+a value can sensibly be assigned to them. For example, consider the
+following definition of a recursive function:
+<Log><![CDATA[
+BindGlobal( "fun", function(n)
+  if n > 0 then
+    return 2*fun(n-1);
+  fi;
+  return 1;
+end );
+]]></Log>
+The problem with that code is that it triggers a syntax warning about
+access to an unbound global variable.
+
+To resolve this, starting with &GAP; 4.12 one can declare the variable with
+<Ref Func="DeclareGlobalName"/> before assigning it via <Ref Func="BindGlobal"/>.
+This informs &GAP; that a global variable with the specified name will
+eventually be defined, and that thus no syntax warnings pertaining to its use
+should be printed.
+
+We recommended to use <Ref Func="DeclareGlobalName"/>/<Ref
+Func="BindGlobal"/> instead of <Ref Func="DeclareGlobalVariable"/>/<Ref
+Func="InstallGlobalVariable"/> whenever possible.
+
+<Ref Func="DeclareGlobalName"/> shall be used in the declaration part
+of the respective package
+(see&nbsp;<Ref Sect="Declaration and Implementation Part"/>),
+values can then be assigned to the new variable as usual, preferably via
+<Ref Func="BindGlobal"/>,
+in the implementation part
+(again, see&nbsp;<Ref Sect="Declaration and Implementation Part"/>).
+</Description>
+</ManSection>
+
 <#Include Label="DeclareGlobalVariable">
 <#Include Label="InstallValue">
 <#Include Label="FlushCaches">
@@ -1006,6 +1045,8 @@ Calls to the following functions belong to the declaration part.
 <Item><Ref Func="DeclareFilter"/>,</Item>
 <Item><Ref Func="DeclareOperation"/>,</Item>
 <Item><Ref Func="DeclareGlobalFunction"/>,</Item>
+<Item><Ref Func="DeclareGlobalName"/>,</Item>
+<Item><Ref Func="DeclareGlobalVariable"/>,</Item>
 <Item><Ref Func="DeclareSynonym"/>,</Item>
 <Item><Ref Func="DeclareSynonymAttr"/>,</Item>
 <Item><Ref Func="DeclareProperty"/>,</Item>
@@ -1015,6 +1056,7 @@ Calls to the following functions belong to the implementation part.
 <List>
 <Item><Ref Func="DeclareRepresentation"/>,</Item>
 <Item><Ref Func="InstallGlobalFunction"/>,</Item>
+<Item><Ref Func="InstallGlobalVariable"/>,</Item>
 <Item><Ref Func="InstallMethod"/>,</Item>
 <Item><Ref Func="InstallImmediateMethod"/>,</Item>
 <Item><Ref Func="InstallOtherMethod"/>,</Item>

doc/ref/gappkg.xml

@@ -752,14 +752,14 @@ and <Ref Func="InstallValue"/> pair. There are also operations
 and their methods,  and  related  objects like attributes and filters which 
 also have <C>Declare...</C> and <C>Install...</C> pairs.
 <P/>
-<E>Secondly</E>,  it's  a  good  idea  to  reduce  the  chance  of  accidental
+<E>Secondly</E>,  it is a  good  idea  to  reduce  the  chance  of  accidental
 overwriting by choosing names for your functions and variables that begin
 with a string that identifies it  with  the  package,  e.g.&nbsp;some  of  the
 undocumented functions in the <Package>Example</Package> package begin with <C>Eg</C>. This is
 especially important in cases where you actually want the user to be able
 to change the value of a function or variable defined  by  your  package,
 for which you have used direct assignments  (for  which  the  user  will
-receive no warning  if  she  accidentally  overwrites  them).  It's  also
+receive no warning  if  she  accidentally  overwrites  them).  It is  also
 important  for  functions  and  variables   defined   via   <C>BindGlobal</C>,
 <C>DeclareGlobalFunction</C>/<C>InstallGlobalFunction</C>                       and
 <C>DeclareGlobalVariable</C>/<C>InstallValue</C>, in order to  avoid  name  clashes
@@ -1446,7 +1446,7 @@ package onto the public server, please ensure that a new archive has
 a new version number. This should be done even for very minor changes.
 <P/>
 For most of the packages it will be inappropriate to re-use the date 
-of the release as a version number. It's much more obvious how big are
+of the release as a version number. It is much more obvious how big are
 the changes between versions "4.4.12", "4.5.1" and "4.5.2" than between 
 versions "2008.12.17", "2011.04.15" and "2011.09.14". The concept of
 using version numbers to convey the meaning of the status of the code

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

@@ -5674,4 +5674,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");