inline-api(3)

NAME

Inline-API - How to bind a programming language to Perl
using Inline.pm

SYNOPSIS

#!/usr/bin/perl
use Inline Foo;
say_it('foo');  # Use Foo to print "Hello, Foo"
__Foo__
foo-sub say_it {
    foo-my $foo = foo-shift;
    foo-print "Hello, $foo0;
}

DESCRIPTION

So you think Inline C is pretty cool, but what you really
need is for Perl to work with the brand new programming
language "Foo". Well you're in luck. "Inline.pm" has sup
port for adding your own Inline Language Support Module
(ILSM), like "Inline::Foo".

Inline has always been intended to work with lots of dif
ferent programming languages. Many of the details can be
shared between implementations, so that "Inline::Java" has
a similar interface to "Inline::ASM". All of the common
code is in "Inline.pm".

Language specific modules like "Inline::Python" are sub
classes of "Inline.pm". They can inherit as much of the
common behaviour as they want, and provide specific
behaviour of their own. This usually comes in the form of
Configuration Options and language specific compilation.

The Inline C support is probably the best boilerplate to
copy from. Since version 0.30 all C support was isolated
into the module "Inline::C" and the parsing grammar is
further broken out into "Inline::C::grammar". All of these
components come with the Inline distribution.

This POD gives you all the details you need for implement
ing an ILSM. For further assistance, contact
inline@perl.org See "SEE ALSO" below.

We'll examine the joke language Inline::Foo which is dis
tributed with Inline. It actually is a full functioning
ILSM. I use it in Inline's test harness to test base
Inline functionality. It is very short, and can help you
get your head wrapped around the Inline API.

A Skeleton

For the remainder of this tutorial, let's assume we're writing an ILSM for the ficticious language "Foo". We'll call it "Inline::Foo". Here is the entire (working) imple mentation.: package Inline::Foo;
use strict;
$Inline::Foo::VERSION = '0.01';
@Inline::Foo::ISA = qw(Inline);
require Inline;
use Carp;; #===========================================================
# Register Foo as an Inline Language Support Module; (ILSM)
#===========================================================
sub register {
return {
language => 'Foo',
aliases => ['foo'],
type => 'interpreted',
suffix => 'foo',

};; }; #===========================================================
# Error messages
#===========================================================
sub usage_config {
my ($key) = @_;
"'$key' is not a valid config option for In

line::Foo0;; }; sub usage_config_bar {
"Invalid value for Inline::Foo config option BAR";; }; #===========================================================
# Validate the Foo Config Options
#===========================================================
sub validate {
my $o = shift;
$o->{ILSM}{PATTERN} ||= 'foo-';
$o->{ILSM}{BAR} ||= 0;
while (@_) {
my ($key, $value) = splice @_, 0, 2;
if ($key eq 'PATTERN') {
$o->{ILSM}{PATTERN} = $value;
next;

}
if ($key eq 'BAR') {

croak usage_config_bar
unless $value =~ /^[01]$/;

$o->{ILSM}{BAR} = $value;
next;

}
croak usage_config($key);
}; }; #===========================================================
# Parse and compile Foo code
#===========================================================
sub build {
my $o = shift;
my $code = $o->{API}{code};
my $pattern = $o->{ILSM}{PATTERN};
$code =~ s/$pattern//g;
$code =~ s/bar-//g if $o->{ILSM}{BAR};
sleep 1; # imitate compile delay
{
package Foo::Tester;
eval $code;

}
croak "Foo build failed:0@" if $@;
my $path = "$o->{API}{install_lib}/au

to/$o->{API}{modpname}";
my $obj = $o->{API}{location};
$o->mkpath($path) unless -d $path;
open FOO_OBJ, "> $obj"

or croak "Can't open $obj for output0!";

print FOO_OBJ $code;
close OO_OBJ;; }; #===========================================================
# Only needed for interpreted languages
#===========================================================
sub load {
my $o = shift;
my $obj = $o->{API}{location};
open FOO_OBJ, "< $obj"
or croak "Can't open $obj for output0!";

my $code = join '', <FOO_OBJ>;
close OO_OBJ;
eval "package $o->{API}{pkg};0code";
croak "Unable to load Foo module $obj:0@" if $@;; }; #===========================================================
# Return a small report about the Foo code.
#===========================================================
sub info {
my $o = shift;
my $text = <<'END';; This is a small report about the Foo code. Perhaps it; contains
information about the functions the parser found which; will be
bound to Perl. It will get included in the text pro; duced by the
Inline 'INFO' command.
END
return $text;; }; 1;
Except for "load()", the subroutines in this code are mandatory for an ILSM. What they do is described below. A few things to note:
1 "Inline::Foo" must be a subclass of Inline. This is: accomplished with:

@Inline::Foo::ISA = qw(Inline);
2 The line '"require Inline;"' is not necessary. But it: is there to remind you not to say '"use Inline;"'.
This will not work.
3 Remember, it is not valid for a user to say:: use Inline::Foo;
"Inline.pm" will detect such usage for you in its "import" method, which is automatically inherited since "Inline::Foo" is a subclass.
4 In the build function, you normally need to parse your: source code. Inline::C uses Parse::RecDescent to do
this. Inline::Foo simply uses eval. (After we strip
out all occurances of 'foo-').; An alternative parsing method that works well for many
ILSMs (like Java and Python) is to use the language's
compiler itself to parse for you. This works as long
as the compiler can be made to give back parse infor
mation.

The Inline API

This section is a more formal specification of what func
tionality you'll need to provide to implement an ILSM.

When Inline determines that some "Foo" code needs to be
compiled it will automatically load your ILSM module. It
will then call various subroutines which you need to sup
ply. We'll call these subroutines "callbacks".

You will need to provide the following 5 callback subrou
tines.

The register() Callback

This subroutine receives no arguments. It returns a refer ence to a hash of ILSM meta-data. Inline calls this rou tine only when it is trying to detect new ILSM-s that have been installed on a given system. Here is an example of the has ref you would return for Foo:: {
language => 'Foo',
aliases => ['foo'],
type => 'interpreted',
suffix => 'foo',; };
The meta-data items have the following meanings:
language: This is the proper name of the language. It is usually
implemented as "Inline::X" for a given language 'X'.
aliases: This is a reference to an array of language name
aliases. The proper name of a language can only con
tain word characters. [A-Za-z0-9_] An alias can con
tain any characters except whitespace and quotes. This
is useful for names like 'C++' and 'C#'.
type: Must be set to 'compiled' or 'interpreted'. Indicates
the category of the language.
suffix: This is the file extension for the cached object that
will be created. For 'compiled' languages, it will
probably be 'so' or 'dll'. The appropriate value is in
"Config.pm".; For interpreted languages, this value can be whatever
you want. Python uses "pydat". Foo uses "foo".
The validate() Callback
This routine gets passed all configuration options that were not already handled by the base Inline module. The options are passed as key/value pairs. It is up to you to validate each option and store its value in the Inline object (which is also passed in). If a particular option is invalid, you should croak with an appropriate error message.
The build() Callback
This subroutine is responsible for doing the parsing and compilation of the Foo source code. The Inline object is passed as the only argument. All pertinent information will be stored in this object. "build()" is required to create a cache object of a specific name, or to croak with an appropriate error message.
This is the meat of your ILSM. Since it will most likely be quite complicated, it is probably best that you study an existing ILSM like "Inline::C".
The load() Callback
This method only needs to be provided for interpreted lan guages. It's responsibility is to start the interpreter.
For compiled languages, the load routine from "Inline.pm" is called which uses "DynaLoader" to load the shared object or DLL.
The info() Callback
This method is called when the user makes use of the "INFO" shortcut. You should return a string containing a small report about the Inlined code.

The Inline Object

"Inline.pm" creates a hash based Perl object for each sec
tion of Inlined source code it receives. This object con
tains lots of information about the code, the environment,
and the configuration options used.

This object is a hash that is broken into several sub
hashes. The only two subhashes that an ILSM should use at
all are $o->{API} and $o->{ILSM}. The first one contains
all of the information that Inline has gather for you in
order for you to create/load a cached object of your
design. The second one is a repository where your ILSM can
freely store data that it might need later on.

This section will describe all of the Inline object "API"
attributes.

The code Attribute

This the actual source code passed in by the user. It is
stored as one long string.

The language Attribute

The proper name of the language being used.

The language_id Attribute

The language name specified by the user. Could be 'C++'
instead of 'CPP'.

The module Attribute

This is the shared object's file name.

The modfname Attribute

This is the shared object's file name.

The modpname Attribute

This is the shared object's installation path extension.

The version Attribute

The version of "Inline.pm" being used.

The pkg Attribute

The Perl package from which this invocation pf Inline was
called.

The install_lib Attribute

This is the directory to write the shared object into.

The build_dir Attribute

This is the directory under which you should write all of
your build related files.

The script Attribute

This is the name of the script that invoked Inline.

The location Attribute

This is the full path name of the executable object in
question.

The suffix Attribute

This is the shared library extension name. (Usually 'so'
or 'dll').

The Inline Namespace

"Inline.pm" has been set up so that anyone can write their
own language support modules. It further allows anyone to
write a different implementation of an existing Inline
language, like C for instance. You can distribute that
module on the CPAN.

If you have plans to implement and distribute an Inline
module, I would ask that you please work with the Inline
community. We can be reached at the Inline mailing list:
inline@perl.org (Send mail to inline-subscribe@perl.org to
subscribe). Here you should find the advice and assistance
needed to make your module a success.

The Inline community will decide if your implementation of
COBOL will be distributed as the official "Inline::COBOL"
or should use an alternate namespace. In matters of dis
pute, I (Brian Ingerson) retain final authority. (and I
hope not to need use of it :-) Actually modules@perl.org
retains the final authority.

But even if you want to work alone, you are free and wel
come to write and distribute Inline language support mod
ules on CPAN. You'll just need to distribute them under a
different package name.

AUTHOR

Brian Ingerson <INGY@cpan.org>

COPYRIGHT

This program is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html

docs.sk

comprehensive documentation repository

Most Viewed