In a sense, perl (the C program) is a good example of embedding Perl
(the language), so I'll demonstrate embedding with I<miniperlmain.c>,
-included in the source distribution. Here's a bastardized, nonportable
+included in the source distribution. Here's a bastardized, non-portable
version of I<miniperlmain.c> containing the essentials of embedding:
#include <EXTERN.h> /* from the Perl distribution */
Notice that we don't use the C<env> pointer. Normally handed to
C<perl_parse> as its final argument, C<env> here is replaced by
-C<NULL>, which means that the current environment will be used. The macros
-PERL_SYS_INIT3() and PERL_SYS_TERM() provide system-specific tune up
-of the C runtime environment necessary to run Perl interpreters; since
-PERL_SYS_INIT3() may change C<env>, it may be more appropriate to provide
-C<env> as an argument to perl_parse().
+C<NULL>, which means that the current environment will be used.
+
+The macros PERL_SYS_INIT3() and PERL_SYS_TERM() provide system-specific
+tune up of the C runtime environment necessary to run Perl interpreters;
+they should only be called once regardless of how many interpreters you
+create or destroy. Call PERL_SYS_INIT3() before you create your first
+interpreter, and PERL_SYS_TERM() after you free your last interpreter.
+
+Since PERL_SYS_INIT3() may change C<env>, it may be more appropriate to
+provide C<env> as an argument to perl_parse().
+
+Also notice that no matter what arguments you pass to perl_parse(),
+PERL_SYS_INIT3() must be invoked on the C main() argc, argv and env and
+only once.
Now compile this program (I'll call it I<interp.c>) into an executable:
main (int argc, char **argv, char **env)
{
- STRLEN n_a;
char *embedding[] = { "", "-e", "0" };
PERL_SYS_INIT3(&argc,&argv,&env);
/** Treat $a as an integer **/
eval_pv("$a = 3; $a **= 2", TRUE);
- printf("a = %d\n", SvIV(get_sv("a", FALSE)));
+ printf("a = %d\n", SvIV(get_sv("a", 0)));
/** Treat $a as a float **/
eval_pv("$a = 3.14; $a **= 2", TRUE);
- printf("a = %f\n", SvNV(get_sv("a", FALSE)));
+ printf("a = %f\n", SvNV(get_sv("a", 0)));
/** Treat $a as a string **/
eval_pv("$a = 'rekcaH lreP rehtonA tsuJ'; $a = reverse($a);", TRUE);
- printf("a = %s\n", SvPV(get_sv("a", FALSE), n_a));
+ printf("a = %s\n", SvPV_nolen(get_sv("a", 0)));
perl_destruct(my_perl);
perl_free(my_perl);
a = Just Another Perl Hacker
In the example above, we've created a global variable to temporarily
-store the computed value of our eval'd expression. It is also
+store the computed value of our eval'ed expression. It is also
possible and in most cases a better strategy to fetch the return value
from I<eval_pv()> instead. Example:
...
- STRLEN n_a;
SV *val = eval_pv("reverse 'rekcaH lreP rehtonA tsuJ'", TRUE);
- printf("%s\n", SvPV(val,n_a));
+ printf("%s\n", SvPV_nolen(val));
...
This way, we avoid namespace pollution by not creating global
{
dSP;
SV* retval;
- STRLEN n_a;
+
PUSHMARK(SP);
eval_sv(sv, G_SCALAR);
PUTBACK;
if (croak_on_error && SvTRUE(ERRSV))
- croak(SvPVx(ERRSV, n_a));
+ croak(SvPVx_nolen(ERRSV));
return retval;
}
I32 match(SV *string, char *pattern)
{
- SV *command = NEWSV(1099, 0), *retval;
- STRLEN n_a;
+ SV *command = newSV(0), *retval;
sv_setpvf(command, "my $string = '%s'; $string =~ %s",
- SvPV(string,n_a), pattern);
+ SvPV_nolen(string), pattern);
retval = my_eval_sv(command, TRUE);
SvREFCNT_dec(command);
I32 substitute(SV **string, char *pattern)
{
- SV *command = NEWSV(1099, 0), *retval;
- STRLEN n_a;
+ SV *command = newSV(0), *retval;
sv_setpvf(command, "$string = '%s'; ($string =~ %s)",
- SvPV(*string,n_a), pattern);
+ SvPV_nolen(*string), pattern);
retval = my_eval_sv(command, TRUE);
SvREFCNT_dec(command);
- *string = get_sv("string", FALSE);
+ *string = get_sv("string", 0);
return SvIV(retval);
}
I32 matches(SV *string, char *pattern, AV **match_list)
{
- SV *command = NEWSV(1099, 0);
+ SV *command = newSV(0);
I32 num_matches;
- STRLEN n_a;
sv_setpvf(command, "my $string = '%s'; @array = ($string =~ %s)",
- SvPV(string,n_a), pattern);
+ SvPV_nolen(string), pattern);
my_eval_sv(command, TRUE);
SvREFCNT_dec(command);
- *match_list = get_av("array", FALSE);
- num_matches = av_len(*match_list) + 1; /** assume $[ is 0 **/
+ *match_list = get_av("array", 0);
+ num_matches = av_len(*match_list) + 1;
return num_matches;
}
AV *match_list;
I32 num_matches, i;
SV *text;
- STRLEN n_a;
PERL_SYS_INIT3(&argc,&argv,&env);
my_perl = perl_alloc();
perl_parse(my_perl, NULL, 3, embedding, NULL);
PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
- text = NEWSV(1099,0);
+ text = newSV(0);
sv_setpv(text, "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 "
printf("matches: m/(wi..)/g found %d matches...\n", num_matches);
for (i = 0; i < num_matches; i++)
- printf("match: %s\n", SvPV(*av_fetch(match_list, i, FALSE),n_a));
+ printf("match: %s\n", SvPV_nolen(*av_fetch(match_list, i, FALSE)));
printf("\n");
/** Remove all vowels from text **/
if (num_matches) {
printf("substitute: s/[aeiou]//gi...%d substitutions made.\n",
num_matches);
- printf("Now text is: %s\n\n", SvPV(text,n_a));
+ printf("Now text is: %s\n\n", SvPV_nolen(text));
}
/** Attempt a substitution **/
char *args[] = { "", DO_CLEAN, NULL };
char filename[BUFFER_SIZE];
int exitstatus = 0;
- STRLEN n_a;
PERL_SYS_INIT3(&argc,&argv,&env);
if((my_perl = perl_alloc()) == NULL) {
/* check $@ */
if(SvTRUE(ERRSV))
- fprintf(stderr, "eval error: %s\n", SvPV(ERRSV,n_a));
+ fprintf(stderr, "eval error: %s\n", SvPV_nolen(ERRSV));
}
}
not be initialized correctly between consecutive runs and your
application may crash.
+See also L<perlxs/Thread-aware system interfaces>.
+
Using C<-Dusethreads -Duseithreads> rather than C<-Dusemultiplicity>
is more appropriate if you intend to run multiple interpreters
concurrently in different threads, because it enables support for
#include <perl.h>
/* we're going to embed two interpreters */
- /* we're going to embed two interpreters */
#define SAY_HELLO "-e", "print qq(Hi, I'm $^X\n)"
Consult L<perlxs>, L<perlguts>, and L<perlapi> for more details.
-=head1 Embedding Perl under Win32
-
-In general, all of the source code shown here should work unmodified under
-Windows.
-
-However, there are some caveats about the command-line examples shown.
-For starters, backticks won't work under the Win32 native command shell.
-The ExtUtils::Embed kit on CPAN ships with a script called
-B<genmake>, which generates a simple makefile to build a program from
-a single C source file. It can be used like this:
-
- C:\ExtUtils-Embed\eg> perl genmake interp.c
- C:\ExtUtils-Embed\eg> nmake
- C:\ExtUtils-Embed\eg> interp -e "print qq{I'm embedded in Win32!\n}"
-
-You may wish to use a more robust environment such as the Microsoft
-Developer Studio. In this case, run this to generate perlxsi.c:
-
- perl -MExtUtils::Embed -e xsinit
-
-Create a new project and Insert -> Files into Project: perlxsi.c,
-perl.lib, and your own source files, e.g. interp.c. Typically you'll
-find perl.lib in B<C:\perl\lib\CORE>, if not, you should see the
-B<CORE> directory relative to C<perl -V:archlib>. The studio will
-also need this path so it knows where to find Perl include files.
-This path can be added via the Tools -> Options -> Directories menu.
-Finally, select Build -> Build interp.exe and you're ready to go.
-
=head1 Hiding Perl_
-If you completely hide the short forms forms of the Perl public API,
+If you completely hide the short forms of the Perl public API,
add -DPERL_NO_SHORT_NAMES to the compilation flags. This means that
for example instead of writing
Perl_warn(aTHX_ "%d bottles of beer on the wall", bottlecount);
-(See L<perlguts/Background and PERL_IMPLICIT_CONTEXT for the explanation
-of the C<aTHX_>.> ) Hiding the short forms is very useful for avoiding
+(See L<perlguts/"Background and PERL_IMPLICIT_CONTEXT"> for the explanation
+of the C<aTHX_>. ) Hiding the short forms is very useful for avoiding
all sorts of nasty (C preprocessor or otherwise) conflicts with other
software packages (Perl defines about 2400 APIs with these short names,
take or leave few hundred, so there certainly is room for conflict.)
Copyright (C) 1995, 1996, 1997, 1998 Doug MacEachern and Jon Orwant. All
Rights Reserved.
-Permission is granted to make and distribute verbatim copies of this
-documentation provided the copyright notice and this permission notice are
-preserved on all copies.
-
-Permission is granted to copy and distribute modified versions of this
-documentation under the conditions for verbatim copying, provided also
-that they are marked clearly as modified versions, that the authors'
-names and title are unchanged (though subtitles and additional
-authors' names may be added), and that the entire resulting derived
-work is distributed under the terms of a permission notice identical
-to this one.
-
-Permission is granted to copy and distribute translations of this
-documentation into another language, under the above conditions for
-modified versions.
+This document may be distributed under the same terms as Perl itself.
https://perl5.git.perl.org / perl5.git / blobdiff