GAP supports a global options system. This is intended as a way for the user to provide guidance to various algorithms that might be used in a computation. Such guidance should not change mathematically the specification of the computation to be performed, although it may change the algorithm used. A typical example is the selection of a strategy for the Todd-Coxeter coset enumeration procedure. An example of something not suited to the options mechanism is the imposition of exponent laws in the p-Quotient algorithm.
The basis of this system is a global stack of records. All the entries of each record are thought of as options settings, and the effective setting of an option is given by the topmost record in which the relevant field is bound.
The reason for the choice of a stack is the intended pattern of use:
PushOptions( rec( stuff ) );
DoSomething( args );
PopOptions();
This can be abbreviated, to DoSomething( args : stuff ); with a small additional abbreviation of stuff permitted. See 4.12-2 for details. The full form can be used where the same options are to run across several calls, or where the DoSomething procedure is actually an infix operator, or other function with special syntax.
An alternative to this system is the use of additional optional arguments in procedure calls. This is not felt to be sufficient because many procedure calls might cause, for example, a coset enumeration and each would need to make provision for the possibility of extra arguments. In this system the options are pushed when the user-level procedure is called, and remain in effect (unless altered) for all procedures called by it.
Note that in some places in the system optional records containing options which are valid only for the immediate function or method call are in fact used.
‣ PushOptions( options_record ) | ( function ) |
This function pushes a record of options onto the global option stack. Note that PushOptions( rec( opt:= fail ) ) has the effect of resetting the option opt, since an option that has never been set has the value fail returned by ValueOption (8.1-5).
Note that there is no check for misspelt or undefined options.
‣ PopOptions( ) | ( function ) |
This function removes the top-most options record from the options stack if there is one.
‣ ResetOptionsStack( ) | ( function ) |
unbinds (i.e. removes) all the options records from the options stack.
Note: ResetOptionsStack should not be used within a function. Its intended use is to clean up the options stack in the event that the user has quit from a break loop, so leaving a stack of no-longer-needed options (see 6.4-1).
‣ OnQuit( ) | ( function ) |
called when a user selects to quit; a break loop entered via execution of Error (6.6-1). As GAP starts up, OnQuit is defined to do nothing, in case an error is encountered during GAP start-up. Later in the loading process we redefine OnQuit to do a variant of ResetOptionsStack (8.1-3) to ensure the options stack is empty after a user quits an Error (6.6-1)-induced break loop. (OnQuit differs from ResetOptionsStack (8.1-3) in that it warns when it does something rather than the other way round.) Currently, OnQuit is not advertised, since exception handling may make it obsolete.
‣ ValueOption( opt ) | ( function ) |
This function is a method for accessing the options stack without changing it; opt should be the name of an option, i.e. a string. A function which makes decisions that might be affected by options should examine the result of ValueOption. If opt is currently not set then fail is returned.
‣ DisplayOptionsStack( ) | ( function ) |
This function prints a human-readable display of the complete options stack.
‣ InfoOptions | ( info class ) |
This info class can be used to enable messages about options being changed (level 1) or accessed (level 2).
The example below shows simple manipulation of the Options Stack, first using PushOptions (8.1-1) and PopOptions (8.1-2) and then using the special function calling syntax.
gap> foo := function() > Print("myopt1 = ", ValueOption("myopt1"), > " myopt2 = ",ValueOption("myopt2"),"\n"); > end; function( ) ... end gap> foo(); myopt1 = fail myopt2 = fail gap> PushOptions(rec(myopt1 := 17)); gap> foo(); myopt1 = 17 myopt2 = fail gap> DisplayOptionsStack(); [ rec( myopt1 := 17 ) ] gap> PopOptions(); gap> foo(); myopt1 = fail myopt2 = fail gap> foo( : myopt1, myopt2 := [Z(3),"aardvark"]); myopt1 = true myopt2 = [ Z(3), "aardvark" ] gap> DisplayOptionsStack(); [ ] gap>
generated by GAPDoc2HTML