pod/perl.pod

   1 =head1 NAME
   2
   3 perl - Practical Extraction and Report Language
   4
   5 =head1 SYNOPSIS
   6
   7 B<perl> S<[ B<-sTuU> ]>
   8         S<[ B<-hv> ] [ B<-V>[:I<configvar>] ]>
   9         S<[ B<-cw> ] [ B<-d>[:I<debugger>] ] [ B<-D>[I<number/list>] ]>
  10         S<[ B<-pna> ] [ B<-F>I<pattern> ] [ B<-l>[I<octal>] ] [ B<-0>[I<octal>] ]>
  11         S<[ B<-I>I<dir> ] [ B<-m>[B<->]I<module> ] [ B<-M>[B<->]I<'module...'> ]>
  12         S<[ B<-P> ]>
  13         S<[ B<-S> ]>
  14         S<[ B<-x>[I<dir>] ]>
  15         S<[ B<-i>[I<extension>] ]>
  16         S<[ B<-e> I<'command'> ] [ B<--> ] [ I<programfile> ] [ I<argument> ]...>
  17
  18 For ease of access, the Perl manual has been split up into a number
  19 of sections:
  20
  21     perl        Perl overview (this section)
  22     perldelta   Perl changes since previous version
  23     perlfaq     Perl frequently asked questions
  24     perltoc     Perl documentation table of contents
  25
  26     perldata    Perl data structures
  27     perlsyn     Perl syntax
  28     perlop      Perl operators and precedence
  29     perlre      Perl regular expressions
  30     perlrun     Perl execution and options
  31     perlfunc    Perl builtin functions
  32     perlvar     Perl predefined variables
  33     perlsub     Perl subroutines
  34     perlmod     Perl modules: how they work
  35     perlmodlib  Perl modules: how to write and use
  36     perlform    Perl formats
  37     perllocale  Perl locale support
  38
  39     perlref     Perl references
  40     perldsc     Perl data structures intro
  41     perllol     Perl data structures: lists of lists
  42     perltoot    Perl OO tutorial
  43     perlobj     Perl objects
  44     perltie     Perl objects hidden behind simple variables
  45     perlbot     Perl OO tricks and examples
  46     perlipc     Perl interprocess communication
  47
  48     perldebug   Perl debugging
  49     perldiag    Perl diagnostic messages
  50     perlsec     Perl security
  51     perltrap    Perl traps for the unwary
  52     perlstyle   Perl style guide
  53
  54     perlpod     Perl plain old documentation
  55     perlbook    Perl book information
  56
  57     perlembed   Perl ways to embed perl in your C or C++ application
  58     perlapio    Perl internal IO abstraction interface
  59     perlxs      Perl XS application programming interface
  60     perlxstut   Perl XS tutorial
  61     perlguts    Perl internal functions for those doing extensions
  62     perlcall    Perl calling conventions from C
  63
  64     perlhist    Perl history records
  65
  66 (If you're intending to read these straight through for the first time,
  67 the suggested order will tend to reduce the number of forward references.)
  68
  69 By default, all of the above manpages are installed in the
  70 F</usr/local/man/> directory.
  71
  72 Extensive additional documentation for Perl modules is available.  The
  73 default configuration for perl will place this additional documentation
  74 in the F</usr/local/lib/perl5/man> directory (or else in the F<man>
  75 subdirectory of the Perl library directory).  Some of this additional
  76 documentation is distributed standard with Perl, but you'll also find
  77 documentation for third-party modules there.
  78
  79 You should be able to view Perl's documentation with your man(1)
  80 program by including the proper directories in the appropriate start-up
  81 files, or in the MANPATH environment variable.  To find out where the
  82 configuration has installed the manpages, type:
  83
  84     perl -V:man.dir
  85
  86 If the directories have a common stem, such as F</usr/local/man/man1>
  87 and F</usr/local/man/man3>, you need only to add that stem
  88 (F</usr/local/man>) to your man(1) configuration files or your MANPATH
  89 environment variable.  If they do not share a stem, you'll have to add
  90 both stems.
  91
  92 If that doesn't work for some reason, you can still use the
  93 supplied F<perldoc> script to view module information.  You might
  94 also look into getting a replacement man program.
  95
  96 If something strange has gone wrong with your program and you're not
  97 sure where you should look for help, try the B<-w> switch first.  It
  98 will often point out exactly where the trouble is.
  99
 100 =head1 DESCRIPTION
 101
 102 Perl is a language optimized for scanning arbitrary
 103 text files, extracting information from those text files, and printing
 104 reports based on that information.  It's also a good language for many
 105 system management tasks.  The language is intended to be practical
 106 (easy to use, efficient, complete) rather than beautiful (tiny,
 107 elegant, minimal).
 108
 109 Perl combines (in the author's opinion, anyway) some of the best
 110 features of C, B<sed>, B<awk>, and B<sh>, so people familiar with
 111 those languages should have little difficulty with it.  (Language
 112 historians will also note some vestiges of B<csh>, Pascal, and even
 113 BASIC-PLUS.)  Expression syntax corresponds quite closely to C
 114 expression syntax.  Unlike most Unix utilities, Perl does not
 115 arbitrarily limit the size of your data--if you've got the memory,
 116 Perl can slurp in your whole file as a single string.  Recursion is of
 117 unlimited depth.  And the tables used by hashes (previously called
 118 "associative arrays") grow as necessary to prevent degraded
 119 performance.  Perl uses sophisticated pattern matching techniques to
 120 scan large amounts of data very quickly.  Although optimized for
 121 scanning text, Perl can also deal with binary data, and can make dbm
 122 files look like hashes.  Setuid Perl scripts are safer than C programs
 123 through a dataflow tracing mechanism which prevents many stupid
 124 security holes.
 125
 126 If you have a problem that would ordinarily use B<sed> or B<awk> or
 127 B<sh>, but it exceeds their capabilities or must run a little faster,
 128 and you don't want to write the silly thing in C, then Perl may be for
 129 you.  There are also translators to turn your B<sed> and B<awk>
 130 scripts into Perl scripts.
 131
 132 But wait, there's more...
 133
 134 Perl version 5 is nearly a complete rewrite, and provides
 135 the following additional benefits:
 136
 137 =over 5
 138
 139 =item * Many usability enhancements
 140
 141 It is now possible to write much more readable Perl code (even within
 142 regular expressions).  Formerly cryptic variable names can be replaced
 143 by mnemonic identifiers.  Error messages are more informative, and the
 144 optional warnings will catch many of the mistakes a novice might make.
 145 This cannot be stressed enough.  Whenever you get mysterious behavior,
 146 try the B<-w> switch!!!  Whenever you don't get mysterious behavior,
 147 try using B<-w> anyway.
 148
 149 =item * Simplified grammar
 150
 151 The new yacc grammar is one half the size of the old one.  Many of the
 152 arbitrary grammar rules have been regularized.  The number of reserved
 153 words has been cut by 2/3.  Despite this, nearly all old Perl scripts
 154 will continue to work unchanged.
 155
 156 =item * Lexical scoping
 157
 158 Perl variables may now be declared within a lexical scope, like "auto"
 159 variables in C.  Not only is this more efficient, but it contributes
 160 to better privacy for "programming in the large".  Anonymous
 161 subroutines exhibit deep binding of lexical variables (closures).
 162
 163 =item * Arbitrarily nested data structures
 164
 165 Any scalar value, including any array element, may now contain a
 166 reference to any other variable or subroutine.  You can easily create
 167 anonymous variables and subroutines.  Perl manages your reference
 168 counts for you.
 169
 170 =item * Modularity and reusability
 171
 172 The Perl library is now defined in terms of modules which can be easily
 173 shared among various packages.  A package may choose to import all or a
 174 portion of a module's published interface.  Pragmas (that is, compiler
 175 directives) are defined and used by the same mechanism.
 176
 177 =item * Object-oriented programming
 178
 179 A package can function as a class.  Dynamic multiple inheritance and
 180 virtual methods are supported in a straightforward manner and with very
 181 little new syntax.  Filehandles may now be treated as objects.
 182
 183 =item * Embeddable and Extensible
 184
 185 Perl may now be embedded easily in your C or C++ application, and can
 186 either call or be called by your routines through a documented
 187 interface.  The XS preprocessor is provided to make it easy to glue
 188 your C or C++ routines into Perl.  Dynamic loading of modules is
 189 supported, and Perl itself can be made into a dynamic library.
 190
 191 =item * POSIX compliant
 192
 193 A major new module is the POSIX module, which provides access to all
 194 available POSIX routines and definitions, via object classes where
 195 appropriate.
 196
 197 =item * Package constructors and destructors
 198
 199 The new BEGIN and END blocks provide means to capture control as
 200 a package is being compiled, and after the program exits.  As a
 201 degenerate case they work just like awk's BEGIN and END when you
 202 use the B<-p> or B<-n> switches.
 203
 204 =item * Multiple simultaneous DBM implementations
 205
 206 A Perl program may now access DBM, NDBM, SDBM, GDBM, and Berkeley DB
 207 files from the same script simultaneously.  In fact, the old dbmopen
 208 interface has been generalized to allow any variable to be tied
 209 to an object class which defines its access methods.
 210
 211 =item * Subroutine definitions may now be autoloaded
 212
 213 In fact, the AUTOLOAD mechanism also allows you to define any arbitrary
 214 semantics for undefined subroutine calls.  It's not for just autoloading.
 215
 216 =item * Regular expression enhancements
 217
 218 You can now specify nongreedy quantifiers.  You can now do grouping
 219 without creating a backreference.  You can now write regular expressions
 220 with embedded whitespace and comments for readability.  A consistent
 221 extensibility mechanism has been added that is upwardly compatible with
 222 all old regular expressions.
 223
 224 =item * Innumerable Unbundled Modules
 225
 226 The Comprehensive Perl Archive Network described in L<perlmodlib>
 227 contains hundreds of plug-and-play modules full of reusable code.
 228 See F<http://www.perl.com/CPAN> for a site near you.
 229
 230 =item * Compilability
 231
 232 While not yet in full production mode, a working perl-to-C compiler
 233 does exist.  It can generate portable byte code, simple C, or
 234 optimized C code.
 235
 236 =back
 237
 238 Okay, that's I<definitely> enough hype.
 239
 240 =head1 ENVIRONMENT
 241
 242 See L<perlrun>.
 243
 244 =head1 AUTHOR
 245
 246 Larry Wall <F<larry@wall.org>>, with the help of oodles of other folks.
 247
 248 If your Perl success stories and testimonials may be of help to others
 249 who wish to advocate the use of Perl in their applications,
 250 or if you wish to simply express your gratitude to Larry and the
 251 Perl developers, please write to <F<perl-thanks@perl.org>>.
 252
 253 =head1 FILES
 254
 255  "/tmp/perl-e$$"        temporary file for -e commands
 256  "@INC"                 locations of perl libraries
 257
 258 =head1 SEE ALSO
 259
 260  a2p    awk to perl translator
 261
 262  s2p    sed to perl translator
 263
 264 =head1 DIAGNOSTICS
 265
 266 The B<-w> switch produces some lovely diagnostics.
 267
 268 See L<perldiag> for explanations of all Perl's diagnostics.  The C<use
 269 diagnostics> pragma automatically turns Perl's normally terse warnings
 270 and errors into these longer forms.
 271
 272 Compilation errors will tell you the line number of the error, with an
 273 indication of the next token or token type that was to be examined.
 274 (In the case of a script passed to Perl via B<-e> switches, each
 275 B<-e> is counted as one line.)
 276
 277 Setuid scripts have additional constraints that can produce error
 278 messages such as "Insecure dependency".  See L<perlsec>.
 279
 280 Did we mention that you should definitely consider using the B<-w>
 281 switch?
 282
 283 =head1 BUGS
 284
 285 The B<-w> switch is not mandatory.
 286
 287 Perl is at the mercy of your machine's definitions of various
 288 operations such as type casting, atof(), and floating-point
 289 output with sprintf().
 290
 291 If your stdio requires a seek or eof between reads and writes on a
 292 particular stream, so does Perl.  (This doesn't apply to sysread()
 293 and syswrite().)
 294
 295 While none of the built-in data types have any arbitrary size limits
 296 (apart from memory size), there are still a few arbitrary limits:  a
 297 given variable name may not be longer than 255 characters, and no
 298 component of your PATH may be longer than 255 if you use B<-S>.  A regular
 299 expression may not compile to more than 32767 bytes internally.
 300
 301 You may mail your bug reports (be sure to include full configuration
 302 information as output by the myconfig program in the perl source tree,
 303 or by C<perl -V>) to <F<perlbug@perl.com>>.
 304 If you've succeeded in compiling perl, the perlbug script in the utils/
 305 subdirectory can be used to help mail in a bug report.
 306
 307 Perl actually stands for Pathologically Eclectic Rubbish Lister, but
 308 don't tell anyone I said that.
 309
 310 =head1 NOTES
 311
 312 The Perl motto is "There's more than one way to do it."  Divining
 313 how many more is left as an exercise to the reader.
 314
 315 The three principal virtues of a programmer are Laziness,
 316 Impatience, and Hubris.  See the Camel Book for why.
 317