This is Info file perl.info, produced by Makeinfo version 1.68 from the input file bigperl.texi. settitle perl  File: perl.info, Node: perldos, Next: perlhpux, Prev: perlcygwin, Up: Top Perl under DOS, W31, W95. ************************* NAME ==== perldos - Perl under DOS, W31, W95. SYNOPSIS ======== These are instructions for building Perl under DOS (or w??), using DJGPP v2.01 or later. Under w95 long filenames are supported. DESCRIPTION =========== Before you start, you should glance through the README file found in the top-level directory where the Perl distribution was extracted. Make sure you read and understand the terms under which this software is being distributed. This port currently supports MakeMaker (the set of modules that is used to build extensions to perl). Therefore, you should be able to build and install most extensions found in the CPAN sites. Prerequisites ------------- DJGPP DJGPP is a port of GNU C/C++ compiler and development tools to 32-bit, protected-mode environment on Intel 32-bit CPUs running MS-DOS and compatible operating systems, by DJ Delorie and friends. For more details (FAQ), check out the home of DJGPP at: http://www.delorie.com/djgpp/ If you have questions about DJGPP, try posting to the DJGPP newsgroup: comp.os.msdos.djgpp, or use the email gateway djgpp@delorie.com. You can find the full DJGPP distribution on any SimTel.Net mirror all over the world. Like: ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2* You need the following files to build perl (or add new modules): v2/djdev202.zip v2/bnu27b.zip v2gnu/gcc2721b.zip v2gnu/bsh1147b.zip v2gnu/mak3761b.zip v2gnu/fil316b.zip v2gnu/sed118b.zip v2gnu/txt122b.zip v2gnu/dif271b.zip v2gnu/grep21b.zip v2gnu/shl112b.zip v2gnu/gawk303b.zip v2misc/csdpmi4b.zip or possibly any newer version. Pthreads Thread support is not tested in this version of the djgpp perl. Shortcomings of Perl under DOS ------------------------------ Perl under DOS lacks some features of perl under UNIX because of deficiencies in the UNIX-emulation, most notably: * fork() and pipe() * some features of the UNIX filesystem regarding link count and file dates * in-place operation is a little bit broken with short filenames * sockets Building -------- * Unpack the source package `perl5.6*.tar.gz' with djtarx. If you want to use long file names under w95, don't forget to use set LFN=y before unpacking the archive. * Create a "symlink" or copy your bash.exe to sh.exe in your `($DJDIR)/bin' directory. ln -s bash.exe sh.exe And make the `SHELL' environment variable point to this `sh.exe': set SHELL=c:/djgpp/bin/sh.exe (use full path name!) You can do this in `djgpp.env' too. Add this line BEFORE any section definition: +SHELL=%DJDIR%/bin/sh.exe * If you have `split.exe' and `gsplit.exe' in your path, then rename `split.exe' to `djsplit.exe', and `gsplit.exe' to `split.exe'. Copy or link `gecho.exe' to `echo.exe' if you don't have `echo.exe'. Copy or link `gawk.exe' to `awk.exe' if you don't have `awk.exe'. * Chdir to the djgpp subdirectory of perl toplevel and type the following command: configure.bat This will do some preprocessing then run the Configure script for you. The Configure script is interactive, but in most cases you just need to press ENTER. If the script says that your package is incomplete, and asks whether to continue, just answer with Y (this can only happen if you don't use long filenames). When Configure asks about the extensions, I suggest IO and Fcntl, and if you want database handling then SDBM_File or GDBM_File (you need to install gdbm for this one). If you want to use the POSIX extension (this is the default), make sure that the stack size of your `cc1.exe' is at least 512kbyte (you can check this with: `stubedit cc1.exe'). You can use the Configure script in non-interactive mode too. When I built my `perl.exe', I used something like this: configure.bat -des You can find more info about Configure's command line switches in the INSTALL file. When the script ends, and you want to change some values in the generated `config.sh' file, then run sh Configure -S after you made your modifications. IMPORTANT: if you use this -S switch, be sure to delete the CONFIG environment variable before running the script: set CONFIG= * Now you can compile Perl. Type: make Testing ------- Type: make test If you're lucky you should see "All tests successful". But there can be a few failed subtests (less than 5 hopefully) depending on some external conditions (e.g. some subtests fail under linux/dosemu or plain dos with short filenames only). Installation ------------ Type: make install This will copy the newly compiled perl and libraries into your DJGPP directory structure. Perl.exe and the utilities go into `($DJDIR)/bin', and the library goes under `($DJDIR)/lib/perl5'. The pod documentation goes under `($DJDIR)/lib/perl5/pod'. AUTHOR ====== Laszlo Molnar, `laszlo.molnar@eth.ericsson.se' SEE ALSO ======== perl(1).  File: perl.info, Node: perldsc, Next: perllol, Prev: perlref, Up: Top Perl Data Structures Cookbook ***************************** NAME ==== perldsc - Perl Data Structures Cookbook DESCRIPTION =========== The single feature most sorely lacking in the Perl programming language prior to its 5.0 release was complex data structures. Even without direct language support, some valiant programmers did manage to emulate them, but it was hard work and not for the faint of heart. You could occasionally get away with the `$m{$AoA,$b}' notation borrowed from *awk* in which the keys are actually more like a single concatenated string `"$AoA$b"', but traversal and sorting were difficult. More desperate programmers even hacked Perl's internal symbol table directly, a strategy that proved hard to develop and maintain-to put it mildly. The 5.0 release of Perl let us have complex data structures. You may now write something like this and all of a sudden, you'd have a array with three dimensions! for $x (1 .. 10) { for $y (1 .. 10) { for $z (1 .. 10) { $AoA[$x][$y][$z] = $x ** $y + $z; } } } Alas, however simple this may appear, underneath it's a much more elaborate construct than meets the eye! How do you print it out? Why can't you say just `print @AoA'? How do you sort it? How can you pass it to a function or get one of these back from a function? Is is an object? Can you save it to disk to read back later? How do you access whole rows or columns of that matrix? Do all the values have to be numeric? As you see, it's quite easy to become confused. While some small portion of the blame for this can be attributed to the reference-based implementation, it's really more due to a lack of existing documentation with examples designed for the beginner. This document is meant to be a detailed but understandable treatment of the many different sorts of data structures you might want to develop. It should also serve as a cookbook of examples. That way, when you need to create one of these complex data structures, you can just pinch, pilfer, or purloin a drop-in example from here. Let's look at each of these possible constructs in detail. There are separate sections on each of the following: * arrays of arrays * hashes of arrays * arrays of hashes * hashes of hashes * more elaborate constructs But for now, let's look at general issues common to all these types of data structures. REFERENCES ========== The most important thing to understand about all data structures in Perl - including multidimensional arrays-is that even though they might appear otherwise, Perl `@ARRAY's and `%HASH'es are all internally one-dimensional. They can hold only scalar values (meaning a string, number, or a reference). They cannot directly contain other arrays or hashes, but instead contain references to other arrays or hashes. You can't use a reference to a array or hash in quite the same way that you would a real array or hash. For C or C++ programmers unused to distinguishing between arrays and pointers to the same, this can be confusing. If so, just think of it as the difference between a structure and a pointer to a structure. You can (and should) read more about references in the perlref(1) man page. Briefly, references are rather like pointers that know what they point to. (Objects are also a kind of reference, but we won't be needing them right away-if ever.) This means that when you have something which looks to you like an access to a two-or-more-dimensional array and/or hash, what's really going on is that the base type is merely a one-dimensional entity that contains references to the next level. It's just that you can use it as though it were a two-dimensional one. This is actually the way almost all C multidimensional arrays work as well. $array[7][12] # array of arrays $array[7]{string} # array of hashes $hash{string}[7] # hash of arrays $hash{string}{'another string'} # hash of hashes Now, because the top level contains only references, if you try to print out your array in with a simple print() function, you'll get something that doesn't look very nice, like this: @AoA = ( [2, 3], [4, 5, 7], [0] ); print $AoA[1][2]; 7 print @AoA; ARRAY(0x83c38)ARRAY(0x8b194)ARRAY(0x8b1d0) That's because Perl doesn't (ever) implicitly dereference your variables. If you want to get at the thing a reference is referring to, then you have to do this yourself using either prefix typing indicators, like `${$blah}', `@{$blah}', `@{$blah[$i]}', or else postfix pointer arrows, like `$a->[3]', `$h->{fred}', or even `$ob->method()->[3]'. COMMON MISTAKES =============== The two most common mistakes made in constructing something like an array of arrays is either accidentally counting the number of elements or else taking a reference to the same memory location repeatedly. Here's the case where you just get the count instead of a nested array: for $i (1..10) { @array = somefunc($i); $AoA[$i] = @array; # WRONG! } That's just the simple case of assigning an array to a scalar and getting its element count. If that's what you really and truly want, then you might do well to consider being a tad more explicit about it, like this: for $i (1..10) { @array = somefunc($i); $counts[$i] = scalar @array; } Here's the case of taking a reference to the same memory location again and again: for $i (1..10) { @array = somefunc($i); $AoA[$i] = \@array; # WRONG! } So, what's the big problem with that? It looks right, doesn't it? After all, I just told you that you need an array of references, so by golly, you've made me one! Unfortunately, while this is true, it's still broken. All the references in @AoA refer to the *very same place*, and they will therefore all hold whatever was last in @array! It's similar to the problem demonstrated in the following C program: #include main() { struct passwd *getpwnam(), *rp, *dp; rp = getpwnam("root"); dp = getpwnam("daemon"); printf("daemon name is %s\nroot name is %s\n", dp->pw_name, rp->pw_name); } Which will print daemon name is daemon root name is daemon The problem is that both rp and `dp' are pointers to the same location in memory! In C, you'd have to remember to malloc() yourself some new memory. In Perl, you'll want to use the array constructor [] or the hash constructor `{}' instead. Here's the right way to do the preceding broken code fragments: for $i (1..10) { @array = somefunc($i); $AoA[$i] = [ @array ]; } The square brackets make a reference to a new array with a copy of what's in @array at the time of the assignment. This is what you want. Note that this will produce something similar, but it's much harder to read: for $i (1..10) { @array = 0 .. $i; @{$AoA[$i]} = @array; } Is it the same? Well, maybe so-and maybe not. The subtle difference is that when you assign something in square brackets, you know for sure it's always a brand new reference with a new copy of the data. Something else could be going on in this new case with the `@{$AoA[$i]}}' dereference on the left-hand-side of the assignment. It all depends on whether `$AoA[$i]' had been undefined to start with, or whether it already contained a reference. If you had already populated @AoA with references, as in $AoA[3] = \@another_array; Then the assignment with the indirection on the left-hand-side would use the existing reference that was already there: @{$AoA[3]} = @array; Of course, this *would* have the "interesting" effect of clobbering @another_array. (Have you ever noticed how when a programmer says something is "interesting", that rather than meaning "intriguing", they're disturbingly more apt to mean that it's "annoying", "difficult", or both? :-) So just remember always to use the array or hash constructors with [] or `{}', and you'll be fine, although it's not always optimally efficient. Surprisingly, the following dangerous-looking construct will actually work out fine: for $i (1..10) { my @array = somefunc($i); $AoA[$i] = \@array; } That's because my() is more of a run-time statement than it is a compile-time declaration *per se*. This means that the my() variable is remade afresh each time through the loop. So even though it *looks* as though you stored the same variable reference each time, you actually did not! This is a subtle distinction that can produce more efficient code at the risk of misleading all but the most experienced of programmers. So I usually advise against teaching it to beginners. In fact, except for passing arguments to functions, I seldom like to see the gimme-a-reference operator (backslash) used much at all in code. Instead, I advise beginners that they (and most of the rest of us) should try to use the much more easily understood constructors [] and `{}' instead of relying upon lexical (or dynamic) scoping and hidden reference-counting to do the right thing behind the scenes. In summary: $AoA[$i] = [ @array ]; # usually best $AoA[$i] = \@array; # perilous; just how my() was that array? @{ $AoA[$i] } = @array; # way too tricky for most programmers CAVEAT ON PRECEDENCE ==================== Speaking of things like `@{$AoA[$i]}', the following are actually the same thing: $aref->[2][2] # clear $$aref[2][2] # confusing That's because Perl's precedence rules on its five prefix dereferencers (which look like someone swearing: `$ @ * % &') make them bind more tightly than the postfix subscripting brackets or braces! This will no doubt come as a great shock to the C or C++ programmer, who is quite accustomed to using `*a[i]' to mean what's pointed to by the *i'th* element of a. That is, they first take the subscript, and only then dereference the thing at that subscript. That's fine in C, but this isn't C. The seemingly equivalent construct in Perl, `$$aref[$i]' first does the deref of $aref, making it take $aref as a reference to an array, and then dereference that, and finally tell you the *i'th* value of the array pointed to by $AoA. If you wanted the C notion, you'd have to write `${$AoA[$i]}' to force the `$AoA[$i]' to get evaluated first before the leading `$' dereferencer. WHY YOU SHOULD ALWAYS `use strict' ================================== If this is starting to sound scarier than it's worth, relax. Perl has some features to help you avoid its most common pitfalls. The best way to avoid getting confused is to start every program like this: #!/usr/bin/perl -w use strict; This way, you'll be forced to declare all your variables with my() and also disallow accidental "symbolic dereferencing". Therefore if you'd done this: my $aref = [ [ "fred", "barney", "pebbles", "bambam", "dino", ], [ "homer", "bart", "marge", "maggie", ], [ "george", "jane", "elroy", "judy", ], ]; print $aref[2][2]; The compiler would immediately flag that as an error *at compile time*, because you were accidentally accessing `@aref', an undeclared variable, and it would thereby remind you to write instead: print $aref->[2][2] DEBUGGING ========= Before version 5.002, the standard Perl debugger didn't do a very nice job of printing out complex data structures. With 5.002 or above, the debugger includes several new features, including command line editing as well as the x command to dump out complex data structures. For example, given the assignment to $AoA above, here's the debugger output: DB<1> x $AoA $AoA = ARRAY(0x13b5a0) 0 ARRAY(0x1f0a24) 0 'fred' 1 'barney' 2 'pebbles' 3 'bambam' 4 'dino' 1 ARRAY(0x13b558) 0 'homer' 1 'bart' 2 'marge' 3 'maggie' 2 ARRAY(0x13b540) 0 'george' 1 'jane' 2 'elroy' 3 'judy' CODE EXAMPLES ============= Presented with little comment (these will get their own manpages someday) here are short code examples illustrating access of various types of data structures. ARRAYS OF ARRAYS ================ Declaration of a ARRAY OF ARRAYS -------------------------------- @AoA = ( [ "fred", "barney" ], [ "george", "jane", "elroy" ], [ "homer", "marge", "bart" ], ); Generation of a ARRAY OF ARRAYS ------------------------------- # reading from file while ( <> ) { push @AoA, [ split ]; } # calling a function for $i ( 1 .. 10 ) { $AoA[$i] = [ somefunc($i) ]; } # using temp vars for $i ( 1 .. 10 ) { @tmp = somefunc($i); $AoA[$i] = [ @tmp ]; } # add to an existing row push @{ $AoA[0] }, "wilma", "betty"; Access and Printing of a ARRAY OF ARRAYS ---------------------------------------- # one element $AoA[0][0] = "Fred"; # another element $AoA[1][1] =~ s/(\w)/\u$1/; # print the whole thing with refs for $aref ( @AoA ) { print "\t [ @$aref ],\n"; } # print the whole thing with indices for $i ( 0 .. $#AoA ) { print "\t [ @{$AoA[$i]} ],\n"; } # print the whole thing one at a time for $i ( 0 .. $#AoA ) { for $j ( 0 .. $#{ $AoA[$i] } ) { print "elt $i $j is $AoA[$i][$j]\n"; } } HASHES OF ARRAYS ================ Declaration of a HASH OF ARRAYS ------------------------------- %HoA = ( flintstones => [ "fred", "barney" ], jetsons => [ "george", "jane", "elroy" ], simpsons => [ "homer", "marge", "bart" ], ); Generation of a HASH OF ARRAYS ------------------------------ # reading from file # flintstones: fred barney wilma dino while ( <> ) { next unless s/^(.*?):\s*//; $HoA{$1} = [ split ]; } # reading from file; more temps # flintstones: fred barney wilma dino while ( $line = <> ) { ($who, $rest) = split /:\s*/, $line, 2; @fields = split ' ', $rest; $HoA{$who} = [ @fields ]; } # calling a function that returns a list for $group ( "simpsons", "jetsons", "flintstones" ) { $HoA{$group} = [ get_family($group) ]; } # likewise, but using temps for $group ( "simpsons", "jetsons", "flintstones" ) { @members = get_family($group); $HoA{$group} = [ @members ]; } # append new members to an existing family push @{ $HoA{"flintstones"} }, "wilma", "betty"; Access and Printing of a HASH OF ARRAYS --------------------------------------- # one element $HoA{flintstones}[0] = "Fred"; # another element $HoA{simpsons}[1] =~ s/(\w)/\u$1/; # print the whole thing foreach $family ( keys %HoA ) { print "$family: @{ $HoA{$family} }\n" } # print the whole thing with indices foreach $family ( keys %HoA ) { print "family: "; foreach $i ( 0 .. $#{ $HoA{$family} } ) { print " $i = $HoA{$family}[$i]"; } print "\n"; } # print the whole thing sorted by number of members foreach $family ( sort { @{$HoA{$b}} <=> @{$HoA{$a}} } keys %HoA ) { print "$family: @{ $HoA{$family} }\n" } # print the whole thing sorted by number of members and name foreach $family ( sort { @{$HoA{$b}} <=> @{$HoA{$a}} || $a cmp $b } keys %HoA ) { print "$family: ", join(", ", sort @{ $HoA{$family} }), "\n"; } ARRAYS OF HASHES ================ Declaration of a ARRAY OF HASHES -------------------------------- @AoH = ( { Lead => "fred", Friend => "barney", }, { Lead => "george", Wife => "jane", Son => "elroy", }, { Lead => "homer", Wife => "marge", Son => "bart", } ); Generation of a ARRAY OF HASHES ------------------------------- # reading from file # format: LEAD=fred FRIEND=barney while ( <> ) { $rec = {}; for $field ( split ) { ($key, $value) = split /=/, $field; $rec->{$key} = $value; } push @AoH, $rec; } # reading from file # format: LEAD=fred FRIEND=barney # no temp while ( <> ) { push @AoH, { split /[\s+=]/ }; } # calling a function that returns a key/value pair list, like # "lead","fred","daughter","pebbles" while ( %fields = getnextpairset() ) { push @AoH, { %fields }; } # likewise, but using no temp vars while (<>) { push @AoH, { parsepairs($_) }; } # add key/value to an element $AoH[0]{pet} = "dino"; $AoH[2]{pet} = "santa's little helper"; Access and Printing of a ARRAY OF HASHES ---------------------------------------- # one element $AoH[0]{lead} = "fred"; # another element $AoH[1]{lead} =~ s/(\w)/\u$1/; # print the whole thing with refs for $href ( @AoH ) { print "{ "; for $role ( keys %$href ) { print "$role=$href->{$role} "; } print "}\n"; } # print the whole thing with indices for $i ( 0 .. $#AoH ) { print "$i is { "; for $role ( keys %{ $AoH[$i] } ) { print "$role=$AoH[$i]{$role} "; } print "}\n"; } # print the whole thing one at a time for $i ( 0 .. $#AoH ) { for $role ( keys %{ $AoH[$i] } ) { print "elt $i $role is $AoH[$i]{$role}\n"; } } HASHES OF HASHES ================ Declaration of a HASH OF HASHES ------------------------------- %HoH = ( flintstones => { lead => "fred", pal => "barney", }, jetsons => { lead => "george", wife => "jane", "his boy" => "elroy", }, simpsons => { lead => "homer", wife => "marge", kid => "bart", }, ); Generation of a HASH OF HASHES ------------------------------ # reading from file # flintstones: lead=fred pal=barney wife=wilma pet=dino while ( <> ) { next unless s/^(.*?):\s*//; $who = $1; for $field ( split ) { ($key, $value) = split /=/, $field; $HoH{$who}{$key} = $value; } # reading from file; more temps while ( <> ) { next unless s/^(.*?):\s*//; $who = $1; $rec = {}; $HoH{$who} = $rec; for $field ( split ) { ($key, $value) = split /=/, $field; $rec->{$key} = $value; } } # calling a function that returns a key,value hash for $group ( "simpsons", "jetsons", "flintstones" ) { $HoH{$group} = { get_family($group) }; } # likewise, but using temps for $group ( "simpsons", "jetsons", "flintstones" ) { %members = get_family($group); $HoH{$group} = { %members }; } # append new members to an existing family %new_folks = ( wife => "wilma", pet => "dino", ); for $what (keys %new_folks) { $HoH{flintstones}{$what} = $new_folks{$what}; } Access and Printing of a HASH OF HASHES --------------------------------------- # one element $HoH{flintstones}{wife} = "wilma"; # another element $HoH{simpsons}{lead} =~ s/(\w)/\u$1/; # print the whole thing foreach $family ( keys %HoH ) { print "$family: { "; for $role ( keys %{ $HoH{$family} } ) { print "$role=$HoH{$family}{$role} "; } print "}\n"; } # print the whole thing somewhat sorted foreach $family ( sort keys %HoH ) { print "$family: { "; for $role ( sort keys %{ $HoH{$family} } ) { print "$role=$HoH{$family}{$role} "; } print "}\n"; } # print the whole thing sorted by number of members foreach $family ( sort { keys %{$HoH{$b}} <=> keys %{$HoH{$a}} } keys %HoH ) { print "$family: { "; for $role ( sort keys %{ $HoH{$family} } ) { print "$role=$HoH{$family}{$role} "; } print "}\n"; } # establish a sort order (rank) for each role $i = 0; for ( qw(lead wife son daughter pal pet) ) { $rank{$_} = ++$i } # now print the whole thing sorted by number of members foreach $family ( sort { keys %{ $HoH{$b} } <=> keys %{ $HoH{$a} } } keys %HoH ) { print "$family: { "; # and print these according to rank order for $role ( sort { $rank{$a} <=> $rank{$b} } keys %{ $HoH{$family} } ) { print "$role=$HoH{$family}{$role} "; } print "}\n"; } MORE ELABORATE RECORDS ====================== Declaration of MORE ELABORATE RECORDS ------------------------------------- Here's a sample showing how to create and use a record whose fields are of many different sorts: $rec = { TEXT => $string, SEQUENCE => [ @old_values ], LOOKUP => { %some_table }, THATCODE => \&some_function, THISCODE => sub { $_[0] ** $_[1] }, HANDLE => \*STDOUT, }; print $rec->{TEXT}; print $rec->{SEQUENCE}[0]; $last = pop @ { $rec->{SEQUENCE} }; print $rec->{LOOKUP}{"key"}; ($first_k, $first_v) = each %{ $rec->{LOOKUP} }; $answer = $rec->{THATCODE}->($arg); $answer = $rec->{THISCODE}->($arg1, $arg2); # careful of extra block braces on fh ref print { $rec->{HANDLE} } "a string\n"; use FileHandle; $rec->{HANDLE}->autoflush(1); $rec->{HANDLE}->print(" a string\n"); Declaration of a HASH OF COMPLEX RECORDS ---------------------------------------- %TV = ( flintstones => { series => "flintstones", nights => [ qw(monday thursday friday) ], members => [ { name => "fred", role => "lead", age => 36, }, { name => "wilma", role => "wife", age => 31, }, { name => "pebbles", role => "kid", age => 4, }, ], }, jetsons => { series => "jetsons", nights => [ qw(wednesday saturday) ], members => [ { name => "george", role => "lead", age => 41, }, { name => "jane", role => "wife", age => 39, }, { name => "elroy", role => "kid", age => 9, }, ], }, simpsons => { series => "simpsons", nights => [ qw(monday) ], members => [ { name => "homer", role => "lead", age => 34, }, { name => "marge", role => "wife", age => 37, }, { name => "bart", role => "kid", age => 11, }, ], }, ); Generation of a HASH OF COMPLEX RECORDS --------------------------------------- # reading from file # this is most easily done by having the file itself be # in the raw data format as shown above. perl is happy # to parse complex data structures if declared as data, so # sometimes it's easiest to do that # here's a piece by piece build up $rec = {}; $rec->{series} = "flintstones"; $rec->{nights} = [ find_days() ]; @members = (); # assume this file in field=value syntax while (<>) { %fields = split /[\s=]+/; push @members, { %fields }; } $rec->{members} = [ @members ]; # now remember the whole thing $TV{ $rec->{series} } = $rec; ########################################################### # now, you might want to make interesting extra fields that # include pointers back into the same data structure so if # change one piece, it changes everywhere, like for example # if you wanted a {kids} field that was a reference # to an array of the kids' records without having duplicate # records and thus update problems. ########################################################### foreach $family (keys %TV) { $rec = $TV{$family}; # temp pointer @kids = (); for $person ( @{ $rec->{members} } ) { if ($person->{role} =~ /kid|son|daughter/) { push @kids, $person; } } # REMEMBER: $rec and $TV{$family} point to same data!! $rec->{kids} = [ @kids ]; } # you copied the array, but the array itself contains pointers # to uncopied objects. this means that if you make bart get # older via $TV{simpsons}{kids}[0]{age}++; # then this would also change in print $TV{simpsons}{members}[2]{age}; # because $TV{simpsons}{kids}[0] and $TV{simpsons}{members}[2] # both point to the same underlying anonymous hash table # print the whole thing foreach $family ( keys %TV ) { print "the $family"; print " is on during @{ $TV{$family}{nights} }\n"; print "its members are:\n"; for $who ( @{ $TV{$family}{members} } ) { print " $who->{name} ($who->{role}), age $who->{age}\n"; } print "it turns out that $TV{$family}{lead} has "; print scalar ( @{ $TV{$family}{kids} } ), " kids named "; print join (", ", map { $_->{name} } @{ $TV{$family}{kids} } ); print "\n"; } Database Ties ============= You cannot easily tie a multilevel data structure (such as a hash of hashes) to a dbm file. The first problem is that all but GDBM and Berkeley DB have size limitations, but beyond that, you also have problems with how references are to be represented on disk. One experimental module that does partially attempt to address this need is the MLDBM module. Check your nearest CPAN site as described in *Note Perlmodlib: perlmodlib, for source code to MLDBM. SEE ALSO ======== perlref(1), perllol(1), perldata(1), perlobj(1) AUTHOR ====== Tom Christiansen <`tchrist@perl.com'> Last update: Wed Oct 23 04:57:50 MET DST 1996  File: perl.info, Node: perlembed, Next: perlapio, Prev: perlbook, Up: Top how to embed perl in your C program *********************************** NAME ==== perlembed - how to embed perl in your C program DESCRIPTION =========== PREAMBLE -------- Do you want to: *Use C from Perl?* Read *Note Perlxstut: perlxstut,, *Note Perlxs: perlxs,, `h2xs' in this node, *Note Perlguts: perlguts,, and *Note Perlapi: perlapi,. *Use a Unix program from Perl?* Read about back-quotes and about system and exec in *Note Perlfunc: perlfunc,. *Use Perl from Perl?* Read about `do', *Note Perlfunc: perlfunc, and `eval', *Note Perlfunc: perlfunc, and `require', *Note Perlfunc: perlfunc, and `use', *Note Perlfunc: perlfunc,. *Use C from C?* Rethink your design. *Use Perl from C?* Read on... ROADMAP ------- `Compiling your C program' in this node `Adding a Perl interpreter to your C program' in this node `Calling a Perl subroutine from your C program' in this node `Evaluating a Perl statement from your C program' in this node `Performing Perl pattern matches and substitutions from your C program' in this node `Fiddling with the Perl stack from your C program' in this node `Maintaining a persistent interpreter' in this node `Maintaining multiple interpreter instances' in this node `Using Perl modules, which themselves use C libraries, from your C program' in this node `Embedding Perl under Win32' in this node Compiling your C program ------------------------ If you have trouble compiling the scripts in this documentation, you're not alone. The cardinal rule: COMPILE THE PROGRAMS IN EXACTLY THE SAME WAY THAT YOUR PERL WAS COMPILED. (Sorry for yelling.) Also, every C program that uses Perl must link in the *perl library*. What's that, you ask? Perl is itself written in C; the perl library is the collection of compiled C programs that were used to create your perl executable (*/usr/bin/perl* or equivalent). (Corollary: you can't use Perl from your C program unless Perl has been compiled on your machine, or installed properly-that's why you shouldn't blithely copy Perl executables from machine to machine without also copying the lib directory.) When you use Perl from C, your C program will-usually-allocate, "run", and deallocate a *PerlInterpreter* object, which is defined by the perl library. If your copy of Perl is recent enough to contain this documentation (version 5.002 or later), then the perl library (and *EXTERN.h* and *perl.h*, which you'll also need) will reside in a directory that looks like this: /usr/local/lib/perl5/your_architecture_here/CORE or perhaps just /usr/local/lib/perl5/CORE or maybe something like /usr/opt/perl5/CORE 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, `Adding a Perl interpreter to your C program' in this node, on my Linux box: % gcc -O2 -Dbool=char -DHAS_BOOL -I/usr/local/include -I/usr/local/lib/perl5/i586-linux/5.003/CORE -L/usr/local/lib/perl5/i586-linux/5.003/CORE -o interp interp.c -lperl -lm (That's all one line.) On my DEC Alpha running old 5.003_05, the incantation is a bit different: % cc -O2 -Olimit 2900 -DSTANDARD_C -I/usr/local/include -I/usr/local/lib/perl5/alpha-dec_osf/5.00305/CORE -L/usr/local/lib/perl5/alpha-dec_osf/5.00305/CORE -L/usr/local/lib -D__LANGUAGE_C__ -D_NO_PROTO -o interp interp.c -lperl -lm How can you figure out what to add? Assuming your Perl is post-5.001, execute a `perl -V' command and pay special attention to the "cc" and "ccflags" information. You'll have to choose the appropriate compiler (cc, *gcc*, et al.) for your machine: `perl -MConfig -e 'print $Config{cc}'' will tell you what to use. You'll also have to choose the appropriate library directory (*/usr/local/lib/...*) for your machine. If your compiler complains that certain functions are undefined, or that it can't locate *-lperl*, then you need to change the path following the -L. If it complains that it can't find *EXTERN.h* and *perl.h*, you need to change the path following the -I. You may have to add extra libraries as well. Which ones? Perhaps those printed by perl -MConfig -e 'print $Config{libs}' Provided your perl binary was properly configured and installed the ExtUtils::Embed module will determine all of this information for you: % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts` If the ExtUtils::Embed module isn't part of your Perl distribution, you can retrieve it from http://www.perl.com/perl/CPAN/modules/by-module/ExtUtils/. (If this documentation came from your Perl distribution, then you're running 5.004 or better and you already have it.) The ExtUtils::Embed kit on CPAN also contains all source code for the examples in this document, tests, additional examples and other information you may find useful. Adding a Perl interpreter to your C program ------------------------------------------- In a sense, perl (the C program) is a good example of embedding Perl (the language), so I'll demonstrate embedding with *miniperlmain.c*, included in the source distribution. Here's a bastardized, nonportable version of *miniperlmain.c* containing the essentials of embedding: #include /* from the Perl distribution */ #include /* from the Perl distribution */ static PerlInterpreter *my_perl; /*** The Perl interpreter ***/ int main(int argc, char **argv, char **env) { my_perl = perl_alloc(); perl_construct(my_perl); perl_parse(my_perl, NULL, argc, argv, (char **)NULL); perl_run(my_perl); perl_destruct(my_perl); perl_free(my_perl); } Notice that we don't use the env pointer. Normally handed to perl_parse as its final argument, env here is replaced by NULL, which means that the current environment will be used. Now compile this program (I'll call it *interp.c*) into an executable: % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts` After a successful compilation, you'll be able to use interp just like perl itself: % interp print "Pretty Good Perl \n"; print "10890 - 9801 is ", 10890 - 9801; Pretty Good Perl 10890 - 9801 is 1089 or % interp -e 'printf("%x", 3735928559)' deadbeef You can also read and execute Perl statements from a file while in the midst of your C program, by placing the filename in *argv[1]* before calling perl_run. Calling a Perl subroutine from your C program --------------------------------------------- To call individual Perl subroutines, you can use any of the *call_** functions documented in *Note Perlcall: perlcall,. In this example we'll use call_argv. That's shown below, in a program I'll call *showtime.c*. #include #include static PerlInterpreter *my_perl; int main(int argc, char **argv, char **env) { char *args[] = { NULL }; my_perl = perl_alloc(); perl_construct(my_perl); perl_parse(my_perl, NULL, argc, argv, NULL); /*** skipping perl_run() ***/ call_argv("showtime", G_DISCARD | G_NOARGS, args); perl_destruct(my_perl); perl_free(my_perl); } where *showtime* is a Perl subroutine that takes no arguments (that's the G_NOARGS) and for which I'll ignore the return value (that's the G_DISCARD). Those flags, and others, are discussed in *Note Perlcall: perlcall,. I'll define the *showtime* subroutine in a file called *showtime.pl*: print "I shan't be printed."; sub showtime { print time; } Simple enough. Now compile and run: % cc -o showtime showtime.c `perl -MExtUtils::Embed -e ccopts -e ldopts` % showtime showtime.pl 818284590 yielding the number of seconds that elapsed between January 1, 1970 (the beginning of the Unix epoch), and the moment I began writing this sentence. In this particular case we don't have to call perl_run, but in general it's considered good practice to ensure proper initialization of library code, including execution of all object DESTROY methods and package `END {}' blocks. If you want to pass arguments to the Perl subroutine, you can add strings to the NULL-terminated args list passed to call_argv. 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: `Fiddling with the Perl stack from your C program' in this node. Evaluating a Perl statement from your C program ----------------------------------------------- Perl provides two API functions to evaluate pieces of Perl code. These are `eval_sv', *Note Perlapi: perlapi, and `eval_pv', *Note Perlapi: perlapi,. 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 `use', *Note Perlfunc: perlfunc,, `require', *Note Perlfunc: perlfunc,, and `do', *Note Perlfunc: perlfunc, to include external Perl files. eval_pv lets us evaluate individual Perl strings, and then extract variables for coercion into C types. The following program, *string.c*, executes three Perl strings, extracting an int from the first, a float from the second, and a `char *' from the third. #include #include static PerlInterpreter *my_perl; main (int argc, char **argv, char **env) { STRLEN n_a; char *embedding[] = { "", "-e", "0" }; my_perl = perl_alloc(); perl_construct( my_perl ); perl_parse(my_perl, NULL, 3, embedding, NULL); perl_run(my_perl); /** Treat $a as an integer **/ eval_pv("$a = 3; $a **= 2", TRUE); printf("a = %d\n", SvIV(get_sv("a", FALSE))); /** Treat $a as a float **/ eval_pv("$a = 3.14; $a **= 2", TRUE); printf("a = %f\n", SvNV(get_sv("a", FALSE))); /** 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)); perl_destruct(my_perl); perl_free(my_perl); } All of those strange functions with sv in their names help convert Perl scalars to C types. They're described in *Note Perlguts: perlguts, and *Note Perlapi: perlapi,. If you compile and run *string.c*, you'll see the results of using *SvIV()* to create an int, *SvNV()* to create a float, and *SvPV()* to create a string: a = 9 a = 9.859600 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 possible and in most cases a better strategy to fetch the return value from *eval_pv()* instead. Example: ... STRLEN n_a; SV *val = eval_pv("reverse 'rekcaH lreP rehtonA tsuJ'", TRUE); printf("%s\n", SvPV(val,n_a)); ... This way, we avoid namespace pollution by not creating global variables and we've simplified our code as well. Performing Perl pattern matches and substitutions from your C program --------------------------------------------------------------------- The *eval_sv()* function lets us evaluate strings of Perl code, so we can define some functions that use it to "specialize" in matches and substitutions: match(), *substitute()*, and *matches()*. I32 match(SV *string, char *pattern); Given a string and a pattern (e.g., `m/clasp/' or `/\b\w*\b/', which in your C program might appear as "/\\b\\w*\\b/"), match() returns 1 if the string matches the pattern and 0 otherwise. int substitute(SV **string, char *pattern); Given a pointer to an SV and an `=~' operation (e.g., `s/bob/robert/g' or `tr[A-Z][a-z]'), substitute() modifies the string within the AV at according to the operation, returning the number of substitutions made. int matches(SV *string, char *pattern, AV **matches); Given an SV, a pattern, and a pointer to an empty AV, matches() evaluates `$string =~ $pattern' in an array context, and fills in matches with the array elements, returning the number of matches found. Here's a sample program, *match.c*, that uses all three (long lines have been wrapped here): #include #include /** my_eval_sv(code, error_check) ** kinda like eval_sv(), ** but we pop the return value off the stack **/ SV* my_eval_sv(SV *sv, I32 croak_on_error) { dSP; SV* retval; STRLEN n_a; PUSHMARK(SP); eval_sv(sv, G_SCALAR); SPAGAIN; retval = POPs; PUTBACK; if (croak_on_error && SvTRUE(ERRSV)) croak(SvPVx(ERRSV, n_a)); return retval; } /** match(string, pattern) ** ** Used for matches in a scalar context. ** ** Returns 1 if the match was successful; 0 otherwise. **/ I32 match(SV *string, char *pattern) { SV *command = NEWSV(1099, 0), *retval; STRLEN n_a; sv_setpvf(command, "my $string = '%s'; $string =~ %s", SvPV(string,n_a), pattern); retval = my_eval_sv(command, TRUE); SvREFCNT_dec(command); return SvIV(retval); } /** substitute(string, pattern) ** ** Used for =~ operations that modify their left-hand side (s/// and tr///) ** ** Returns the number of successful matches, and ** modifies the input string if there were any. **/ I32 substitute(SV **string, char *pattern) { SV *command = NEWSV(1099, 0), *retval; STRLEN n_a; sv_setpvf(command, "$string = '%s'; ($string =~ %s)", SvPV(*string,n_a), pattern); retval = my_eval_sv(command, TRUE); SvREFCNT_dec(command); *string = get_sv("string", FALSE); return SvIV(retval); } /** matches(string, pattern, matches) ** ** Used for matches in an array context. ** ** Returns the number of matches, ** and fills in **matches with the matching substrings **/ I32 matches(SV *string, char *pattern, AV **match_list) { SV *command = NEWSV(1099, 0); I32 num_matches; STRLEN n_a; sv_setpvf(command, "my $string = '%s'; @array = ($string =~ %s)", SvPV(string,n_a), 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 **/ return num_matches; } main (int argc, char **argv, char **env) { PerlInterpreter *my_perl = perl_alloc(); char *embedding[] = { "", "-e", "0" }; AV *match_list; I32 num_matches, i; SV *text = NEWSV(1099,0); STRLEN n_a; perl_construct(my_perl); perl_parse(my_perl, NULL, 3, embedding, NULL); 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 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"); if (match(text, "m/quarter/")) /** Does text contain 'quarter'? **/ printf("match: Text contains the word 'quarter'.\n\n"); else printf("match: Text doesn't contain the word 'quarter'.\n\n"); if (match(text, "m/eighth/")) /** Does text contain 'eighth'? **/ printf("match: Text contains the word 'eighth'.\n\n"); else printf("match: Text doesn't contain the word 'eighth'.\n\n"); /** Match all occurrences of /wi../ **/ num_matches = matches(text, "m/(wi..)/g", &match_list); 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("\n"); /** Remove all vowels from text **/ num_matches = substitute(&text, "s/[aeiou]//gi"); 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)); } /** Attempt a substitution **/ if (!substitute(&text, "s/Perl/C/")) { printf("substitute: s/Perl/C...No substitution made.\n\n"); } SvREFCNT_dec(text); PL_perl_destruct_level = 1; perl_destruct(my_perl); perl_free(my_perl); } which produces the output (again, long lines have been wrapped here) match: Text contains the word 'quarter'. match: Text doesn't contain the word 'eighth'. matches: m/(wi..)/g found 2 matches... match: will match: with substitute: s/[aeiou]//gi...139 substitutions made. 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 substitute: s/Perl/C...No substitution made. Fiddling with the Perl stack from your C program ------------------------------------------------ When trying to explain stacks, most computer science textbooks mumble something about spring-loaded columns of cafeteria plates: the last thing you pushed on the stack is the first thing you pop off. That'll do for our purposes: your C program will push some arguments onto "the Perl stack", shut its eyes while some magic happens, and then pop the results-the return value of your Perl subroutine-off the stack. First you'll need to know how to convert between C types and Perl types, with newSViv() and sv_setnv() and newAV() and all their friends. They're described in *Note Perlguts: perlguts, and *Note Perlapi: perlapi,. Then you'll need to know how to manipulate the Perl stack. That's described in *Note Perlcall: perlcall,. Once you've understood those, embedding Perl in C is easy. Because C has no builtin function for integer exponentiation, let's make Perl's ** operator available to it (this is less useful than it sounds, because Perl implements ** with C's *pow()* function). First I'll create a stub exponentiation function in *power.pl*: sub expo { my ($a, $b) = @_; return $a ** $b; } Now I'll create a C program, *power.c*, with a function *PerlPower()* that contains all the perlguts necessary to push the two arguments into *expo()* and to pop the return value out. Take a deep breath... #include #include static PerlInterpreter *my_perl; static void PerlPower(int a, int b) { dSP; /* initialize stack pointer */ ENTER; /* everything created after here */ SAVETMPS; /* ...is a temporary variable. */ 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 */ call_pv("expo", G_SCALAR); /* call the function */ SPAGAIN; /* refresh stack pointer */ /* pop the return value from stack */ printf ("%d to the %dth power is %d.\n", a, b, POPi); PUTBACK; FREETMPS; /* free that return value */ LEAVE; /* ...and the XPUSHed "mortal" args.*/ } int main (int argc, char **argv, char **env) { char *my_argv[] = { "", "power.pl" }; my_perl = perl_alloc(); perl_construct( my_perl ); perl_parse(my_perl, NULL, 2, my_argv, (char **)NULL); perl_run(my_perl); PerlPower(3, 4); /*** Compute 3 ** 4 ***/ perl_destruct(my_perl); perl_free(my_perl); } Compile and run: % cc -o power power.c `perl -MExtUtils::Embed -e ccopts -e ldopts` % power 3 to the 4th power is 81. Maintaining a persistent interpreter ------------------------------------ When developing interactive and/or potentially long-running applications, it's a good idea to maintain a persistent interpreter rather than allocating and constructing a new interpreter multiple times. The major reason is speed: since Perl will only be loaded into memory once. However, you have to be more cautious with namespace and variable scoping when using a persistent interpreter. In previous examples we've been using global variables in the default package main. We knew exactly what code would be run, and assumed we could avoid variable collisions and outrageous symbol table growth. Let's say your application is a server that will occasionally run Perl code from some arbitrary file. Your server has no way of knowing what code it's going to run. Very dangerous. If the file is pulled in by `perl_parse()', compiled into a newly constructed interpreter, and subsequently cleaned out with `perl_destruct()' afterwards, you're shielded from most namespace 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 `eval', *Note Perlfunc: perlfunc,. 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 `call_argv', *Note Perlapi: perlapi,, We'll call the subroutine `Embed::Persistent::eval_file' which lives in the file `persistent.pl' and pass the filename and boolean cleanup/cache flag as arguments. Note that the process will continue to grow for each file that it uses. In addition, there might be AUTOLOADed subroutines and other 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 `my', *Note Perlfunc: perlfunc, whenever possible. package Embed::Persistent; #persistent.pl use strict; our %Cache; use Symbol qw(delete_package); sub valid_package_name { my($string) = @_; $string =~ s/([^A-Za-z0-9\/])/sprintf("_%2x",unpack("C",$1))/eg; # second pass only for words starting with a digit $string =~ s|/(\d)|sprintf("/_%2x",unpack("C",$1))|eg; # Dress it up as a real package name $string =~ s|/|::|g; return "Embed" . $string; } sub eval_file { my($filename, $delete) = @_; my $package = valid_package_name($filename); my $mtime = -M $filename; if(defined $Cache{$package}{mtime} && $Cache{$package}{mtime} <= $mtime) { # we have compiled this subroutine already, # it has not been updated on disk, nothing left to do print STDERR "already compiled $package->handler\n"; } else { local *FH; open FH, $filename or die "open '$filename' $!"; local($/) = undef; my $sub = ; close FH; #wrap the code into a subroutine inside our unique package my $eval = qq{package $package; sub handler { $sub; }}; { # hide our variables within this block my($filename,$mtime,$package,$sub); eval $eval; } die $@ if $@; #cache it unless we're cleaning out each time $Cache{$package}{mtime} = $mtime unless $delete; } eval {$package->handler;}; die $@ if $@; delete_package($package) if $delete; #take a look if you want #print Devel::Symdump->rnew($package)->as_string, $/; } 1; __END__ /* persistent.c */ #include #include /* 1 = clean out filename's symbol table after each request, 0 = don't */ #ifndef DO_CLEAN #define DO_CLEAN 0 #endif static PerlInterpreter *perl = NULL; int main(int argc, char **argv, char **env) { char *embedding[] = { "", "persistent.pl" }; char *args[] = { "", DO_CLEAN, NULL }; char filename [1024]; int exitstatus = 0; STRLEN n_a; if((perl = perl_alloc()) == NULL) { fprintf(stderr, "no memory!"); exit(1); } perl_construct(perl); exitstatus = perl_parse(perl, NULL, 2, embedding, NULL); if(!exitstatus) { exitstatus = perl_run(perl); while(printf("Enter file name: ") && gets(filename)) { /* call the subroutine, passing it the filename as an argument */ args[0] = filename; call_argv("Embed::Persistent::eval_file", G_DISCARD | G_EVAL, args); /* check $@ */ if(SvTRUE(ERRSV)) fprintf(stderr, "eval error: %s\n", SvPV(ERRSV,n_a)); } } PL_perl_destruct_level = 0; perl_destruct(perl); perl_free(perl); exit(exitstatus); } Now compile: % cc -o persistent persistent.c `perl -MExtUtils::Embed -e ccopts -e ldopts` Here's a example script file: #test.pl my $string = "hello"; foo($string); sub foo { print "foo says: @_\n"; } Now run: % persistent Enter file name: test.pl foo says: hello Enter file name: test.pl already compiled Embed::test_2epl->handler foo says: hello Enter file name: ^C Maintaining multiple interpreter instances ------------------------------------------ Some rare applications will need to create more than one interpreter during a session. Such an application might sporadically decide to release any resources associated with the interpreter. The program must take care to ensure that this takes place before the next interpreter is constructed. By default, the global variable `PL_perl_destruct_level' is set to 0, since extra cleaning isn't needed when a program has only one interpreter. Setting `PL_perl_destruct_level' to 1 makes everything squeaky clean: PL_perl_destruct_level = 1; while(1) { ... /* reset global variables here with PL_perl_destruct_level = 1 */ perl_construct(my_perl); ... /* clean and reset _everything_ during perl_destruct */ perl_destruct(my_perl); perl_free(my_perl); ... /* let's go do it again! */ } When *perl_destruct()* is called, the interpreter's syntax parse tree and symbol tables are cleaned up, and global variables are reset. Now suppose we have more than one interpreter instance running at the same time. This is feasible, but only if you used the `-DMULTIPLICITY' flag when building Perl. By default, that sets `PL_perl_destruct_level' to 1. Let's give it a try: #include #include /* 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)" int main(int argc, char **argv, char **env) { PerlInterpreter *one_perl = perl_alloc(), *two_perl = perl_alloc(); char *one_args[] = { "one_perl", SAY_HELLO }; char *two_args[] = { "two_perl", SAY_HELLO }; perl_construct(one_perl); perl_construct(two_perl); perl_parse(one_perl, NULL, 3, one_args, (char **)NULL); perl_parse(two_perl, NULL, 3, two_args, (char **)NULL); perl_run(one_perl); perl_run(two_perl); perl_destruct(one_perl); perl_destruct(two_perl); perl_free(one_perl); perl_free(two_perl); } Compile as usual: % cc -o multiplicity multiplicity.c `perl -MExtUtils::Embed -e ccopts -e ldopts` Run it, Run it: % multiplicity Hi, I'm one_perl Hi, I'm two_perl Using Perl modules, which themselves use C libraries, from your C program ------------------------------------------------------------------------- If you've played with the examples above and tried to embed a script that *use()*s a Perl module (such as Socket) which itself uses a C or C++ library, this probably happened: Can't load module Socket, dynamic loading not available in this perl. (You may need to build a new perl executable which either supports dynamic loading or has the Socket module statically linked into it.) What's wrong? Your interpreter doesn't know how to communicate with these extensions on its own. A little glue will help. Up until now you've been calling *perl_parse()*, handing it NULL for the second argument: perl_parse(my_perl, NULL, argc, my_argv, NULL); That's where the glue code can be inserted to create the initial contact between Perl and linked C/C++ routines. Let's take a look some pieces of *perlmain.c* to see how Perl does this: #ifdef __cplusplus # define EXTERN_C extern "C" #else # define EXTERN_C extern #endif static void xs_init (void); EXTERN_C void boot_DynaLoader (CV* cv); EXTERN_C void boot_Socket (CV* cv); EXTERN_C void xs_init() { char *file = __FILE__; /* DynaLoader is a special case */ newXS("DynaLoader::boot_DynaLoader", boot_DynaLoader, file); newXS("Socket::bootstrap", boot_Socket, file); } Simply put: for each extension linked with your Perl executable (determined during its initial configuration on your computer or when adding a new extension), a Perl subroutine is created to incorporate the extension's routines. Normally, that subroutine is named *Module::bootstrap()* and is invoked when you say *use Module*. In turn, this hooks into an XSUB, *boot_Module*, which creates a Perl counterpart for each of the extension's XSUBs. Don't worry about this part; leave that to the xsubpp and extension authors. If your extension is dynamically loaded, DynaLoader creates *Module::bootstrap()* for you on the fly. In fact, if you have a working DynaLoader then there is rarely any need to link in any other extensions statically. Once you have this code, slap it into the second argument of *perl_parse()*: perl_parse(my_perl, xs_init, argc, my_argv, NULL); Then compile: % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts` % interp use Socket; use SomeDynamicallyLoadedModule; print "Now I can use extensions!\n"' ExtUtils::Embed can also automate writing the *xs_init* glue code. % perl -MExtUtils::Embed -e xsinit -- -o perlxsi.c % cc -c perlxsi.c `perl -MExtUtils::Embed -e ccopts` % cc -c interp.c `perl -MExtUtils::Embed -e ccopts` % cc -o interp perlxsi.o interp.o `perl -MExtUtils::Embed -e ldopts` Consult *Note Perlxs: perlxs,, *Note Perlguts: perlguts,, and *Note Perlapi: perlapi, for more details. Embedding Perl under Win32 ========================== At the time of this writing (5.004), there are two versions of Perl which run under Win32. (The two versions are merging in 5.005.) Interfacing to ActiveState's Perl library is quite different from the examples in this documentation, as significant changes were made to the internal Perl API. However, it is possible to embed ActiveState's Perl runtime. For details, see the Perl for Win32 FAQ at http://www.perl.com/CPAN/doc/FAQs/win32/perlwin32faq.html. With the "official" Perl version 5.004 or higher, all the examples within this documentation will compile and run untouched, although the build process is slightly different between Unix and Win32. For starters, backticks don't work under the Win32 native command shell. The ExtUtils::Embed kit on CPAN ships with a script called *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 *C:\perl\lib\CORE*, if not, you should see the *CORE* directory relative to `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. MORAL ===== You can sometimes *write faster code* in C, but you can always *write code faster* in Perl. Because you can use each from the other, combine them as you wish. AUTHOR ====== Jon Orwant <`orwant@tpj.com'> and Doug MacEachern <`dougm@osf.org'>, with small contributions from Tim Bunce, Tom Christiansen, Guy Decoux, Hallvard Furuseth, Dov Grobgeld, and Ilya Zakharevich. Doug MacEachern has an article on embedding in Volume 1, Issue 4 of The Perl Journal (http://tpj.com). Doug is also the developer of the most widely-used Perl embedding: the mod_perl system (perl.apache.org), which embeds Perl in the Apache web server. Oracle, Binary Evolution, ActiveState, and Ben Sugars's nsapi_perl have used this model for Oracle, Netscape and Internet Information Server Perl plugins. July 22, 1998 COPYRIGHT ========= 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.