=head1 NAME
Inline::SLang::Config - How to configure Inline::SLang
=head1 DESCRIPTION
The L<Inline|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.
=head2 Options
=head3 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:
=over 2
=item
"Global"
Binds functions in the Global namespace only. This is the
B<
default
> value.
=item
"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).
=item 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.
=back
The
default
behaviour is
for
functions in the
"Global"
namespace to be bound
to the Perl C<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 C<foo> namespace
into the Perl
package
C<bar>. Therefore,
BIND_NS
=> [
"Global=foo"
,
"foo"
],
will
bind
all S-Lang functions from the C<Global> and
C<foo> namespaces into Perl's C<foo>
package
.
Note that B<
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 C<
import
> and C<evalfile> commands
instead.
The following examples are also available in the
F<examples/>
sub
-directory of the source code (this directory
is not installed by C<make install>).
=over 2
=item 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
printf
"I am %s\n"
, foo::fn_in_foo(
"dummyval"
);
printf
"I am %s\n"
, fn_in_global(
"dummyval"
);
=item 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
printf
"I am %s\n"
, foo::fn_in_foo(
"dummyval"
);
printf
"I am %s\n"
, fn_in_global(
"dummyval"
);
=item 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
printf
"I am %s\n"
, bar::fn_in_foo(
"dummyval"
);
printf
"I am %s\n"
, fn_in_global(
"dummyval"
);
=item 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
printf
"I am %s\n"
, foo::fn_in_foo(
"dummyval"
);
printf
"I am %s\n"
, fn_in_global(
"dummyval"
);
=back
=head3 BIND_SLFUNCS - which S-Lang intrinsic functions to
bind
?
This option is used to give a list of S-Lang I<intrinsic>
functions which are to be bound to Perl. The
default
value
is B<[]>, i.e.
no
functions.
Note that there are B<
no
> checks on whether it makes sense
to
bind
the specified function, or whether it conflicts
with
an existing Perl definition.
=over 2
=item Example of binding an intrinsic command into main:
use
Inline
'SLang'
=>
Config
=>
BIND_SLFUNCS
=> [
"typeof"
];
use
Inline
'SLang'
=>
"define get_typeof(x) { typeof(x); }"
;
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"
);
=item Example of binding an intrinsic command into the foo
package
:
use
Inline
'SLang'
=>
Config
=>
BIND_NS
=>
"Global=foo"
,
BIND_SLFUNCS
=> [
"typeof"
];
printf
"The S-Lang type of 'foo' is %s\n"
, foo::typeof(
"foo"
);
=back
The reason
for
giving C<
" "
> as the S-Lang code in the
last
example is to stop C<Inline> from complaining about being
sent
no
code.
=head3 EXPORT - how to export Perl functions from Inline::SLang
The L<Inline::SLang module|Inline::SLang> contains
a number of utility routines that are - by
default
- only
available using the fully-qualified
package
name. If you would
rather
use
C<sl_array(...)> than C<Inline::SLang::sl_array(...)>
then you can
use
the C<EXPORT> option.
This resembles the standard Perl export mechanism but
is not as feature rich.
The available functions are (see
L<Inline::SLang>
for
a detailed description):
=over 4
=item sl_array()
A wrapper
around
the constructor
for
the C<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.
=item sl_eval()
Call S-Lang's C<
eval
()> routine and, on
exit
, convert the
stack to Perl.
=item sl_typeof()
A wrapper
around
S-Lang's C<typeof()> routine. It is more
efficient than using S-Lang's typeof routine.
=item C<< <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
C<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 - as of version 0.12 of C<Inline::SLang> - you can
also
use
the name of I<synonyms> as well as the I<base>
classes. For instance, C<Int32_Type()> will
return
the datatype that corresponds to the S-Lang
C<Int32_Type> type.
=back
The C<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 C<EXPORT> array or give the value C<!types> which
includes them all.
Note that we
do
not
accept
the full syntax of the
L<Exporter|Exporter> module: the C<EXPORT> option
should be thought of as a toy car
next
to the
RV that is the C<Exporter> module.
=head2 What functions and namespaces have been bound to Perl?
The C<info> option of L<Inline|Inline> can be useful to see
what
has
(and
has
not) been bound to Perl. As an example
try
the following (available as F<examples/info.pl> in the
source code of the module):
perl -MInline=info <<FOO