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> ]> S<[ B<-hv> ] [ B<-V>[:I<configvar>] ]>
   8     S<[ B<-cw> ] [ B<-d>[:I<debugger>] ] [ B<-D>[I<number/list>] ]>
   9     S<[ B<-pna> ] [ B<-F>I<pattern> ] [ B<-l>[I<octal>] ] [ B<-0>[I<octal>] ]>
  10     S<[ B<-I>I<dir> ] [ B<-m>[B<->]I<module> ] [ B<-M>[B<->]I<'module...'> ]>
  11     S<[ B<-P> ]> S<[ B<-S> ]> S<[ B<-x>[I<dir>] ]>
  12     S<[ B<-i>[I<extension>] ]> S<[ B<-e> I<'command'> ]
  13     [ B<--> ] [ I<programfile> ] [ I<argument> ]...>
  14
  15 For ease of access, the Perl manual has been split up into several sections:
  16
  17     perl                Perl overview (this section)
  18     perlfaq             Perl frequently asked questions
  19     perltoc             Perl documentation table of contents
  20
  21     perlsyn             Perl syntax
  22     perldata            Perl data structures
  23     perlop              Perl operators and precedence
  24     perlsub             Perl subroutines
  25     perlfunc            Perl builtin functions
  26     perlreftut          Perl references short introduction
  27     perldsc             Perl data structures intro
  28     perllol             Perl data structures: arrays of arrays
  29     perlrequick         Perl regular expressions quick start
  30     perlretut           Perl regular expressions tutorial
  31
  32     perlrun             Perl execution and options
  33     perllexwarn         Perl warnings and their control
  34     perldebug           Perl debugging
  35
  36     perlopentut         Perl open() tutorial
  37     perlvar             Perl predefined variables
  38     perlmod             Perl modules: how they work
  39     perlpod             Perl plain old documentation
  40
  41     perlstyle           Perl style guide
  42     perlmodlib          Perl modules: how to write and use
  43     perlmodinstall      Perl modules: how to install from CPAN
  44     perlnewmod          Perl modules: preparing a new module for distribution
  45     perltrap            Perl traps for the unwary
  46     perlport            Perl portability guide
  47     perlsec             Perl security
  48
  49     perlref             Perl references, the rest of the story
  50     perlre              Perl regular expressions, the rest of the story
  51     perlform            Perl formats
  52     perllocale          Perl locale support
  53     perlunicode         Perl unicode support
  54
  55     perlboot            Perl OO tutorial for beginners
  56     perltoot            Perl OO tutorial, part 1
  57     perltootc           Perl OO tutorial, part 2
  58     perlobj             Perl objects
  59     perlbot             Perl OO tricks and examples
  60     perltie             Perl objects hidden behind simple variables
  61
  62     perlipc             Perl interprocess communication
  63     perlnumber          Perl number semantics
  64     perlfork            Perl fork() information
  65     perlthrtut          Perl threads tutorial
  66
  67     perldiag            Perl diagnostic messages
  68     perlfaq1            General Questions About Perl
  69     perlfaq2            Obtaining and Learning about Perl
  70     perlfaq3            Programming Tools
  71     perlfaq4            Data Manipulation
  72     perlfaq5            Files and Formats
  73     perlfaq6            Regexes
  74     perlfaq7            Perl Language Issues
  75     perlfaq8            System Interaction
  76     perlfaq9            Networking
  77
  78     perlcompile         Perl compiler suite intro
  79
  80     perlembed           Perl ways to embed perl in your C or C++ application
  81     perldebguts         Perl debugging guts and tips
  82     perlxstut           Perl XS tutorial
  83     perlxs              Perl XS application programming interface
  84     perlguts            Perl internal functions for those doing extensions
  85     perlcall            Perl calling conventions from C
  86     perlutil            utilities packaged with the Perl distribution
  87     perlfilter          Perl source filters
  88     perldbmfilter       Perl DBM filters
  89     perlapi             Perl API listing (autogenerated)
  90     perlintern          Perl internal functions (autogenerated)
  91     perlapio            Perl internal IO abstraction interface
  92     perltodo            Perl things to do
  93     perlhack            Perl hackers guide
  94
  95     perlhist            Perl history records
  96     perldelta           Perl changes since previous version
  97     perl56delta         Perl changes in version 5.6
  98     perl5005delta       Perl changes in version 5.005
  99     perl5004delta       Perl changes in version 5.004
 100
 101     perlamiga           Perl notes for Amiga
 102     perlcygwin          Perl notes for Cygwin
 103     perldos             Perl notes for DOS
 104     perlhpux            Perl notes for HP-UX
 105     perlmachten         Perl notes for Power MachTen
 106     perlos2             Perl notes for OS/2
 107     perlos390           Perl notes for OS/390
 108     perlvms             Perl notes for VMS
 109     perlwin32           Perl notes for Windows
 110
 111 (If you're intending to read these straight through for the first time,
 112 the suggested order will tend to reduce the number of forward references.)
 113
 114 By default, the manpages listed above are installed in the
 115 F</usr/local/man/> directory.
 116
 117 Extensive additional documentation for Perl modules is available.  The
 118 default configuration for perl will place this additional documentation
 119 in the F</usr/local/lib/perl5/man> directory (or else in the F<man>
 120 subdirectory of the Perl library directory).  Some of this additional
 121 documentation is distributed standard with Perl, but you'll also find
 122 documentation for third-party modules there.
 123
 124 You should be able to view Perl's documentation with your man(1)
 125 program by including the proper directories in the appropriate start-up
 126 files, or in the MANPATH environment variable.  To find out where the
 127 configuration has installed the manpages, type:
 128
 129     perl -V:man.dir
 130
 131 If the directories have a common stem, such as F</usr/local/man/man1>
 132 and F</usr/local/man/man3>, you need only to add that stem
 133 (F</usr/local/man>) to your man(1) configuration files or your MANPATH
 134 environment variable.  If they do not share a stem, you'll have to add
 135 both stems.
 136
 137 If that doesn't work for some reason, you can still use the
 138 supplied F<perldoc> script to view module information.  You might
 139 also look into getting a replacement man program.
 140
 141 If something strange has gone wrong with your program and you're not
 142 sure where you should look for help, try the B<-w> switch first.  It
 143 will often point out exactly where the trouble is.
 144
 145 =head1 DESCRIPTION
 146
 147 Perl is a language optimized for scanning arbitrary
 148 text files, extracting information from those text files, and printing
 149 reports based on that information.  It's also a good language for many
 150 system management tasks.  The language is intended to be practical
 151 (easy to use, efficient, complete) rather than beautiful (tiny,
 152 elegant, minimal).
 153
 154 Perl combines (in the author's opinion, anyway) some of the best
 155 features of C, B<sed>, B<awk>, and B<sh>, so people familiar with
 156 those languages should have little difficulty with it.  (Language
 157 historians will also note some vestiges of B<csh>, Pascal, and even
 158 BASIC-PLUS.)  Expression syntax corresponds closely to C
 159 expression syntax.  Unlike most Unix utilities, Perl does not
 160 arbitrarily limit the size of your data--if you've got the memory,
 161 Perl can slurp in your whole file as a single string.  Recursion is of
 162 unlimited depth.  And the tables used by hashes (sometimes called
 163 "associative arrays") grow as necessary to prevent degraded
 164 performance.  Perl can use sophisticated pattern matching techniques to
 165 scan large amounts of data quickly.  Although optimized for
 166 scanning text, Perl can also deal with binary data, and can make dbm
 167 files look like hashes.  Setuid Perl scripts are safer than C programs
 168 through a dataflow tracing mechanism that prevents many stupid
 169 security holes.
 170
 171 If you have a problem that would ordinarily use B<sed> or B<awk> or
 172 B<sh>, but it exceeds their capabilities or must run a little faster,
 173 and you don't want to write the silly thing in C, then Perl may be for
 174 you.  There are also translators to turn your B<sed> and B<awk>
 175 scripts into Perl scripts.
 176
 177 But wait, there's more...
 178
 179 Begun in 1993 (see L<perlhist>), Perl version 5 is nearly a complete
 180 rewrite that provides the following additional benefits:
 181
 182 =over
 183
 184 =item * modularity and reusability using innumerable modules
 185
 186 Described in L<perlmod>, L<perlmodlib>, and L<perlmodinstall>.
 187
 188 =item * embeddable and extensible
 189
 190 Described in L<perlembed>, L<perlxstut>, L<perlxs>, L<perlcall>,
 191 L<perlguts>, and L<xsubpp>.
 192
 193 =item * roll-your-own magic variables (including multiple simultaneous DBM implementations)
 194
 195 Described in L<perltie> and L<AnyDBM_File>.
 196
 197 =item * subroutines can now be overridden, autoloaded, and prototyped
 198
 199 Described in L<perlsub>.
 200
 201 =item * arbitrarily nested data structures and anonymous functions
 202
 203 Described in L<perlreftut>, L<perlref>, L<perldsc>, and L<perllol>.
 204
 205 =item * object-oriented programming
 206
 207 Described in L<perlobj>, L<perltoot>, and L<perlbot>.
 208
 209 =item * compilability into C code or Perl bytecode
 210
 211 Described in L<B> and L<B::Bytecode>.
 212
 213 =item * support for light-weight processes (threads)
 214
 215 Described in L<perlthrtut> and L<Thread>.
 216
 217 =item * support for internationalization, localization, and Unicode
 218
 219 Described in L<perllocale> and L<utf8>.
 220
 221 =item * lexical scoping
 222
 223 Described in L<perlsub>.
 224
 225 =item * regular expression enhancements
 226
 227 Described in L<perlre>, with additional examples in L<perlop>.
 228
 229 =item * enhanced debugger and interactive Perl environment, with integrated editor support
 230
 231 Described in L<perldebug>.
 232
 233 =item * POSIX 1003.1 compliant library
 234
 235 Described in L<POSIX>.
 236
 237 =back
 238
 239 Okay, that's I<definitely> enough hype.
 240
 241 =head1 AVAILABILITY
 242
 243 Perl is available for most operating systems, including virtually
 244 all Unix-like platforms.  See L<perlport/"Supported Platforms">
 245 for a listing.
 246
 247 =head1 ENVIRONMENT
 248
 249 See L<perlrun>.
 250
 251 =head1 AUTHOR
 252
 253 Larry Wall <larry@wall.org>, with the help of oodles of other folks.
 254
 255 If your Perl success stories and testimonials may be of help to others
 256 who wish to advocate the use of Perl in their applications,
 257 or if you wish to simply express your gratitude to Larry and the
 258 Perl developers, please write to perl-thanks@perl.org .
 259
 260 =head1 FILES
 261
 262  "@INC"                 locations of perl libraries
 263
 264 =head1 SEE ALSO
 265
 266  a2p    awk to perl translator
 267  s2p    sed to perl translator
 268
 269  http://www.perl.com/       the Perl Home Page
 270  http://www.perl.com/CPAN   the Comprehensive Perl Archive
 271
 272 =head1 DIAGNOSTICS
 273
 274 The C<use warnings> pragma (and the B<-w> switch) produces some
 275 lovely diagnostics.
 276
 277 See L<perldiag> for explanations of all Perl's diagnostics.  The C<use
 278 diagnostics> pragma automatically turns Perl's normally terse warnings
 279 and errors into these longer forms.
 280
 281 Compilation errors will tell you the line number of the error, with an
 282 indication of the next token or token type that was to be examined.
 283 (In a script passed to Perl via B<-e> switches, each
 284 B<-e> is counted as one line.)
 285
 286 Setuid scripts have additional constraints that can produce error
 287 messages such as "Insecure dependency".  See L<perlsec>.
 288
 289 Did we mention that you should definitely consider using the B<-w>
 290 switch?
 291
 292 =head1 BUGS
 293
 294 The B<-w> switch is not mandatory.
 295
 296 Perl is at the mercy of your machine's definitions of various
 297 operations such as type casting, atof(), and floating-point
 298 output with sprintf().
 299
 300 If your stdio requires a seek or eof between reads and writes on a
 301 particular stream, so does Perl.  (This doesn't apply to sysread()
 302 and syswrite().)
 303
 304 While none of the built-in data types have any arbitrary size limits
 305 (apart from memory size), there are still a few arbitrary limits:  a
 306 given variable name may not be longer than 251 characters.  Line numbers
 307 displayed by diagnostics are internally stored as short integers,
 308 so they are limited to a maximum of 65535 (higher numbers usually being
 309 affected by wraparound).
 310
 311 You may mail your bug reports (be sure to include full configuration
 312 information as output by the myconfig program in the perl source
 313 tree, or by C<perl -V>) to perlbug@perl.com .  If you've succeeded
 314 in compiling perl, the B<perlbug> script in the F<utils/> subdirectory
 315 can be used to help mail in a bug report.
 316
 317 Perl actually stands for Pathologically Eclectic Rubbish Lister, but
 318 don't tell anyone I said that.
 319
 320 =head1 NOTES
 321
 322 The Perl motto is "There's more than one way to do it."  Divining
 323 how many more is left as an exercise to the reader.
 324
 325 The three principal virtues of a programmer are Laziness,
 326 Impatience, and Hubris.  See the Camel Book for why.
 327