=head1 NAME

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

=head1 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!";
  }

=head1 DESCRIPTION

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

The C<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.

=head1 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 L<Term::Slang|Term::Slang> module (on CPAN) if you
want an interface to the terminal library provided by S-Lang.

=head1 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 C<Inline::SLang>
can be found in L<Inline::SLang::Config>.
For more details on C<Inline>, see L<Inline> or
C<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
 ***

=head2 Functions

Using functions defined in S-Lang is just like using Perl subs. You
just supply the source code to Inline::SLang - see the
L<Inline manual|Inline> 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 C<array_map()> and C<assoc_get_keys()>) - in the 
default namespace ("Global") are bound to Perl. The
Perl functions are available in the C<main> package.

The C<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
C<BIND_SLFUNCS> option.
See L<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 I<beware> when you define a S-Lang function called 
C<open()>!

=head2 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
C<foo()> and C<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 I<lvalue> support
in modern versions of Perl. 
Currently it's not a very high priority issue (and may never be).

=head2 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 L<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.

=head1 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.
In fact, I may up this to about 1.4.9, for ease of testing.

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.8.0 (solaris and 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.

=head1 BUGS AND DEFICIENCIES

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

=head1 SEE ALSO

L<Inline::SLang::Config>, L<Inline::SLang::Types>, L<Term::Slang>

For information about using C<Inline>, see L<Inline>.

For information about other Inline languages, see L<Inline-Support>.

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

=head1 ACKNOWLEDGEMENTS

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

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

=head1 CHANGES

=over 4

=item v0.06 Thu Apr  3 22:36:54 EST 2003

Note that in the next release the class names for objects will be
shortened from Inline::SLang::Foo_Type to Foo_Type.

Notable changes are:

=over 4

=item *

Essentially all S-Lang I<scalars> can now be converted to
Perl. Those without a direct translation to a native Perl
type are converted to "opaque" Perl objects, with classes
called C<Inline::SLang::XXX> where C<XXX> equals the
name of their S-Lang data type. Essentially all you can
do with these objects is pass them back to S-Lang
routines. However, it does mean you can now call routines that
return module-defined types.

Currently the S-Lang file types (so C<File_Type> and
C<FD_Type>) are converted using this scheme, which means you
can I<not> use them with Perl I/O commands. I need to
read up a lot more on Perl's I/O mechanism before I
can change this (if it's possible).

=item *

"Named" structures - e.g. C<Foo_Type> created by
C<< typedef struct {...} Foo_Type; >> - are now handled
as C<Inline::SLang::XXX> objects, where C<XXX> matches the 
structure type (so C<Foo_Type> in this example).
These classes are sub-classes of C<Inline::SLang::Struct_Type>.

=item *

Fixed handling of BIND_NS =E<gt> "All".

=item *

Added an examples/ directory to the distribution, which
contains simple examples (mainly from L<Inline::SLang::Types>).
Note that these files are I<not> installed into the Perl
tree by 'make install'.

=back

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

Notable changes are:

=over 4

=item *

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

=item *

Ref_Type variables are now supported (scalars only)
via the C<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.

=item *

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

=item *

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.

=item *

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

=back

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

Notable changes are:

=over 4

=item *

License changed to GNU GPL and copyright holder to SAO.

=item *

Now binds all functions (other than S-Lang intrinsic
functions) in the Global namespace. Added the C<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.

=item *

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

=item *

Fixed memory leaks when converting C<Assoc_Type> 
arrays to Perl.

=item *

S-Lang C<Struct_Type> variables are converted to 
C<Inline::SLang::struct> objects.

=back

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

Initial public release

=back

=head1 AUTHOR

Doug Burke <djburke@cpan.org>

=head1 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.

=head1 WARRANTY

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

