++ed by:
SHLOMIF MISHIN POTATOGIM STEVENL DAVIDO

19 PAUSE users
10 non-PAUSE users.

Ingy döt Net

NAME

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

SYNOPSIS

    #!/usr/bin/perl
    
    say_it('foo');  # Use Foo++ to print "Hello, Foo"
    
    use Inline Foo => <<'EOFOO';
    
      /FOO  This is a function written in Foo++  OOF/    
    
      deefoon foonkshun say_it 
        < fooprint "Hello,", arrrg(0) >
    
    EOFOO

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 support for adding your own Inline Language Support Module (ILSM), like Inline::Foo.

Inline has always been intended to work with lots of different 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 subclasses 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.

You may also wish to look at the joke language Inline::Foo which is distributed 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.

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

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::FooPP. Here is the skeleton Perl code you'll need to implement it.

    package Inline::FooPP;
    
    use strict;
    require Inline;
    require Inline::FooPP::grammar;
    use Parse::RecDescent;
    use Config;
    use Carp;
    
    $Inline::FooPP::VERSION = '0.05';
    @Inline::FooPP::ISA = qw(Inline);
    
    #===========================================================
    # Register Foo++ as an Inline Language Support Module (ILSM)
    #===========================================================
    sub register {
        return {
                language => 'FooPP',
                aliases => ['Foo++', 'F++'],
                type => 'compiled',
                suffix => $Config{so},
               };
    }
    
    #==================================
    # Validate the Foo++ Config Options
    #==================================
    sub validate {
        my $o = shift; # This is the Inline object
    
        $o->{ILSM} = {};
        while (@_) {
        my ($key, $value) = (shift, shift);
        if ($key eq 'BAR') {
            $o->{ILSM}{BAR} = $value;  # Store config value in object
            next;
        }
        if ($key eq 'BAZ') {
            $o->{ILSM}{BAZ} = $value;
            next;
        }
        croak "'$key' is not a valid config option for Inline::FooPP\n";
        }
    }
    
    #=============================
    # Parse and compile Foo++ code
    #=============================
    sub build {
        my $o = shift;
        $o->parse;
        $o->compile;
    }
    
    #======================================
    # Only needed for interpreted languages
    #======================================
    sub load {
        my $o = shift;
    }
    
    #============================================
    # 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 produced by the
    Inline 'INFO' command.
    END
        return $text;
    }

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::FooPP must be a subclass of Inline. This is accomplished with:

        @Inline::FooPP::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::FooPP;

    Inline.pm will detect such usage for you in its import method, which is automatically inherited since Inline::FooPP is a subclass.

  4. It is not necessary to implement your parsing with Parse::RecDescent. But I recommend it. :-)

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

The Inline API

This section is a more formal specification of what functionality 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 module. It will then call various subroutines which you need to supply. We'll call these subroutines "callbacks".

You will need to provide the following 5 callback subroutines.

The register() Callback

This subroutine receives no arguments. It returns a reference to a hash of ILSM meta-data. Inline calls this routine 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 => 'FooPP',
     aliases => ['Foo++', 'F++'],
     type => 'compiled',
    };

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 contain word characters. [A-Za-z0-9_] An alias can contain 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.

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 is passed as the only argument. All pertinent information will be stored in this object. build() is required to create a shared 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 languages. 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 section of Inlined source code it receives. This object contains lots of information about the code, the environment, and the configuration options used. You are free to store any additional information in the object.

To prevent naming clashes with future version of Inline you use a subhash under the key 'ILSM'. This is the convention.

This section will describe all of the Inline object 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 'Foo++' instead of 'FooPP'.

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 parser Attribute

This is the place where the Parse::RecDescent parser object is normally stored.

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 mod_exists Attribute

This is a flag indicating whether or not this module has already been compiled. (1 for true and 0 for false)

The config Attribute

This is where all of the non-language specific configuration options are stored.

FORCE_BUILD

Flag indicating whether or not Inline should call the Inline::FooPP::build() method even if the code has already been compiled. (0 or 1)

Flag indicating whether or not Inline should print a version message. (0 or 1)

CLEAN_AFTER_BUILD

Flag indicating whether or not Inline should delete the contents of the build directory after a successful compilation (0 or 1)

Flag indicating whether or not Inline should print an informational report about the code being compiled. (0 or 1)

DIRECTORY

The name of the base directory for building and installing Inline executables.

REPORTBUG

Flag indicating whether or not Inline is in REPORTBUG mode. (0 or 1)

CLEAN_BUILD_AREA

Flag indicating whether or not Inline should perform a special cleanup function on the BLIB directory. (0 or 1)

SITE_INSTALL

Flag indicating whether or not the Inline code is meant to be part of a permanent module installation. (0 or 1)

WITH

A reference to an array of module names that Inline should poll for configuration hints.

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 dispute, 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 welcome to write and distribute Inline language support modules on CPAN. You'll just need to distribute them under a different package name.

SEE ALSO

For generic information about Inline, see Inline.

For information about using Inline with C see Inline::C.

For information on supported languages and platforms see Inline-Support.

Inline's mailing list is inline@perl.org

To subscribe, send email to inline-subscribe@perl.org

AUTHOR

Brian Ingerson <INGY@cpan.org>

COPYRIGHT

Copyright (c) 2000, 2001. Brian Ingerson. All rights reserved.

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