diff options
Diffstat (limited to 'upstream/debian-unstable/man1/perlfaq3.1')
| -rw-r--r-- | upstream/debian-unstable/man1/perlfaq3.1 | 1161 |
1 files changed, 1161 insertions, 0 deletions
diff --git a/upstream/debian-unstable/man1/perlfaq3.1 b/upstream/debian-unstable/man1/perlfaq3.1 new file mode 100644 index 00000000..19fcb454 --- /dev/null +++ b/upstream/debian-unstable/man1/perlfaq3.1 @@ -0,0 +1,1161 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "PERLFAQ3 1" +.TH PERLFAQ3 1 2024-01-12 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +perlfaq3 \- Programming Tools +.SH VERSION +.IX Header "VERSION" +version 5.20210520 +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This section of the FAQ answers questions related to programmer tools +and programming support. +.SS "How do I do (anything)?" +.IX Subsection "How do I do (anything)?" +Have you looked at CPAN (see perlfaq2)? The chances are that +someone has already written a module that can solve your problem. +Have you read the appropriate manpages? Here's a brief index: +.IP Basics 4 +.IX Item "Basics" +.RS 4 +.PD 0 +.IP "perldata \- Perl data types" 4 +.IX Item "perldata - Perl data types" +.IP "perlvar \- Perl pre-defined variables" 4 +.IX Item "perlvar - Perl pre-defined variables" +.IP "perlsyn \- Perl syntax" 4 +.IX Item "perlsyn - Perl syntax" +.IP "perlop \- Perl operators and precedence" 4 +.IX Item "perlop - Perl operators and precedence" +.IP "perlsub \- Perl subroutines" 4 +.IX Item "perlsub - Perl subroutines" +.RE +.RS 4 +.RE +.IP Execution 4 +.IX Item "Execution" +.RS 4 +.IP "perlrun \- how to execute the Perl interpreter" 4 +.IX Item "perlrun - how to execute the Perl interpreter" +.IP "perldebug \- Perl debugging" 4 +.IX Item "perldebug - Perl debugging" +.RE +.RS 4 +.RE +.IP Functions 4 +.IX Item "Functions" +.RS 4 +.IP "perlfunc \- Perl builtin functions" 4 +.IX Item "perlfunc - Perl builtin functions" +.RE +.RS 4 +.RE +.IP Objects 4 +.IX Item "Objects" +.RS 4 +.IP "perlref \- Perl references and nested data structures" 4 +.IX Item "perlref - Perl references and nested data structures" +.IP "perlmod \- Perl modules (packages and symbol tables)" 4 +.IX Item "perlmod - Perl modules (packages and symbol tables)" +.IP "perlobj \- Perl objects" 4 +.IX Item "perlobj - Perl objects" +.IP "perltie \- how to hide an object class in a simple variable" 4 +.IX Item "perltie - how to hide an object class in a simple variable" +.RE +.RS 4 +.RE +.IP "Data Structures" 4 +.IX Item "Data Structures" +.RS 4 +.IP "perlref \- Perl references and nested data structures" 4 +.IX Item "perlref - Perl references and nested data structures" +.IP "perllol \- Manipulating arrays of arrays in Perl" 4 +.IX Item "perllol - Manipulating arrays of arrays in Perl" +.IP "perldsc \- Perl Data Structures Cookbook" 4 +.IX Item "perldsc - Perl Data Structures Cookbook" +.RE +.RS 4 +.RE +.IP Modules 4 +.IX Item "Modules" +.RS 4 +.IP "perlmod \- Perl modules (packages and symbol tables)" 4 +.IX Item "perlmod - Perl modules (packages and symbol tables)" +.IP "perlmodlib \- constructing new Perl modules and finding existing ones" 4 +.IX Item "perlmodlib - constructing new Perl modules and finding existing ones" +.RE +.RS 4 +.RE +.IP Regexes 4 +.IX Item "Regexes" +.RS 4 +.IP "perlre \- Perl regular expressions" 4 +.IX Item "perlre - Perl regular expressions" +.IP "perlfunc \- Perl builtin functions>" 4 +.IX Item "perlfunc - Perl builtin functions>" +.IP "perlop \- Perl operators and precedence" 4 +.IX Item "perlop - Perl operators and precedence" +.IP "perllocale \- Perl locale handling (internationalization and localization)" 4 +.IX Item "perllocale - Perl locale handling (internationalization and localization)" +.RE +.RS 4 +.RE +.IP "Moving to perl5" 4 +.IX Item "Moving to perl5" +.RS 4 +.IP "perltrap \- Perl traps for the unwary" 4 +.IX Item "perltrap - Perl traps for the unwary" +.IP perl 4 +.IX Item "perl" +.RE +.RS 4 +.RE +.IP "Linking with C" 4 +.IX Item "Linking with C" +.RS 4 +.IP "perlxstut \- Tutorial for writing XSUBs" 4 +.IX Item "perlxstut - Tutorial for writing XSUBs" +.IP "perlxs \- XS language reference manual" 4 +.IX Item "perlxs - XS language reference manual" +.IP "perlcall \- Perl calling conventions from C" 4 +.IX Item "perlcall - Perl calling conventions from C" +.IP "perlguts \- Introduction to the Perl API" 4 +.IX Item "perlguts - Introduction to the Perl API" +.IP "perlembed \- how to embed perl in your C program" 4 +.IX Item "perlembed - how to embed perl in your C program" +.RE +.RS 4 +.RE +.IP Various 4 +.IX Item "Various" +.PD +<http://www.cpan.org/misc/olddoc/FMTEYEWTK.tgz> +(not a man-page but still useful, a collection of various essays on +Perl techniques) +.PP +A crude table of contents for the Perl manpage set is found in perltoc. +.SS "How can I use Perl interactively?" +.IX Subsection "How can I use Perl interactively?" +The typical approach uses the Perl debugger, described in the +\&\fBperldebug\fR\|(1) manpage, on an "empty" program, like this: +.PP +.Vb 1 +\& perl \-de 42 +.Ve +.PP +Now just type in any legal Perl code, and it will be immediately +evaluated. You can also examine the symbol table, get stack +backtraces, check variable values, set breakpoints, and other +operations typically found in symbolic debuggers. +.PP +You can also use Devel::REPL which is an interactive shell for Perl, +commonly known as a REPL \- Read, Evaluate, Print, Loop. It provides +various handy features. +.SS "How do I find which modules are installed on my system?" +.IX Subsection "How do I find which modules are installed on my system?" +From the command line, you can use the \f(CW\*(C`cpan\*(C'\fR command's \f(CW\*(C`\-l\*(C'\fR switch: +.PP +.Vb 1 +\& $ cpan \-l +.Ve +.PP +You can also use \f(CW\*(C`cpan\*(C'\fR's \f(CW\*(C`\-a\*(C'\fR switch to create an autobundle file +that \f(CW\*(C`CPAN.pm\*(C'\fR understands and can use to re-install every module: +.PP +.Vb 1 +\& $ cpan \-a +.Ve +.PP +Inside a Perl program, you can use the ExtUtils::Installed module to +show all installed distributions, although it can take awhile to do +its magic. The standard library which comes with Perl just shows up +as "Perl" (although you can get those with Module::CoreList). +.PP +.Vb 1 +\& use ExtUtils::Installed; +\& +\& my $inst = ExtUtils::Installed\->new(); +\& my @modules = $inst\->modules(); +.Ve +.PP +If you want a list of all of the Perl module filenames, you +can use File::Find::Rule: +.PP +.Vb 1 +\& use File::Find::Rule; +\& +\& my @files = File::Find::Rule\-> +\& extras({follow => 1})\-> +\& file()\-> +\& name( \*(Aq*.pm\*(Aq )\-> +\& in( @INC ) +\& ; +.Ve +.PP +If you do not have that module, you can do the same thing +with File::Find which is part of the standard library: +.PP +.Vb 2 +\& use File::Find; +\& my @files; +\& +\& find( +\& { +\& wanted => sub { +\& push @files, $File::Find::fullname +\& if \-f $File::Find::fullname && /\e.pm$/ +\& }, +\& follow => 1, +\& follow_skip => 2, +\& }, +\& @INC +\& ); +\& +\& print join "\en", @files; +.Ve +.PP +If you simply need to check quickly to see if a module is +available, you can check for its documentation. If you can +read the documentation the module is most likely installed. +If you cannot read the documentation, the module might not +have any (in rare cases): +.PP +.Vb 1 +\& $ perldoc Module::Name +.Ve +.PP +You can also try to include the module in a one-liner to see if +perl finds it: +.PP +.Vb 1 +\& $ perl \-MModule::Name \-e1 +.Ve +.PP +(If you don't receive a "Can't locate ... in \f(CW@INC\fR" error message, then Perl +found the module name you asked for.) +.SS "How do I debug my Perl programs?" +.IX Subsection "How do I debug my Perl programs?" +(contributed by brian d foy) +.PP +Before you do anything else, you can help yourself by ensuring that +you let Perl tell you about problem areas in your code. By turning +on warnings and strictures, you can head off many problems before +they get too big. You can find out more about these in strict +and warnings. +.PP +.Vb 3 +\& #!/usr/bin/perl +\& use strict; +\& use warnings; +.Ve +.PP +Beyond that, the simplest debugger is the \f(CW\*(C`print\*(C'\fR function. Use it +to look at values as you run your program: +.PP +.Vb 1 +\& print STDERR "The value is [$value]\en"; +.Ve +.PP +The Data::Dumper module can pretty-print Perl data structures: +.PP +.Vb 2 +\& use Data::Dumper qw( Dumper ); +\& print STDERR "The hash is " . Dumper( \e%hash ) . "\en"; +.Ve +.PP +Perl comes with an interactive debugger, which you can start with the +\&\f(CW\*(C`\-d\*(C'\fR switch. It's fully explained in perldebug. +.PP +If you'd like a graphical user interface and you have Tk, you can use +\&\f(CW\*(C`ptkdb\*(C'\fR. It's on CPAN and available for free. +.PP +If you need something much more sophisticated and controllable, Leon +Brocard's Devel::ebug (which you can call with the \f(CW\*(C`\-D\*(C'\fR switch as \f(CW\*(C`\-Debug\*(C'\fR) +gives you the programmatic hooks into everything you need to write your +own (without too much pain and suffering). +.PP +You can also use a commercial debugger such as Affrus (Mac OS X), Komodo +from Activestate (Windows and Mac OS X), or EPIC (most platforms). +.SS "How do I profile my Perl programs?" +.IX Subsection "How do I profile my Perl programs?" +(contributed by brian d foy, updated Fri Jul 25 12:22:26 PDT 2008) +.PP +The \f(CW\*(C`Devel\*(C'\fR namespace has several modules which you can use to +profile your Perl programs. +.PP +The Devel::NYTProf (New York Times Profiler) does both statement +and subroutine profiling. It's available from CPAN and you also invoke +it with the \f(CW\*(C`\-d\*(C'\fR switch: +.PP +.Vb 1 +\& perl \-d:NYTProf some_perl.pl +.Ve +.PP +It creates a database of the profile information that you can turn into +reports. The \f(CW\*(C`nytprofhtml\*(C'\fR command turns the data into an HTML report +similar to the Devel::Cover report: +.PP +.Vb 1 +\& nytprofhtml +.Ve +.PP +You might also be interested in using the Benchmark to +measure and compare code snippets. +.PP +You can read more about profiling in \fIProgramming Perl\fR, chapter 20, +or \fIMastering Perl\fR, chapter 5. +.PP +perldebguts documents creating a custom debugger if you need to +create a special sort of profiler. brian d foy describes the process +in \fIThe Perl Journal\fR, "Creating a Perl Debugger", +<http://www.ddj.com/184404522> , and "Profiling in Perl" +<http://www.ddj.com/184404580> . +.PP +Perl.com has two interesting articles on profiling: "Profiling Perl", +by Simon Cozens, <https://www.perl.com/pub/2004/06/25/profiling.html/> +and "Debugging and Profiling mod_perl Applications", by Frank Wiles, +<http://www.perl.com/pub/a/2006/02/09/debug_mod_perl.html> . +.PP +Randal L. Schwartz writes about profiling in "Speeding up Your Perl +Programs" for \fIUnix Review\fR, +<http://www.stonehenge.com/merlyn/UnixReview/col49.html> , and "Profiling +in Template Toolkit via Overriding" for \fILinux Magazine\fR, +<http://www.stonehenge.com/merlyn/LinuxMag/col75.html> . +.SS "How do I cross-reference my Perl programs?" +.IX Subsection "How do I cross-reference my Perl programs?" +The B::Xref module can be used to generate cross-reference reports +for Perl programs. +.PP +.Vb 1 +\& perl \-MO=Xref[,OPTIONS] scriptname.plx +.Ve +.SS "Is there a pretty-printer (formatter) for Perl?" +.IX Subsection "Is there a pretty-printer (formatter) for Perl?" +Perl::Tidy comes with a perl script perltidy which indents and +reformats Perl scripts to make them easier to read by trying to follow +the rules of the perlstyle. If you write Perl, or spend much time reading +Perl, you will probably find it useful. +.PP +Of course, if you simply follow the guidelines in perlstyle, +you shouldn't need to reformat. The habit of formatting your code +as you write it will help prevent bugs. Your editor can and should +help you with this. The perl-mode or newer cperl-mode for emacs +can provide remarkable amounts of help with most (but not all) +code, and even less programmable editors can provide significant +assistance. Tom Christiansen and many other VI users swear by +the following settings in vi and its clones: +.PP +.Vb 2 +\& set ai sw=4 +\& map! ^O {^M}^[O^T +.Ve +.PP +Put that in your \fI.exrc\fR file (replacing the caret characters +with control characters) and away you go. In insert mode, ^T is +for indenting, ^D is for undenting, and ^O is for blockdenting\-\-as +it were. A more complete example, with comments, can be found at +<http://www.cpan.org/authors/id/T/TO/TOMC/scripts/toms.exrc.gz> +.SS "Is there an IDE or Windows Perl Editor?" +.IX Subsection "Is there an IDE or Windows Perl Editor?" +Perl programs are just plain text, so any editor will do. +.PP +If you're on Unix, you already have an IDE\-\-Unix itself. The Unix +philosophy is the philosophy of several small tools that each do one +thing and do it well. It's like a carpenter's toolbox. +.PP +If you want an IDE, check the following (in alphabetical order, not +order of preference): +.IP Eclipse 4 +.IX Item "Eclipse" +<http://e\-p\-i\-c.sf.net/> +.Sp +The Eclipse Perl Integration Project integrates Perl +editing/debugging with Eclipse. +.IP Enginsite 4 +.IX Item "Enginsite" +<http://www.enginsite.com/> +.Sp +Perl Editor by EngInSite is a complete integrated development +environment (IDE) for creating, testing, and debugging Perl scripts; +the tool runs on Windows 9x/NT/2000/XP or later. +.IP "IntelliJ IDEA" 4 +.IX Item "IntelliJ IDEA" +<https://plugins.jetbrains.com/plugin/7796> +.Sp +Camelcade plugin provides Perl5 support in IntelliJ IDEA and other JetBrains IDEs. +.IP Kephra 4 +.IX Item "Kephra" +<http://kephra.sf.net> +.Sp +GUI editor written in Perl using wxWidgets and Scintilla with lots of smaller features. +Aims for a UI based on Perl principles like TIMTOWTDI and "easy things should be easy, +hard things should be possible". +.IP Komodo 4 +.IX Item "Komodo" +<http://www.ActiveState.com/Products/Komodo/> +.Sp +ActiveState's cross-platform (as of October 2004, that's Windows, Linux, +and Solaris), multi-language IDE has Perl support, including a regular expression +debugger and remote debugging. +.IP Notepad++ 4 +.IX Item "Notepad++" +<http://notepad\-plus.sourceforge.net/> +.IP "Open Perl IDE" 4 +.IX Item "Open Perl IDE" +<http://open\-perl\-ide.sourceforge.net/> +.Sp +Open Perl IDE is an integrated development environment for writing +and debugging Perl scripts with ActiveState's ActivePerl distribution +under Windows 95/98/NT/2000. +.IP OptiPerl 4 +.IX Item "OptiPerl" +<http://www.optiperl.com/> +.Sp +OptiPerl is a Windows IDE with simulated CGI environment, including +debugger and syntax-highlighting editor. +.IP Padre 4 +.IX Item "Padre" +<http://padre.perlide.org/> +.Sp +Padre is cross-platform IDE for Perl written in Perl using wxWidgets to provide +a native look and feel. It's open source under the Artistic License. It +is one of the newer Perl IDEs. +.IP PerlBuilder 4 +.IX Item "PerlBuilder" +<http://www.solutionsoft.com/perl.htm> +.Sp +PerlBuilder is an integrated development environment for Windows that +supports Perl development. +.IP visiPerl+ 4 +.IX Item "visiPerl+" +<http://helpconsulting.net/visiperl/index.html> +.Sp +From Help Consulting, for Windows. +.IP "Visual Perl" 4 +.IX Item "Visual Perl" +<http://www.activestate.com/Products/Visual_Perl/> +.Sp +Visual Perl is a Visual Studio.NET plug-in from ActiveState. +.IP Zeus 4 +.IX Item "Zeus" +<http://www.zeusedit.com/lookmain.html> +.Sp +Zeus for Windows is another Win32 multi-language editor/IDE +that comes with support for Perl. +.PP +For editors: if you're on Unix you probably have vi or a vi clone +already, and possibly an emacs too, so you may not need to download +anything. In any emacs the cperl-mode (M\-x cperl-mode) gives you +perhaps the best available Perl editing mode in any editor. +.PP +If you are using Windows, you can use any editor that lets you work +with plain text, such as NotePad or WordPad. Word processors, such as +Microsoft Word or WordPerfect, typically do not work since they insert +all sorts of behind-the-scenes information, although some allow you to +save files as "Text Only". You can also download text editors designed +specifically for programming, such as Textpad ( +<http://www.textpad.com/> ) and UltraEdit ( <http://www.ultraedit.com/> ), +among others. +.PP +If you are using MacOS, the same concerns apply. MacPerl (for Classic +environments) comes with a simple editor. Popular external editors are +BBEdit ( <http://www.barebones.com/products/bbedit/> ) or Alpha ( +<http://www.his.com/~jguyer/Alpha/Alpha8.html> ). MacOS X users can use +Unix editors as well. +.IP "GNU Emacs" 4 +.IX Item "GNU Emacs" +<http://www.gnu.org/software/emacs/windows/ntemacs.html> +.IP MicroEMACS 4 +.IX Item "MicroEMACS" +<http://www.microemacs.de/> +.IP XEmacs 4 +.IX Item "XEmacs" +<http://www.xemacs.org/Download/index.html> +.IP Jed 4 +.IX Item "Jed" +<http://space.mit.edu/~davis/jed/> +.PP +or a vi clone such as +.IP Vim 4 +.IX Item "Vim" +<http://www.vim.org/> +.IP Vile 4 +.IX Item "Vile" +<http://invisible\-island.net/vile/vile.html> +.PP +The following are Win32 multilanguage editor/IDEs that support Perl: +.IP MultiEdit 4 +.IX Item "MultiEdit" +<http://www.MultiEdit.com/> +.IP SlickEdit 4 +.IX Item "SlickEdit" +<http://www.slickedit.com/> +.IP ConTEXT 4 +.IX Item "ConTEXT" +<http://www.contexteditor.org/> +.PP +There is also a toyedit Text widget based editor written in Perl +that is distributed with the Tk module on CPAN. The ptkdb +( <http://ptkdb.sourceforge.net/> ) is a Perl/Tk\-based debugger that +acts as a development environment of sorts. Perl Composer +( <http://perlcomposer.sourceforge.net/> ) is an IDE for Perl/Tk +GUI creation. +.PP +In addition to an editor/IDE you might be interested in a more +powerful shell environment for Win32. Your options include +.IP bash 4 +.IX Item "bash" +from the Cygwin package ( <http://cygwin.com/> ) +.IP zsh 4 +.IX Item "zsh" +<http://www.zsh.org/> +.PP +Cygwin is covered by the GNU General Public +License (but that shouldn't matter for Perl use). Cygwin +contains (in addition to the shell) a comprehensive set +of standard Unix toolkit utilities. +.IP "BBEdit and TextWrangler" 4 +.IX Item "BBEdit and TextWrangler" +are text editors for OS X that have a Perl sensitivity mode +( <http://www.barebones.com/> ). +.SS "Where can I get Perl macros for vi?" +.IX Subsection "Where can I get Perl macros for vi?" +For a complete version of Tom Christiansen's vi configuration file, +see <http://www.cpan.org/authors/id/T/TO/TOMC/scripts/toms.exrc.gz> , +the standard benchmark file for vi emulators. The file runs best with nvi, +the current version of vi out of Berkeley, which incidentally can be built +with an embedded Perl interpreter\-\-see <http://www.cpan.org/src/misc/> . +.SS "Where can I get perl-mode or cperl-mode for emacs?" +.IX Xref "emacs" +.IX Subsection "Where can I get perl-mode or cperl-mode for emacs?" +Since Emacs version 19 patchlevel 22 or so, there have been both a +perl\-mode.el and support for the Perl debugger built in. These should +come with the standard Emacs 19 distribution. +.PP +Note that the perl-mode of emacs will have fits with \f(CW"main\*(Aqfoo"\fR +(single quote), and mess up the indentation and highlighting. You +are probably using \f(CW"main::foo"\fR in new Perl code anyway, so this +shouldn't be an issue. +.PP +For CPerlMode, see <http://www.emacswiki.org/cgi\-bin/wiki/CPerlMode> +.SS "How can I use curses with Perl?" +.IX Subsection "How can I use curses with Perl?" +The Curses module from CPAN provides a dynamically loadable object +module interface to a curses library. A small demo can be found at the +directory <http://www.cpan.org/authors/id/T/TO/TOMC/scripts/rep.gz> ; +this program repeats a command and updates the screen as needed, rendering +\&\fBrep ps axu\fR similar to \fBtop\fR. +.SS "How can I write a GUI (X, Tk, Gtk, etc.) in Perl?" +.IX Xref "GUI Tk Wx WxWidgets Gtk Gtk2 CamelBones Qt" +.IX Subsection "How can I write a GUI (X, Tk, Gtk, etc.) in Perl?" +(contributed by Ben Morrow) +.PP +There are a number of modules which let you write GUIs in Perl. Most +GUI toolkits have a perl interface: an incomplete list follows. +.IP Tk 4 +.IX Item "Tk" +This works under Unix and Windows, and the current version doesn't +look half as bad under Windows as it used to. Some of the gui elements +still don't 'feel' quite right, though. The interface is very natural +and 'perlish', making it easy to use in small scripts that just need a +simple gui. It hasn't been updated in a while. +.IP Wx 4 +.IX Item "Wx" +This is a Perl binding for the cross-platform wxWidgets toolkit +( <http://www.wxwidgets.org> ). It works under Unix, Win32 and Mac OS X, +using native widgets (Gtk under Unix). The interface follows the C++ +interface closely, but the documentation is a little sparse for someone +who doesn't know the library, mostly just referring you to the C++ +documentation. +.IP "Gtk and Gtk2" 4 +.IX Item "Gtk and Gtk2" +These are Perl bindings for the Gtk toolkit ( <http://www.gtk.org> ). The +interface changed significantly between versions 1 and 2 so they have +separate Perl modules. It runs under Unix, Win32 and Mac OS X (currently +it requires an X server on Mac OS, but a 'native' port is underway), and +the widgets look the same on every platform: i.e., they don't match the +native widgets. As with Wx, the Perl bindings follow the C API closely, +and the documentation requires you to read the C documentation to +understand it. +.IP Win32::GUI 4 +.IX Item "Win32::GUI" +This provides access to most of the Win32 GUI widgets from Perl. +Obviously, it only runs under Win32, and uses native widgets. The Perl +interface doesn't really follow the C interface: it's been made more +Perlish, and the documentation is pretty good. More advanced stuff may +require familiarity with the C Win32 APIs, or reference to MSDN. +.IP CamelBones 4 +.IX Item "CamelBones" +CamelBones ( <http://camelbones.sourceforge.net> ) is a Perl interface to +Mac OS X's Cocoa GUI toolkit, and as such can be used to produce native +GUIs on Mac OS X. It's not on CPAN, as it requires frameworks that +CPAN.pm doesn't know how to install, but installation is via the +standard OSX package installer. The Perl API is, again, very close to +the ObjC API it's wrapping, and the documentation just tells you how to +translate from one to the other. +.IP Qt 4 +.IX Item "Qt" +There is a Perl interface to TrollTech's Qt toolkit, but it does not +appear to be maintained. +.IP Athena 4 +.IX Item "Athena" +Sx is an interface to the Athena widget set which comes with X, but +again it appears not to be much used nowadays. +.SS "How can I make my Perl program run faster?" +.IX Subsection "How can I make my Perl program run faster?" +The best way to do this is to come up with a better algorithm. This +can often make a dramatic difference. Jon Bentley's book +\&\fIProgramming Pearls\fR (that's not a misspelling!) has some good tips +on optimization, too. Advice on benchmarking boils down to: benchmark +and profile to make sure you're optimizing the right part, look for +better algorithms instead of microtuning your code, and when all else +fails consider just buying faster hardware. You will probably want to +read the answer to the earlier question "How do I profile my Perl +programs?" if you haven't done so already. +.PP +A different approach is to autoload seldom-used Perl code. See the +AutoSplit and AutoLoader modules in the standard distribution for +that. Or you could locate the bottleneck and think about writing just +that part in C, the way we used to take bottlenecks in C code and +write them in assembler. Similar to rewriting in C, modules that have +critical sections can be written in C (for instance, the PDL module +from CPAN). +.PP +If you're currently linking your perl executable to a shared +\&\fIlibc.so\fR, you can often gain a 10\-25% performance benefit by +rebuilding it to link with a static libc.a instead. This will make a +bigger perl executable, but your Perl programs (and programmers) may +thank you for it. See the \fIINSTALL\fR file in the source distribution +for more information. +.PP +The undump program was an ancient attempt to speed up Perl program by +storing the already-compiled form to disk. This is no longer a viable +option, as it only worked on a few architectures, and wasn't a good +solution anyway. +.SS "How can I make my Perl program take less memory?" +.IX Subsection "How can I make my Perl program take less memory?" +When it comes to time-space tradeoffs, Perl nearly always prefers to +throw memory at a problem. Scalars in Perl use more memory than +strings in C, arrays take more than that, and hashes use even more. While +there's still a lot to be done, recent releases have been addressing +these issues. For example, as of 5.004, duplicate hash keys are +shared amongst all hashes using them, so require no reallocation. +.PP +In some cases, using \fBsubstr()\fR or \fBvec()\fR to simulate arrays can be +highly beneficial. For example, an array of a thousand booleans will +take at least 20,000 bytes of space, but it can be turned into one +125\-byte bit vector\-\-a considerable memory savings. The standard +Tie::SubstrHash module can also help for certain types of data +structure. If you're working with specialist data structures +(matrices, for instance) modules that implement these in C may use +less memory than equivalent Perl modules. +.PP +Another thing to try is learning whether your Perl was compiled with +the system malloc or with Perl's builtin malloc. Whichever one it +is, try using the other one and see whether this makes a difference. +Information about malloc is in the \fIINSTALL\fR file in the source +distribution. You can find out whether you are using perl's malloc by +typing \f(CW\*(C`perl \-V:usemymalloc\*(C'\fR. +.PP +Of course, the best way to save memory is to not do anything to waste +it in the first place. Good programming practices can go a long way +toward this: +.IP "Don't slurp!" 4 +.IX Item "Don't slurp!" +Don't read an entire file into memory if you can process it line +by line. Or more concretely, use a loop like this: +.Sp +.Vb 6 +\& # +\& # Good Idea +\& # +\& while (my $line = <$file_handle>) { +\& # ... +\& } +.Ve +.Sp +instead of this: +.Sp +.Vb 7 +\& # +\& # Bad Idea +\& # +\& my @data = <$file_handle>; +\& foreach (@data) { +\& # ... +\& } +.Ve +.Sp +When the files you're processing are small, it doesn't much matter which +way you do it, but it makes a huge difference when they start getting +larger. +.IP "Use map and grep selectively" 4 +.IX Item "Use map and grep selectively" +Remember that both map and grep expect a LIST argument, so doing this: +.Sp +.Vb 1 +\& @wanted = grep {/pattern/} <$file_handle>; +.Ve +.Sp +will cause the entire file to be slurped. For large files, it's better +to loop: +.Sp +.Vb 3 +\& while (<$file_handle>) { +\& push(@wanted, $_) if /pattern/; +\& } +.Ve +.IP "Avoid unnecessary quotes and stringification" 4 +.IX Item "Avoid unnecessary quotes and stringification" +Don't quote large strings unless absolutely necessary: +.Sp +.Vb 1 +\& my $copy = "$large_string"; +.Ve +.Sp +makes 2 copies of \f(CW$large_string\fR (one for \f(CW$copy\fR and another for the +quotes), whereas +.Sp +.Vb 1 +\& my $copy = $large_string; +.Ve +.Sp +only makes one copy. +.Sp +Ditto for stringifying large arrays: +.Sp +.Vb 4 +\& { +\& local $, = "\en"; +\& print @big_array; +\& } +.Ve +.Sp +is much more memory-efficient than either +.Sp +.Vb 1 +\& print join "\en", @big_array; +.Ve +.Sp +or +.Sp +.Vb 4 +\& { +\& local $" = "\en"; +\& print "@big_array"; +\& } +.Ve +.IP "Pass by reference" 4 +.IX Item "Pass by reference" +Pass arrays and hashes by reference, not by value. For one thing, it's +the only way to pass multiple lists or hashes (or both) in a single +call/return. It also avoids creating a copy of all the contents. This +requires some judgement, however, because any changes will be propagated +back to the original data. If you really want to mangle (er, modify) a +copy, you'll have to sacrifice the memory needed to make one. +.IP "Tie large variables to disk" 4 +.IX Item "Tie large variables to disk" +For "big" data stores (i.e. ones that exceed available memory) consider +using one of the DB modules to store it on disk instead of in RAM. This +will incur a penalty in access time, but that's probably better than +causing your hard disk to thrash due to massive swapping. +.SS "Is it safe to return a reference to local or lexical data?" +.IX Subsection "Is it safe to return a reference to local or lexical data?" +Yes. Perl's garbage collection system takes care of this so +everything works out right. +.PP +.Vb 4 +\& sub makeone { +\& my @a = ( 1 .. 10 ); +\& return \e@a; +\& } +\& +\& for ( 1 .. 10 ) { +\& push @many, makeone(); +\& } +\& +\& print $many[4][5], "\en"; +\& +\& print "@many\en"; +.Ve +.SS "How can I free an array or hash so my program shrinks?" +.IX Subsection "How can I free an array or hash so my program shrinks?" +(contributed by Michael Carman) +.PP +You usually can't. Memory allocated to lexicals (i.e. \fBmy()\fR variables) +cannot be reclaimed or reused even if they go out of scope. It is +reserved in case the variables come back into scope. Memory allocated +to global variables can be reused (within your program) by using +\&\fBundef()\fR and/or \fBdelete()\fR. +.PP +On most operating systems, memory allocated to a program can never be +returned to the system. That's why long-running programs sometimes re\- +exec themselves. Some operating systems (notably, systems that use +\&\fBmmap\fR\|(2) for allocating large chunks of memory) can reclaim memory that +is no longer used, but on such systems, perl must be configured and +compiled to use the OS's malloc, not perl's. +.PP +In general, memory allocation and de-allocation isn't something you can +or should be worrying about much in Perl. +.PP +See also "How can I make my Perl program take less memory?" +.SS "How can I make my CGI script more efficient?" +.IX Subsection "How can I make my CGI script more efficient?" +Beyond the normal measures described to make general Perl programs +faster or smaller, a CGI program has additional issues. It may be run +several times per second. Given that each time it runs it will need +to be re-compiled and will often allocate a megabyte or more of system +memory, this can be a killer. Compiling into C \fBisn't going to help +you\fR because the process start-up overhead is where the bottleneck is. +.PP +There are three popular ways to avoid this overhead. One solution +involves running the Apache HTTP server (available from +<http://www.apache.org/> ) with either of the mod_perl or mod_fastcgi +plugin modules. +.PP +With mod_perl and the Apache::Registry module (distributed with +mod_perl), httpd will run with an embedded Perl interpreter which +pre-compiles your script and then executes it within the same address +space without forking. The Apache extension also gives Perl access to +the internal server API, so modules written in Perl can do just about +anything a module written in C can. For more on mod_perl, see +<http://perl.apache.org/> +.PP +With the FCGI module (from CPAN) and the mod_fastcgi +module (available from <http://www.fastcgi.com/> ) each of your Perl +programs becomes a permanent CGI daemon process. +.PP +Finally, Plack is a Perl module and toolkit that contains PSGI middleware, +helpers and adapters to web servers, allowing you to easily deploy scripts which +can continue running, and provides flexibility with regards to which web server +you use. It can allow existing CGI scripts to enjoy this flexibility and +performance with minimal changes, or can be used along with modern Perl web +frameworks to make writing and deploying web services with Perl a breeze. +.PP +These solutions can have far-reaching effects on your system and on the way you +write your CGI programs, so investigate them with care. +.PP +See also +<http://www.cpan.org/modules/by\-category/15_World_Wide_Web_HTML_HTTP_CGI/> . +.SS "How can I hide the source for my Perl program?" +.IX Subsection "How can I hide the source for my Perl program?" +Delete it. :\-) Seriously, there are a number of (mostly +unsatisfactory) solutions with varying levels of "security". +.PP +First of all, however, you \fIcan't\fR take away read permission, because +the source code has to be readable in order to be compiled and +interpreted. (That doesn't mean that a CGI script's source is +readable by people on the web, though\-\-only by people with access to +the filesystem.) So you have to leave the permissions at the socially +friendly 0755 level. +.PP +Some people regard this as a security problem. If your program does +insecure things and relies on people not knowing how to exploit those +insecurities, it is not secure. It is often possible for someone to +determine the insecure things and exploit them without viewing the +source. Security through obscurity, the name for hiding your bugs +instead of fixing them, is little security indeed. +.PP +You can try using encryption via source filters (Starting from Perl +5.8 the Filter::Simple and Filter::Util::Call modules are included in +the standard distribution), but any decent programmer will be able to +decrypt it. You can try using the byte code compiler and interpreter +described later in perlfaq3, but the curious might still be able to +de-compile it. You can try using the native-code compiler described +later, but crackers might be able to disassemble it. These pose +varying degrees of difficulty to people wanting to get at your code, +but none can definitively conceal it (true of every language, not just +Perl). +.PP +It is very easy to recover the source of Perl programs. You simply +feed the program to the perl interpreter and use the modules in +the B:: hierarchy. The B::Deparse module should be able to +defeat most attempts to hide source. Again, this is not +unique to Perl. +.PP +If you're concerned about people profiting from your code, then the +bottom line is that nothing but a restrictive license will give you +legal security. License your software and pepper it with threatening +statements like "This is unpublished proprietary software of XYZ Corp. +Your access to it does not give you permission to use it blah blah +blah." We are not lawyers, of course, so you should see a lawyer if +you want to be sure your license's wording will stand up in court. +.SS "How can I compile my Perl program into byte code or C?" +.IX Subsection "How can I compile my Perl program into byte code or C?" +(contributed by brian d foy) +.PP +In general, you can't do this. There are some things that may work +for your situation though. People usually ask this question +because they want to distribute their works without giving away +the source code, and most solutions trade disk space for convenience. +You probably won't see much of a speed increase either, since most +solutions simply bundle a Perl interpreter in the final product +(but see "How can I make my Perl program run faster?"). +.PP +The Perl Archive Toolkit is Perl's analog to Java's JAR. It's freely +available and on CPAN ( <https://metacpan.org/pod/PAR> ). +.PP +There are also some commercial products that may work for you, although +you have to buy a license for them. +.PP +The Perl Dev Kit ( <http://www.activestate.com/Products/Perl_Dev_Kit/> ) +from ActiveState can "Turn your Perl programs into ready-to-run +executables for HP-UX, Linux, Solaris and Windows." +.PP +Perl2Exe ( <http://www.indigostar.com/perl2exe.htm> ) is a command line +program for converting perl scripts to executable files. It targets both +Windows and Unix platforms. +.ie n .SS "How can I get ""#!perl"" to work on [MS\-DOS,NT,...]?" +.el .SS "How can I get \f(CW#!perl\fP to work on [MS\-DOS,NT,...]?" +.IX Subsection "How can I get #!perl to work on [MS-DOS,NT,...]?" +For OS/2 just use +.PP +.Vb 1 +\& extproc perl \-S \-your_switches +.Ve +.PP +as the first line in \f(CW\*(C`*.cmd\*(C'\fR file (\f(CW\*(C`\-S\*(C'\fR due to a bug in cmd.exe's +"extproc" handling). For DOS one should first invent a corresponding +batch file and codify it in \f(CW\*(C`ALTERNATE_SHEBANG\*(C'\fR (see the +\&\fIdosish.h\fR file in the source distribution for more information). +.PP +The Win95/NT installation, when using the ActiveState port of Perl, +will modify the Registry to associate the \f(CW\*(C`.pl\*(C'\fR extension with the +perl interpreter. If you install another port, perhaps even building +your own Win95/NT Perl from the standard sources by using a Windows port +of gcc (e.g., with cygwin or mingw32), then you'll have to modify +the Registry yourself. In addition to associating \f(CW\*(C`.pl\*(C'\fR with the +interpreter, NT people can use: \f(CW\*(C`SET PATHEXT=%PATHEXT%;.PL\*(C'\fR to let them +run the program \f(CW\*(C`install\-linux.pl\*(C'\fR merely by typing \f(CW\*(C`install\-linux\*(C'\fR. +.PP +Under "Classic" MacOS, a perl program will have the appropriate Creator and +Type, so that double-clicking them will invoke the MacPerl application. +Under Mac OS X, clickable apps can be made from any \f(CW\*(C`#!\*(C'\fR script using Wil +Sanchez' DropScript utility: <http://www.wsanchez.net/software/> . +.PP +\&\fIIMPORTANT!\fR: Whatever you do, PLEASE don't get frustrated, and just +throw the perl interpreter into your cgi-bin directory, in order to +get your programs working for a web server. This is an EXTREMELY big +security risk. Take the time to figure out how to do it correctly. +.SS "Can I write useful Perl programs on the command line?" +.IX Subsection "Can I write useful Perl programs on the command line?" +Yes. Read perlrun for more information. Some examples follow. +(These assume standard Unix shell quoting rules.) +.PP +.Vb 2 +\& # sum first and last fields +\& perl \-lane \*(Aqprint $F[0] + $F[\-1]\*(Aq * +\& +\& # identify text files +\& perl \-le \*(Aqfor(@ARGV) {print if \-f && \-T _}\*(Aq * +\& +\& # remove (most) comments from C program +\& perl \-0777 \-pe \*(Aqs{/\e*.*?\e*/}{}gs\*(Aq foo.c +\& +\& # make file a month younger than today, defeating reaper daemons +\& perl \-e \*(Aq$X=24*60*60; utime(time(),time() + 30 * $X,@ARGV)\*(Aq * +\& +\& # find first unused uid +\& perl \-le \*(Aq$i++ while getpwuid($i); print $i\*(Aq +\& +\& # display reasonable manpath +\& echo $PATH | perl \-nl \-072 \-e \*(Aq +\& s![^/+]*$!man!&&\-d&&!$s{$_}++&&push@m,$_;END{print"@m"}\*(Aq +.Ve +.PP +OK, the last one was actually an Obfuscated Perl Contest entry. :\-) +.SS "Why don't Perl one-liners work on my DOS/Mac/VMS system?" +.IX Subsection "Why don't Perl one-liners work on my DOS/Mac/VMS system?" +The problem is usually that the command interpreters on those systems +have rather different ideas about quoting than the Unix shells under +which the one-liners were created. On some systems, you may have to +change single-quotes to double ones, which you must \fINOT\fR do on Unix +or Plan9 systems. You might also have to change a single % to a %%. +.PP +For example: +.PP +.Vb 2 +\& # Unix (including Mac OS X) +\& perl \-e \*(Aqprint "Hello world\en"\*(Aq +\& +\& # DOS, etc. +\& perl \-e "print \e"Hello world\en\e"" +\& +\& # Mac Classic +\& print "Hello world\en" +\& (then Run "Myscript" or Shift\-Command\-R) +\& +\& # MPW +\& perl \-e \*(Aqprint "Hello world\en"\*(Aq +\& +\& # VMS +\& perl \-e "print ""Hello world\en""" +.Ve +.PP +The problem is that none of these examples are reliable: they depend on the +command interpreter. Under Unix, the first two often work. Under DOS, +it's entirely possible that neither works. If 4DOS was the command shell, +you'd probably have better luck like this: +.PP +.Vb 1 +\& perl \-e "print <Ctrl\-x>"Hello world\en<Ctrl\-x>"" +.Ve +.PP +Under the Mac, it depends which environment you are using. The MacPerl +shell, or MPW, is much like Unix shells in its support for several +quoting variants, except that it makes free use of the Mac's non-ASCII +characters as control characters. +.PP +Using \fBqq()\fR, q(), and \fBqx()\fR, instead of "double quotes", 'single +quotes', and `backticks`, may make one-liners easier to write. +.PP +There is no general solution to all of this. It is a mess. +.PP +[Some of this answer was contributed by Kenneth Albanowski.] +.SS "Where can I learn about CGI or Web programming in Perl?" +.IX Subsection "Where can I learn about CGI or Web programming in Perl?" +For modules, get the CGI or LWP modules from CPAN. For textbooks, +see the two especially dedicated to web stuff in the question on +books. For problems and questions related to the web, like "Why +do I get 500 Errors" or "Why doesn't it run from the browser right +when it runs fine on the command line", see the troubleshooting +guides and references in perlfaq9 or in the CGI MetaFAQ: +.PP +.Vb 1 +\& L<http://www.perl.org/CGI_MetaFAQ.html> +.Ve +.PP +Looking into <https://plackperl.org> and modern Perl web frameworks is highly recommended, +though; web programming in Perl has evolved a long way from the old days of +simple CGI scripts. +.SS "Where can I learn about object-oriented Perl programming?" +.IX Subsection "Where can I learn about object-oriented Perl programming?" +A good place to start is perlootut, and you can use perlobj for +reference. +.PP +A good book on OO on Perl is the "Object-Oriented Perl" +by Damian Conway from Manning Publications, or "Intermediate Perl" +by Randal Schwartz, brian d foy, and Tom Phoenix from O'Reilly Media. +.SS "Where can I learn about linking C with Perl?" +.IX Subsection "Where can I learn about linking C with Perl?" +If you want to call C from Perl, start with perlxstut, +moving on to perlxs, xsubpp, and perlguts. If you want to +call Perl from C, then read perlembed, perlcall, and +perlguts. Don't forget that you can learn a lot from looking at +how the authors of existing extension modules wrote their code and +solved their problems. +.PP +You might not need all the power of XS. The Inline::C module lets +you put C code directly in your Perl source. It handles all the +magic to make it work. You still have to learn at least some of +the perl API but you won't have to deal with the complexity of the +XS support files. +.SS "I've read perlembed, perlguts, etc., but I can't embed perl in my C program; what am I doing wrong?" +.IX Subsection "I've read perlembed, perlguts, etc., but I can't embed perl in my C program; what am I doing wrong?" +Download the ExtUtils::Embed kit from CPAN and run `make test'. If +the tests pass, read the pods again and again and again. If they +fail, submit a bug report to <https://github.com/Perl/perl5/issues> +with the output of +\&\f(CW\*(C`make test TEST_VERBOSE=1\*(C'\fR along with \f(CW\*(C`perl \-V\*(C'\fR. +.SS "When I tried to run my script, I got this message. What does it mean?" +.IX Subsection "When I tried to run my script, I got this message. What does it mean?" +A complete list of Perl's error messages and warnings with explanatory +text can be found in perldiag. You can also use the splain program +(distributed with Perl) to explain the error messages: +.PP +.Vb 2 +\& perl program 2>diag.out +\& splain [\-v] [\-p] diag.out +.Ve +.PP +or change your program to explain the messages for you: +.PP +.Vb 1 +\& use diagnostics; +.Ve +.PP +or +.PP +.Vb 1 +\& use diagnostics \-verbose; +.Ve +.SS "What's MakeMaker?" +.IX Subsection "What's MakeMaker?" +(contributed by brian d foy) +.PP +The ExtUtils::MakeMaker module, better known simply as "MakeMaker", +turns a Perl script, typically called \f(CW\*(C`Makefile.PL\*(C'\fR, into a Makefile. +The Unix tool \f(CW\*(C`make\*(C'\fR uses this file to manage dependencies and actions +to process and install a Perl distribution. +.SH "AUTHOR AND COPYRIGHT" +.IX Header "AUTHOR AND COPYRIGHT" +Copyright (c) 1997\-2010 Tom Christiansen, Nathan Torkington, and +other authors as noted. All rights reserved. +.PP +This documentation is free; you can redistribute it and/or modify it +under the same terms as Perl itself. +.PP +Irrespective of its distribution, all code examples here are in the public +domain. You are permitted and encouraged to use this code and any +derivatives thereof in your own programs for fun or for profit as you +see fit. A simple comment in the code giving credit to the FAQ would +be courteous but is not required. |