Guile is an interpreter for the Scheme programming language. "Scheme is a statically scoped and properly tail-recursive dialect of the Lisp programming language invented by Guy Lewis Steele Jr. and Gerald Jay Sussman." You can find this quote in the language definition for Scheme here:

This module is being developed in order to support the development and usage of an Inline::Guile module. The intention is to allow Perl programmers to intermix Perl and Guile code in their programs and modules.

This module provides an interface to almost every function available in libguile. This encompasses almost the entire gh_ and scm_ sets. In general, any function that takes one or more SCM arguements and returns an SCM or void will be available. Many other functions are also available - see the FUNCTION LIST section below for a complete list.

Functions are called without their scm_, gh_ prefixes in the Guile namespace. For example, to call the C function gh_cons, you write:

my $cons = Guile::cons($car, $cdr);

In the cases where both a gh_ and an scm_ funtion exist the gh_ function is used.

No attempt will be made to document all the Guile functions - for that you must refer to the Guile documentation. Try "info guile" to get started.

The above calls determine the type of the SCM automatically. This works well for constants but not so well for variables. For example, the code below doesn't create an integer SCM with the value 100:

my $number = 10;
$number .= "0";
my $scm = new Guile::SCM $number;

That's because Perl transformed the $number into a string scalar in order to concatenate "0" to it. Thus, new() created an SCM with the string value "100". The difference doesn't matter to Perl but a Guile function you call might not be expecting a string instead of a number. To solve this problem, you need to create the SCM with an explicit type:

my $scm = new Guile::SCM integer => $number;

Another reason to use an explicit type is to create types that have no obvious corollary in Perl, like a pair. Normally Guile assumes that array-refs should be translated into lists. To create a pair you need to specify the "pair" type and a reference to a two-element array:

my $scm = new Guile::SCM pair => ["foo", 20];

The following types are available for use with new():

integer
real
string
symbol
list
pair

For each of these types Guile has a predicate function for identifying them. In Guile these functions end in a "?". In the Perl interface they have a "_p" ending instead. These functions return a boolean indicating if their argument is of the specified type:

In the above example $three contains an SCM with the integer value 3. The addition is performed inside Guile - no conversion to Perl datatypes is requied. This doesn't matter much in general practice but it allows greater flexibility in handling Guile data that Perl would have a difficult time representing like large integers and floating point numbers.

Schemers in the audience will recognize the above as an associative list. Eventually I'd like to support hash accessors for such structures. See the TODO section for all manner of crazy schemes like this.

The Guile::SCM object also provides an overloaded procedure call interface. This can be used to call procedures and closures in Guile. For example, if you lookup a procedure by name, you can then call the procedure:

It may seem like a lot of work to create an SCM. It is, but it's very rarely necessary. For example, the below does just what you'd expect it to:

my $cell = Guile::cons(1, 2);

Creates a cons cell (aka pair) out of the values 1 and 2. These values are auto-translated into SCMs using the single argument form of Guile::SCM::new() above. This is the same thing, writen out:

my $cell = Guile::cons(Guile::SCM::new(1), Guile::SCM::new(2));

Any Guile function that expects an SCM for an argument will accept Perl variables and attempt to auto-convert them to SCMs. Not all Perl types can be auto-converted at this time - see the docs above for Guile::SCM::new() for the current list.

This module is in an early alpha state. Many important things still don't work. Here's an incomplete list of TODO items:

ports

I'd like to be able to pass ports and filehandles back and forth between Guile and Perl. It seems do-able but requires a rather elaborate tie system.

hashes

This should be pretty easy but probably isn't a high priority. Guile doesn't encourage a lot of hash usage.

associative lists

Schemers don't use a lot of hashes but they do use associative lists. Currently these are supported with the same tools Schemers always use. I'd also like to give them a hash interface to make things easier on Perl programmers. This is another complicated tie project.

vectors and arrays

Their fixed dimensions don't make for an obvious mapping into Perl. Perhaps a PDL mapping? Or a specialized tied object?

big numbers, big floats, big problems

Guile supports a much more robust numeric system than Perl. Possible integration of Math::BigInt and Math::BigFloat? This probably requires a more mathy mind than mine.

objects (?)

Two uninhibited object systems meet and... explode?

callbacks into Perl

This seems easy enough but the API needs to be carefully designed. A good implementation could lead to a Inline::CPR type thing for Guile that would give Guile programmers access to Perl. Egads!

I'd like this interface to allow passing of closures back and forth between Guile and Perl. It already works from Guile => Perl.

continuations

I have no idea what needs to be done or what might be possible here. I serriously doubt Perl will ever support continuations in a meaningful way. Does that mean they can't work with Guile.pm? I'm not sure.

Sometimes Guile will dump core if you give it arguments it wasn't expecting. For example, if you do

Guile::cdr(1);

You should expect a core dump. I don't know if I'm in the right position to fix this since it seems to me more like a problem inside Guile itself.

If you find yourself getting core dumps, try using Guile::write() to examine the data you're passing to Guile functions. You might also consider coding defensively using the predicate functions (*_p) to verify the type of the data you're working with.

This project is just starting and the more people that get involved the better. For the time being we can use the Inline mailing-list to get organized. Send a blank message to inline-subscribe@perl.org to join the list.

If you just want to report a bug (just one?) or tell how sick the whole idea makes you then you can email me directly at sam@tregar.com.

This module is free software; you can redistribute it and/or modify it under the terms of either:

a) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or

b) the "Artistic License" which comes with this module.

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. See either the GNU General Public License or the Artistic License for more details.

You should have received a copy of the Artistic License with this module, in the file ARTISTIC. If not, I'll be glad to provide one.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA