Goto Chapter: Top 1 2 3 4 5 6 7 8 9 10 11 Ind
 [Top of Book]  [Contents]   [Previous Chapter]   [Next Chapter] 

7 Add Functions
 7.1 Functions Installed by Add
 7.2 Add Method
 7.3 InstallAdd Function
 7.4 Install All Adds
 7.5 Prepare functions

7 Add Functions

This section describes the overall structure of Add-functions and the functions installed by them.

7.1 Functions Installed by Add

Add functions (up to some exceptions) have the following syntax

DeclareOperation( "AddSomeFunc", [ IsCapCategory, IsList, IsInt ] );

The first argument is the category to which some function (e.g. KernelObject) is added, the second is a list containing pairs of functions and additional filters for the arguments, (e.g. if one argument is a morphism, an additional filter could be IsMomomorphism). The third is a weight which will then be the weight for SomeFunc. This is described later. If only one function is to be installed, the list can be replaced by the function. Via InstallMethod, CAP installs the given function(s) as methods for the install name of SomeFunc, as listed in the MethodRecord. If no install name is given, the name SomeFunc is used.

All installed methods follow the following steps, described below:

Every other part, except from function, does only depend on the name SomeFunc. We now explain the steps in detail.

7.2 Add Method

Except from installing a new method for the name SomeFunc, an Add method does slightly more. Every Add method has the same structure. The steps in the Add method are as follows:

After calling an add method, the corresponding Operation is available in the category. Also, some derivations, which are triggered by the setting of the primitive value, might be available.

7.3 InstallAdd Function

Almost all Add methods in the CAP kernel are installed by the CapInternalInstallAdd operation. The definition of this function is as follows:

DeclareOperation( "CapInternalInstallAdd", [ IsRecord ] );

The record can have the following components, used as described:

Using all those entries, the operation CapInternalInstallAdd installs add methods as described above. It first provides a sanity check for all the entries described, then installs the Add method in 4 ways, with list or functions as second argument, and with an optional third parameter for the weight.

7.4 Install All Adds

The function CAP_INTERNAL_INSTALL_ALL_ADDS does not take any arguments, it is an auxiliary function which iterates over the CAP_INTERNAL_METHOD_NAME_RECORD and calls, after some cosmetics, the CapInternalInstallAdd with the corresponding method record entry. The steps below are performed for every entry of the method record:

Please note that we are now in the case where the operation belongs to a universal construction, (e.g. KernelLift) and is not a WithGiven type of operation.

After one call of this function, all add methods are installed correctly. A second call should not do anything.

7.5 Prepare functions

7.5-1 CAPOperationPrepareFunction
‣ CAPOperationPrepareFunction( prepare_function, category, func )( function )

Returns: a function

Given a non-CAP-conform function for any of the categorical operations, i.e., a function that computes the direct sum of two objects instead of a list of objects, this function wraps the function with a wrapper function to fit in the CAP context. For the mentioned binary direct sum one can call this function with "BinaryDirectSumToDirectSum" as prepare_function, the category, and the binary direct sum function. The function then returns a function that can be used for the direct sum categorical operation.

Note that func is not handled by the CAP caching mechanism and that the use of prepare functions is incompatible with WithGiven operations. Thus, one has to ensure manually that the equality and typing specifications are fulfilled.

7.5-2 CAPAddPrepareFunction
‣ CAPAddPrepareFunction( prepare_function, name, doc_string[, precondition_list] )( function )

Adds a prepare function to the list of CAP's prepare functions. The first argument is the prepare function itself. It should always be a function that takes a category and a function and returns a function. The argument name is the name of the prepare function, which is used in CAPOperationPrepareFunction. The argument doc_string should be a short string describing the functions. The optional argument precondition_list can describe preconditions for the prepare function to work, i.e., if the category does need to have PreCompose computable. This information is also recovered automatically from the prepare function itself, so the precondition_list is only necessary if the function needed is not explicitly used in the prepare function, e.g., if you use + instead of AdditionForMorphisms.

7.5-3 ListCAPPrepareFunctions
‣ ListCAPPrepareFunctions( arg )( function )

Lists all prepare functions.

 [Top of Book]  [Contents]   [Previous Chapter]   [Next Chapter] 
Goto Chapter: Top 1 2 3 4 5 6 7 8 9 10 11 Ind

generated by GAPDoc2HTML