Goto Chapter: Top 1 2 Bib Ind
 [Top of Book]  [Contents]   [Previous Chapter]   [Next Chapter] 

2 Interface for Declarations and Method Installations
 2.1 Declaration and Installation Functions

2 Interface for Declarations and Method Installations

The utilities in this Chapter provide an access to GAPs object type - operations - method system which is a bit different from the conventions used in the GAP library. We summarize the main differences.

Families.

It is compulsory in GAP to put each object into a family. For example this must be specified with the creation of a type of an object, see FamilyObj (???), NewFamily (???), NewType (???). But for many objects its familiy seems essentially irrelevant in practice. Here, we define a DefaultFamily (2.1-1) and interface functions like MakeType (2.1-2) which implicitly include this default family if GAP needs one.

Declaration of operations.

In the GAP library operations are declared with prescribing numbers of arguments and giving constraints on the type of objects for which methods are allowed to install (several declarations of the same operation are possible), see DeclareOperation (???). Calls of InstallMethod (???) for not declared types of object lead to an error.

This is a debugging feature for the method installation. It is irrelevant for the actual method selection and can in fact be circumvented by using InstallOtherMethod (???). Using the functions MakeOperation (2.1-3) and NewMethod (2.1-5) one can ignore this debugging feature.

Documentation of methods.

With the installation of a method, see InstallMethod (???), one can specify a comment string describing for which types of objects a method is applicable. The actual applicability is specified by a filter for each argument - note that some non-simple filters may not be printed in a nice form (try for example NamesFilter(IsMatrix)). This together leads for example to difficult to understand information with ApplicableMethod (???).

Our function NewMethod (2.1-5) takes strings describing the types of the allowed arguments of a method. These strings are also used for (precise) comments.

Several installations of a method.

Sometimes a method can be used for several types of arguments or one should install a method several times to get the rankings with respect to several other methods right. This can be done with one call of NewMethod (2.1-5) via or-conjunctions in the strings describing the argument types.

Compound declarations.

We provide functions that allow to declare several operations, variables, attributes, ..., in one call.

2.1 Declaration and Installation Functions

2.1-1 DefaultFamily
‣ DefaultFamily( family )

This is a family used for all new types of objects created with MakeType (2.1-2). For many applications you don't need to know about this at all.

2.1-2 MakeType
‣ MakeType( filt[, data] )( function )

Returns: an object type.

This creates an object type for which the filters given by filt are set (including their implied filters). Optionally, a type can also carry an additional arbitrary data object.

This essentially calls NewType (???) using DefaultFamily (2.1-1) as family.

2.1-3 MakeOperation
‣ MakeOperation( nam1[, nam2, ...] )( function )
‣ MakeAttribute( nam1[, nam2, ...] )( function )
‣ MakeGlobalVariable( nam1[, nam2, ...] )( function )
‣ MakeGlobalFunction( nam1[, nam2, ...] )( function )

All arguments must be strings. For each argument nam1, nam2, ..., these functions declare one operation, attribute, global variable or global function, respectively, with the given name. In case of operations and attributes, these are declared without constraints on the number or type of arguments of corresponding methods.

Note that the variables with names nam1, ..., are make read-only by the declaration. This is very useful to avoid accidental overwriting by a user, or for detecting compatibility problems with the GAP library or packages.

2.1-4 MakeProperty
‣ MakeProperty( nam, impl[, rk] )( function )

The argument nam must be a string, impl must be a filter, and rk a non-negative integer. This function does several things:

Compare with DeclareProperty (???).

2.1-5 NewMethod
‣ NewMethod( oper, filt, fun[, rk] )( function )

This function is an interface to the more elaborate function InstallOtherMethod (???) in the GAP library.

The argument oper must be an operation, filt must be a string or list of strings, fun a function, and the optional argument rk a non-negative integer. Giving a string as filt is equivalent to giving a list with this string as single entry.

The strings given in filt are split at substrings "or" which are surrounded by whitespace. The remaining substrings each must evaluate (with EvalString (???)) to a filter. The function fun is then installed as method for the operation oper for all combinations of filters resulting from the splitting and evaluation of the strings in filt.

The argument rk is used as offset for the rank of the method(s). Its default value, if not given, is 0. One should try to avoid using this optional argument whenever possible. Instead multiple installations of the same method may be more sensible.

 [Top of Book]  [Contents]   [Previous Chapter]   [Next Chapter] 
Goto Chapter: Top 1 2 Bib Ind

generated by GAPDoc2HTML