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

NAME

Inline::SLang - Write Perl subs in S-Lang.

SYNOPSIS

print "9 + 16 = ", add(9,16), "\n";
print "9 - 16 = ", subtract(9,16), "\n";
print JAxH('Inline'), "\n";

use Inline SLang;

__END__
__SLang__

define add      (a,b) { return a + b; }
define subtract (a,b) { return a - b; }

define JAxH () {
  variable type = ();
  return "Just Another " + string(type) + " Hacker!";
}

DESCRIPTION

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

The Inline::SLang module allows you to put S-Lang source code directly "inline" in a Perl script or module. It sets up an in-process S-Lang interpreter, runs your code, and then examines the interpreter's symbol table, looking for things to bind to Perl.

The process of interrogating the S-Lang interpreter only occurs the first time you run your S-Lang code. The namespaces are cached, and subsequent calls use the cached version. Of course, your S-Lang code must still be run every time your run the Perl script -- but Inline::S-Lang already knows the results of running it.

What is S-Lang?

From the S-Lang library home page at http://www.s-lang.org/

S-Lang is a multi-platform programmer's library designed to allow a developer to create robust multi-platform software. It provides facilities required by interactive applications such as display/screen management, keyboard input, keymaps, and so on. The most exciting feature of the library is the slang interpreter that may be easily embedded into a program to make it extensible.

For our purposes it is the S-Lang interpreter that we are interested in. See the Term::Slang module (on CPAN) if you want an interface to the terminal library provided by S-Lang.

Using the Inline::SLang Module

Using Inline::SLang will seem very similar to using any other Inline language, thanks to Inline's consistent look and feel.

This section will explain the different ways to use Inline::SLang. Further details on configuring the behaviour of Inline::SLang can be found in Inline::SLang::Config. For more details on Inline, see Inline or perldoc Inline.

***
*** The following looks like it should be okay, although
*** comments/thoughts/suggestions are more than welcome
*** The mapping of S-Lang namepace to Perl package for
*** the functions may cause issues: perhaps namespace
*** 'foo' should map to package SLang::foo to make things
*** "cleaner"? Although this implictly creates the SLang
*** namespace for packages which hasn't been passed through
*** modules@perl.org
***

Functions

Using functions defined in S-Lang is just like using Perl subs. You just supply the source code to Inline::SLang - see the Inline manual for the various ways of doing this - and then use them in your Perl code. For example:

# set up a S-Lang function
use Inline SLang => <<'END';
define doit() { vmessage("Printing from S-Lang"); }
END

# now call the S-Lang function from Perl
doit();

By default all S-Lang functions - other than S-Lang intrinsic functions (the functions defined by the S-Lang interpreter, such as array_map() and assoc_get_keys()) - in the default namespace ("Global") are bound to Perl. The Perl functions are available in the main package.

The BIND_NS configuration option can be used to change the list of S-Lang namespaces bound to Perl. If you have need of an intrinsic S-Lang function then you can either write a wrapper routine or use the BIND_SLFUNCS option. See Inline::SLang::Config for more details.

Note that there are no checks that a S-Lang symbol, when mapped to Perl, does not clobber an existing value (or is a Perl built-in function so can not be over-ridden). So beware when you define a S-Lang function called open()!

Variables

We currently do not bind any variables to Perl. To access variables you have to write S-Lang routines that read/write the variable, as shown by the foo() and bar() routines below:

variable foobar = "a string";
define foo()  { return foobar; }
define bar(x) { foobar = x; }

It should not be too hard to also bind variables to Perl functions; this would make it easy to read, but setting them would (?) require making use of the lvalue support in modern versions of Perl. Currently it's not a very high priority issue (and may never be).

Supported Data Types

***
*** Guess what, it's not seamless at the moment!
***

Inline::S-Lang attempts to seamlessly convert between Perl and S-Lang data types. For "simple" types - for example strings - where there is a direct match between S-Lang and Perl, the conversion is not noticeable. For more complicated types - such as complex numbers - S-Lang variables are converted to Perl objects. See Inline::SLang::Types for more information on how the various data types are supported.

The module currently assumes that yor S-Lang library has been compiled with support for both floating-point and complex numbers.

Note that, in version 0.05, the support is much better for converting from S-Lang to Perl than the other way around.

SUPPORTED PLATFORMS

***
*** requirements not yet fixed in stone
***

The module is designed to work with version 1.4.x of the S-Lang library, although I make no promises for anything earlier than 1.4.4.

The support for the BIND_NS option is flaky prior to v1.4.3 (it appears to be due to S-Lang and not this module). Also, use of the "All" option is restricted to those systems using version v1.4.7 or higher. So I suggest upgrading!

S-Lang versions tested: 1.4.4 (solaris), 1.4.8 (linux & solaris)

Inline::S-Lang has so far been tested on Linux and Solaris 2.8 only. It should work on UNIX platforms; I would be surprised if it works without tweaking on other systems.

Perl versions tested: 5.6.1 (solaris), 5.8.0 (linux)

It is intended to support Perl versions >= 5.6.0 only (at least the release versions rather than the development releases). It is not clear yet whether we really need any >= 5.6.0 functionality, but this restriction does make testing/developing a lot easier for me.

BUGS AND DEFICIENCIES

This is pre-alpha release code. So, by design, there will be lots of bugs and deficiencies.

SEE ALSO

Inline::SLang::Config, Inline::SLang::Types, Term::Slang

For information about using Inline, see Inline.

For information about other Inline languages, see Inline-Support.

For information about S-Lang see http://www.s-lang.org/.

ACKNOWLEDGEMENTS

John Davis (for S-Lang), Brian Ingerson (for the Inline framework), and Neil Watkiss since I stole virtually everything from his Inline::Python and Inline::Ruby modules.

However, please do not assume that any errors in this module are in any way related to the above people.

CHANGES

v0.05 Fri Mar 14 11:57:31 EST 2003

Notable changes are:

  • Handling of 'foreign' S-Lang types - those for which we have introduced special classes such as DataType_Type variables - has been changed to use a scheme in which the Perl class name is formed from the concatanation of Inline::SLang:: and the S-Lang type (so Inline::SLang::struct has been renamed to Inline::SLang::Struct_Type).

    The classes are also more uniform in that they have a number of common functions and, where possible, the method names are similar to S-Lang functions with the same functionality.

  • Ref_Type variables are now supported (scalars only) via the Inline::SLang::Ref_Type class. Unfortunately this requires use of function/types that are not part of the public interface of the S-Lang library.

  • The BIND_NS option only works for v1.4.3 and higher of S-Lang. The option has been enhanced to allow namespace "renaming" and the use of "All" to specify all known namespaces (this only works for v1.4.7 and higher of S-Lang). The only valid string options are now "Global(=...)" and "All".

  • The BIND_SLFUNCS option has been added to allow you to use slected S-Lang intrinsic functions directly from Perl (i.e. without having to write a S-Lang wrapper function around it). To help avoid nameclashes you can chose your own name for the function in Perl.

  • Documentation on S-Lang specific configuration options has been moved to Inline::SLang::Config.

v0.04 Fri Mar 7 00:14:47 EST 2003

Notable changes are:

  • License changed to GNU GPL and copyright holder to SAO.

  • Now binds all functions (other than S-Lang intrinsic functions) in the Global namespace. Added the BIND_NS configuration option to allow functions in other namespaces to be bound as well. Use the Inline '-MInline=INFO' option to find out what functions have been bound.

  • S-Lang Struct_Type variables are converted to Inline::SLang::struct objects. There are memory leaks!

  • Fixed memory leaks when converting Assoc_Type arrays to Perl.

  • S-Lang Struct_Type variables are converted to Inline::SLang::struct objects.

v0.03 Tue Jan 28 12:01:49 EST 2003

Initial public release

AUTHOR

Doug Burke <djburke@cpan.org>

COPYRIGHT

This software is Copyright (C) 2003 Smithsonian Astrophysical Observatory. All rights are course reserved.

It is released under the GNU General Public License. You may find a copy of this licence in the file LICENSE within the source distribution or at

http://www.fsf.org/copyleft/gpl.html

Prior to version 0.04 the module was distributed under the same terms as Perl.

WARRANTY

There is no warranty. Please see the GNU General Public License for more details.