Initial commit of OpenSPARC T2 design and verification files.

[OpenSPARC-T2-DV] / tools / perl-5.8.0 / man / man3 / Inline-API.3

.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Inline-API 3"
.TH Inline-API 3 "2002-10-28" "perl v5.8.0" "User Contributed Perl Documentation"
.SH "NAME"
Inline\-API \- How to bind a programming language to Perl using Inline.pm
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    #!/usr/bin/perl
.Ve
.PP
.Vb 2
\&    use Inline Foo;
\&    say_it('foo');  # Use Foo to print "Hello, Foo"
.Ve
.PP
.Vb 5
\&    __Foo__ 
\&    foo-sub say_it {
\&        foo-my $foo = foo-shift;
\&        foo-print "Hello, $foo\en";
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "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 \*(L"Foo\*(R". Well you're
in luck. \f(CW\*(C`Inline.pm\*(C'\fR has support for adding your own Inline Language
Support Module (\fB\s-1ILSM\s0\fR), like \f(CW\*(C`Inline::Foo\*(C'\fR.
.PP
Inline has always been intended to work with lots of different
programming languages. Many of the details can be shared between
implementations, so that \f(CW\*(C`Inline::Java\*(C'\fR has a similar interface to
\&\f(CW\*(C`Inline::ASM\*(C'\fR. All of the common code is in \f(CW\*(C`Inline.pm\*(C'\fR.
.PP
Language specific modules like \f(CW\*(C`Inline::Python\*(C'\fR are subclasses of
\&\f(CW\*(C`Inline.pm\*(C'\fR. 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.
.PP
The Inline C support is probably the best boilerplate to copy from.
Since version 0.30 all C support was isolated into the module
\&\f(CW\*(C`Inline::C\*(C'\fR and the parsing grammar is further broken out into
\&\f(CW\*(C`Inline::C::grammar\*(C'\fR. All of these components come with the Inline
distribution.
.PP
This \s-1POD\s0 gives you all the details you need for implementing an \s-1ILSM\s0.
For further assistance, contact inline@perl.org See \*(L"\s-1SEE\s0 \s-1ALSO\s0\*(R" below.
.PP
We'll examine the joke language Inline::Foo which is distributed with
Inline. It actually is a full functioning \s-1ILSM\s0. 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 \s-1API\s0.
.SH "A Skeleton"
.IX Header "A Skeleton"
For the remainder of this tutorial, let's assume we're writing an \s-1ILSM\s0
for the ficticious language \f(CW\*(C`Foo\*(C'\fR. We'll call it \f(CW\*(C`Inline::Foo\*(C'\fR. Here
is the entire (working) implementation.
.PP
.Vb 6
\&    package Inline::Foo;
\&    use strict;
\&    $Inline::Foo::VERSION = '0.01';
\&    @Inline::Foo::ISA = qw(Inline);
\&    require Inline;
\&    use Carp;
.Ve
.PP
.Vb 11
\&    #===========================================================
\&    # Register Foo as an Inline Language Support Module (ILSM)
\&    #===========================================================
\&    sub register {
\&        return {
\&            language => 'Foo',
\&            aliases => ['foo'],
\&            type => 'interpreted',
\&            suffix => 'foo',
\&           };
\&    }
.Ve
.PP
.Vb 7
\&    #===========================================================
\&    # Error messages
\&    #===========================================================
\&    sub usage_config { 
\&        my ($key) = @_;
\&        "'$key' is not a valid config option for Inline::Foo\en";
\&    }
.Ve
.PP
.Vb 3
\&    sub usage_config_bar { 
\&        "Invalid value for Inline::Foo config option BAR";
\&    }
.Ve
.PP
.Vb 22
\&    #===========================================================
\&    # 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);
\&        }
\&    }
.Ve
.PP
.Vb 23
\&    #===========================================================
\&    # 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:\en$@" if $@;
\&        my $path = "$o->{API}{install_lib}/auto/$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 output\en$!";
\&        print FOO_OBJ $code;
\&        close \e*FOO_OBJ;
\&    }
.Ve
.PP
.Vb 13
\&    #===========================================================
\&    # 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 output\en$!";
\&        my $code = join '', <FOO_OBJ>;
\&        close \e*FOO_OBJ;
\&        eval "package $o->{API}{pkg};\en$code";
\&        croak "Unable to load Foo module $obj:\en$@" if $@;
\&    }
.Ve
.PP
.Vb 13
\&    #===========================================================
\&    # 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;
\&    }
.Ve
.PP
.Vb 1
\&    1;
.Ve
.PP
Except for \f(CW\*(C`load()\*(C'\fR, the subroutines in this code are mandatory for an
\&\s-1ILSM\s0. What they do is described below. A few things to note:
.IP "1" 4
.IX Item "1"
\&\f(CW\*(C`Inline::Foo\*(C'\fR must be a subclass of Inline. This is accomplished with:
.Sp
.Vb 1
\&    @Inline::Foo::ISA = qw(Inline);
.Ve
.IP "2" 4
.IX Item "2"
The line '\f(CW\*(C`require Inline;\*(C'\fR' is not necessary. But it is there to
remind you not to say '\f(CW\*(C`use Inline;\*(C'\fR'. This will not work.
.IP "3" 4
.IX Item "3"
Remember, it is not valid for a user to say:
.Sp
.Vb 1
\&    use Inline::Foo;
.Ve
.Sp
\&\f(CW\*(C`Inline.pm\*(C'\fR will detect such usage for you in its \f(CW\*(C`import\*(C'\fR method,
which is automatically inherited since \f(CW\*(C`Inline::Foo\*(C'\fR is a subclass.
.IP "4" 4
.IX Item "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\-').
.Sp
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.
.SH "The Inline API"
.IX Header "The Inline API"
This section is a more formal specification of what functionality you'll
need to provide to implement an \s-1ILSM\s0.
.PP
When Inline determines that some \f(CW\*(C`Foo\*(C'\fR code needs to be compiled it
will automatically load your \s-1ILSM\s0 module. It will then call various
subroutines which you need to supply. We'll call these subroutines
\&\*(L"callbacks\*(R".
.PP
You will need to provide the following 5 callback subroutines. 
.Sh "The \fIregister()\fP Callback"
.IX Subsection "The register() Callback"
This subroutine receives no arguments. It returns a reference to a hash
of \s-1ILSM\s0 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:
.PP
.Vb 6
\&    {
\&     language => 'Foo',
\&     aliases => ['foo'],
\&     type => 'interpreted',
\&     suffix => 'foo',
\&    };
.Ve
.PP
The meta-data items have the following meanings:
.IP "language" 4
.IX Item "language"
This is the proper name of the language. It is usually implemented as
\&\f(CW\*(C`Inline::X\*(C'\fR for a given language 'X'.
.IP "aliases" 4
.IX Item "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#'.
.IP "type" 4
.IX Item "type"
Must be set to 'compiled' or 'interpreted'. Indicates the category of
the language.
.IP "suffix" 4
.IX Item "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 \f(CW\*(C`Config.pm\*(C'\fR.
.Sp
For interpreted languages, this value can be whatever you want. Python
uses \f(CW\*(C`pydat\*(C'\fR. Foo uses \f(CW\*(C`foo\*(C'\fR.
.Sh "The \fIvalidate()\fP Callback"
.IX Subsection "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.
.Sh "The \fIbuild()\fP Callback"
.IX Subsection "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. \f(CW\*(C`build()\*(C'\fR is
required to create a cache object of a specific name, or to croak with
an appropriate error message.
.PP
This is the meat of your \s-1ILSM\s0. Since it will most likely be quite
complicated, it is probably best that you study an existing \s-1ILSM\s0 like
\&\f(CW\*(C`Inline::C\*(C'\fR.
.Sh "The \fIload()\fP Callback"
.IX Subsection "The load() Callback"
This method only needs to be provided for interpreted languages. It's
responsibility is to start the interpreter.
.PP
For compiled languages, the load routine from \f(CW\*(C`Inline.pm\*(C'\fR is called
which uses \f(CW\*(C`DynaLoader\*(C'\fR to load the shared object or \s-1DLL\s0.
.Sh "The \fIinfo()\fP Callback"
.IX Subsection "The info() Callback"
This method is called when the user makes use of the \f(CW\*(C`INFO\*(C'\fR
shortcut. You should return a string containing a small report about
the Inlined code.
.SH "The Inline Object"
.IX Header "The Inline Object"
\&\f(CW\*(C`Inline.pm\*(C'\fR 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.
.PP
This object is a hash that is broken into several subhashes. The only
two subhashes that an \s-1ILSM\s0 should use at all are \f(CW$o\fR\->{\s-1API\s0} and
\&\f(CW$o\fR\->{\s-1ILSM\s0}. 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 \s-1ILSM\s0 can freely
store data that it might need later on.
.PP
This section will describe all of the Inline object \*(L"\s-1API\s0\*(R" attributes.
.Sh "The code Attribute"
.IX Subsection "The code Attribute"
This the actual source code passed in by the user. It is stored as one
long string.
.Sh "The language Attribute"
.IX Subsection "The language Attribute"
The proper name of the language being used.
.Sh "The language_id Attribute"
.IX Subsection "The language_id Attribute"
The language name specified by the user. Could be '\*(C+' instead of '\s-1CPP\s0'.
.Sh "The module Attribute"
.IX Subsection "The module Attribute"
This is the shared object's file name.
.Sh "The modfname Attribute"
.IX Subsection "The modfname Attribute"
This is the shared object's file name.
.Sh "The modpname Attribute"
.IX Subsection "The modpname Attribute"
This is the shared object's installation path extension.
.Sh "The version Attribute"
.IX Subsection "The version Attribute"
The version of \f(CW\*(C`Inline.pm\*(C'\fR being used.
.Sh "The pkg Attribute"
.IX Subsection "The pkg Attribute"
The Perl package from which this invocation pf Inline was called.
.Sh "The install_lib Attribute"
.IX Subsection "The install_lib Attribute"
This is the directory to write the shared object into.
.Sh "The build_dir Attribute"
.IX Subsection "The build_dir Attribute"
This is the directory under which you should write all of your build
related files.
.Sh "The script Attribute"
.IX Subsection "The script Attribute"
This is the name of the script that invoked Inline.
.Sh "The location Attribute"
.IX Subsection "The location Attribute"
This is the full path name of the executable object in question.
.Sh "The suffix Attribute"
.IX Subsection "The suffix Attribute"
This is the shared library extension name. (Usually 'so' or 'dll').
.SH "The Inline Namespace"
.IX Header "The Inline Namespace"
\&\f(CW\*(C`Inline.pm\*(C'\fR 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 \s-1CPAN\s0.
.PP
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.
.PP
The Inline community will decide if your implementation of \s-1COBOL\s0 will be
distributed as the official \f(CW\*(C`Inline::COBOL\*(C'\fR 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 \fBfinal\fR authority.
.PP
But even if you want to work alone, you are free and welcome to write
and distribute Inline language support modules on \s-1CPAN\s0. You'll just need
to distribute them under a different package name.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
For generic information about Inline, see Inline.
.PP
For information about using Inline with C see Inline::C.
.PP
For information on supported languages and platforms see
Inline-Support.
.PP
Inline's mailing list is inline@perl.org
.PP
To subscribe, send email to inline\-subscribe@perl.org
.SH "AUTHOR"
.IX Header "AUTHOR"
Brian Ingerson <INGY@cpan.org>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2000, 2001, 2002. Brian Ingerson. All rights reserved.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
.PP
See http://www.perl.com/perl/misc/Artistic.html