/ 
Inline-SLang-0.11
River stage zero No dependents
/ Inline::SLang::Config

NAME

Inline::SLang::Config - How to configure Inline::SLang

DESCRIPTION

The Inline documentation describes how you can configure the Inline-specific options. Please review that document if you are unfamiliar with the way Inline works (in particular the section on "Configuration Options"). This document describes the options that are available to configure the S-Lang interface.

Options

BIND_NS - what namespaces should be searched?

This option - which takes either a string or a reference to an array of strings - specifies the S-Lang namespaces which are searched for functions to bind to Perl. The accepted values are:

"Global"

Binds functions in the Global namespace only. This is the default value.

"All"

Binds functions in all the namespaces that are defined at the time of compilation. You can not use the namespace renaming feature discussed below with this option (so "All=foo" does not work).

Array reference

If an array reference is given then it should contain the names of the namespaces to search for S-Lang functions. In most case you will want to ensure that "Global" is contained in this list.

The default behaviour is for functions in the "Global" namespace to be bound to the Perl main package (so they can be used without any package specifier) while functions in other namespaces are placed into the Perl package whose name equals that of the S-Lang namespace (see below for examples). This can be changed by supplying strings matching "foo=bar", which says to bind S-Lang functions from the foo namespace into the Perl package bar. Therefore,

BIND_NS => [ "Global=foo", "foo" ],

will bind all S-Lang functions from the Global and foo namespaces into Perl's foo package.

Note that no checks are made for over-writing functions when they are bound to Perl. Also, if you are using this functionality you should probably be using the 2-argument form of S-Lang's import and evalfile commands instead.

The following examples are also available in the examples/ sub-directory of the source code (this directory is not installed by make install).

Example of using a single namespace:
use Inline 'SLang' => Config => BIND_NS => ["foo"];
use Inline 'SLang' => <<'EOS1';
 define fn_in_global(x) { "in global"; }
 implements( "foo" );
 define fn_in_foo(x) { "in foo"; }
EOS1

# this works
printf "I am %s\n", foo::fn_in_foo("dummyval");

# this does not work since fn_in_global is in the
# Global namespace which was not given to the
# BIND_NS option
printf "I am %s\n", fn_in_global("dummyval");
Example of using multiple namespaces:
use Inline 'SLang' => Config => BIND_NS => [ "Global", "foo" ];
use Inline 'SLang' => <<'EOS1';
 define fn_in_global(x) { "in global"; }
 implements( "foo" );
 define fn_in_foo(x) { "in foo"; }
EOS1

# this works
printf "I am %s\n", foo::fn_in_foo("dummyval");

# as does this
printf "I am %s\n", fn_in_global("dummyval");
Example of renaming a namespace:
use Inline 'SLang' => Config => BIND_NS => [ "Global", "foo=bar" ];
use Inline 'SLang' => <<'EOS1';
 define fn_in_global(x) { "in global"; }
 implements( "foo" );
 define fn_in_foo(x) { "in foo"; }
EOS1

# this works
printf "I am %s\n", bar::fn_in_foo("dummyval");

# as does this
printf "I am %s\n", fn_in_global("dummyval");
Example of using all namespaces:
use Inline 'SLang' => Config => BIND_NS => "All";
use Inline 'SLang' => <<'EOS1';
 define fn_in_global(x) { "in global"; }
 implements( "foo" );
 define fn_in_foo(x) { "in foo"; }
EOS1

# this works
printf "I am %s\n", foo::fn_in_foo("dummyval");

# as does this
printf "I am %s\n", fn_in_global("dummyval");

BIND_SLFUNCS - which S-Lang intrinsic functions to bind?

This option is used to give a list of S-Lang intrinsic functions which are to be bound to Perl. The default value is [], i.e. no functions.

Note that there are no checks on whether it makes sense to bind the specified function, or whether it conflicts with an existing Perl definition.

Example of binding an intrinsic command into main:
use Inline 'SLang' => Config => BIND_SLFUNCS => ["typeof"];
use Inline 'SLang' => "define get_typeof(x) { typeof(x); }";

# both lines print
#  The S-Lang type of 'foo' is String_Type
printf "The S-Lang type of 'foo' is %s\n", get_typeof("foo");
printf "The S-Lang type of 'foo' is %s\n", typeof("foo");
Example of binding an intrinsic command into the foo package:
use Inline 'SLang' => Config =>
  BIND_NS => "Global=foo",
  BIND_SLFUNCS => ["typeof"];
use Inline 'SLang' => " ";

# This also prints
#  The S-Lang type of 'foo' is String_Type
printf "The S-Lang type of 'foo' is %s\n", foo::typeof("foo");

The reason for giving " " as the S-Lang code in the last example is to stop Inline from complaining about being sent no code.

EXPORT - how to export Perl functions from Inline::SLang

The Inline::SLang module contains a number of utility routines that are - by default - only available using the fully-qualified package name. If you would rather use sl_array(...) than Inline::SLang::sl_array(...) then you can use the EXPORT option. This resembles the standard Perl export mechanism but is not as feature rich.

The available functions are (see Inline::SLang for a detailed description):

sl_array()

A wrapper around the constructor for the Array_Type class. Useful if you want to ensure that a Perl array reference is converted to the correct array type and size in S-Lang.

sl_eval()

Call S-Lang's eval() routine and, on exit, convert the stack to Perl.

sl_typeof()

A wrapper around S-Lang's typeof() routine. It is more efficient than using S-Lang's typeof routine.

<datatype name>()

A function is created for each S-Lang datatype known about when the Perl code is executed (so this includes typedef-fed structures and any application-specific datatypes from imported modules). The name of the function matches the name of the S-Lang datatype and returns a Perl DataType_Type object whose value matches the function name - so

Integer_Type()

is just the same as calling

DataType_Type->new("Integer_Type");

Note that this only holds for the "main" types; for synonyms - such as Int_Type and Float32_Type - you still have to use the DataType_Type constructor.

The EXPORT option accepts a reference to an array that lists the names of the functions to export, e.g.

use Inline 'SLang' => Config => EXPORT => [ "sl_array" ];

If you want to export the datatype functions then you can either list the names of the required functions in the EXPORT array or give the value !types which includes them all.

Note that we do not accept the full syntax of the Exporter module: the EXPORT option should be thought of as a toy car next to the RV that is the Exporter module.

What functions and namespaces have been bound to Perl?

The info option of Inline can be useful to see what has (and has not) been bound to Perl. As an example try the following (available as examples/info.pl in the source code of the module):

perl -MInline=info <<FOO
use Inline SLang;
# let's not actually do anything
__END__
__SLang__
typedef struct { foo, bar } FooBarStruct_Type;
variable foobar = "a string";
define foo()  { return foobar; }
define bar(x) { foobar = x; }
FOO

The relevant part of the output (as of version 0.11) is:

Configuration details
---------------------

Version of S-Lang: 1.4.8
Perl module version is 0.11 with no support for PDL

The following S-Lang types are recognised:
 UShort_Type UInteger_Type Double_Type _IntegerP_Type
 FooBarStruct_Type [Struct_Type] Struct_Type FD_Type BString_Type
 Integer_Type Null_Type Undefined_Type Char_Type Float_Type Array_Type
 Short_Type Any_Type Assoc_Type Complex_Type Ref_Type String_Type
 File_Type UChar_Type DataType_Type

The following S-Lang namespaces have been bound to Perl:

  2 functions from namespace Global are bound to package main
        bar()
        foo()

Any S-Lang intrinsic functions bound to Perl are indicated using the format S-Lang name() -> Perl name(), even when the Perl and S-Lang names match (this may change).

If you have a typedef statement defining a "named" structure then the name of the structure will be followed by "[Struct_Type]", as with the FooBarStruct_Type variable type in the example above.

The format of this section is liable to change; any suggestions are very welcome.

SEE ALSO

Inline::SLang, Inline