Welcome To Our Shell

Mister Spy & Souheyl Bypass Shell

  
  8 Options Stack
  
  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.11-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.
  
  
  8.1 Functions Dealing with the Options Stack
  
  8.1-1 PushOptions
  
  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.
  
  8.1-2 PopOptions
  
  PopOptions(  )  function
  
  This  function removes the top-most options record from the options stack if
  there is one.
  
  8.1-3 ResetOptionsStack
  
  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).
  
  8.1-4 OnQuit
  
  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.
  
  8.1-5 ValueOption
  
  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.
  
  8.1-6 DisplayOptionsStack
  
  DisplayOptionsStack(  )  function
  
  This function prints a human-readable display of the complete options stack.
  
  8.1-7 InfoOptions
  
  InfoOptions info class
  
  This  info  class can be used to enable messages about options being changed
  (level 1) or accessed (level 2).
  
  
  8.2 Options Stack – an Example
  
  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.
  
    Example  
    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>