X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlembed.pod;h=f7c8e4a3e19b7c1ba50cdff3b90f78147b2ecf15;hb=9949743fb3b989b8694b2a5e666ad6a181918a59;hp=e1ab91eaba91aa25ab0a9061825a9141beb9cbd0;hpb=95b76e31e0b4c4fa94c15c8c06055a7dba0b7f75;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlembed.pod b/pod/perlembed.pod index e1ab91e..f7c8e4a 100644 --- a/pod/perlembed.pod +++ b/pod/perlembed.pod @@ -12,7 +12,7 @@ Do you want to: =item B -Read L and L. +Read L, L and L. =item B @@ -20,8 +20,7 @@ Read about back-quotes and about C and C in L. =item B -Read about L and L and L -and L. +Read about do(), eval(), require(), and use() in L. =item B @@ -35,27 +34,49 @@ Read on... =head2 ROADMAP -L +Compiling your C program There's one example in each of the nine sections: -L +=over 4 -L +=item * -L +Adding a Perl interpreter to your C program -L +=item * -L +Calling a Perl subroutine from your C program -L +=item * -L +Evaluating a Perl statement from your C program -L +=item * -L +Performing Perl pattern matches and substitutions from your C program + +=item * + +Fiddling with the Perl stack from your C program + +=item * + +Maintaining a persistent interpreter + +=item * + +Maintaining multiple interpreter instances + +=item * + +Using Perl modules, which themselves use C libraries, from your C program + +=item * + +Embedding Perl under Win32 + +=back =head2 Compiling your C program @@ -96,7 +117,7 @@ Execute this statement for a hint about where to find CORE: perl -MConfig -e 'print $Config{archlib}' Here's how you'd compile the example in the next section, -L, on my Linux box: +Adding a Perl interpreter to your C program, on my Linux box: % gcc -O2 -Dbool=char -DHAS_BOOL -I/usr/local/include -I/usr/local/lib/perl5/i586-linux/5.003/CORE @@ -199,8 +220,8 @@ calling I. =head2 Calling a Perl subroutine from your C program To call individual Perl subroutines, you can use any of the B -functions documented in the L manpage. -In this example we'll use I. +functions documented in L. +In this example we'll use perl_call_argv(). That's shown below, in a program I'll call I. @@ -257,21 +278,20 @@ If you want to pass arguments to the Perl subroutine, you can add strings to the C-terminated C list passed to I. For other data types, or to examine return values, you'll need to manipulate the Perl stack. That's demonstrated in the -last section of this document: L. +last section of this document: Fiddling with the Perl stack from +your C program. =head2 Evaluating a Perl statement from your C program Perl provides two API functions to evaluate pieces of Perl code. -These are L and L. +These are perl_eval_sv() and perl_eval_pv(). Arguably, these are the only routines you'll ever need to execute snippets of Perl code from within your C program. Your code can be as long as you wish; it can contain multiple statements; it can employ -L, L and L to include -external Perl files. +use(), require(), and do() to include external Perl files. -I lets us evaluate individual Perl strings, and then +perl_eval_pv() lets us evaluate individual Perl strings, and then extract variables for coercion into C types. The following program, I, executes three Perl strings, extracting an C from the first, a C from the second, and a C from the third. @@ -320,7 +340,7 @@ I to create a string: In the example above, we've created a global variable to temporarily store the computed value of our eval'd expression. It is also possible and in most cases a better strategy to fetch the return value -from L instead. Example: +from perl_eval_pv() instead. Example: ... SV *val = perl_eval_pv("reverse 'rekcaH lreP rehtonA tsuJ'", TRUE); @@ -370,7 +390,7 @@ been wrapped here): dSP; SV* retval; - PUSHMARK(sp); + PUSHMARK(SP); perl_eval_sv(sv, G_SCALAR); SPAGAIN; @@ -392,7 +412,7 @@ been wrapped here): I32 match(SV *string, char *pattern) { - SV *command = newSV(0), *retval; + SV *command = NEWSV(1099, 0), *retval; sv_setpvf(command, "my $string = '%s'; $string =~ %s", SvPV(string,na), pattern); @@ -413,7 +433,7 @@ been wrapped here): I32 substitute(SV **string, char *pattern) { - SV *command = newSV(0), *retval; + SV *command = NEWSV(1099, 0), *retval; sv_setpvf(command, "$string = '%s'; ($string =~ %s)", SvPV(*string,na), pattern); @@ -435,7 +455,7 @@ been wrapped here): I32 matches(SV *string, char *pattern, AV **match_list) { - SV *command = newSV(0); + SV *command = NEWSV(1099, 0); I32 num_matches; sv_setpvf(command, "my $string = '%s'; @array = ($string =~ %s)", @@ -456,7 +476,7 @@ been wrapped here): char *embedding[] = { "", "-e", "0" }; AV *match_list; I32 num_matches, i; - SV *text = newSV(0); + SV *text = NEWSV(1099,0); perl_construct(my_perl); perl_parse(my_perl, NULL, 3, embedding, NULL); @@ -563,7 +583,7 @@ deep breath... dSP; /* initialize stack pointer */ ENTER; /* everything created after here */ SAVETMPS; /* ...is a temporary variable. */ - PUSHMARK(sp); /* remember the stack pointer */ + PUSHMARK(SP); /* remember the stack pointer */ XPUSHs(sv_2mortal(newSViv(a))); /* push the base onto the stack */ XPUSHs(sv_2mortal(newSViv(b))); /* push the exponent onto stack */ PUTBACK; /* make local stack pointer global */ @@ -626,10 +646,10 @@ troubles. One way to avoid namespace collisions in this scenario is to translate the filename into a guaranteed-unique package name, and then compile -the code into that package using L. In the example +the code into that package using eval(). In the example below, each file will only be compiled once. Or, the application might choose to clean out the symbol table associated with the file -after it's no longer needed. Using L, We'll +after it's no longer needed. Using perl_call_argv(), We'll call the subroutine C which lives in the file C and pass the filename and boolean cleanup/cache flag as arguments. @@ -640,7 +660,7 @@ conditions that cause Perl's symbol table to grow. You might want to add some logic that keeps track of the process size, or restarts itself after a certain number of requests, to ensure that memory consumption is minimized. You'll also want to scope your variables -with L whenever possible. +with my() whenever possible. package Embed::Persistent; @@ -648,6 +668,7 @@ with L whenever possible. use strict; use vars '%Cache'; + use Symbol qw(delete_package); sub valid_package_name { my($string) = @_; @@ -660,20 +681,6 @@ with L whenever possible. return "Embed" . $string; } - #borrowed from Safe.pm - sub delete_package { - my $pkg = shift; - my ($stem, $leaf); - - no strict 'refs'; - $pkg = "main::$pkg\::"; # expand to full symbol table name - ($stem, $leaf) = $pkg =~ m/(.*::)(\w+::)$/; - - my $stem_symtab = *{$stem}{HASH}; - - delete $stem_symtab->{$leaf}; - } - sub eval_file { my($filename, $delete) = @_; my $package = valid_package_name($filename); @@ -1010,7 +1017,7 @@ Dov Grobgeld, and Ilya Zakharevich. Check out Doug's article on embedding in Volume 1, Issue 4 of The Perl Journal. Info about TPJ is available from http://tpj.com. -April 14, 1997 +July 17, 1997 Some of this material is excerpted from Jon Orwant's book: I, Waite Group Press, 1996 (ISBN 1-57169-064-6) and appears