[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.10.3 Perl Bindings

CS has extensive bindings for Perl version 5.

Getting Started

To make use of CS classes from a Perl script, first make sure that the file cspace.pm (found in your CS/scripts/perl5 directory) is available to Perl. The easiest way to do this is with this code near the top of your script:
 
BEGIN { push @INC, "$ENV{CRYSTAL}/scripts/perl5" }

Also make sure that the cspace.so (Unix/Linux/MacOSX) or cspace.dll (Windows) file is in the same directory as the cspace.pm file.

Then add this line near the top of the script:
 
use cspace;

Functions and Classes

CS has several global functions, which can be accessed easily from Perl. For instance, in C++, one might do:
 
const char *str = "Hello, world!";
int key = csHashCompute (str);
Perl is almost exactly the same, the most notable difference being the cspace:: prefix:
 
$str = "Hello, world!";
$key = cspace::csHashCompute ($str);

To create an object instance, we use the new "keyword":
 
$vect = new cspace::csVector3 (1, 2, 3);
The object will be deleted automatically when it goes out of scope. Perl also has built-in reference counting, so if the object is still referenced in some other Perl code when it goes out of scope, it will still exist until there are no more references to it in Perl.

There are three ways to access object properties:
 
print $vect->x;		# Preferred way, conforms to Perl convention
print $vect->{"x"};	# Swig's generated primary way
print $vect->get_x();	# Swig's generated secondary way

And three ways to modify object properties:
 
$vect->x(123);		# Preferred way, conforms to Perl convention
$vect->{"x"} = 123;	# Swig's generated primary way
$vect->set_x(123);	# Swig's generated secondary way

Calling methods works as you might expect:
 
$vect->Norm();

Arrays

Wherever an array is expected, or wherever an array is returned, in or from a CS C++ call, a Perl array reference is used.

Operator Overloading

Operator overloading is not yet supported. All the code required to support it has been written, but the code requires some non-existant features of Swig.

The operators that exist in C++ and which Perl can overload are: + - * / % << >> & | ^ && || ! ~ < <= == >= > != ++ -- = += -= *= /= %= <<= >>= &= |= ^=

And: ** **= (expontentiation), lt le eq ge gt ne (string comparison), <> (iteration), x x= (repeat), . .= (concatenate), $ @ % * & (convert to Perl native types: scalar, array, hash, glob, subroutine), abs (absolute value), truth evaluation, stringify and numerify.

Interface Pointers

Supposing you call a function that returns a pointer to some interface. You can store the returned value in a variable, and use it similarly to how objects are used in Perl (see above). You can call their methods in the same way, and pass them on to further functions as parameters where appropriate.

The Perl bindings automatically correctly handle csRef and csPtr.

Implementing Interfaces

You can write your own Perl class and have it inherit from a CS interface, then use instances of that class wherever an implementation of that interface is expected. Currently the interfaces that support this feature are iEventHandler iEventPlug iAwsSink but it is easy to add more.

 
package MyPerlEventHandler;
@ISA = qw{ cspace::iEventHandler };
sub new
{
  $x = {};
  bless ($x, "MyPerlEventHandler");
  return $x;
}
sub HandleEvent
{
  ($self, $event) = @_;
  # your event handler here...
}

package main;
$eventq = cspace::CS_QUERY_REGISTRY ($object_reg, "iEventQueue");
$handler = new MyPerlEventHandler;
$eventq->RegisterListener ($handler);

Special Cases

Macros that take Interfaces as Parameters

In Perl, CS macros that take interface names as parameters, for instance CS_QUERY_REGISTRY(), take those interface names as strings:

 
$engine = cspace::CS_QUERY_REGISTRY($object_reg, "iEngine");

csRGBpixel

To convert a csRGBpixel to a csRGBcolor, use the asRGBcolor method:

 
$color = $pixel->asRGBcolor();

iSprite2DState

iSprite2DState has an extra method in Perl, GetVertexByIndex, which takes a single integer parameter, an array index, and returns a csSprite2DVertex from the sprite's array of vertices.

iEvent

The overloaded Add and Find methods in iEvent are replaced in Perl with ones with names which explicitly specify the types of their parameters (since otherwise Perl wouldn't know which C++ function to call):


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

This document was generated using texi2html