1Inline::API(3) User Contributed Perl Documentation Inline::API(3)
2
6 Inline-API - How to bind a programming language to Perl using Inline.pm
7
9 #!/usr/bin/perl
10 use Inline Foo;
12 say_it('foo'); # Use Foo to print "Hello, Foo"
13 __Foo__
15 foo-sub say_it {
16 foo-my $foo = foo-shift;
17 foo-print "Hello, $foo\n";
18 }
19
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 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 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 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 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 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
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 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 #===========================================================
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 #===========================================================
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 sub usage_config_bar {
83 "Invalid value for Inline::Foo config option BAR";
84 }
85 #===========================================================
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 #===========================================================
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 #===========================================================
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 #===========================================================
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 1;
162 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 • "Inline::Foo" must be a subclass of Inline. This is accomplished
167 with:
168 @Inline::Foo::ISA = qw(Inline);
170 • 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 • Remember, it is not valid for a user to say:
175 use Inline::Foo;
177 "Inline.pm" will detect such usage for you in its "import" method,
179 which is automatically inherited since "Inline::Foo" is a subclass.
180 • 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 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
191 This section is a more formal specification of what functionality
192 you'll need to provide to implement an ILSM.
193 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 You will need to provide the following 5 callback subroutines.
200 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 {
208 language => 'Foo',
209 aliases => ['foo'],
210 type => 'interpreted',
211 suffix => 'foo',
212 };
213 The meta-data items have the following meanings:
215 language
217 This is the proper name of the language. It is usually implemented
218 as "Inline::X" for a given language 'X'.
219 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 type
227 Must be set to 'compiled' or 'interpreted'. Indicates the category
228 of the language.
229 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 For interpreted languages, this value can be whatever you want.
236 Python uses "pydat". Foo uses "foo".
237 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 Note that all the keywords this routine receives will be converted to
246 upper- case by "Inline", whatever case the program gave.
247 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 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 The load() Callback
260 This method only needs to be provided for interpreted languages. It's
261 responsibility is to start the interpreter.
262 For compiled languages, the load routine from "Inline.pm" is called
264 which uses "DynaLoader" to load the shared object or DLL.
265 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
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 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 This section will describe all of the Inline object "API" attributes.
285 The code Attribute
287 This the actual source code passed in by the user. It is stored as
288 one long string.
289 The language Attribute
291 The proper name of the language being used.
292 The language_id Attribute
294 The language name specified by the user. Could be 'C++' instead of
295 'CPP'.
296 The module Attribute
298 This is the shared object's file name.
299 The modfname Attribute
301 This is the shared object's file name.
302 The modpname Attribute
304 This is the shared object's installation path extension.
305 The version Attribute
307 The version of "Inline.pm" being used.
308 The pkg Attribute
310 The Perl package from which this invocation pf Inline was called.
311 The install_lib Attribute
313 This is the directory to write the shared object into.
314 The build_dir Attribute
316 This is the directory under which you should write all of your
317 build related files.
318 The script Attribute
320 This is the name of the script that invoked Inline.
321 The location Attribute
323 This is the full path name of the executable object in question.
324 The suffix Attribute
326 This is the shared library extension name. (Usually 'so' or 'dll').
327 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
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 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 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 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
359 For generic information about Inline, see Inline.
360 For information about using Inline with C see Inline::C.
362 For information on supported languages and platforms see Inline-
364 Support.
365 Inline's mailing list is inline@perl.org
367 To subscribe, send email to inline-subscribe@perl.org
369
371 Ingy döt Net <ingy@cpan.org>
372
374 Copyright 2000-2019. Ingy döt Net.
375 Copyright 2008, 2010, 2011. Sisyphus.
377 This program is free software; you can redistribute it and/or modify it
379 under the same terms as Perl itself.
380 See <http://www.perl.com/perl/misc/Artistic.html>
382perl v5.32.1 2021-01-27 Inline::API(3)