view release on metacpan or  search on metacpan

Guile.pm  view on Meta::CPAN

C<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.

=head1 CONVENIENCE FUNCTIONS

I've added a few convenience functions that I thought would help make
using Guile from Perl easier.

=head2 call($proc_name, @args)

This is equivalent to C<apply(lookup($proc_name), \@args)>.  It allows
you to pass the name of the procedure to call instead of a Guile
procedure object (although that will work too).

=head1 GUILE DATA

Guile has a single datatype called an SCM.  You can create an SCM by
calling the new() method in the Guile::SCM package:

   my $scm = new Guile::SCM;

This creats an SCM with the "undefined" value (aka SCM_UNDEFINED).  To
create an SCM with a more useful value you call new with an argument:

   # to create a string SCM:
   my $scm = new Guile::SCM "foo";

   # an integer
   my $scm = new Guile::SCM 100_000;

   # a floating-point number
   my $scm = new Guile::SCM 10.5e5;

   # a list of integers
   my $scm = new Guile::SCM [ 10, 20, 30, 40 ]

   # a list of mixed types
   my $scm = new Guile::SCM [ 10, "foo", 30, 40.5 ]

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:

  # prints 1
  my $scm = new Guile::SCM integer => 10;
  print "1\n" if Guile::integer_p($scm);

=head1 OVERLOAD MAGIC

The Guile::SCM class provides an overload interface for most
overloaded operations.  

=head2 Math

Mathematic operations on Guile::SCM objects are handled with Guile's
procedures:

   my $one = new Guile::SCM 1;
   my $two = new Guile::SCM 2;
   my $three = $one + $two;

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.

=head2 Array Accessors

You can treat Guile lists and pairs as arrays from Perl:

  my $list = new Guile::SCM [ 'foo', 'bar', 1, 2 ];
  print "Guile, say foo: ", $list->[0], "\n";

Will print:

  Guile, say foo: foo

This works for list structures of any complexity:

  my $alist = Guile::SCM->new([ Guile::SCM->new(pair => [ foo => 1 ]),
                                Guile::SCM->new(pair => [ bar => 2 ]) ]);
  print "Foo: ", $alist->[0][1], "\n",