|
#############################################################################
##
## This file is part of GAP, a system for computational discrete algebra.
## This file's authors include Steve Linton.
##
## Copyright of GAP belongs to its developers, whose names are too numerous
## to list here. Please refer to the COPYRIGHT file for details.
##
## SPDX-License-Identifier: GPL-2.0-or-later
##
## <#GAPDoc Label="[1]{options}">
## &GAP; supports a <E>global options system</E>. 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
## <M>p</M>-Quotient algorithm.
## <P/>
## 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.
## <P/>
## The reason for the choice of a stack is the intended pattern of use:
## <P/>
## <C>PushOptions( rec( <A>stuff</A> ) );</C>
## <P/>
## <C>DoSomething( <A>args</A> );</C>
## <P/>
## <C>PopOptions();</C>
## <P/>
## This can be abbreviated,
## to <C>DoSomething( <A>args</A> : <A>stuff</A> );</C> with
## a small additional abbreviation of <A>stuff</A> permitted. See
## <Ref Subsect="Function Call With Options"/> for details. The full form
## can be used where the same options are to run across several
## calls, or where the <C>DoSomething</C> procedure is actually an infix
## operator, or other function with special syntax.
## <P/>
## 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.
## <P/>
## 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.
## <#/GAPDoc>
##
#############################################################################
##
#F PushOptions( <options_record> ) set new options
##
## <#GAPDoc Label="PushOptions">
## <ManSection>
## <Func Name="PushOptions" Arg='options_record'/>
##
## <Description>
## This function pushes a record of options onto the global option stack.
## Note that <C>PushOptions( rec( <A>opt</A>:= fail ) )</C> has the effect
## of resetting the option <A>opt</A>, since an option that has never been
## set has the value <K>fail</K> returned by <Ref Func="ValueOption"/>.
## <P/>
## Note that there is no check for misspelt or undefined options.
## </Description>
## </ManSection>
## <#/GAPDoc>
##
DeclareGlobalFunction( "PushOptions");
#############################################################################
##
#F PopOptions( ) remove options
##
## <#GAPDoc Label="PopOptions">
## <ManSection>
## <Func Name="PopOptions" Arg=''/>
##
## <Description>
## This function removes the top-most options record from the options stack
## if there is one.
## </Description>
## </ManSection>
## <#/GAPDoc>
##
DeclareGlobalFunction( "PopOptions");
#############################################################################
##
#F ResetOptionsStack( ) remove all options
##
## <#GAPDoc Label="ResetOptionsStack">
## <ManSection>
## <Func Name="ResetOptionsStack" Arg=''/>
##
## <Description>
## unbinds (i.e. removes) all the options records from the options stack.
## <P/>
## <E>Note:</E>
## <Ref Func="ResetOptionsStack"/> should <E>not</E> be used within a
## function.
## Its intended use is to clean up the options stack in the event
## that the user has <K>quit</K> from a <K>break</K> loop,
## so leaving a stack of no-longer-needed options
## (see <Ref Subsect="quit"/>).
## </Description>
## </ManSection>
## <#/GAPDoc>
##
DeclareGlobalFunction( "ResetOptionsStack");
#############################################################################
##
#F OnQuit( ) currently removes all options
##
## <#GAPDoc Label="OnQuit">
## <ManSection>
## <Func Name="OnQuit" Arg=''/>
##
## <Description>
## called when a user selects to <C>quit;</C> a break loop entered via
## execution of <Ref Func="Error"/>.
## As &GAP; starts up, <Ref Func="OnQuit"/> is defined to do nothing,
## in case an error is encountered during &GAP; start-up.
## Later in the loading process we redefine <Ref Func="OnQuit"/> to do a variant of
## <Ref Func="ResetOptionsStack"/> to ensure the options stack is empty
## after a user quits an <Ref Func="Error"/>-induced break loop.
## (<Ref Func="OnQuit"/> differs from <Ref Func="ResetOptionsStack"/>
## in that it warns when it does something rather than the other way round.)
## Currently, <Ref Func="OnQuit"/> is not advertised,
## since exception handling may make it obsolete.
## </Description>
## </ManSection>
## <#/GAPDoc>
##
#Unbind(OnQuit); # We don't do this because it would leave
#DeclareGlobalFunction( "OnQuit" ); # us vulnerable to an Error happening
# before OnQuit's definition is installed
#############################################################################
##
#F ValueOption( <opt> )
##
## <#GAPDoc Label="ValueOption">
## <ManSection>
## <Func Name="ValueOption" Arg='opt'/>
##
## <Description>
## This function is a method for accessing the options stack without
## changing it;
## <A>opt</A> 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 <Ref Func="ValueOption"/>.
## If <A>opt</A> is currently not set then <K>fail</K> is returned.
## </Description>
## </ManSection>
## <#/GAPDoc>
##
DeclareGlobalFunction( "ValueOption");
#############################################################################
##
#F DisplayOptionsStack( ) display the options stack
##
## <#GAPDoc Label="DisplayOptionsStack">
## <ManSection>
## <Func Name="DisplayOptionsStack" Arg=''/>
##
## <Description>
## This function prints a human-readable display of the complete
## options stack.
## <P/>
## </Description>
## </ManSection>
## <#/GAPDoc>
##
DeclareGlobalFunction( "DisplayOptionsStack");
#############################################################################
##
#V InfoOptions info class for options
##
## <#GAPDoc Label="InfoOptions">
## <ManSection>
## <InfoClass Name="InfoOptions"/>
##
## <Description>
## This info class can be used to enable messages about options being
## changed (level 1) or accessed (level 2).
## </Description>
## </ManSection>
## <#/GAPDoc>
##
DeclareInfoClass("InfoOptions");
[ Dauer der Verarbeitung: 0.7 Sekunden
(vorverarbeitet)
]
|
