Perl module for Ruby Version 0.2.9 Yoshida Masato = Introduction This is a module to call Perl functions from Ruby programs. Because Ruby and Perl are linked together, it might cause some kind of conflicts. = Installation This module is available on ruby-1.4.6. I recommend you to use it with ruby-1.6.4 or later. Of course Perl is a must. This module works well with Perl 5.005_03. It may work with the Perl configured with '-Dusethreads', but I cannot tell what happens with threads active. Perl and Ruby must use the same malloc, otherwise it may be very unstable. Be sure that Perl and Ruby share same malloc, otherwise this module might be very unstable. Perl's malloc library is not recommended. You should configure Perl with: ./Configure -dse -D d_dosuid -Uusemymalloc Then compile this module with: ruby extconf.rb make make site-install It tested with Linux2.0.36+libc5ˇ¤Solaris2.5.1/SPARCˇ¤ Solaris2.6/SPARCˇ¤Solaris7/Intel. If it is unstable caused by conflicts of libraries, static link with Ruby may be a clue. When Perl is compiled into a shared library, some OS may not load libperl.so. In this case, you must specify the shared library with: ruby extconf.rb --with-libperl=/usr/lib/libperl.so To call Ruby functions from Perl programs, install the Ruby module for Perl. This module works only with Perl programs embedded in Ruby. The install might fail without availability of dynamic linking. cd Ruby perl Makefile.PL make make install = Usage If you do not link this module statically with Ruby, preset: require "perl" Create a Perl object and call Perl code with 'eval' or 'call' method. perl = Perl.new("-e", "0") perl.eval("$a = 100") ret = perl.get_sv("a") == Data Type Conversion from Perl to Ruby Some methods such as Perl#eval, Perl#call, Perl#get_sv, PerlObject#send, PerlObject#call, PerlObject#[] and PerlObject#value convert Perl's scalar return values into Ruby values. Ruby can treat Perl's object values in the reference form. Perl's type Ruby's type -------------------------- undef nil IV (integer) Integer NV (real) Float PV (string) String RV (reference) PerlObject You can receive the last evaluated scalar value in Perl. If the last is not scalar, Ruby would fail to receive it. For example: ary = perl.eval('(1, 2, 3)') -> an integer 3 ary = perl.eval('[1, 2, 3]') -> a reference to an array as PerlObject object == Data Type Conversion from Ruby to Perl Parameters of Perl#call, PerlObject#send, PerlObject#call and PerlObject#[]= are converted into Perl values from Ruby values. Ruby's type Perl type ----------------------------------------- nil undef Fixnum IV (integer) Float NV (real) String PV (string) Array RV to AV (reference to an array) Hash RV to HV (reference to a hash) PerlObject RV (reference) other (conversion to string) Both the elements of an array and a hash obey this rule and are converted recursively. Perl's hash keys must be in string, so mapping Ruby's hash cannot be in perfect. For example: Ruby's hash {1=>'a', '1'=>'b'} will be converted into Perl hash {'1'=>'a'} or {'1'=>'b'}. Note: * Hash-like parameters of Perl is a simple list in fact. You can replace these parameters with a list in Ruby. * A word or strings (in Perl) must be quoted. Perl: func1(A=>1, B=>2); Ruby: perl.call('func1', 'A', 1, 'B', 2) * A reference to a hash can be converted from a Ruby's hash. Perl: func1({A=>1, B=>2}); Ruby: perl.call('func1', {'A'=>1, 'B'=>2}) = API Reference == Perl class A Perl object is a Perl interpreter. To create multiple instances raises a PerlError exception. To call Object#send method, you must use a 'send_' (or '__send__') method. === Singleton methods new(...) Creates a Perl object. Parameters are used as a Perl's command line. To omit parameters is equal to ("-e", "0"). A runtime error of Perl raises a PerlError exception. For example: perl_obj = Perl.new("-MIO::Handle", "-e", "0"); === Methods eval(str) Ealuates str as Perl expressions. It returns the last evaluated scalar value. The expressions are evaluated under scalar context. To evaluate under list context, you must enclose the expression with '[]'. When str contains Ruby's meta characters, you should quote str with '' or %q//. Since this method create its own scope, 'my' variables in the expression are available in the expression. A runtime error of Perl raises a PerlError exception. For example: input = perl_obj.eval("join('', @{[<>]})") perl_obj.eval(%q! print "Hello\n" !) call(func, ...) Executes a Perl function. The rest parameters are converted into Perl value and used as the function's arguments. It returns the function's return value. A runtime error of Perl raises a PerlError exception. For example: perl_obj.eval("sub test { $_[0] + $_[1] }") ret = perl_obj.call("test", 1, 2) send(class, method, ...) Calls a Perl method of a class. The rest parameters are converted into Perl value and used as the method's arguments. It returns the methods's return value. A Missing class or method terminates the program without any exceptions. A runtime error of Perl raises a PerlError exception. For exapmle: obj = perl_obj.send("IO::Handle", "new") get_sv(name) Gets a value of a scalar variable. A prefex '$' must be removed. For example: perl_obj.eval("$var = 123") var = perl_obj.get_sv("var") == PerlObject class A PerlObject is a wrapper object of a Perl's reference type. It is valid while a Perl object lives. To call Object#send method, you must use a 'send_' (or '__send__') method. === Methods Except the following method or the derived methods from Object, any mathod calls of this object are delegated to the wrapped Perl object. The same name method of Perl can be called with 'send' method. send(methodName, ...) Calls a method of a blessed object. The rest parameters are converted into Perl value and used as the method's arguments. It returns the methods's return value. A non-blessed object or a missing method terminates the program without any exceptions. A runtime error of Perl raises a PerlError exception. For example: obj = perl.send('Class', 'new') ## the followings have the same meanings. obj.send('method', 1) obj.method(1) call(...) Evaluates an anonymous subroutine object. The rest parameters are converted into Perl value and used as the method's arguments. It returns the methods's return value. A non-subroutine object or a runtime error of Perl raises a PerlError exception. value Resolves a reference and get the value. It cannot get the value that is not a scalar. When the value is a subroutine object, use 'call', and when it is an array or a hash, use [], to_a, to_hash. A non-reference object raises a TypeError exception. to_s Converts the value into a string. to_i Converts the value into an integer. to_f Converts the value into a real number. to_a Converts the value into an array if the value is an array. Each array elemant is not converted recursively. If the value is not an array, it returns an array of one element. to_hash Converts the value into a hash if the value is a hash. Each hash element is not converted recursively. A non-hash value raises a TypeError exception. [] Gets a value of an array or hash element. The array index must be an integer and the hash index must be a string. Non-array or non-hash value raises a TypeError exception. []= Sets a value of an array or a hash element. The array index must be an integer and the hash index must be a string. The value is converted into Perl's type. Non-array or non-hash value raises a TypeError exception. == Ruby for Perl module This is the Perl extension module to call Ruby functions back from Perl programs. This module is available only in Perl programs in Ruby. It is difficult to manage lifetimes of Ruby objects, objects in Ruby is set not to be held in Perl. To use this module, eval 'use Ruby' in a Perl program or create a Perl object with '-MRuby' option. For example: perl = Perl("-MRuby", "-e", "0") def hello(n) print "Hello, #{n}\n" end perl.eval(%q! Ruby::call("hello", "world"); !) === Functions Ruby::eval(str) Ealuates str as Ruby expressions. It returns the last evaluated expression. A runtime error raises a exception and give controls back to the outer Ruby program. Return values are converted as the following. Ruby's type Perl's type ----------------------------------------- nil undef Fixnum IV (integer) Bignum string Float NV (real) String PV (string) Array RV to AV (reference to an array) Hash RV to HV (reference to a hash) other string of an object identifier (OID). Ruby::call(func, ...) Executes a Ruby function. The rest parameters are converted into Ruby value and used as the function's arguments. It returns the function's return value. A runtime error raises a exception and give controls back to the outer Ruby program. Parameters are converted into: Perl's type Ruby's type -------------------------- undef nil IV (integer) Integer NV (real) Float PV (string) String other (conversion to) String Ruby::send(oid, method, ...) Calls a Ruby method of the object with oid. The rest parameters are converted into Ruby value and used as the method's arguments. It returns the method's return value. The oid might be invalid in general (by GC), so this function doesn't always work correctly. A runtime error raises an exception and give controls back to the outer Ruby program. Ruby::call function is identical with the following code. sub call { my $func = shift; my $obj = Ruby::eval("Object"); Ruby::send($obj, $func, @_); } = Copying This extension module is copyrighted free software by Yoshida Masato. You can redistribute it and/or modify it under the same term as Ruby or Perl. = Author Yoshida Masato = History Nov 14, 2001 version 0.2.9 fixed for Perl 5.6.x with -Dusethreads Jun 11, 2001 version 0.2.8 fixed Makefile.PL for ruby 1.6.4 (thanks to Akinori -Aki- MUSHA) Apr 30, 2001 version 0.2.7b refined English document (thanks to SugHimsi == SUGIHARA Hiroshi) Apr 27, 2001 version 0.2.7a English document Nov 18, 1998 version 0.1 initial release