txt: ## dist_zef-iynehz-Inline-Scheme-Gambit.md
  [![Actions Status](https://github.com/iynehz/perl6-Inline-Scheme-Gambit/actions/workflows/ci.yml/badge.svg)](https://github.com/iynehz/perl6-Inline-Scheme-Gambit/actions)
  
  # Inline::Scheme::Gambit
  
  This is a Raku module which allows execution of Gambit Scheme code from
  Raku code with inspiration from other Inline:: modules like
  Inline::Python, Inline::Lua, Inline::Scheme::Guile, etc.
  
  ## Synopsis
  
  ```
  use Inline::Scheme::Gambit;
  
  my $gambit = Inline::Scheme::Gambit.new;
  
  my $code = q:to/END/;
      (define (fib n)
       (if (< n 2) n (+ (fib (- n 1)) (fib (- n 2)))))
  END
  
  $gambit.run($code);
  say $gambit.call('fib', 8);
  
  say $gambit.call('map',
                   $gambit.run(q{(lambda (n) (fib n))}),
                   [0 .. 8]);
  
  ```
  
  ## Status
  
  Testing has only been done under Rakudo MoarVM on x86-64 Linux. It requires
  Gambit-C 4, and Gambit-C 4.8.3 and 4.2.8 have been tested by the author.
  
  Values can be passed to and returned from Gambit-C. Simple types
  like boolean, integer, number, string, list, table, vector should
  work. Present mapping between Gambit-C and Raku types is as
  following table.
  
  ```
  Gambit-C            from Perl                       to Perl
  boolean             Bool                            Bool
  integer(exact)      Int                             Int
  rational(exact)     Rat                             Rat
  rational(inexact)   Num                             Num
  complex             Complex                         Complex
  string              Stringy                         Str
  list                Positional                      Array            
  table               Associative                     Hash            
  vector                                              Array
  procedure                                           OpaquePointer
  other objects       OpaquePointer                   OpaquePointer
  
  ```
  
  Note that at present both scheme list and vector converts to Array
  in Raku, but through the call() method (see below) Raku Array only
  converts to list.
  
  The API is incomplete and experimental. It may change in future if
  necessary.
  
  ### To Do
  
  * Think about wrapping OpaquePointer for scheme-object, so that it can
    do better on scheme list/vector/procedure/etc.
  * Support scheme record type.
  * Improve error handling.
  
  ## Install
  
  ```
  zef install Inline::Scheme::Gambit
  
  ```
  
  It by default tries to use 'gsc-script' or 'gsc' as the gsc command,
  and dynamically link to libgambc.so. It supports several environment
  variables to override the default behavior.
  
  For example to override gsc in case 'gsc-script' or 'gsc' is not in
  PATH, or 'gsc-script' is an incorrect symlink.
  
  ```
  GSC=/usr/bin/gsc zef install Inline::Scheme::Gambit
  
  ```
  
  And if on your system gambit dll is not named libgambc.so, you can override
  it like below,
  
  ```
  LIBS="-l:libgambit.so.4" zef install Inline::Scheme::Gambit
  
  ```
  
  Or if you would like to static link to some libgambit.a
  
  ```
  LIBS=-lutil MYEXTLIB=/usr/lib/gambit-c/libgambit.a zef install Inline::Scheme::Gambit
  
  ```
  
  You can refer to Makefile.in and Build.pm to know more details.
  
  ## Usage
  
  ### Inline::Scheme::Gambit
  
  Object of Inline::Scheme::Gambit represents a global Gambit-C instance.
  
  #### method new()
  
  Returns the global Inline::Scheme::Gambit singleton. The first call to
  new() initializes the singleton.
  
  #### method run(Str:D $code)
  
  Runs $code and returns any resulting value.
  
  #### method call(Str:D $name, \*\*@args)
  
  Calls the named function with @args, and returns any resulting value.
  
  ## Contact
  
  <https://github.com/iynehz/perl6-Inline-Scheme-Gambit>
  