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