1Inline::API(3)        User Contributed Perl Documentation       Inline::API(3)
2
3
4

NAME

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

SYNOPSIS

9           #!/usr/bin/perl
10
11           use Inline Foo;
12           say_it('foo');  # Use Foo to print "Hello, Foo"
13
14           __Foo__
15           foo-sub say_it {
16               foo-my $foo = foo-shift;
17               foo-print "Hello, $foo\n";
18           }
19

DESCRIPTION

21       So you think Inline C is pretty cool, but what you really need is for
22       Perl to work with the brand new programming language "Foo". Well you're
23       in luck.  "Inline.pm" has support for adding your own Inline Language
24       Support Module (ILSM), like "Inline::Foo".
25
26       Inline has always been intended to work with lots of different
27       programming languages. Many of the details can be shared between
28       implementations, so that "Inline::Java" has a similar interface to
29       "Inline::ASM". All of the common code is in "Inline.pm".
30
31       Language specific modules like "Inline::Python" are subclasses of
32       "Inline.pm". They can inherit as much of the common behaviour as they
33       want, and provide specific behaviour of their own. This usually comes
34       in the form of Configuration Options and language specific compilation.
35
36       The Inline C support is probably the best boilerplate to copy from.
37       Since version 0.30 all C support was isolated into the module
38       "Inline::C" and the parsing grammar is further broken out into
39       "Inline::C::grammar". All of these components come with the Inline
40       distribution.
41
42       This POD gives you all the details you need for implementing an ILSM.
43       For further assistance, contact inline@perl.org See ["SEE ALSO"] below.
44
45       We'll examine the joke language Inline::Foo which is distributed with
46       Inline.  It actually is a full functioning ILSM. I use it in Inline's
47       test harness to test base Inline functionality. It is very short, and
48       can help you get your head wrapped around the Inline API.
49

A SKELETON

51       For the remainder of this tutorial, let's assume we're writing an ILSM
52       for the ficticious language "Foo". We'll call it "Inline::Foo". Here is
53       the entire (working) implementation.
54
55           package Inline::Foo;
56           use strict;
57           $Inline::Foo::VERSION = '0.01';
58           @Inline::Foo::ISA = qw(Inline);
59           require Inline;
60           use Carp;
61
62           #===========================================================
63           # Register Foo as an Inline Language Support Module (ILSM)
64           #===========================================================
65           sub register {
66               return {
67                   language => 'Foo',
68                   aliases => ['foo'],
69                   type => 'interpreted',
70                   suffix => 'foo',
71                  };
72           }
73
74           #===========================================================
75           # Error messages
76           #===========================================================
77           sub usage_config {
78               my ($key) = @_;
79               "'$key' is not a valid config option for Inline::Foo\n";
80           }
81
82           sub usage_config_bar {
83               "Invalid value for Inline::Foo config option BAR";
84           }
85
86           #===========================================================
87           # Validate the Foo Config Options
88           #===========================================================
89           sub validate {
90               my $o = shift;
91               $o->{ILSM}{PATTERN} ||= 'foo-';
92               $o->{ILSM}{BAR} ||= 0;
93               while (@_) {
94               my ($key, $value) = splice @_, 0, 2;
95               if ($key eq 'PATTERN') {
96                   $o->{ILSM}{PATTERN} = $value;
97                   next;
98               }
99               if ($key eq 'BAR') {
100                   croak usage_config_bar
101                     unless $value =~ /^[01]$/;
102                   $o->{ILSM}{BAR} = $value;
103                   next;
104               }
105               croak usage_config($key);
106               }
107           }
108
109           #===========================================================
110           # Parse and compile Foo code
111           #===========================================================
112           sub build {
113               my $o = shift;
114               my $code = $o->{API}{code};
115               my $pattern = $o->{ILSM}{PATTERN};
116               $code =~ s/$pattern//g;
117               $code =~ s/bar-//g if $o->{ILSM}{BAR};
118               sleep 1;             # imitate compile delay
119               {
120                   package Foo::Tester;
121                   eval $code;
122               }
123               croak "Foo build failed:\n$@" if $@;
124               my $path = "$o->{API}{install_lib}/auto/$o->{API}{modpname}";
125               my $obj = $o->{API}{location};
126               $o->mkpath($path) unless -d $path;
127               open FOO_OBJ, "> $obj"
128                 or croak "Can't open $obj for output\n$!";
129               print FOO_OBJ $code;
130               close \*FOO_OBJ;
131           }
132
133           #===========================================================
134           # Only needed for interpreted languages
135           #===========================================================
136           sub load {
137               my $o = shift;
138               my $obj = $o->{API}{location};
139               open FOO_OBJ, "< $obj"
140                 or croak "Can't open $obj for output\n$!";
141               my $code = join '', <FOO_OBJ>;
142               close \*FOO_OBJ;
143               eval "package $o->{API}{pkg};\n$code";
144               croak "Unable to load Foo module $obj:\n$@" if $@;
145           }
146
147           #===========================================================
148           # Return a small report about the Foo code.
149           #===========================================================
150           sub info {
151               my $o = shift;
152               my $text = <<'END';
153           This is a small report about the Foo code. Perhaps it contains
154           information about the functions the parser found which will be
155           bound to Perl. It will get included in the text produced by the
156           Inline 'INFO' command.
157           END
158               return $text;
159           }
160
161           1;
162
163       Except for load(), the subroutines in this code are mandatory for an
164       ILSM.  What they do is described below. A few things to note:
165
166       •   "Inline::Foo" must be a subclass of Inline. This is accomplished
167           with:
168
169               @Inline::Foo::ISA = qw(Inline);
170
171       •   The line '"require Inline;"' is not necessary. But it is there to
172           remind you not to say '"use Inline;"'. This will not work.
173
174       •   Remember, it is not valid for a user to say:
175
176               use Inline::Foo;
177
178           "Inline.pm" will detect such usage for you in its "import" method,
179           which is automatically inherited since "Inline::Foo" is a subclass.
180
181       •   In the build function, you normally need to parse your source code.
182           Inline::C uses Parse::RecDescent to do this. Inline::Foo simply
183           uses eval. (After we strip out all occurrences of 'foo-').
184
185           An alternative parsing method that works well for many ILSMs (like
186           Java and Python) is to use the language's compiler itself to parse
187           for you. This works as long as the compiler can be made to give
188           back parse information.
189

THE INLINE API

191       This section is a more formal specification of what functionality
192       you'll need to provide to implement an ILSM.
193
194       When Inline determines that some "Foo" code needs to be compiled it
195       will automatically load your ILSM module. It will then call various
196       subroutines which you need to supply. We'll call these subroutines
197       "callbacks".
198
199       You will need to provide the following 5 callback subroutines.
200
201   The register() Callback
202       This subroutine receives no arguments. It returns a reference to a hash
203       of ILSM meta-data. Inline calls this routine only when it is trying to
204       detect new ILSM-s that have been installed on a given system. Here is
205       an example of the has ref you would return for Foo:
206
207           {
208               language => 'Foo',
209               aliases => ['foo'],
210               type => 'interpreted',
211               suffix => 'foo',
212           };
213
214       The meta-data items have the following meanings:
215
216       language
217           This is the proper name of the language. It is usually implemented
218           as "Inline::X" for a given language 'X'.
219
220       aliases
221           This is a reference to an array of language name aliases. The
222           proper name of a language can only contain word characters.
223           A-Za-z0-9_ An alias can contain any characters except whitespace
224           and quotes. This is useful for names like 'C++' and 'C#'.
225
226       type
227           Must be set to 'compiled' or 'interpreted'. Indicates the category
228           of the language.
229
230       suffix
231           This is the file extension for the cached object that will be
232           created. For 'compiled' languages, it will probably be 'so' or
233           'dll'. The appropriate value is in "Config.pm".
234
235           For interpreted languages, this value can be whatever you want.
236           Python uses "pydat". Foo uses "foo".
237
238   The validate() Callback
239       This routine gets passed all configuration options that were not
240       already handled by the base Inline module. The options are passed as
241       key/value pairs.  It is up to you to validate each option and store its
242       value in the Inline object (which is also passed in). If a particular
243       option is invalid, you should croak with an appropriate error message.
244
245       Note that all the keywords this routine receives will be converted to
246       upper- case by "Inline", whatever case the program gave.
247
248   The build() Callback
249       This subroutine is responsible for doing the parsing and compilation of
250       the Foo source code. The Inline object is passed as the only argument.
251       All pertinent information will be stored in this object. build() is
252       required to create a cache object of a specific name, or to croak with
253       an appropriate error message.
254
255       This is the meat of your ILSM. Since it will most likely be quite
256       complicated, it is probably best that you study an existing ILSM like
257       "Inline::C".
258
259   The load() Callback
260       This method only needs to be provided for interpreted languages. It's
261       responsibility is to start the interpreter.
262
263       For compiled languages, the load routine from "Inline.pm" is called
264       which uses "DynaLoader" to load the shared object or DLL.
265
266   The info() Callback
267       This method is called when the user makes use of the "INFO" shortcut.
268       You should return a string containing a small report about the Inlined
269       code.
270

THE INLINE OBJECT

272       "Inline.pm" creates a hash based Perl object for each section of
273       Inlined source code it receives. This object contains lots of
274       information about the code, the environment, and the configuration
275       options used.
276
277       This object is a hash that is broken into several subhashes. The only
278       two subhashes that an ILSM should use at all are $o->{API} and
279       $o->{ILSM}. The first one contains all of the information that Inline
280       has gather for you in order for you to create/load a cached object of
281       your design. The second one is a repository where your ILSM can freely
282       store data that it might need later on.
283
284       This section will describe all of the Inline object "API" attributes.
285
286       The code Attribute
287           This the actual source code passed in by the user. It is stored as
288           one long string.
289
290       The language Attribute
291           The proper name of the language being used.
292
293       The language_id Attribute
294           The language name specified by the user. Could be 'C++' instead of
295           'CPP'.
296
297       The module Attribute
298           This is the shared object's file name.
299
300       The modfname Attribute
301           This is the shared object's file name.
302
303       The modpname Attribute
304           This is the shared object's installation path extension.
305
306       The version Attribute
307           The version of "Inline.pm" being used.
308
309       The pkg Attribute
310           The Perl package from which this invocation pf Inline was called.
311
312       The install_lib Attribute
313           This is the directory to write the shared object into.
314
315       The build_dir Attribute
316           This is the directory under which you should write all of your
317           build related files.
318
319       The script Attribute
320           This is the name of the script that invoked Inline.
321
322       The location Attribute
323           This is the full path name of the executable object in question.
324
325       The suffix Attribute
326           This is the shared library extension name. (Usually 'so' or 'dll').
327
328   derive_minus_I Method
329       ILSMs may need to run Perl subprocesses with a similar environment to
330       the current one - particularly @INC. This method can be called to
331       return a list of absolute paths to pass to a Perl interpreter to
332       recreate that environment.  You will need to prepend "-I" to each one.
333       This method omits from that list any paths that occur in $ENV{PERL5LIB}
334       or the Perl default libraries since those will be available already.
335

THE INLINE NAMESPACE

337       "Inline.pm" has been set up so that anyone can write their own language
338       support modules. It further allows anyone to write a different
339       implementation of an existing Inline language, like C for instance. You
340       can distribute that module on the CPAN.
341
342       If you have plans to implement and distribute an Inline module, I would
343       ask that you please work with the Inline community. We can be reached
344       at the Inline mailing list: inline@perl.org (Send mail to
345       inline-subscribe@perl.org to subscribe). Here you should find the
346       advice and assistance needed to make your module a success.
347
348       The Inline community will decide if your implementation of COBOL will
349       be distributed as the official "Inline::COBOL" or should use an
350       alternate namespace. In matters of dispute, I (Ingy döt Net) retain
351       final authority.  (and I hope not to need use of it :-) Actually
352       modules@perl.org retains the final authority.
353
354       But even if you want to work alone, you are free and welcome to write
355       and distribute Inline language support modules on CPAN. You'll just
356       need to distribute them under a different package name.
357

SEE ALSO

359       For generic information about Inline, see Inline.
360
361       For information about using Inline with C see Inline::C.
362
363       For information on supported languages and platforms see Inline-
364       Support.
365
366       Inline's mailing list is inline@perl.org
367
368       To subscribe, send email to inline-subscribe@perl.org
369

AUTHOR

371       Ingy döt Net <ingy@cpan.org>
372
374       Copyright 2000-2019. Ingy döt Net.
375
376       Copyright 2008, 2010, 2011. Sisyphus.
377
378       This program is free software; you can redistribute it and/or modify it
379       under the same terms as Perl itself.
380
381       See <http://www.perl.com/perl/misc/Artistic.html>
382
383
384
385perl v5.36.0                      2023-01-20                    Inline::API(3)
Impressum