Math::GAP - GAP interpreter controller for Perl

NAME
SYNOPSIS
ABSTRACT
DESCRIPTION

GAP
WHAT CAN DO THIS MODULE

METHODS
DEFAULT CONFIGURATION
DEPENDENCIES
BUGS AND LIMITATIONS
SEE ALSO
AUTHOR
COPYRIGHT AND LICENCE

NAME

SYNOPSIS

  use Math::GAP;
  my $gap_term = new Math::GAP;
  $gap_term->load("guava");
  $gap_term->code("F:=PolynomialRing(GF(8));;Display(F);");
  print $gap_term->get();

ABSTRACT

GAP stands for Groups, Algorithms, Programming. It is a "System for Computational Discrete Algebra" see http://www.gap-system.org/. This module defines (inside-out) objects that wrap a GAP interpreter. This allows to execute GAP code in Perl, precisely, inside the interpreter and to read the output produced by the code. One of the interest is to allow scripting with GAP, which is not a feature of the standard GAP interpreter.

DESCRIPTION

GAP

GAP (Groups, Algorithms, Programming) is a computational algebra software (under GNU GPL) available from http://www.gap-system.org/. It comes as an interpreted language and an interpreter. The interpreter does not support scripting.

WHAT CAN DO THIS MODULE

This module allows to create Perl objects that execute GAP code. When an object is created, a GAP interpreter is launched as a new process. The object can send GAP code to the interpreter and, separately, collect its output. A default GAP interpreter is set during the installation, but this can be changed at run-time.

METHODS

Controlling the GAP interpreter executable: set_GAP() and get_GAP()

You can set change the default path set during installation

        Math::GAP->set_GAP('/my/path/to/gap');

You can even use command line option

        Math::GAP->set_GAP('/my/path/to/gap', '-b -o 515');

or equivalently

        Math::GAP->set_GAP('/my/path/to/gap', '-b','-o 515');

The first argument, that is the path to GAP, is loosely checked to be an exec file, but nothing serious. Say, it is just here to catch typo. In case the test fails, you get an exception 'Non executable GAP Interpreter'.

To get the current setting use Math::GAP->get_GAP(). Beware, its return values is context sensitive:

in list context, return an array: the first element is the command to start gap, the remaining is a list of options (each element is a string that may contain several command line options).

        my ($path,@options)=Math::GAP->get_GAP();

in scalar context, only the first element, that is the command to start GAP, is returned.

        my $just_the_path=Math::GAP->get_GAP();

Constructing an object: new()

The constructor is simply named new

        my $term=Math::GAP->new()

It starts a new GAP interpreter and returns a blessed reference. Each object has his own interpreter. The interpreter is started using the return value of get_GAP() method.

Sending GAP code to the interpreter: code()

To execute GAP code there is the code() method

        $obj->code($string,$option_hash_ref);

$string must be valid GAP code (no verification is done before sending the string to GAP). The hash can contain a key 'discard'; in that case, the output of the GAP interpreter, for $string only, will be discarded

        $obj->code('Display(3);',{discard=>1});
        print obj->get();                      #print nothing

Collecting the output: get()

Use

        $obj->get()

to collect the result of previous commands sent to the interpreter. Try to clean the output (removing promp 'gap>' ...). A call to get() collect all the previous commands, except for discarded ones.

        $obj->code('2+2;');
        $obj->code('3+3;',{discard=>1});
        $obj->code('4+4;');
        print obj->get();                       #print 4\n8\n

Loading a file/package in the GAP interpreter: load()

It is possible to load a file or package in the GAP interpreter using

        $obj->load($file_or_package_name,$option_hash_ref);

The $file_or_package_name argument is first tested to be a readable file (-r). If not try to load as a package. $option_hash_ref is used only for key 'discard' and in case of a file.

This is just a simple wrapping for Read and LoadPackage GAP functions.

Destructing an object

This is done automatically when the object goes out of scope. The GAP interpreter is stopped at that time.

INTERNALS

The new method use start_GAP() to create the filehandles and to start the interpreter. Internal use only.

DEFAULT CONFIGURATION

The default executable is located during the installation, you can check its value with Math::GAP->get_GAP(): it is the first element of the array in list context, or the return value in scalar context.

The default options to start the GAP is simply the '-b' flag (suppress the banner at start up). So, just after loading the Math::GAP module a call to Math::GAP->get_GAP() in list context return an array of size 2, first element the command, second element a string '-b'.

DEPENDENCIES

This module requires these other modules and libraries:

from Perl core modules :

 Carp,
 ExtUtils::MakeMaker,
 File::Find,
 File::Spec,
 IO::Handle,
 List::Util,
 Scalar::Util,
 Socket,
 Test::More.

a GAP interpreter.

It must be installed on your system. If it is installed prior to this module installation, the installation try and set the default path of the interpreter. Otherwise, you will have to set it using a class method.

BUGS AND LIMITATIONS

There are no known bugs in this module. Please report problems to Fabien Galand (galand@cpan.org)

AUTHOR

Fabien Galand (galand@cpan.org)

COPYRIGHT AND LICENCE

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See the perlartistic manpage.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.