Avoid a possible race condition where a parallel make might
[perl.git] / pod / perlintro.pod
1 =head1 NAME
2
3 perlintro -- a brief introduction and overview of Perl
4
5 =head1 DESCRIPTION
6
7 This document is intended to give you a quick overview of the Perl
8 programming language, along with pointers to further documentation.  It
9 is intended as a "bootstrap" guide for those who are new to the
10 language, and provides just enough information for you to be able to
11 read other peoples' Perl and understand roughly what it's doing, or
12 write your own simple scripts.
13
14 This introductory document does not aim to be complete.  It does not
15 even aim to be entirely accurate.  In some cases perfection has been
16 sacrificed in the goal of getting the general idea across.  You are
17 I<strongly> advised to follow this introduction with more information
18 from the full Perl manual, the table of contents to which can be found
19 in L<perltoc>.
20
21 Throughout this document you'll see references to other parts of the
22 Perl documentation.  You can read that documentation using the C<perldoc>
23 command or whatever method you're using to read this document.
24
25 =head2 What is Perl?
26
27 Perl is a general-purpose programming language originally developed for
28 text manipulation and now used for a wide range of tasks including
29 system administration, web development, network programming, GUI
30 development, and more.
31
32 The language is intended to be practical (easy to use, efficient,
33 complete) rather than beautiful (tiny, elegant, minimal).  Its major
34 features are that it's easy to use, supports both procedural and
35 object-oriented (OO) programming, has powerful built-in support for text
36 processing, and has one of the world's most impressive collections of
37 third-party modules.
38
39 Different definitions of Perl are given in L<perl>, L<perlfaq1> and
40 no doubt other places.  From this we can determine that Perl is different
41 things to different people, but that lots of people think it's at least
42 worth writing about.
43
44 =head2 Running Perl programs
45
46 To run a Perl program from the Unix command line:
47
48     perl progname.pl
49
50 Alternatively, put this as the first line of your script:
51
52     #!/usr/bin/env perl
53
54 ... and run the script as C</path/to/script.pl>.  Of course, it'll need
55 to be executable first, so C<chmod 755 script.pl> (under Unix).
56
57 (This start line assumes you have the B<env> program. You can also put
58 directly the path to your perl executable, like in C<#!/usr/bin/perl>).
59
60 For more information, including instructions for other platforms such as
61 Windows and Mac OS, read L<perlrun>.
62
63 =head2 Safety net
64
65 Perl by default is very forgiving. In order to make it more robust
66 it is recommended to start every program with the following lines:
67
68     #!/usr/bin/perl
69     use strict;
70     use warnings;
71
72 The two additional lines request from perl to catch various common
73 problems in your code. They check different things so you need both. A
74 potential problem caught by C<use strict;> will cause your code to stop
75 immediately when it is encountered, while C<use warnings;> will merely
76 give a warning (like the command-line switch B<-w>) and let your code run.
77 To read more about them check their respective manual pages at L<strict>
78 and L<warnings>.
79
80 =head2 Basic syntax overview
81
82 A Perl script or program consists of one or more statements.  These
83 statements are simply written in the script in a straightforward
84 fashion.  There is no need to have a C<main()> function or anything of
85 that kind.
86
87 Perl statements end in a semi-colon:
88
89     print "Hello, world";
90
91 Comments start with a hash symbol and run to the end of the line
92
93     # This is a comment
94
95 Whitespace is irrelevant:
96
97     print
98         "Hello, world"
99         ;
100
101 ... except inside quoted strings:
102
103     # this would print with a linebreak in the middle
104     print "Hello
105     world";
106
107 Double quotes or single quotes may be used around literal strings:
108
109     print "Hello, world";
110     print 'Hello, world';
111
112 However, only double quotes "interpolate" variables and special
113 characters such as newlines (C<\n>):
114
115     print "Hello, $name\n";     # works fine
116     print 'Hello, $name\n';     # prints $name\n literally
117
118 Numbers don't need quotes around them:
119
120     print 42;
121
122 You can use parentheses for functions' arguments or omit them
123 according to your personal taste.  They are only required
124 occasionally to clarify issues of precedence.
125
126     print("Hello, world\n");
127     print "Hello, world\n";
128
129 More detailed information about Perl syntax can be found in L<perlsyn>.
130
131 =head2 Perl variable types
132
133 Perl has three main variable types: scalars, arrays, and hashes.
134
135 =over 4
136
137 =item Scalars
138
139 A scalar represents a single value:
140
141     my $animal = "camel";
142     my $answer = 42;
143
144 Scalar values can be strings, integers or floating point numbers, and Perl
145 will automatically convert between them as required.  There is no need
146 to pre-declare your variable types, but you have to declare them using
147 the C<my> keyword the first time you use them. (This is one of the
148 requirements of C<use strict;>.)
149
150 Scalar values can be used in various ways:
151
152     print $animal;
153     print "The animal is $animal\n";
154     print "The square of $answer is ", $answer * $answer, "\n";
155
156 There are a number of "magic" scalars with names that look like
157 punctuation or line noise.  These special variables are used for all
158 kinds of purposes, and are documented in L<perlvar>.  The only one you
159 need to know about for now is C<$_> which is the "default variable".
160 It's used as the default argument to a number of functions in Perl, and
161 it's set implicitly by certain looping constructs.
162
163     print;          # prints contents of $_ by default
164
165 =item Arrays
166
167 An array represents a list of values:
168
169     my @animals = ("camel", "llama", "owl");
170     my @numbers = (23, 42, 69);
171     my @mixed   = ("camel", 42, 1.23);
172
173 Arrays are zero-indexed.  Here's how you get at elements in an array:
174
175     print $animals[0];              # prints "camel"
176     print $animals[1];              # prints "llama"
177
178 The special variable C<$#array> tells you the index of the last element
179 of an array:
180
181     print $mixed[$#mixed];       # last element, prints 1.23
182
183 You might be tempted to use C<$#array + 1> to tell you how many items there
184 are in an array.  Don't bother.  As it happens, using C<@array> where Perl
185 expects to find a scalar value ("in scalar context") will give you the number
186 of elements in the array:
187
188     if (@animals < 5) { ... }
189
190 The elements we're getting from the array start with a C<$> because
191 we're getting just a single value out of the array -- you ask for a scalar,
192 you get a scalar.
193
194 To get multiple values from an array:
195
196     @animals[0,1];                  # gives ("camel", "llama");
197     @animals[0..2];                 # gives ("camel", "llama", "owl");
198     @animals[1..$#animals];         # gives all except the first element
199
200 This is called an "array slice".
201
202 You can do various useful things to lists:
203
204     my @sorted    = sort @animals;
205     my @backwards = reverse @numbers;
206
207 There are a couple of special arrays too, such as C<@ARGV> (the command
208 line arguments to your script) and C<@_> (the arguments passed to a
209 subroutine).  These are documented in L<perlvar>.
210
211 =item Hashes
212
213 A hash represents a set of key/value pairs:
214
215     my %fruit_color = ("apple", "red", "banana", "yellow");
216
217 You can use whitespace and the C<< => >> operator to lay them out more
218 nicely:
219
220     my %fruit_color = (
221         apple  => "red",
222         banana => "yellow",
223     );
224
225 To get at hash elements:
226
227     $fruit_color{"apple"};           # gives "red"
228
229 You can get at lists of keys and values with C<keys()> and
230 C<values()>.
231
232     my @fruits = keys %fruit_colors;
233     my @colors = values %fruit_colors;
234
235 Hashes have no particular internal order, though you can sort the keys
236 and loop through them.
237
238 Just like special scalars and arrays, there are also special hashes.
239 The most well known of these is C<%ENV> which contains environment
240 variables.  Read all about it (and other special variables) in
241 L<perlvar>.
242
243 =back
244
245 Scalars, arrays and hashes are documented more fully in L<perldata>.
246
247 More complex data types can be constructed using references, which allow
248 you to build lists and hashes within lists and hashes.
249
250 A reference is a scalar value and can refer to any other Perl data
251 type. So by storing a reference as the value of an array or hash
252 element, you can easily create lists and hashes within lists and
253 hashes. The following example shows a 2 level hash of hash
254 structure using anonymous hash references.
255
256     my $variables = {
257         scalar  =>  {
258                      description => "single item",
259                      sigil => '$',
260                     },
261         array   =>  {
262                      description => "ordered list of items",
263                      sigil => '@',
264                     },
265         hash    =>  {
266                      description => "key/value pairs",
267                      sigil => '%',
268                     },
269     };
270
271     print "Scalars begin with a $variables->{'scalar'}->{'sigil'}\n";
272
273 Exhaustive information on the topic of references can be found in
274 L<perlreftut>, L<perllol>, L<perlref> and L<perldsc>.
275
276 =head2 Variable scoping
277
278 Throughout the previous section all the examples have used the syntax:
279
280     my $var = "value";
281
282 The C<my> is actually not required; you could just use:
283
284     $var = "value";
285
286 However, the above usage will create global variables throughout your
287 program, which is bad programming practice.  C<my> creates lexically
288 scoped variables instead.  The variables are scoped to the block
289 (i.e. a bunch of statements surrounded by curly-braces) in which they
290 are defined.
291
292     my $x = "foo";
293     my $some_condition = 1;
294     if ($some_condition) {
295         my $y = "bar";
296         print $x;           # prints "foo"
297         print $y;           # prints "bar"
298     }
299     print $x;               # prints "foo"
300     print $y;               # prints nothing; $y has fallen out of scope
301
302 Using C<my> in combination with a C<use strict;> at the top of
303 your Perl scripts means that the interpreter will pick up certain common
304 programming errors.  For instance, in the example above, the final
305 C<print $y> would cause a compile-time error and prevent you from
306 running the program.  Using C<strict> is highly recommended.
307
308 =head2 Conditional and looping constructs
309
310 Perl has most of the usual conditional and looping constructs except for
311 case/switch (but if you really want it, there is a Switch module in Perl
312 5.8 and newer, and on CPAN. See the section on modules, below, for more
313 information about modules and CPAN).
314
315 The conditions can be any Perl expression.  See the list of operators in
316 the next section for information on comparison and boolean logic operators,
317 which are commonly used in conditional statements.
318
319 =over 4
320
321 =item if
322
323     if ( condition ) {
324         ...
325     } elsif ( other condition ) {
326         ...
327     } else {
328         ...
329     }
330
331 There's also a negated version of it:
332
333     unless ( condition ) {
334         ...
335     }
336
337 This is provided as a more readable version of C<if (!I<condition>)>.
338
339 Note that the braces are required in Perl, even if you've only got one
340 line in the block.  However, there is a clever way of making your one-line
341 conditional blocks more English like:
342
343     # the traditional way
344     if ($zippy) {
345         print "Yow!";
346     }
347
348     # the Perlish post-condition way
349     print "Yow!" if $zippy;
350     print "We have no bananas" unless $bananas;
351
352 =item while
353
354     while ( condition ) {
355         ...
356     }
357
358 There's also a negated version, for the same reason we have C<unless>:
359
360     until ( condition ) {
361         ...
362     }
363
364 You can also use C<while> in a post-condition:
365
366     print "LA LA LA\n" while 1;          # loops forever
367
368 =item for
369
370 Exactly like C:
371
372     for ($i = 0; $i <= $max; $i++) {
373         ...
374     }
375
376 The C style for loop is rarely needed in Perl since Perl provides
377 the more friendly list scanning C<foreach> loop.
378
379 =item foreach
380
381     foreach (@array) {
382         print "This element is $_\n";
383     }
384
385     print $list[$_] foreach 0 .. $max;
386
387     # you don't have to use the default $_ either...
388     foreach my $key (keys %hash) {
389         print "The value of $key is $hash{$key}\n";
390     }
391
392 =back
393
394 For more detail on looping constructs (and some that weren't mentioned in
395 this overview) see L<perlsyn>.
396
397 =head2 Builtin operators and functions
398
399 Perl comes with a wide selection of builtin functions.  Some of the ones
400 we've already seen include C<print>, C<sort> and C<reverse>.  A list of
401 them is given at the start of L<perlfunc> and you can easily read
402 about any given function by using C<perldoc -f I<functionname>>.
403
404 Perl operators are documented in full in L<perlop>, but here are a few
405 of the most common ones:
406
407 =over 4
408
409 =item Arithmetic
410
411     +   addition
412     -   subtraction
413     *   multiplication
414     /   division
415
416 =item Numeric comparison
417
418     ==  equality
419     !=  inequality
420     <   less than
421     >   greater than
422     <=  less than or equal
423     >=  greater than or equal
424
425 =item String comparison
426
427     eq  equality
428     ne  inequality
429     lt  less than
430     gt  greater than
431     le  less than or equal
432     ge  greater than or equal
433
434 (Why do we have separate numeric and string comparisons?  Because we don't
435 have special variable types, and Perl needs to know whether to sort
436 numerically (where 99 is less than 100) or alphabetically (where 100 comes
437 before 99).
438
439 =item Boolean logic
440
441     &&  and
442     ||  or
443     !   not
444
445 (C<and>, C<or> and C<not> aren't just in the above table as descriptions
446 of the operators -- they're also supported as operators in their own
447 right.  They're more readable than the C-style operators, but have
448 different precedence to C<&&> and friends.  Check L<perlop> for more
449 detail.)
450
451 =item Miscellaneous
452
453     =   assignment
454     .   string concatenation
455     x   string multiplication
456     ..  range operator (creates a list of numbers)
457
458 =back
459
460 Many operators can be combined with a C<=> as follows:
461
462     $a += 1;        # same as $a = $a + 1
463     $a -= 1;        # same as $a = $a - 1
464     $a .= "\n";     # same as $a = $a . "\n";
465
466 =head2 Files and I/O
467
468 You can open a file for input or output using the C<open()> function.
469 It's documented in extravagant detail in L<perlfunc> and L<perlopentut>,
470 but in short:
471
472     open(my $in,  "<",  "input.txt")  or die "Can't open input.txt: $!";
473     open(my $out, ">",  "output.txt") or die "Can't open output.txt: $!";
474     open(my $log, ">>", "my.log")     or die "Can't open my.log: $!";
475
476 You can read from an open filehandle using the C<< <> >> operator.  In
477 scalar context it reads a single line from the filehandle, and in list
478 context it reads the whole file in, assigning each line to an element of
479 the list:
480
481     my $line  = <$in>;
482     my @lines = <$in>;
483
484 Reading in the whole file at one time is called slurping. It can
485 be useful but it may be a memory hog. Most text file processing
486 can be done a line at a time with Perl's looping constructs.
487
488 The C<< <> >> operator is most often seen in a C<while> loop:
489
490     while (<$in>) {     # assigns each line in turn to $_
491         print "Just read in this line: $_";
492     }
493
494 We've already seen how to print to standard output using C<print()>.
495 However, C<print()> can also take an optional first argument specifying
496 which filehandle to print to:
497
498     print STDERR "This is your final warning.\n";
499     print $out $record;
500     print $log $logmessage;
501
502 When you're done with your filehandles, you should C<close()> them
503 (though to be honest, Perl will clean up after you if you forget):
504
505     close $in or die "$in: $!";
506
507 =head2 Regular expressions
508
509 Perl's regular expression support is both broad and deep, and is the
510 subject of lengthy documentation in L<perlrequick>, L<perlretut>, and
511 elsewhere.  However, in short:
512
513 =over 4
514
515 =item Simple matching
516
517     if (/foo/)       { ... }  # true if $_ contains "foo"
518     if ($a =~ /foo/) { ... }  # true if $a contains "foo"
519
520 The C<//> matching operator is documented in L<perlop>.  It operates on
521 C<$_> by default, or can be bound to another variable using the C<=~>
522 binding operator (also documented in L<perlop>).
523
524 =item Simple substitution
525
526     s/foo/bar/;               # replaces foo with bar in $_
527     $a =~ s/foo/bar/;         # replaces foo with bar in $a
528     $a =~ s/foo/bar/g;        # replaces ALL INSTANCES of foo with bar in $a
529
530 The C<s///> substitution operator is documented in L<perlop>.
531
532 =item More complex regular expressions
533
534 You don't just have to match on fixed strings.  In fact, you can match
535 on just about anything you could dream of by using more complex regular
536 expressions.  These are documented at great length in L<perlre>, but for
537 the meantime, here's a quick cheat sheet:
538
539     .                   a single character
540     \s                  a whitespace character (space, tab, newline, ...)
541     \S                  non-whitespace character
542     \d                  a digit (0-9)
543     \D                  a non-digit
544     \w                  a word character (a-z, A-Z, 0-9, _)
545     \W                  a non-word character
546     [aeiou]             matches a single character in the given set
547     [^aeiou]            matches a single character outside the given set
548     (foo|bar|baz)       matches any of the alternatives specified
549
550     ^                   start of string
551     $                   end of string
552
553 Quantifiers can be used to specify how many of the previous thing you
554 want to match on, where "thing" means either a literal character, one
555 of the metacharacters listed above, or a group of characters or
556 metacharacters in parentheses.
557
558     *                   zero or more of the previous thing
559     +                   one or more of the previous thing
560     ?                   zero or one of the previous thing
561     {3}                 matches exactly 3 of the previous thing
562     {3,6}               matches between 3 and 6 of the previous thing
563     {3,}                matches 3 or more of the previous thing
564
565 Some brief examples:
566
567     /^\d+/              string starts with one or more digits
568     /^$/                nothing in the string (start and end are adjacent)
569     /(\d\s){3}/         a three digits, each followed by a whitespace
570                         character (eg "3 4 5 ")
571     /(a.)+/             matches a string in which every odd-numbered letter
572                         is a (eg "abacadaf")
573
574     # This loop reads from STDIN, and prints non-blank lines:
575     while (<>) {
576         next if /^$/;
577         print;
578     }
579
580 =item Parentheses for capturing
581
582 As well as grouping, parentheses serve a second purpose.  They can be
583 used to capture the results of parts of the regexp match for later use.
584 The results end up in C<$1>, C<$2> and so on.
585
586     # a cheap and nasty way to break an email address up into parts
587
588     if ($email =~ /([^@]+)@(.+)/) {
589         print "Username is $1\n";
590         print "Hostname is $2\n";
591     }
592
593 =item Other regexp features
594
595 Perl regexps also support backreferences, lookaheads, and all kinds of
596 other complex details.  Read all about them in L<perlrequick>,
597 L<perlretut>, and L<perlre>.
598
599 =back
600
601 =head2 Writing subroutines
602
603 Writing subroutines is easy:
604
605     sub logger {
606         my $logmessage = shift;
607         open my $logfile, ">>", "my.log" or die "Could not open my.log: $!";
608         print $logfile $logmessage;
609     }
610
611 Now we can use the subroutine just as any other built-in function:
612
613     logger("We have a logger subroutine!");
614
615 What's that C<shift>?  Well, the arguments to a subroutine are available
616 to us as a special array called C<@_> (see L<perlvar> for more on that).
617 The default argument to the C<shift> function just happens to be C<@_>.
618 So C<my $logmessage = shift;> shifts the first item off the list of
619 arguments and assigns it to C<$logmessage>.
620
621 We can manipulate C<@_> in other ways too:
622
623     my ($logmessage, $priority) = @_;       # common
624     my $logmessage = $_[0];                 # uncommon, and ugly
625
626 Subroutines can also return values:
627
628     sub square {
629         my $num = shift;
630         my $result = $num * $num;
631         return $result;
632     }
633
634 Then use it like:
635
636     $sq = square(8);
637
638 For more information on writing subroutines, see L<perlsub>.
639
640 =head2 OO Perl
641
642 OO Perl is relatively simple and is implemented using references which
643 know what sort of object they are based on Perl's concept of packages.
644 However, OO Perl is largely beyond the scope of this document.
645 Read L<perlboot>, L<perltoot>, L<perltooc> and L<perlobj>.
646
647 As a beginning Perl programmer, your most common use of OO Perl will be
648 in using third-party modules, which are documented below.
649
650 =head2 Using Perl modules
651
652 Perl modules provide a range of features to help you avoid reinventing
653 the wheel, and can be downloaded from CPAN ( http://www.cpan.org/ ).  A
654 number of popular modules are included with the Perl distribution
655 itself.
656
657 Categories of modules range from text manipulation to network protocols
658 to database integration to graphics.  A categorized list of modules is
659 also available from CPAN.
660
661 To learn how to install modules you download from CPAN, read
662 L<perlmodinstall>.
663
664 To learn how to use a particular module, use C<perldoc I<Module::Name>>.
665 Typically you will want to C<use I<Module::Name>>, which will then give
666 you access to exported functions or an OO interface to the module.
667
668 L<perlfaq> contains questions and answers related to many common
669 tasks, and often provides suggestions for good CPAN modules to use.
670
671 L<perlmod> describes Perl modules in general.  L<perlmodlib> lists the
672 modules which came with your Perl installation.
673
674 If you feel the urge to write Perl modules, L<perlnewmod> will give you
675 good advice.
676
677 =head1 AUTHOR
678
679 Kirrily "Skud" Robert <skud@cpan.org>