perl5.002beta3
[perl.git] / pod / perlembed.pod
1 =head1 NAME
2
3 perlembed - how to embed perl in your C program
4
5 =head1 DESCRIPTION
6
7 =head2 PREAMBLE
8
9 Do you want to:
10
11 =over 5
12
13 =item B<Use C from Perl?>  
14
15 Read L<perlcall> and L<perlxs>.
16
17 =item B<Use a UNIX program from Perl?>  
18
19 Read about backquotes and L<perlfunc/system> and L<perlfunc/exec>.
20
21 =item B<Use Perl from Perl?>  
22
23 Read about L<perlfunc/do> and L<perlfunc/eval> and L<perlmod/use> 
24 and L<perlmod/require>.
25
26 =item B<Use C from C?>  
27
28 Rethink your design.
29
30 =item B<Use Perl from C?>  
31
32 Read on...
33
34 =back
35
36 =head2 ROADMAP
37
38 L<Compiling your C program>
39
40 There's one example in each of the five sections:
41
42 L<Adding a Perl interpreter to your C program>
43
44 L<Calling a Perl subroutine from your C program>
45
46 L<Evaluating a Perl statement from your C program>
47
48 L<Performing Perl pattern matches and substitutions from your C program>
49
50 L<Fiddling with the Perl stack from your C program>
51
52 This documentation is UNIX specific.
53
54 =head2 Compiling your C program
55
56 Every C program that uses Perl must link in the I<perl library>.  
57
58 What's that, you ask?  Perl is itself written in C; the perl library
59 is the collection of compiled C programs that were used to create your
60 perl executable (I</usr/bin/perl> or equivalent).  (Corollary: you
61 can't use Perl from your C program unless Perl has been compiled on
62 your machine, or installed properly--that's why you shouldn't blithely
63 copy Perl executables from machine to machine without also copying the
64 I<lib> directory.)
65
66 Your C program will--usually--allocate, "run", and deallocate a
67 I<PerlInterpreter> object, which is defined in the perl library.  
68
69 If your copy of Perl is recent enough to contain this documentation
70 (5.002 or later), then the perl library (and I<EXTERN.h> and
71 I<perl.h>, which you'll also need) will
72 reside in a directory resembling this:
73
74     /usr/local/lib/perl5/your_architecture_here/CORE
75
76 or perhaps just
77
78     /usr/local/lib/perl5/CORE
79
80 or maybe something like
81
82     /usr/opt/perl5/CORE
83
84 Execute this statement for a hint about where to find CORE:
85
86     perl -e 'use Config; print $Config{archlib}'
87
88 Here's how you might compile the example in the next section,
89 L<Adding a Perl interpreter to your C program>,
90 on a DEC Alpha running the OSF operating system:
91
92     % cc -o interp interp.c -L/usr/local/lib/perl5/alpha-dec_osf/CORE 
93     -I/usr/local/lib/perl5/alpha-dec_osf/CORE -lperl -lm
94
95 You'll have to choose the appropriate compiler (I<cc>, I<gcc>, et al.)  and
96 library directory (I</usr/local/lib/...>)  for your machine.  If your
97 compiler complains that certain functions are undefined, or that it
98 can't locate I<-lperl>, then you need to change the path following the
99 -L.  If it complains that it can't find I<EXTERN.h> or I<perl.h>, you need
100 to change the path following the -I.  
101
102 You may have to add extra libraries as well.  Which ones?
103 Perhaps those printed by 
104
105    perl -e 'use Config; print $Config{libs}'
106
107 =head2 Adding a Perl interpreter to your C program
108
109 In a sense, perl (the C program) is a good example of embedding Perl
110 (the language), so I'll demonstrate embedding with I<miniperlmain.c>,
111 from the source distribution.  Here's a bastardized, non-portable version of
112 I<miniperlmain.c> containing the essentials of embedding:
113
114     #include <stdio.h>
115     #include <EXTERN.h>               /* from the Perl distribution     */
116     #include <perl.h>                 /* from the Perl distribution     */
117     
118     static PerlInterpreter *my_perl;  /***    The Perl interpreter    ***/
119    
120     int main(int argc, char **argv, char **env)
121     {
122         my_perl = perl_alloc();
123         perl_construct(my_perl);
124         perl_parse(my_perl, NULL, argc, argv, env);
125         perl_run(my_perl);
126         perl_destruct(my_perl);
127         perl_free(my_perl);
128     }
129
130 Now compile this program (I'll call it I<interp.c>) into an executable:
131
132     % cc -o interp interp.c -L/usr/local/lib/perl5/alpha-dec_osf/CORE 
133     -I/usr/local/lib/perl5/alpha-dec_osf/CORE -lperl -lm
134
135 After a successful compilation, you'll be able to use I<interp> just
136 like perl itself:
137
138     % interp
139     print "Pretty Good Perl \n";
140     print "10890 - 9801 is ", 10890 - 9801;
141     <CTRL-D>
142     Pretty Good Perl
143     10890 - 9801 is 1089
144
145 or
146
147     % interp -e 'printf("%x", 3735928559)'
148     deadbeef
149
150 You can also read and execute Perl statements from a file while in the
151 midst of your C program, by placing the filename in I<argv[1]> before
152 calling I<perl_run()>.  
153
154 =head2 Calling a Perl subroutine from your C program
155
156 To call individual Perl subroutines, you'll need to remove the call to
157 I<perl_run()> and replace it with a call to I<perl_call_argv()>.
158
159 That's shown below, in a program I'll call I<showtime.c>.
160
161     #include <stdio.h>
162     #include <EXTERN.h>
163     #include <perl.h>                 
164     
165     static PerlInterpreter *my_perl;  
166     
167     int main(int argc, char **argv, char **env)
168     {
169         my_perl = perl_alloc();
170         perl_construct(my_perl);
171     
172         perl_parse(my_perl, NULL, argc, argv, env);
173     
174                                      /*** This replaces perl_run() ***/
175         perl_call_argv("showtime", G_DISCARD | G_NOARGS, argv);
176         perl_destruct(my_perl);
177         perl_free(my_perl);
178     }
179
180 where I<showtime> is a Perl subroutine that takes no arguments (that's the
181 I<G_NOARGS>) and for which I'll ignore the return value (that's the 
182 I<G_DISCARD>).  Those flags, and others, are discussed in L<perlcall>.
183
184 I'll define the I<showtime> subroutine in a file called I<showtime.pl>:
185
186     print "I shan't be printed.";
187     
188     sub showtime {
189         print time;
190     }
191
192 Simple enough.  Now compile and run:
193
194     % cc -o showtime showtime.c -L/usr/local/lib/perl5/alpha-dec_osf/CORE 
195     -I/usr/local/lib/perl5/alpha-dec_osf/CORE -lperl -lm
196     
197     % showtime showtime.pl
198     818284590
199
200 yielding the number of seconds that elapsed between January 1, 1970
201 (the beginning of the UNIX epoch), and the moment I began writing this
202 sentence.
203
204 If you want to pass some arguments to the Perl subroutine, or
205 you want to access the return value, you'll need to manipulate the
206 Perl stack, demonstrated in the last section of this document: 
207 L<Fiddling with the Perl stack from your C program>
208
209 =head2 Evaluating a Perl statement from your C program
210
211 NOTE: This section, and the next, employ some very brittle techniques
212 for evaluting strings of Perl code.  Perl 5.002 contains some nifty
213 features that enable A Better Way (such as with L<perlguts/perl_eval_sv>).
214 Look for updates to this document soon.
215
216 One way to evaluate a Perl string is to define a function (we'll call 
217 ours I<perl_eval()>) that wraps around Perl's L<perlfunc/eval>.
218
219 Arguably, this is the only routine you'll ever need to execute
220 snippets of Perl code from within your C program.  Your string can be
221 as long as you wish; it can contain multiple statements; it can
222 use L<perlmod/require> or L<perlfunc/do> to include external Perl
223 files.  
224
225 Our I<perl_eval()> lets us evaluate individual Perl strings, and then 
226 extract variables for coercion into C types.  The following program, 
227 I<string.c>, executes three Perl strings, extracting an C<int> from
228 the first, a C<float> from the second, and a C<char *> from the third.
229
230    #include <stdio.h>
231    #include <EXTERN.h>
232    #include <perl.h>
233    
234    static PerlInterpreter *my_perl;
235    
236    int perl_eval(char *string)
237    {
238      char *argv[2];
239      argv[0] = string;
240      argv[1] = NULL;
241      perl_call_argv("_eval_", 0, argv);
242    }
243    
244    main (int argc, char **argv, char **env)
245    {
246      char *embedding[] = { "", "-e", "sub _eval_ { eval $_[0] }" };
247      STRLEN length;
248    
249      my_perl = perl_alloc();
250      perl_construct( my_perl );
251    
252      perl_parse(my_perl, NULL, 3, embedding, env);
253    
254                                        /** Treat $a as an integer **/
255      perl_eval("$a = 3; $a **= 2");
256      printf("a = %d\n", SvIV(perl_get_sv("a", FALSE)));
257    
258                                        /** Treat $a as a float **/
259      perl_eval("$a = 3.14; $a **= 2");
260      printf("a = %f\n", SvNV(perl_get_sv("a", FALSE)));
261    
262                                        /** Treat $a as a string **/
263      perl_eval("$a = 'rekcaH lreP rehtonA tsuJ'; $a = reverse($a); ");
264      printf("a = %s\n", SvPV(perl_get_sv("a", FALSE), length));
265    
266      perl_destruct(my_perl);
267      perl_free(my_perl);
268    }
269
270 All of those strange functions with I<sv> in their names help convert Perl scalars to C types.  They're described in L<perlguts>.
271
272 If you compile and run I<string.c>, you'll see the results of using
273 I<SvIV()> to create an C<int>, I<SvNV()> to create a C<float>, and
274 I<SvPV()> to create a string:
275
276    a = 9
277    a = 9.859600
278    a = Just Another Perl Hacker
279
280
281 =head2 Performing Perl pattern matches and substitutions from your C program
282
283 Our I<perl_eval()> lets us evaluate strings of Perl code, so we can
284 define some functions that use it to "specialize" in matches and
285 substitutions: I<match()>, I<substitute()>, and I<matches()>.
286
287    char match(char *string, char *pattern); 
288
289 Given a string and a pattern (e.g. "m/clasp/" or "/\b\w*\b/", which in
290 your program might be represented as C<"/\\b\\w*\\b/">),
291 returns 1 if the string matches the pattern and 0 otherwise.
292
293
294    int substitute(char *string[], char *pattern);
295
296 Given a pointer to a string and an "=~" operation (e.g. "s/bob/robert/g" or 
297 "tr[A-Z][a-z]"), modifies the string according to the operation,
298 returning the number of substitutions made.
299
300    int matches(char *string, char *pattern, char **matches[]);
301
302 Given a string, a pattern, and a pointer to an empty array of strings,
303 evaluates C<$string =~ $pattern> in an array context, and fills in
304 I<matches> with the array elements (allocating memory as it does so), 
305 returning the number of matches found.
306
307 Here's a sample program, I<match.c>, that uses all three:
308
309    #include <stdio.h>
310    #include <EXTERN.h>
311    #include <perl.h>
312    
313    static PerlInterpreter *my_perl;
314    
315    int eval(char *string)
316    {
317      char *argv[2];
318      argv[0] = string;
319      argv[1] = NULL;
320      perl_call_argv("_eval_", 0, argv);
321    }
322    
323    /** match(string, pattern)
324     ** 
325     ** Used for matches in a scalar context.
326     **
327     ** Returns 1 if the match was successful; 0 otherwise. 
328     **/
329    char match(char *string, char *pattern) 
330    {
331      char *command;
332      command = malloc(sizeof(char) * strlen(string) + strlen(pattern) + 37);
333      sprintf(command, "$string = '%s'; $return = $string =~ %s", 
334         string, pattern); 
335      perl_eval(command);
336      free(command);
337      return SvIV(perl_get_sv("return", FALSE));
338    }
339    
340    /** substitute(string, pattern)
341     **
342     ** Used for =~ operations that modify their left-hand side (s/// and tr///)
343     **
344     ** Returns the number of successful matches, and
345     ** modifies the input string if there were any.
346     **/
347    int substitute(char *string[], char *pattern) 
348    {
349      char *command;
350      STRLEN length;
351      command = malloc(sizeof(char) * strlen(*string) + strlen(pattern) + 35);
352      sprintf(command, "$string = '%s'; $ret = ($string =~ %s)", 
353         *string, pattern); 
354      perl_eval(command);
355      free(command);
356      *string = SvPV(perl_get_sv("string", FALSE), length);
357      return SvIV(perl_get_sv("ret", FALSE));
358    }
359    
360    /** matches(string, pattern, matches)
361     ** 
362     ** Used for matches in an array context.
363     **
364     ** Returns the number of matches, 
365     ** and fills in **matches with the matching substrings (allocates memory!)
366     **/
367    int matches(char *string, char *pattern, char **matches[]) 
368    {
369      char *command;
370      SV *current_match;
371      AV *array;
372      I32 num_matches;
373      STRLEN length;
374      int i;
375    
376      command = malloc(sizeof(char) * strlen(string) + strlen(pattern) + 38);
377      sprintf(command, "$string = '%s'; @array = ($string =~ %s)", 
378         string, pattern); 
379      perl_eval(command);
380      free(command);
381      array = perl_get_av("array", FALSE);
382      num_matches = av_len(array) + 1; /** assume $[ is 0 **/
383      *matches = (char **) malloc(sizeof(char *) * num_matches);
384      for (i = 0; i <= num_matches; i++) {  
385        current_match = av_shift(array);
386        (*matches)[i] = SvPV(current_match, length);
387      }
388      return num_matches;
389    }
390    
391    main (int argc, char **argv, char **env)
392    {
393      char *embedding[] = { "", "-e", "sub _eval_ { eval $_[0] }" };
394      char *text, **matches;
395      int num_matches, i;
396      int j;
397    
398      my_perl = perl_alloc();
399      perl_construct( my_perl );
400    
401      perl_parse(my_perl, NULL, 3, embedding, env);
402    
403      text = (char *) malloc(sizeof(char) * 486); /** A long string follows! **/
404      sprintf(text, "%s", "When he is at a convenience store and the bill comes to some amount like 76 cents, Maynard is aware that there is something he *should* do, something that will enable him to get back a quarter, but he has no idea *what*.  He fumbles through his red squeezey changepurse and gives the boy three extra pennies with his dollar, hoping that he might luck into the correct amount.  The boy gives him back two of his own pennies and then the big shiny quarter that is his prize. -RICHH");  
405    
406      if (perl_match(text, "m/quarter/")) /** Does text contain 'quarter'? **/
407        printf("perl_match: Text contains the word 'quarter'.\n\n");
408      else 
409        printf("perl_match: Text doesn't contain the word 'quarter'.\n\n");
410    
411      if (perl_match(text, "m/eighth/")) /** Does text contain 'eighth'? **/
412        printf("perl_match: Text contains the word 'eighth'.\n\n");
413      else 
414        printf("perl_match: Text doesn't contain the word 'eighth'.\n\n");
415    
416                                        /** Match all occurrences of /wi../ **/
417      num_matches = perl_matches(text, "m/(wi..)/g", &matches);
418      
419      printf("perl_matches: m/(wi..)/g found %d matches...\n", num_matches);
420      for (i = 0; i < num_matches; i++) 
421        printf("match: %s\n", matches[i]);
422      printf("\n");
423      for (i = 0; i < num_matches; i++) {
424        free(matches[i]);
425      }
426      free(matches);
427    
428                                        /** Remove all vowels from text **/
429      num_matches = perl_substitute(&text, "s/[aeiou]//gi");
430      if (num_matches) {
431        printf("perl_substitute: s/[aeiou]//gi...%d substitutions made.\n", 
432         num_matches);
433        printf("Now text is: %s\n\n", text);
434      }
435    
436                                        /** Attempt a substitution
437      if (!perl_substitute(&text, "s/Perl/C/")) {
438        printf("perl_substitute: s/Perl/C...No substitution made.\n\n");
439      }
440    
441      free(text);
442    
443      perl_destruct(my_perl);
444      perl_free(my_perl);
445    }
446
447 which produces the output
448
449    perl_match: Text contains the word 'quarter'.
450    
451    perl_match: Text doesn't contain the word 'eighth'.
452    
453    perl_matches: m/(wi..)/g found 2 matches...
454    match: will
455    match: with
456    
457    perl_substitute: s/[aeiou]//gi...139 substitutions made.
458    Now text is: Whn h s t  cnvnnc str nd th bll cms t sm mnt lk 76 cnts, Mynrd s wr tht thr s smthng h *shld* d, smthng tht wll nbl hm t gt bck  qrtr, bt h hs n d *wht*.  H fmbls thrgh hs rd sqzy chngprs nd gvs th by thr xtr pnns wth hs dllr, hpng tht h mght lck nt th crrct mnt.  Th by gvs hm bck tw f hs wn pnns nd thn th bg shny qrtr tht s hs prz. -RCHH
459    
460    perl_substitute: s/Perl/C...No substitution made.
461       
462 =head2 Fiddling with the Perl stack from your C program
463
464 When trying to explain stacks, most computer science textbooks mumble
465 something about spring-loaded columns of cafeteria plates: the last
466 thing you pushed on the stack is the first thing you pop off.  That'll
467 do for our purposes: your C program will push some arguments onto "the Perl
468 stack", shut its eyes while some magic happens, and then pop the
469 results--the return value of your Perl subroutine--off the stack.
470    
471 First you'll need to know how to convert between C types and Perl
472 types, with newSViv() and sv_setnv() and newAV() and all their
473 friends.  They're described in L<perlguts>.
474
475 Then you'll need to know how to manipulate the Perl stack.  That's
476 described in L<perlcall>.
477
478 Once you've understood those, embedding Perl in C is easy.  
479
480 Since C has no built-in function for integer exponentiation, let's
481 make Perl's ** operator available to it (this is less useful than it
482 sounds, since Perl implements ** with C's I<pow()> function).  First
483 I'll create a stub exponentiation function in I<power.pl>:
484
485     sub expo {
486         my ($a, $b) = @_;
487         return $a ** $b;
488     }
489
490 Now I'll create a C program, I<power.c>, with a function
491 I<PerlPower()> that contains all the perlguts necessary to push the
492 two arguments into I<expo()> and to pop the return value out.  Take a
493 deep breath...
494
495     #include <stdio.h>
496     #include <EXTERN.h>
497     #include <perl.h>
498     
499     static PerlInterpreter *my_perl;
500     
501     static void
502     PerlPower(int a, int b)
503     {
504       dSP;                            /* initialize stack pointer      */
505       ENTER;                          /* everything created after here */
506       SAVETMPS;                       /* ...is a temporary variable.   */
507       PUSHMARK(sp);                   /* remember the stack pointer    */
508       XPUSHs(sv_2mortal(newSViv(a))); /* push the base onto the stack  */
509       XPUSHs(sv_2mortal(newSViv(b))); /* push the exponent onto stack  */
510       PUTBACK;                      /* make local stack pointer global */
511       perl_call_pv("expo", G_SCALAR); /* call the function             */
512       SPAGAIN;                        /* refresh stack pointer         */
513                                     /* pop the return value from stack */
514       printf ("%d to the %dth power is %d.\n", a, b, POPi);
515       PUTBACK;                               
516       FREETMPS;                       /* free that return value        */
517       LEAVE;                       /* ...and the XPUSHed "mortal" args.*/
518     }
519     
520     int main (int argc, char **argv, char **env) 
521     {
522       char *my_argv[2];
523     
524       my_perl = perl_alloc();
525       perl_construct( my_perl );
526     
527       my_argv[1] = (char *) malloc(10);
528       sprintf(my_argv[1], "power.pl");
529     
530       perl_parse(my_perl, NULL, argc, my_argv, env);
531       
532       PerlPower(3, 4);                      /*** Compute 3 ** 4 ***/
533     
534       perl_destruct(my_perl);
535       perl_free(my_perl);
536     }
537     
538
539
540 Compile and run:
541
542     % cc -o power power.c -L/usr/local/lib/perl5/alpha-dec_osf/CORE 
543     -I/usr/local/lib/perl5/alpha-dec_osf/CORE -lperl -lm
544     
545     % power 
546     3 to the 4th power is 81.
547
548 =head1 MORAL
549
550 You can sometimes I<write faster code> in C, but
551 you can always I<write code faster> in Perl.  Since you can use
552 each from the other, combine them as you wish.
553
554
555 =head1 AUTHOR
556
557 Jon Orwant F<E<lt>orwant@media.mit.eduE<gt>>, with contributions from
558 Tim Bunce, Tom Christiansen, Dov Grobgeld, and Ilya Zakharevich.
559
560 December 18, 1995
561
562 Some of this material is excerpted from my book: I<Perl 5 Interactive>, 
563 Waite Group Press, 1996 (ISBN 1-57169-064-6) and appears
564 courtesy of Waite Group Press.
565