The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Language-XS-0.02
River stage zero No dependents
2 ++
/ Language::XS

NAME

Language::XS - Write XS code on the fly and load it dynamically.

SYNOPSIS

  use Language::XS;

DESCRIPTION

This module allows C & XS-code creation "on-the-fly", i.e. while your script is running.

Here is a very simple example:

 # create a Language::XS-object
 my $xs = new Language::XS cachedir => undef;
 # add plain C to the header
 $xs->hdr("#include <stdio.h>");
 # add a c function (not using xs syntax)
 $xs->cfun('printf ("I was called with %d arguments\n", items);');

 # now compile and find the code-reference
 my $coderef = $xs->find;
 # Now call it
 $coderef->(1, "Zwei", 1/3);

METHODS

new attr => value, ...

Creates a new Language::XS object. Known attributes are:

 id             a unique id that woill be shared among all modules
 cachedir       the common directory where shared objects should be cached.
                set to undef when you want to disable sharing (must be
                an  absolute path)

Default values will be supplied when necessary. Two common idioms are:

 $xs = new Language::XS;                        # caching enabled
 $xs = new Language::XS cachedir => undef;      # caching disabled

cached

Returns true when as shared object with the given id already exists. This obviously only makes sense when you gave the module a unique id.

hdr sourcecode, [id]

Add sourcecode to the header portion. Similar to the header portion of an XS module, you can insert any valid C-code here. Most often you'd add some include directives, though.

id can be used to identify this portion (for error messages).

cfun functionbody, [id], [prototype]

Adds a XS function whose body is given in functionbody. Unlike XS, you have to do argument processing (i.e. fiddling with ST(0)) yourself. id specifies the function name (for find() or error messages), and can be omitted (which results in a default name).

prototype is an optional string that specifies the perl protoype. Remember that only the parser will evaluate prototypes.

xsfun xs-source

Similar to cfun, but is able to parse normal XS syntax (most of it, that is). Pity that I haven't yet implemented this function, since that would require serious recoding of xsubpp.

uselib lib...

Link against all the libraries given as arguments. The libraries should be specified as strings of the form -llibrary. Additional search paths can be given using -L/path/to/libs. See ExtUtils::Liblist.

incpath path...

Add additional include paths. These paths are prepended to the other include paths.

gen

Create the shared object file. This method is called automatically by load and even by find. This function returns a truth status and fills the messages attribute (see messages) with any compiler/linker warnings or errors.

messages

Returns the compiler messages (created & updated by gen).

load

Tries to load the shared object, generating it if necessary. Returns a truth status.

find [id]

Find the function (either xs or c) with id id and return a code-ref to it. If id is omitted, the default function (see cfun) is returned instead. If no shared object is loaded, calls load.

BUGS/PROBLEMS

Requires a C compiler (or even worse: the same C compiler perl was compiled with).

Does (most probably) not work on many os's, especially non-unix ones.

You cannot yet use normal XS syntax.

Line number handling could be better.

AUTHOR

Marc Lehmann <schmorp@schmorp.de>.

SEE ALSO

perl(1).