/ 
Inline-SLang-0.05
River stage zero No dependents
/ Inline::SLang::Types

NAME

Inline::SLang::Types - Support for S-Lang types

SYNOPSIS

use Inline SLang;
use Math::Complex;

# $val is a Math::Complex object after this call
my $val = makecplx();
print "Perl has been sent $val\n";
# note: the multiplication is done using Math::Complex
printcplx( $val * cplx(0,1) );

my $type = typecplx($val);
print "And the S-Lang datatype is $type\n";
print "        Perl               " .  ref($type) . "\n";

__END__
__SLang__

define makecplx() { return 3 + 4i; }
define printcplx(cval) {
  () = printf( "S-Lang has been sent %s\n", string(cval) );
}
define typecplx(cval) { return typeof(cval); }

DESCRIPTION

***
*** This is currently a pre alpha release.
*** Use at your own risk
***

The aim is to allow a user to program "naturally" in Perl and S-Lang, and so native data types are used wherever possible. However, objects are used when necessary (for some un-defined definition of necessary) to preserve type information. As an example, consider swapping a complex number between S-Lang and Perl. In S-Lang it would be represented as a Complex_Type and in Perl we choose to use a Math::Complex object. Something simple - such as an array reference containing two elements - could have been used, but then we would not be able to convert it back into a Complex_Type variable in S-Lang (well, not without telling the computer this is what we wanted).

An alternative is to use the Perl Data Language (ie PDL), since it provides variables ("piddles") which retain type information and are optimised for numeric work. Support for PDL is planned (once the initial kinks of the perl interface have been worked out) but currently not implemented (as of v0.05). Note that this will not remove the need for a number of object types, such as Inline::SLang::struct.

Supported Perl Data Types

***
*** NOTE: actually, for unsupported types we currently die
***

The following data types may be passed from Perl into S-Lang. Any unrecognized type is replaced with undef during translation.

I am leaning towards returing some sort of opaque reference for unrecognized types - eg Inline::SLang::unknown - so that the perl code won't be able to access them but will be able to pass them along to other S-Lang routines which can use them. This is necessary to allow support of modules and/or packages which may define new types. We may be able to make the class name more meaningful (i.e. replace unknown by the S-Lang type of the variable). Or we may not.

  • undef

    Converted to NULL.

    See discussion above (e.g. Inline::SLang::unknown).

  • Integer

    Converted to S-Lang Integer_Type.

  • Floating Point

    Converted to S-Lang Double_Type.

  • Math::Complex

    Converted to S-Lang Complex_Type.

  • String

    Converted to S-Lang String_Type.

  • Inline::SLang::DataType_Type

    Converted to S-Lang DataType_Type.

  • Inline::SLang::Struct_Type

    Converted to S-Lang Struct_Type.

    LEAKS MEMORY.

  • Inline::SLang::Ref_Type

    Converted to S-Lang Ref_Type.

  • Array Reference

    *** NOT SUPPORTED ***

    I am leaning towards returning an array of type Any_Type, since there's no guarantee that the perl array will be of one type, or form a regular nD array.

  • Hash Reference

    *** NOT SUPPORTED ***

    This should be converted to a S-Lang Assoc_Type object. Since we don't know the types of all the elements in the Perl hash array, it's simplest to always create the values as Any_Type variables. That's if I actually knew how to do that...

  • all others

    *** NOT SUPPORTED ***

Supported S-Lang Data Types

The following S-Lang types may be returned from a S-Lang function to Perl. Unrecognized types currently cause the code to die (or perhaps to return undef; I really should check).

  • NULL

    Converted to a perl undef.

  • [Char|UChar|Short|UShort|Int|UInt|Long|ULong]_Type

    Converted to a perl integer. The unsigned types are converted as unsigned values, whatever difference that makes.

  • [Float|Double]_Type

    Converted to a perl floating-point number.

  • Complex_Type

    Converted to a Math::Complex object.

  • String_Type

    Converted to a perl string.

  • DataType_Type

    An object of class Inline::SLang::DataType_Type is returned. See below for further details.

  • Ref_Type

    An object of class Inline::SLang::Ref_Type is returned. See below for further details.

  • Array_Type

    Converted to a perl array reference. Currently only 1 and 2 dimensional arrays of numeric (including complex numbers) and strings are handled.

  • Assoc_Type

    *** Partially supported ***

    A reference to a hash array is returned. However, this only works if the values stored in the array are of a type which we can convert into a 1D array. So, 'variable a = Assoc_Type [Int_Type];' will be converted, but 'variable b = Assoc_Type [];' will not, since we do not currently support Any_Type objects.

  • Struct_Type

    An object of class Inline::SLang::Struct_Type is returned. See below for further details.

  • all others

    *** NOT SUPPORTED ***

    Will likely use the Inline::SLang::unknown class (or at least someting that resembles this idea).

DATATYPE CLASSES

***
*** Comments would be welcome on the following approach
*** It could be less verbose (particularly the
*** Inline::SLang::*** class names), but I think the
*** current approach is somewhat logical/easy to follow
***

Objects are used to represent those S-Lang data types for which there is no corresponding Perl data type: for complex numbers we use the Math::Complex module which is distributed with Perl; for numeric types we may use piddles (see the documentation for the Perl Data Language); and for other types we use a class specific to Inline::SLang.

Complex numbers

Complex numbers are represented as Complex_Type in S-Lang and as a Math::Complex object in Perl. See the Math::Complex documentation for information on how to use this class.

Numeric types as piddles

***
*** Support for PDL is not yet available (v0.05)
***

The Perl Data Language (PDL) is a set of perl modules designed to provide fast, efficient, numeric capabilities in Perl (if you routinely deal with arrays of numbers in Perl you should have a look at PDL; see http://pdl.perl.org/).

Currently S-Lang arrays are converted to Perl array references (as discussed below). This is fine for strings (and is the obvious representation), and does allow easy access to the data. However, for numeric arrays it's not the most efficient and presents issues when converting Perl to S-Lang data [ie one would have to loop through the entire array to work out what S-Lang datatype and dimensionality/sizes to use]. Perhaps we should use a reference to a scalar as done in Astro::FITS::CFITSIO, but this approach has it's own issues (how do we find out the size of the array?).

It is likely that a routine will be used to define whether S-Lang numeric arrays should be turned into piddles or references to perl arrays (following the approach of the Astro::FITS::CFITSIO module). However, unlike the CFITSIO module, I am likely to convert to either a perl array reference or a piddle - ie no reference to a character array representing the data (ie force users to use piddles if they want efficiency).

Other types

A number of S-Lang types do not map to an obvious Perl type. For these types, Inline::SLang creates an object of class Inline::SLang::<type>, where <type> is the name of the S-lang datatype (i.e. the output of S-Lang's typeof function).

Each class provides a number of methods, as listed below. These methods are not exported into the calling packages namespace, so they can only be accessed using the "object-oriented" form, i.e.

$obj->foo()

Note that the new() method is not defined for some classes, which means you can only create them by calling a S-Lang function.

Common methods

All classes provide the following methods:

typeof()

Returns a string containing the name of the S-Lang datatype of the object (which corresponds to the name of the Perl class without the leading Inline::SLang::).

stringify()

The "print" method for the objects has been over-loaded to use the stringify() method: for most types it will return the datatype name (namely the output of the typeof() method), whereas for certain classes - such as Inline::SLang::Struct_Type - it will print out a formated representation of the data.

The class descriptions below describe the output format if it does not match that of the typeof() method.

is_struct_type()

Returns a 1 if the object represents a S-Lang structure, and 0 otherwise. This is currently rather useless since the only class for which a 1 is returned is Inline::SLang::Struct_Type. It has been introduced in the hope that we will be able to create objects for "named" structures (ie those created via S-Lang's typedef command).

DataType_Type

S-Lang Datatype_Type values are represented using Inline::SLang::DataType_Type objects.

The class-specific methods are:

new()
$dtype = Inline::SLang::DataType_Type->new($type);

The new() method accepts a string ($type) containing the name of the S-Lang datatype (e.g. "UChar_Type").

stringify()

The name of the datatype represented by the object is returned.

For instance

$type = Inline::SLang::DataType_Type->new("Any_Type");
print("And the type is '$type'\n");

outputs

And the type is 'Any_Type'.

Note that the typeof() method returns the string "DataType_Type" and not the value of the variable.

Struct_Type

***
*** I want to represent structures like
***   typedef struct {...} FooBar_Struct;
*** as Inline::SLang::FooBar_Struct objects 
*** but I need to think about this/work on it
*** first ...
***

S-Lang structures - variables with a type of Struct_Type - are represented using Inline::SLang::Struct_Type objects.

The methods are similar to the S-Lang versions, although struct_ has been removed from the names and the get and set functions allow multiple fields to be specified in a single call. Not all S-Lang functions are available, although the functionality of the missing functions should be possible with the current interface.

Missing are

set_struct_fields()
_push_struct_field_values()

Need to add

something like copy() or dup() with "field-slicing" a la
  dup_struct() in CIAO's varmm module.

The class-specific methods are:

is_struct_type()

This returns 1.

new()
@fields = ( "foo", "bar", "baz" );
$s1 = Inline::SLang::Struct_Type->new(@fields);
$s2 = Inline::SLang::Struct_Type->new(\@fields);

Create a S-Lang structure from Perl. The new() method accepts a list of field names using either an array reference or as an actual list. The order of the array determines the order of the fields in the structure.

It is not possible to set the values of the fields with this method (at least not for now; perhaps we should allow a hash reference to be supplied but then how do we define the order of the fields?).

get_field_names()
@names = $s1->get_field_names();

Returns, as an array, the names of the fields contained in the structure. Note that, unlike S-Lang's get_struct_field_names(), it does not return an array reference

get_field()
$val  = $s1->get_field( "bar" );
@vals = $s1->get_field( "foo", "baz" );

Returns the value of the specified field(s). If given more than one field name then the values are returned as an array.

The routine dies if given a field name that does not exist in the structure.

set_field()
$s1->set_field( "bar", 1 );
$s1->set_field( foo => 23, baz => "a string" );

Sets the supplied to the supplied values. The argument list is interpreted as pairs of "field name", "new value"; as shown above the => separator can be used to improve the readability of your code.

The routine dies if given a field name that does not exist in the structure.

stringify()

The structure type and contents are output. The output is currently very crude, and only really works if the fields contain scalars.

@f = ( "one", "two", "three" );
$s = Inline::SLang::Struct_Type->new(@f);
$s->set_field("one",1,"two",2,"three",3);
print "$s\n";

outputs

Structure Type: Struct_Type
        one     = 1
        two     = 2
        three   = 3

Ref_Type

S-Lang Ref_Type values are represented using Inline::SLang::Ref_Type objects. Note that these objects can only be created from S-Lang (i.e. there is no new() method). In fact, there is little that you can do with these objects in Perl; if you want to access/change the value referred to then you need to pass the object back to S-Lang.

There are no class-specific methods.

SEE ALSO

Inline::SLang, Math::Complex, PDL

AUTHOR, COPYRIGHT, LICENSE, and WARRANTY

See the Inline::SLang documentation.