[GAP Forum] function search feature

[Frank Lübeck]

On Thu, Feb 23, 2012 at 08:11:20PM +0000, Alexander Konovalov wrote:
> I've noticed that this question was not answered yet in the Forum:
> 
> On 9 Jan 2012, at 09:59, kroeker wrote:
> 
> > Hello,
> > 
> > sometimes I am looking for a function which is applicable to a specific object
> > without knowing the name of the function. To find the desired function
> > I have to read a lot of documentation, look for examples, ask an experienced GAP programmer (or the GAP-Forum) and so on.
> > 
> > Would it be possible to implement a search through all existing functions
> > where one of the parameters is an object of a specified type?
> 
> So, the short answer is 'No' - GAP function may take any argument(s), one does not
> specify to which arguments it applies when the function is created. GAP also
> has a notion of 'operation' which is a bunch of functions, called 'methods' 
> - these are installed with particular requirements on their arguments. Here 
> you may call ApplicableMethod (see ?ApplicableMethod) to get the function 
> which will be applied to arguments in a call to a specified operation - but
> this is not what you want, since you need to know the name of the operation
> in advance. For example,

Dear Jakob, dear Forum,

Sorry, I must have overlooked the original post. 

This reminds me that I have once written a utility function 
   AllOperations(obj)
which returns a list of 6 lists of names of operations such that
the operations from the i-th list have a method that allows obj as
argument number i. 

I think (a variant of) this is used for a completion function in the 
Sage interface to GAP. The function is appended below.

As Alexander pointed out, something like that is only possible for
operations (whose methods are installed with requirements on the arguments)
and not for general functions in GAP.

With best regards,
  Frank

-- 
///  Dr. Frank Lübeck, Lehrstuhl D für Mathematik, Templergraben 64,  ///
\\\                    52062 Aachen, Germany                          \\\
///  E-mail: Frank.Luebeck at Math.RWTH-Aachen.De                        ///
\\\  WWW:    http://www.math.rwth-aachen.de/~Frank.Luebeck/           \\\

#############   file AllOps.g ##############################################
##  AllOperations                                           Frank Lübeck
##  
##  The function AllOperations(obj) returns a list l of 6 entries.
##  Here l[i] is a list of names of documented operations which have
##  an installed method that accepts obj as i-th argument.
##  
##  Use the result with care. This is a purely technical check if the object
##  obj fulfills the requirements given in method installations. This does
##  not mean that there is a sensible example for each of the given
##  operations with obj being one of the arguments. For example, there
##  exist (fallback) methods for some operations installed with requirement 
##  'IsObject' for some argument(s), these appear in the result of 
##  AllOperations for every GAP object obj. This effect would be even much
##  worse if we considered all operations, not just the documented ones.
##  
if not IsBound(AllOperations) then
  AllOperations := function(obj)
    local flags, res, oper, methods, o, l, i, j, b;
    flags := TypeObj(obj)![2];
    res := List([1..6], i->[]);
    for o in [1..Length(OPERATIONS)/2] do
      oper := OPERATIONS[2*o-1];
      for l in [1..6] do
        methods := METHODS_OPERATION(oper, l);
        for i in [1..Length(methods)/(l+4)] do
          for j in [1..l] do
            if IS_SUBSET_FLAGS(flags, methods[(l+4)*(i-1)+1+j]) then
              if not oper in res[j] then 
                Add(res[j], oper);
              fi;
            fi;
          od;
        od;
      od;
    od;
    res := List(res, c-> List(c, NameFunction));
    # cache doc entries
    if not IsBound(GAPInfo.cachedDocEntries) then
      IsDocumentedWord("Size");
      GAPInfo.cachedDocEntries := [];
      for b in RecFields(HELP_BOOKS_INFO) do
        Append(GAPInfo.cachedDocEntries, List(HELP_BOOKS_INFO.(b).entries,
               e-> StripEscapeSequences(e[1])));
      od;
      GAPInfo.cachedDocEntries := Immutable(Set(GAPInfo.cachedDocEntries));
      IsSSortedList(GAPInfo.cachedDocEntries);
    fi;
    # throw out the Setter's and non-documented ones 
    res := List(res, a-> Filtered(a, s-> PositionSublist(s, "Setter(") <> 1
                         and s in GAPInfo.cachedDocEntries));
    for o in res do
      Sort(o);
    od;
    return res;
  end;
fi;