extra code in pp_concat, Take 2
[p5sagit/p5-mst-13.2.git] / pod / perlfaq3.pod
CommitLineData
68dc0745 1=head1 NAME
2
571e049f 3perlfaq3 - Programming Tools ($Revision: 1.47 $, $Date: 2005/03/27 07:21:22 $)
68dc0745 4
5=head1 DESCRIPTION
6
7This section of the FAQ answers questions related to programmer tools
8and programming support.
9
10=head2 How do I do (anything)?
11
12Have you looked at CPAN (see L<perlfaq2>)? The chances are that
13someone has already written a module that can solve your problem.
3958b146 14Have you read the appropriate manpages? Here's a brief index:
68dc0745 15
5a964f20 16 Basics perldata, perlvar, perlsyn, perlop, perlsub
17 Execution perlrun, perldebug
18 Functions perlfunc
68dc0745 19 Objects perlref, perlmod, perlobj, perltie
20 Data Structures perlref, perllol, perldsc
f102b883 21 Modules perlmod, perlmodlib, perlsub
d92eb7b0 22 Regexes perlre, perlfunc, perlop, perllocale
68dc0745 23 Moving to perl5 perltrap, perl
24 Linking w/C perlxstut, perlxs, perlcall, perlguts, perlembed
06a5f41f 25 Various http://www.cpan.org/misc/olddoc/FMTEYEWTK.tgz
26 (not a man-page but still useful, a collection
27 of various essays on Perl techniques)
68dc0745 28
3958b146 29A crude table of contents for the Perl manpage set is found in L<perltoc>.
68dc0745 30
31=head2 How can I use Perl interactively?
32
33The typical approach uses the Perl debugger, described in the
3958b146 34perldebug(1) manpage, on an ``empty'' program, like this:
68dc0745 35
36 perl -de 42
37
38Now just type in any legal Perl code, and it will be immediately
39evaluated. You can also examine the symbol table, get stack
40backtraces, check variable values, set breakpoints, and other
92c2ed05 41operations typically found in symbolic debuggers.
68dc0745 42
43=head2 Is there a Perl shell?
44
04d666b1 45The psh (Perl sh) is currently at version 1.8. The Perl Shell is a
46shell that combines the interactive nature of a Unix shell with the
47power of Perl. The goal is a full featured shell that behaves as
48expected for normal shell activity and uses Perl syntax and
49functionality for control-flow statements and other things.
50You can get psh at http://www.focusresearch.com/gregor/psh/ .
55e174a4 51
f3b9614f 52Zoidberg is a similar project and provides a shell written in perl,
53configured in perl and operated in perl. It is intended as a login shell
54and development environment. It can be found at http://zoidberg.sf.net/
55or your local CPAN mirror.
56
55e174a4 57The Shell.pm module (distributed with Perl) makes Perl try commands
58which aren't part of the Perl language as shell commands. perlsh
59from the source distribution is simplistic and uninteresting, but
60may still be what you want.
68dc0745 61
49d635f9 62=head2 How do I find which modules are installed on my system?
63
64You can use the ExtUtils::Installed module to show all
65installed distributions, although it can take awhile to do
66its magic. The standard library which comes with Perl just
67shows up as "Perl" (although you can get those with
793f5136 68Module::CoreList).
49d635f9 69
70 use ExtUtils::Installed;
197aec24 71
49d635f9 72 my $inst = ExtUtils::Installed->new();
73 my @modules = $inst->modules();
74
75If you want a list of all of the Perl module filenames, you
76can use File::Find::Rule.
77
78 use File::Find::Rule;
197aec24 79
49d635f9 80 my @files = File::Find::Rule->file()->name( '*.pm' )->in( @INC );
81
82If you do not have that module, you can do the same thing
197aec24 83with File::Find which is part of the standard library.
49d635f9 84
85 use File::Find;
86 my @files;
87
88 find sub { push @files, $File::Find::name if -f _ && /\.pm$/ },
89 @INC;
90
91 print join "\n", @files;
197aec24 92
49d635f9 93If you simply need to quickly check to see if a module is
94available, you can check for its documentation. If you can
197aec24 95read the documentation the module is most likely installed.
49d635f9 96If you cannot read the documentation, the module might not
97have any (in rare cases).
98
99 prompt% perldoc Module::Name
100
101You can also try to include the module in a one-liner to see if
102perl finds it.
103
104 perl -MModule::Name -e1
197aec24 105
68dc0745 106=head2 How do I debug my Perl programs?
107
197aec24 108Have you tried C<use warnings> or used C<-w>? They enable warnings
a6dd486b 109to detect dubious practices.
68dc0745 110
92c2ed05 111Have you tried C<use strict>? It prevents you from using symbolic
112references, makes you predeclare any subroutines that you call as bare
113words, and (probably most importantly) forces you to predeclare your
a6dd486b 114variables with C<my>, C<our>, or C<use vars>.
68dc0745 115
a6dd486b 116Did you check the return values of each and every system call? The operating
117system (and thus Perl) tells you whether they worked, and if not
92c2ed05 118why.
68dc0745 119
92c2ed05 120 open(FH, "> /etc/cantwrite")
121 or die "Couldn't write to /etc/cantwrite: $!\n";
68dc0745 122
92c2ed05 123Did you read L<perltrap>? It's full of gotchas for old and new Perl
a6dd486b 124programmers and even has sections for those of you who are upgrading
92c2ed05 125from languages like I<awk> and I<C>.
126
127Have you tried the Perl debugger, described in L<perldebug>? You can
128step through your program and see what it's doing and thus work out
129why what it's doing isn't what it should be doing.
68dc0745 130
131=head2 How do I profile my Perl programs?
132
e083a89c 133You should get the Devel::DProf module from the standard distribution
197aec24 134(or separately on CPAN) and also use Benchmark.pm from the standard
135distribution. The Benchmark module lets you time specific portions of
136your code, while Devel::DProf gives detailed breakdowns of where your
e083a89c 137code spends its time.
68dc0745 138
92c2ed05 139Here's a sample use of Benchmark:
140
141 use Benchmark;
142
143 @junk = `cat /etc/motd`;
144 $count = 10_000;
145
146 timethese($count, {
147 'map' => sub { my @a = @junk;
148 map { s/a/b/ } @a;
6c43ef16 149 return @a },
92c2ed05 150 'for' => sub { my @a = @junk;
92c2ed05 151 for (@a) { s/a/b/ };
152 return @a },
153 });
154
155This is what it prints (on one machine--your results will be dependent
156on your hardware, operating system, and the load on your machine):
157
158 Benchmark: timing 10000 iterations of for, map...
159 for: 4 secs ( 3.97 usr 0.01 sys = 3.98 cpu)
160 map: 6 secs ( 4.97 usr 0.00 sys = 4.97 cpu)
161
65acb1b1 162Be aware that a good benchmark is very hard to write. It only tests the
a6dd486b 163data you give it and proves little about the differing complexities
65acb1b1 164of contrasting algorithms.
165
68dc0745 166=head2 How do I cross-reference my Perl programs?
167
197aec24 168The B::Xref module can be used to generate cross-reference reports
83ded9ee 169for Perl programs.
68dc0745 170
c8db1d39 171 perl -MO=Xref[,OPTIONS] scriptname.plx
68dc0745 172
173=head2 Is there a pretty-printer (formatter) for Perl?
174
55e174a4 175Perltidy is a Perl script which indents and reformats Perl scripts
176to make them easier to read by trying to follow the rules of the
177L<perlstyle>. If you write Perl scripts, or spend much time reading
178them, you will probably find it useful. It is available at
179http://perltidy.sourceforge.net
180
181Of course, if you simply follow the guidelines in L<perlstyle>,
182you shouldn't need to reformat. The habit of formatting your code
183as you write it will help prevent bugs. Your editor can and should
184help you with this. The perl-mode or newer cperl-mode for emacs
185can provide remarkable amounts of help with most (but not all)
186code, and even less programmable editors can provide significant
187assistance. Tom Christiansen and many other VI users swear by
188the following settings in vi and its clones:
65acb1b1 189
190 set ai sw=4
d92eb7b0 191 map! ^O {^M}^[O^T
65acb1b1 192
55e174a4 193Put that in your F<.exrc> file (replacing the caret characters
65acb1b1 194with control characters) and away you go. In insert mode, ^T is
a6dd486b 195for indenting, ^D is for undenting, and ^O is for blockdenting--
55e174a4 196as it were. A more complete example, with comments, can be found at
213329dd 197http://www.cpan.org/authors/id/TOMC/scripts/toms.exrc.gz
92c2ed05 198
49d635f9 199The a2ps http://www-inf.enst.fr/%7Edemaille/a2ps/black+white.ps.gz does
06a5f41f 200lots of things related to generating nicely printed output of
f05bbc40 201documents, as does enscript at http://people.ssh.fi/mtr/genscript/ .
65acb1b1 202
d92eb7b0 203=head2 Is there a ctags for Perl?
68dc0745 204
bc06af74 205Recent versions of ctags do much more than older versions did.
206EXUBERANT CTAGS is available from http://ctags.sourceforge.net/
207and does a good job of making tags files for perl code.
208
209There is also a simple one at
a93751fa 210http://www.cpan.org/authors/id/TOMC/scripts/ptags.gz which may do
bc06af74 211the trick. It can be easy to hack this into what you want.
65acb1b1 212
213=head2 Is there an IDE or Windows Perl Editor?
214
6641ed39 215Perl programs are just plain text, so any editor will do.
216
6641ed39 217If you're on Unix, you already have an IDE--Unix itself. The UNIX
218philosophy is the philosophy of several small tools that each do one
219thing and do it well. It's like a carpenter's toolbox.
220
28b41a80 221If you want an IDE, check the following (in alphabetical order, not
222order of preference):
68fbfbd7 223
224=over 4
225
28b41a80 226=item Eclipse
227
228The Eclipse Perl Integration Project integrates Perl
229editing/debugging with Eclipse.
230
231The website for the project is http://e-p-i-c.sf.net/
232
68fbfbd7 233=item Komodo
234
28b41a80 235ActiveState's cross-platform (as of October 2004, that's Windows, Linux,
236and Solaris), multi-language IDE has Perl support, including a regular expression
5ca69f12 237debugger and remote debugging
28b41a80 238( http://www.ActiveState.com/Products/Komodo/ ).
68fbfbd7 239
ac1094a1 240=item Open Perl IDE
241
242( http://open-perl-ide.sourceforge.net/ )
243Open Perl IDE is an integrated development environment for writing
244and debugging Perl scripts with ActiveState's ActivePerl distribution
245under Windows 95/98/NT/2000.
246
28b41a80 247=item OptiPerl
248
249( http://www.optiperl.com/ ) is a Windows IDE with simulated CGI
250environment, including debugger and syntax highlighting editor.
251
5ca69f12 252=item PerlBuilder
253
f224927c 254( http://www.solutionsoft.com/perl.htm ) is an integrated development
5ca69f12 255environment for Windows that supports Perl development.
8782d048 256
68fbfbd7 257=item visiPerl+
258
ac1094a1 259( http://helpconsulting.net/visiperl/ )
260From Help Consulting, for Windows.
68fbfbd7 261
28b41a80 262=item Visual Perl
263
264( http://www.activestate.com/Products/Visual_Perl/ )
265Visual Perl is a Visual Studio.NET plug-in from ActiveState.
29b1171f 266
29b1171f 267
68fbfbd7 268=back
269
5a13f98a 270For editors: if you're on Unix you probably have vi or a vi clone already,
6641ed39 271and possibly an emacs too, so you may not need to download anything.
5a13f98a 272In any emacs the cperl-mode (M-x cperl-mode) gives you perhaps the
6641ed39 273best available Perl editing mode in any editor.
274
cc30d1a7 275If you are using Windows, you can use any editor that lets
276you work with plain text, such as NotePad or WordPad. Word
277processors, such as Microsoft Word or WordPerfect, typically
278do not work since they insert all sorts of behind-the-scenes
279information, although some allow you to save files as "Text
280Only". You can also download text editors designed
281specifically for programming, such as Textpad
f224927c 282( http://www.textpad.com/ ) and UltraEdit
bfeeaf1b 283( http://www.ultraedit.com/ ), among others.
cc30d1a7 284
49d635f9 285If you are using MacOS, the same concerns apply. MacPerl
cc30d1a7 286(for Classic environments) comes with a simple editor.
bfeeaf1b 287Popular external editors are BBEdit ( http://www.bbedit.com/ )
c98c5709 288or Alpha ( http://www.his.com/~jguyer/Alpha/Alpha8.html ). MacOS X users can
877ae92e 289use Unix editors as well.
68fbfbd7 290
291=over 4
292
293=item GNU Emacs
294
295http://www.gnu.org/software/emacs/windows/ntemacs.html
296
297=item MicroEMACS
298
49d635f9 299http://www.microemacs.de/
68fbfbd7 300
301=item XEmacs
302
303http://www.xemacs.org/Download/index.html
304
49d635f9 305=item Jed
306
307http://space.mit.edu/~davis/jed/
308
68fbfbd7 309=back
310
311or a vi clone such as
312
313=over 4
314
315=item Elvis
316
317ftp://ftp.cs.pdx.edu/pub/elvis/ http://www.fh-wedel.de/elvis/
318
319=item Vile
320
49d635f9 321http://dickey.his.com/vile/vile.html
68fbfbd7 322
323=item Vim
324
325http://www.vim.org/
326
68fbfbd7 327=back
328
5a13f98a 329For vi lovers in general, Windows or elsewhere:
f05bbc40 330
331 http://www.thomer.com/thomer/vi/vi.html
6641ed39 332
f224927c 333nvi ( http://www.bostic.com/vi/ , available from CPAN in src/misc/) is
5a13f98a 334yet another vi clone, unfortunately not available for Windows, but in
6641ed39 335UNIX platforms you might be interested in trying it out, firstly because
336strictly speaking it is not a vi clone, it is the real vi, or the new
337incarnation of it, and secondly because you can embed Perl inside it
338to use Perl as the scripting language. nvi is not alone in this,
7c82de66 339though: at least also vim and vile offer an embedded Perl.
614a1598 340
68fbfbd7 341The following are Win32 multilanguage editor/IDESs that support Perl:
342
343=over 4
344
345=item Codewright
346
c98c5709 347http://www.borland.com/codewright/
68fbfbd7 348
349=item MultiEdit
350
351http://www.MultiEdit.com/
352
353=item SlickEdit
354
355http://www.slickedit.com/
356
357=back
8782d048 358
6641ed39 359There is also a toyedit Text widget based editor written in Perl
360that is distributed with the Tk module on CPAN. The ptkdb
f224927c 361( http://world.std.com/~aep/ptkdb/ ) is a Perl/tk based debugger that
8782d048 362acts as a development environment of sorts. Perl Composer
49d635f9 363( http://perlcomposer.sourceforge.net/ ) is an IDE for Perl/Tk
e083a89c 364GUI creation.
365
8782d048 366In addition to an editor/IDE you might be interested in a more
68fbfbd7 367powerful shell environment for Win32. Your options include
368
369=over 4
370
371=item Bash
372
1577cd80 373from the Cygwin package ( http://sources.redhat.com/cygwin/ )
68fbfbd7 374
375=item Ksh
376
f224927c 377from the MKS Toolkit ( http://www.mks.com/ ), or the Bourne shell of
1577cd80 378the U/WIN environment ( http://www.research.att.com/sw/tools/uwin/ )
68fbfbd7 379
380=item Tcsh
381
f224927c 382ftp://ftp.astron.com/pub/tcsh/ , see also
68fbfbd7 383http://www.primate.wisc.edu/software/csh-tcsh-book/
384
385=item Zsh
386
f224927c 387ftp://ftp.blarg.net/users/amol/zsh/ , see also http://www.zsh.org/
68fbfbd7 388
389=back
390
614a1598 391MKS and U/WIN are commercial (U/WIN is free for educational and
392research purposes), Cygwin is covered by the GNU Public License (but
393that shouldn't matter for Perl use). The Cygwin, MKS, and U/WIN all
394contain (in addition to the shells) a comprehensive set of standard
395UNIX toolkit utilities.
8782d048 396
5a13f98a 397If you're transferring text files between Unix and Windows using FTP
398be sure to transfer them in ASCII mode so the ends of lines are
399appropriately converted.
400
e083a89c 401On Mac OS the MacPerl Application comes with a simple 32k text editor
402that behaves like a rudimentary IDE. In contrast to the MacPerl Application
733271b5 403the MPW Perl tool can make use of the MPW Shell itself as an editor (with
68fbfbd7 404no 32k limit).
405
406=over 4
407
c98c5709 408=item Affrus
68fbfbd7 409
7678cced 410is a full Perl development enivornment with full debugger support
411( http://www.latenightsw.com ).
68fbfbd7 412
413=item Alpha
414
415is an editor, written and extensible in Tcl, that nonetheless has
733271b5 416built in support for several popular markup and programming languages
c98c5709 417including Perl and HTML ( http://www.his.com/~jguyer/Alpha/Alpha8.html ).
418
419=item BBEdit and BBEdit Lite
420
421are text editors for Mac OS that have a Perl sensitivity mode
422( http://web.barebones.com/ ).
423
68fbfbd7 424
425=back
426
427Pepper and Pe are programming language sensitive text editors for Mac
1577cd80 428OS X and BeOS respectively ( http://www.hekkelman.com/ ).
68dc0745 429
430=head2 Where can I get Perl macros for vi?
431
432For a complete version of Tom Christiansen's vi configuration file,
a93751fa 433see http://www.cpan.org/authors/Tom_Christiansen/scripts/toms.exrc.gz ,
a6dd486b 434the standard benchmark file for vi emulators. The file runs best with nvi,
5a964f20 435the current version of vi out of Berkeley, which incidentally can be built
bfeeaf1b 436with an embedded Perl interpreter--see http://www.cpan.org/src/misc/ .
68dc0745 437
438=head2 Where can I get perl-mode for emacs?
439
440Since Emacs version 19 patchlevel 22 or so, there have been both a
87275199 441perl-mode.el and support for the Perl debugger built in. These should
68dc0745 442come with the standard Emacs 19 distribution.
443
87275199 444In the Perl source directory, you'll find a directory called "emacs",
68dc0745 445which contains a cperl-mode that color-codes keywords, provides
446context-sensitive help, and other nifty things.
447
92c2ed05 448Note that the perl-mode of emacs will have fits with C<"main'foo">
d92eb7b0 449(single quote), and mess up the indentation and highlighting. You
65acb1b1 450are probably using C<"main::foo"> in new Perl code anyway, so this
92c2ed05 451shouldn't be an issue.
68dc0745 452
453=head2 How can I use curses with Perl?
454
455The Curses module from CPAN provides a dynamically loadable object
5a964f20 456module interface to a curses library. A small demo can be found at the
49d635f9 457directory http://www.cpan.org/authors/Tom_Christiansen/scripts/rep.gz ;
5a964f20 458this program repeats a command and updates the screen as needed, rendering
459B<rep ps axu> similar to B<top>.
68dc0745 460
461=head2 How can I use X or Tk with Perl?
462
5a964f20 463Tk is a completely Perl-based, object-oriented interface to the Tk toolkit
464that doesn't force you to use Tcl just to get at Tk. Sx is an interface
465to the Athena Widget set. Both are available from CPAN. See the
a93751fa 466directory http://www.cpan.org/modules/by-category/08_User_Interfaces/
68dc0745 467
a6dd486b 468Invaluable for Perl/Tk programming are the Perl/Tk FAQ at
c98c5709 469http://phaseit.net/claird/comp.lang.perl.tk/ptkFAQ.html , the Perl/Tk Reference
92c2ed05 470Guide available at
213329dd 471http://www.cpan.org/authors/Stephen_O_Lidie/ , and the
92c2ed05 472online manpages at
87275199 473http://www-users.cs.umn.edu/%7Eamundson/perl/perltk/toc.html .
92c2ed05 474
68dc0745 475=head2 How can I make my Perl program run faster?
476
92c2ed05 477The best way to do this is to come up with a better algorithm. This
b73a15ae 478can often make a dramatic difference. Jon Bentley's book
5cd0b561 479I<Programming Pearls> (that's not a misspelling!) has some good tips
92c2ed05 480on optimization, too. Advice on benchmarking boils down to: benchmark
481and profile to make sure you're optimizing the right part, look for
482better algorithms instead of microtuning your code, and when all else
57b19278 483fails consider just buying faster hardware. You will probably want to
5cd0b561 484read the answer to the earlier question ``How do I profile my Perl
485programs?'' if you haven't done so already.
68dc0745 486
92c2ed05 487A different approach is to autoload seldom-used Perl code. See the
68dc0745 488AutoSplit and AutoLoader modules in the standard distribution for
489that. Or you could locate the bottleneck and think about writing just
490that part in C, the way we used to take bottlenecks in C code and
5cd0b561 491write them in assembler. Similar to rewriting in C, modules that have
492critical sections can be written in C (for instance, the PDL module
493from CPAN).
494
495If you're currently linking your perl executable to a shared
496I<libc.so>, you can often gain a 10-25% performance benefit by
497rebuilding it to link with a static libc.a instead. This will make a
498bigger perl executable, but your Perl programs (and programmers) may
499thank you for it. See the F<INSTALL> file in the source distribution
500for more information.
501
502The undump program was an ancient attempt to speed up Perl program by
503storing the already-compiled form to disk. This is no longer a viable
504option, as it only worked on a few architectures, and wasn't a good
505solution anyway.
68dc0745 506
507=head2 How can I make my Perl program take less memory?
508
509When it comes to time-space tradeoffs, Perl nearly always prefers to
510throw memory at a problem. Scalars in Perl use more memory than
65acb1b1 511strings in C, arrays take more than that, and hashes use even more. While
68dc0745 512there's still a lot to be done, recent releases have been addressing
513these issues. For example, as of 5.004, duplicate hash keys are
514shared amongst all hashes using them, so require no reallocation.
515
516In some cases, using substr() or vec() to simulate arrays can be
517highly beneficial. For example, an array of a thousand booleans will
518take at least 20,000 bytes of space, but it can be turned into one
a6dd486b 519125-byte bit vector--a considerable memory savings. The standard
68dc0745 520Tie::SubstrHash module can also help for certain types of data
521structure. If you're working with specialist data structures
522(matrices, for instance) modules that implement these in C may use
523less memory than equivalent Perl modules.
524
525Another thing to try is learning whether your Perl was compiled with
54310121 526the system malloc or with Perl's builtin malloc. Whichever one it
68dc0745 527is, try using the other one and see whether this makes a difference.
528Information about malloc is in the F<INSTALL> file in the source
529distribution. You can find out whether you are using perl's malloc by
530typing C<perl -V:usemymalloc>.
531
24f1ba9b 532Of course, the best way to save memory is to not do anything to waste
533it in the first place. Good programming practices can go a long way
534toward this:
535
536=over 4
537
538=item * Don't slurp!
539
540Don't read an entire file into memory if you can process it line
541by line. Or more concretely, use a loop like this:
542
543 #
544 # Good Idea
545 #
546 while (<FILE>) {
547 # ...
548 }
549
550instead of this:
551
552 #
553 # Bad Idea
554 #
555 @data = <FILE>;
556 foreach (@data) {
557 # ...
558 }
559
560When the files you're processing are small, it doesn't much matter which
561way you do it, but it makes a huge difference when they start getting
197aec24 562larger.
24f1ba9b 563
bc06af74 564=item * Use map and grep selectively
565
566Remember that both map and grep expect a LIST argument, so doing this:
567
568 @wanted = grep {/pattern/} <FILE>;
569
570will cause the entire file to be slurped. For large files, it's better
571to loop:
572
573 while (<FILE>) {
574 push(@wanted, $_) if /pattern/;
575 }
576
577=item * Avoid unnecessary quotes and stringification
578
579Don't quote large strings unless absolutely necessary:
580
581 my $copy = "$large_string";
582
583makes 2 copies of $large_string (one for $copy and another for the
584quotes), whereas
585
586 my $copy = $large_string;
587
588only makes one copy.
589
590Ditto for stringifying large arrays:
591
592 {
593 local $, = "\n";
594 print @big_array;
595 }
596
597is much more memory-efficient than either
598
599 print join "\n", @big_array;
600
601or
602
603 {
604 local $" = "\n";
605 print "@big_array";
606 }
607
608
24f1ba9b 609=item * Pass by reference
610
611Pass arrays and hashes by reference, not by value. For one thing, it's
612the only way to pass multiple lists or hashes (or both) in a single
613call/return. It also avoids creating a copy of all the contents. This
614requires some judgment, however, because any changes will be propagated
615back to the original data. If you really want to mangle (er, modify) a
616copy, you'll have to sacrifice the memory needed to make one.
617
618=item * Tie large variables to disk.
619
620For "big" data stores (i.e. ones that exceed available memory) consider
621using one of the DB modules to store it on disk instead of in RAM. This
ed8cf1fe 622will incur a penalty in access time, but that's probably better than
24f1ba9b 623causing your hard disk to thrash due to massive swapping.
624
625=back
626
49d635f9 627=head2 Is it safe to return a reference to local or lexical data?
68dc0745 628
49d635f9 629Yes. Perl's garbage collection system takes care of this so
630everything works out right.
68dc0745 631
632 sub makeone {
633 my @a = ( 1 .. 10 );
634 return \@a;
635 }
636
197aec24 637 for ( 1 .. 10 ) {
68dc0745 638 push @many, makeone();
639 }
640
641 print $many[4][5], "\n";
642
643 print "@many\n";
644
645=head2 How can I free an array or hash so my program shrinks?
646
7678cced 647(contributed by Michael Carman)
648
649You usually can't. Memory allocated to lexicals (i.e. my() variables)
650cannot be reclaimed or reused even if they go out of scope. It is
651reserved in case the variables come back into scope. Memory allocated
652to global variables can be reused (within your program) by using
653undef()ing and/or delete().
654
655On most operating systems, memory allocated to a program can never be
656returned to the system. That's why long-running programs sometimes re-
657exec themselves. Some operating systems (notably, systems that use
658mmap(2) for allocating large chunks of memory) can reclaim memory that
659is no longer used, but on such systems, perl must be configured and
660compiled to use the OS's malloc, not perl's.
661
46fc3d4c 662In general, memory allocation and de-allocation isn't something you can
7678cced 663or should be worrying about much in Perl.
664
665See also "How can I make my Perl program take less memory?"
68dc0745 666
667=head2 How can I make my CGI script more efficient?
668
669Beyond the normal measures described to make general Perl programs
670faster or smaller, a CGI program has additional issues. It may be run
671several times per second. Given that each time it runs it will need
46fc3d4c 672to be re-compiled and will often allocate a megabyte or more of system
68dc0745 673memory, this can be a killer. Compiling into C B<isn't going to help
46fc3d4c 674you> because the process start-up overhead is where the bottleneck is.
68dc0745 675
92c2ed05 676There are two popular ways to avoid this overhead. One solution
677involves running the Apache HTTP server (available from
f224927c 678http://www.apache.org/ ) with either of the mod_perl or mod_fastcgi
92c2ed05 679plugin modules.
680
681With mod_perl and the Apache::Registry module (distributed with
682mod_perl), httpd will run with an embedded Perl interpreter which
683pre-compiles your script and then executes it within the same address
684space without forking. The Apache extension also gives Perl access to
685the internal server API, so modules written in Perl can do just about
686anything a module written in C can. For more on mod_perl, see
687http://perl.apache.org/
688
65acb1b1 689With the FCGI module (from CPAN) and the mod_fastcgi
bfeeaf1b 690module (available from http://www.fastcgi.com/ ) each of your Perl
87275199 691programs becomes a permanent CGI daemon process.
68dc0745 692
693Both of these solutions can have far-reaching effects on your system
87275199 694and on the way you write your CGI programs, so investigate them with
68dc0745 695care.
696
a93751fa 697See http://www.cpan.org/modules/by-category/15_World_Wide_Web_HTML_HTTP_CGI/ .
5a964f20 698
65acb1b1 699A non-free, commercial product, ``The Velocity Engine for Perl'',
a6dd486b 700(http://www.binevolve.com/ or http://www.binevolve.com/velocigen/ )
701might also be worth looking at. It will allow you to increase the
702performance of your Perl programs, running programs up to 25 times
703faster than normal CGI Perl when running in persistent Perl mode or 4
704to 5 times faster without any modification to your existing CGI
705programs. Fully functional evaluation copies are available from the
706web site.
c8db1d39 707
68dc0745 708=head2 How can I hide the source for my Perl program?
709
710Delete it. :-) Seriously, there are a number of (mostly
92c2ed05 711unsatisfactory) solutions with varying levels of ``security''.
68dc0745 712
713First of all, however, you I<can't> take away read permission, because
714the source code has to be readable in order to be compiled and
715interpreted. (That doesn't mean that a CGI script's source is
a6dd486b 716readable by people on the web, though--only by people with access to
717the filesystem.) So you have to leave the permissions at the socially
92c2ed05 718friendly 0755 level.
68dc0745 719
720Some people regard this as a security problem. If your program does
a6dd486b 721insecure things and relies on people not knowing how to exploit those
68dc0745 722insecurities, it is not secure. It is often possible for someone to
723determine the insecure things and exploit them without viewing the
724source. Security through obscurity, the name for hiding your bugs
725instead of fixing them, is little security indeed.
726
83df6a1d 727You can try using encryption via source filters (Starting from Perl
7285.8 the Filter::Simple and Filter::Util::Call modules are included in
729the standard distribution), but any decent programmer will be able to
730decrypt it. You can try using the byte code compiler and interpreter
731described below, but the curious might still be able to de-compile it.
732You can try using the native-code compiler described below, but
733crackers might be able to disassemble it. These pose varying degrees
734of difficulty to people wanting to get at your code, but none can
735definitively conceal it (true of every language, not just Perl).
68dc0745 736
49d635f9 737It is very easy to recover the source of Perl programs. You simply
738feed the program to the perl interpreter and use the modules in
739the B:: hierarchy. The B::Deparse module should be able to
740defeat most attempts to hide source. Again, this is not
741unique to Perl.
742
68dc0745 743If you're concerned about people profiting from your code, then the
d92eb7b0 744bottom line is that nothing but a restrictive license will give you
68dc0745 745legal security. License your software and pepper it with threatening
92c2ed05 746statements like ``This is unpublished proprietary software of XYZ Corp.
68dc0745 747Your access to it does not give you permission to use it blah blah
92c2ed05 748blah.'' We are not lawyers, of course, so you should see a lawyer if
d92eb7b0 749you want to be sure your license's wording will stand up in court.
68dc0745 750
54310121 751=head2 How can I compile my Perl program into byte code or C?
68dc0745 752
7678cced 753(contributed by brian d foy)
754
755In general, you can't do this. There are some things that may work
756for your situation though. People usually ask this question
757because they want to distribute their works without giving away
758the source code, and most solutions trade disk space for convenience.
759You probably won't see much of a speed increase either, since most
760solutions simply bundle a Perl interpreter in the final product
761(but see L<How can I make my Perl program run faster?>).
762
763The Perl Archive Toolkit (http://par.perl.org/index.cgi) is
764Perl's analog to Java's JAR. It's freely available and on
765CPAN (http://search.cpan.org/dist/PAR/).
766
767The B::* namespace, often called "the Perl compiler", but is really a
768way for Perl programs to peek at its innards rather than create
769pre-compiled versions of your program. However. the B::Bytecode
770module can turn your script into a bytecode format that could be
771loaded later by the ByteLoader module and executed as a regular Perl
772script.
773
774There are also some commercial products that may work for
775you, although you have to buy a license for them.
776
777The Perl Dev Kit
778(http://www.activestate.com/Products/Perl_Dev_Kit/) from
779ActiveState can "Turn your Perl programs into ready-to-run
780executables for HP-UX, Linux, Solaris and Windows."
781
782Perl2Exe (http://www.indigostar.com/perl2exe.htm) is a
783command line program for converting perl scripts to
784executable files. It targets both Windows and unix
785platforms.
786
5a964f20 787
65acb1b1 788=head2 How can I compile Perl into Java?
789
a6dd486b 790You can also integrate Java and Perl with the
c98c5709 791Perl Resource Kit from O'Reilly Media. See
a6dd486b 792http://www.oreilly.com/catalog/prkunix/ .
793
794Perl 5.6 comes with Java Perl Lingo, or JPL. JPL, still in
795development, allows Perl code to be called from Java. See jpl/README
796in the Perl source tree.
65acb1b1 797
92c2ed05 798=head2 How can I get C<#!perl> to work on [MS-DOS,NT,...]?
68dc0745 799
800For OS/2 just use
801
802 extproc perl -S -your_switches
803
804as the first line in C<*.cmd> file (C<-S> due to a bug in cmd.exe's
46fc3d4c 805`extproc' handling). For DOS one should first invent a corresponding
fd1adc71 806batch file and codify it in C<ALTERNATE_SHEBANG> (see the
807F<dosish.h> file in the source distribution for more information).
68dc0745 808
92c2ed05 809The Win95/NT installation, when using the ActiveState port of Perl,
810will modify the Registry to associate the C<.pl> extension with the
d92eb7b0 811perl interpreter. If you install another port, perhaps even building
812your own Win95/NT Perl from the standard sources by using a Windows port
d702ae42 813of gcc (e.g., with cygwin or mingw32), then you'll have to modify
d92eb7b0 814the Registry yourself. In addition to associating C<.pl> with the
815interpreter, NT people can use: C<SET PATHEXT=%PATHEXT%;.PL> to let them
816run the program C<install-linux.pl> merely by typing C<install-linux>.
68dc0745 817
8e30f651 818Under "Classic" MacOS, a perl program will have the appropriate Creator and
819Type, so that double-clicking them will invoke the MacPerl application.
820Under Mac OS X, clickable apps can be made from any C<#!> script using Wil
821Sanchez' DropScript utility: http://www.wsanchez.net/software/ .
68dc0745 822
823I<IMPORTANT!>: Whatever you do, PLEASE don't get frustrated, and just
824throw the perl interpreter into your cgi-bin directory, in order to
87275199 825get your programs working for a web server. This is an EXTREMELY big
68dc0745 826security risk. Take the time to figure out how to do it correctly.
827
87275199 828=head2 Can I write useful Perl programs on the command line?
68dc0745 829
830Yes. Read L<perlrun> for more information. Some examples follow.
831(These assume standard Unix shell quoting rules.)
832
833 # sum first and last fields
5a964f20 834 perl -lane 'print $F[0] + $F[-1]' *
68dc0745 835
836 # identify text files
837 perl -le 'for(@ARGV) {print if -f && -T _}' *
838
5a964f20 839 # remove (most) comments from C program
68dc0745 840 perl -0777 -pe 's{/\*.*?\*/}{}gs' foo.c
841
842 # make file a month younger than today, defeating reaper daemons
843 perl -e '$X=24*60*60; utime(time(),time() + 30 * $X,@ARGV)' *
844
845 # find first unused uid
846 perl -le '$i++ while getpwuid($i); print $i'
847
848 # display reasonable manpath
849 echo $PATH | perl -nl -072 -e '
850 s![^/+]*$!man!&&-d&&!$s{$_}++&&push@m,$_;END{print"@m"}'
851
87275199 852OK, the last one was actually an Obfuscated Perl Contest entry. :-)
68dc0745 853
87275199 854=head2 Why don't Perl one-liners work on my DOS/Mac/VMS system?
68dc0745 855
856The problem is usually that the command interpreters on those systems
857have rather different ideas about quoting than the Unix shells under
858which the one-liners were created. On some systems, you may have to
859change single-quotes to double ones, which you must I<NOT> do on Unix
860or Plan9 systems. You might also have to change a single % to a %%.
861
862For example:
863
864 # Unix
865 perl -e 'print "Hello world\n"'
866
46fc3d4c 867 # DOS, etc.
68dc0745 868 perl -e "print \"Hello world\n\""
869
46fc3d4c 870 # Mac
68dc0745 871 print "Hello world\n"
872 (then Run "Myscript" or Shift-Command-R)
873
d2321c93 874 # MPW
875 perl -e 'print "Hello world\n"'
876
68dc0745 877 # VMS
878 perl -e "print ""Hello world\n"""
879
a6dd486b 880The problem is that none of these examples are reliable: they depend on the
92c2ed05 881command interpreter. Under Unix, the first two often work. Under DOS,
a6dd486b 882it's entirely possible that neither works. If 4DOS was the command shell,
92c2ed05 883you'd probably have better luck like this:
68dc0745 884
885 perl -e "print <Ctrl-x>"Hello world\n<Ctrl-x>""
886
46fc3d4c 887Under the Mac, it depends which environment you are using. The MacPerl
68dc0745 888shell, or MPW, is much like Unix shells in its support for several
46fc3d4c 889quoting variants, except that it makes free use of the Mac's non-ASCII
68dc0745 890characters as control characters.
891
65acb1b1 892Using qq(), q(), and qx(), instead of "double quotes", 'single
893quotes', and `backticks`, may make one-liners easier to write.
894
d2321c93 895There is no general solution to all of this. It is a mess.
68dc0745 896
897[Some of this answer was contributed by Kenneth Albanowski.]
898
899=head2 Where can I learn about CGI or Web programming in Perl?
900
901For modules, get the CGI or LWP modules from CPAN. For textbooks,
902see the two especially dedicated to web stuff in the question on
92c2ed05 903books. For problems and questions related to the web, like ``Why
904do I get 500 Errors'' or ``Why doesn't it run from the browser right
8305e449 905when it runs fine on the command line'', see the troubleshooting
906guides and references in L<perlfaq9> or in the CGI MetaFAQ:
68dc0745 907
8305e449 908 http://www.perl.org/CGI_MetaFAQ.html
0f542199 909
68dc0745 910=head2 Where can I learn about object-oriented Perl programming?
911
a6dd486b 912A good place to start is L<perltoot>, and you can use L<perlobj>,
06a5f41f 913L<perlboot>, L<perltoot>, L<perltooc>, and L<perlbot> for reference.
914(If you are using really old Perl, you may not have all of these,
915try http://www.perldoc.com/ , but consider upgrading your perl.)
916
917A good book on OO on Perl is the "Object-Oriented Perl"
197aec24 918by Damian Conway from Manning Publications,
06a5f41f 919http://www.manning.com/Conway/index.html
68dc0745 920
921=head2 Where can I learn about linking C with Perl? [h2xs, xsubpp]
922
923If you want to call C from Perl, start with L<perlxstut>,
924moving on to L<perlxs>, L<xsubpp>, and L<perlguts>. If you want to
925call Perl from C, then read L<perlembed>, L<perlcall>, and
926L<perlguts>. Don't forget that you can learn a lot from looking at
927how the authors of existing extension modules wrote their code and
928solved their problems.
929
7678cced 930=head2 I've read perlembed, perlguts, etc., but I can't embed perl in my C program; what am I doing wrong?
68dc0745 931
932Download the ExtUtils::Embed kit from CPAN and run `make test'. If
933the tests pass, read the pods again and again and again. If they
87275199 934fail, see L<perlbug> and send a bug report with the output of
68dc0745 935C<make test TEST_VERBOSE=1> along with C<perl -V>.
936
83ded9ee 937=head2 When I tried to run my script, I got this message. What does it mean?
68dc0745 938
87275199 939A complete list of Perl's error messages and warnings with explanatory
940text can be found in L<perldiag>. You can also use the splain program
941(distributed with Perl) to explain the error messages:
68dc0745 942
943 perl program 2>diag.out
944 splain [-v] [-p] diag.out
945
946or change your program to explain the messages for you:
947
948 use diagnostics;
949
950or
951
952 use diagnostics -verbose;
953
954=head2 What's MakeMaker?
955
87275199 956This module (part of the standard Perl distribution) is designed to
68dc0745 957write a Makefile for an extension module from a Makefile.PL. For more
958information, see L<ExtUtils::MakeMaker>.
959
960=head1 AUTHOR AND COPYRIGHT
961
7678cced 962Copyright (c) 1997-2005 Tom Christiansen, Nathan Torkington, and
963other authors as noted. All rights reserved.
5a964f20 964
5a7beb56 965This documentation is free; you can redistribute it and/or modify it
966under the same terms as Perl itself.
c8db1d39 967
87275199 968Irrespective of its distribution, all code examples here are in the public
c8db1d39 969domain. You are permitted and encouraged to use this code and any
970derivatives thereof in your own programs for fun or for profit as you
971see fit. A simple comment in the code giving credit to the FAQ would
972be courteous but is not required.