/ 
Inline-SLang-0.04
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.03). Note that this will not remove the need for a number of object types, such as Inline::SLang::struct.

Handling numeric arrays

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?).

I am tempted to use array references and then force users to use PDL if they want efficiency.

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.

  • 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

    Converted to S-Lang DataType_Type.

  • Inline::SLang::struct

    Converted to S-Lang Struct_Type.

    LEAKS MEMORY.

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

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

  • 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 is returned. Currently this is a very simple class (see below).

  • 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 is returned. See below for further details.

  • all others

    *** NOT SUPPORTED ***

    Will likely use the C,Inline::SLang::unknown> class.

DATATYPE CLASSES

Complex numbers

Complex numbers are represented as Complex_Type in S-Lang and as a Math::Complex object in Perl.

Datatypes

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

Currently there are only two methods and the API could change based on use/feed-back:

  • Inline::SLang::datatype->new()

    Given a string containing the name of the datatype (eg "UChar_Type"), the constructor

  • stringify()

    Converts the object into a string. In practice you would not call this method directly since you can just include the variable into a string:

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

Structures

S-Lang Struct_Type objects are represented using Inline::SLang::struct objects.

The public (ie usable) methods of this object are as described below. Any method names beginning with an undersocre character ('_') are to be considered private and should not be used, since they are not guaranteed to stay the same between versions.

  • Inline::SLang::struct->new( $name1, ..., $namen );

    Creates a structure with field names as given in the supplied arguments ($name1 to $namen).

  • $self->fields()

    Returns an array reference which contains the names of all the fields:

    $aref = $self->fields();
foreach my $f ( @$aref ) { print "Field: $f\n" }

  • $self->get( $name, ... );

    Returns the value of the specified fields. These fields do not need to be specified in the order they are stored in the structure. The routine croak's if a field is requested that does not exist in the structure.

    print "field foo = " . $self->get("foo") . "\n";
my @vals = $self->get("a","b","c");

  • $self->set( $name1, $value1, $name2, $value2, ... );

    Sets the values of the specified values. These fields do not need to be specified in the order they are stored in the structure. The routine croak's if a field is specified that does not exist in the structure.

    $self->set("foo",1);
$self->set("foo",1,"goo",23.4);

  • stringify

    Used when converting the object to a string. The field names and values are specified using a format that may change.

    print "$self";
  a     = 23.4
  bb    = a string

    It doesn't handle things like arrays very well.

SEE ALSO

Inline::SLang, Math::Complex

AUTHOR

Doug Burke <djburke@cpan.org>

COPYRIGHT

Copyright (c) 2003, Doug Burke.

All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html.