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