From 15ee51f173b6def2ce202d495cc309c4c9937057 Mon Sep 17 00:00:00 2001 From: chromatic Date: Wed, 19 Oct 2011 16:34:50 -0700 Subject: [PATCH] Edited chapter 9. --- sections/chapter_09.pod | 17 +- sections/code_generation.pod | 140 +++++++-------- sections/distributions.pod | 158 ++++++++--------- sections/files.pod | 302 +++++++++++++++++++-------------- sections/handling_warnings.pod | 99 +++++------ sections/modules.pod | 111 ++++++------ sections/overloading.pod | 68 ++++---- sections/taint.pod | 64 ++++--- sections/testing.pod | 219 +++++++++++++----------- sections/universal.pod | 109 ++++++------ 10 files changed, 671 insertions(+), 616 deletions(-) diff --git a/sections/chapter_09.pod b/sections/chapter_09.pod index 45a705d3..627902e3 100644 --- a/sections/chapter_09.pod +++ b/sections/chapter_09.pod @@ -2,16 +2,13 @@ Z -Writing simple example programs to solve example problems in a book helps you -learn a language in the small. Yet writing real programs requires more than -learning the syntax of a language, or its design principles, or even how to -find and use its libraries. - -Practical programming requires you to manage code: to organize it, to know that -it works, to make it robust in the face of errors of logic or intent, and to do -all of this in a concise, clear, and maintainable fashion. Fortunately, modern -Perl provides many tools and techniques to write real programs--from testing to -the organization of your source code. +A book can teach you to write small programs to solve small example problems. +You can learn a lot of syntax that way. To write real programs to solve real +problems, you must learn to I code written in your language. How do you +organize code? How do you know that it works? How can you make it robust in the +face of errors? What makes code concise, clear, and maintainable? + +Modern Perl provides many tools and techniques to write real programs. L diff --git a/sections/code_generation.pod b/sections/code_generation.pod index b98f7e62..9167d111 100644 --- a/sections/code_generation.pod +++ b/sections/code_generation.pod @@ -2,25 +2,24 @@ Z -Improving as a programmer requires you to search for better abstractions. The -less code you have to write, the better. The more general your solutions, the -better. When you can delete code and add features, you've achieved something -great. - Novice programmers write more code than they need to write, partly from -unfamiliarity with their languages, libraries, and idioms, but also due to -inexperience creating and maintaining good abstractions. They start by writing -long lists of procedural code, then discover functions, then parameters, then -objects, and--perhaps--higher-order functions and closures. +unfamiliarity with languages, libraries, and idioms, but also due to +inexperience. They start by writing long lists of procedural code, then +discover functions, then parameters, then objects, and--perhaps--higher-order +functions and closures. + +As you become a better programmer, you'll write less code to solve the same +problems. You'll use better abstractions. You'll write more general code. You +can reuse code--and when you can add features by deleting code, you'll achieve +something great. X X Writing programs to write programs for you--I or I)--offers greater possibilities for abstraction. This can be as -clear as exploiting higher-order programming capabilities or a rat hole down -which you find yourself confused and frightened. The techniques are powerful -and useful. For example, they form the basis of Moose (L). +generation>)--offers greater possibilities for abstraction. While you can make +a huge mess, you can also build amazing things. For example, metaprogramming +techniques make Moose possible (L). The C technique (L) for missing functions and methods demonstrates this technique in a constrained form; Perl 5's function and method @@ -48,18 +47,10 @@ want to) load an optional dependency: =end programlisting If C is not available, its C function will exist, but -will do nothing. - -=begin sidebar - -This isn't necessarily the I way to handle this feature, as the Null -Object pattern offers more encapsulation, but it is I way to do things. - -=end sidebar - -This simple example is deceptive. You must handle quoting issues to include -variables within your Cd code. Add more complexity to interpolate some -but not others: +will do nothing. Yet this simple example is deceptive. Getting C right +takes some work; you must handle quoting issues to include variables within +your Cd code. Add more complexity to interpolate some variables but not +others: =begin programlisting @@ -86,12 +77,12 @@ but not others: =end programlisting -Woe to those who forget a backslash! Good luck convincing your syntax -highlighter what's happening! Worse yet, each invocation of string C -builds a new data structure representing the entire code. Compiling code isn't -free, either--cheaper than performing IO, perhaps, but not free. +Woe to those who forget a backslash! Good luck convincing your syntax +highlighter what's happening! Worse yet, each invocation of string C +builds a new data structure representing the entire code. Compiling code isn't +free, either. -Even so, this technique is simple and reasonably easy to understand. +Even with its limitations, this technique is reasonably simple. =head2 Parametric Closures @@ -125,10 +116,9 @@ without requiring additional evaluation: =end programlisting -This code avoids unpleasant quoting issues and runs more quickly, as there's -only one compilation stage, no matter how many accessors you create. It even -uses less memory by sharing the compiled code between all instances of the -closure. All that differs is the binding to the C<$attrname> lexical. In a +This code avoids unpleasant quoting issues and compiles each closure only once. +It even uses less memory by sharing the compiled code between all closure +instances. All that differs is the binding to the C<$attrname> lexical. In a long-running process, or with a lot of accessors, this technique can be very useful. @@ -155,20 +145,27 @@ X The odd syntax of an asteriskN, where a I is Perl jargon for "symbol table".> deferencing a hash refers to a -symbol in the current I, which is the place in the current +symbol in the current I, which is the portion of the current namespace which contains globally-accessible symbols such as package globals, -functions, and methods. Assigning a reference to a symbol table entry installs -or replaces the appropriate entry. To promote an anonymous function to a -method, assign that function reference to the appropriate entry in the symbol -table. +functions, and methods. Assigning a reference to a symbol table entry installs +or replaces the appropriate entry. To promote an anonymous function to a +method, store that function's reference in the symbol table. + +=begin sidebar + +X> +The CPAN module C offers a nicer interface to this symbol table +hackery. + +=end sidebar X pragma> X> -This operation refers to a symbol with a string, not a literal variable name, -so it's a symbolic reference and it's necessary to disable C reference -checking for the operation. Many programs have a subtle bug in similar code, -as they assign and generate in a single line: +Assigning to a symbol table symbol with a string, not a literal variable name, +is a symbolic reference. You must disable C reference checking for the +operation. Many programs have a subtle bug in similar code, as they assign and +generate in a single line: =begin programlisting @@ -176,20 +173,18 @@ as they assign and generate in a single line: no strict 'refs'; *{ $methname } = sub { - # subtle bug: strict refs - # are disabled in here too + # subtle bug: strict refs disabled in here too }; } =end programlisting -This example disables strictures for the outer block as well as the inner -block, the body of the function itself. Only the assignment violates strict -reference checking, so disable strictures for that operation alone. +This example disables strictures for the outer block as well as the body of the +function itself. Only the assignment violates strict reference checking, so +disable strictures for that operation alone. If the name of the method is a string literal in your source code, rather than -the contents of a variable, you can assign to the relevant symbol directly -rather than through a symbolic reference: +the contents of a variable, you can assign to the relevant symbol directly: =begin programlisting @@ -215,13 +210,13 @@ not be available when you expect it. X> -Force Perl to run code--to generate other code--during the compilation stage by -wrapping it in a C block. When the Perl 5 parser encounters a block -labeled C, it parses the entire block. Provided it contains no syntax -errors, the block will run immediately. When it finishes, parsing will -continue as if there were no interruption. +Force Perl to run code--to generate other code--during compilation by wrapping +it in a C block. When the Perl 5 parser encounters a block labeled +C, it parses the entire block. Provided it contains no syntax errors, +the block will run immediately. When it finishes, parsing will continue as if +there had been no interruption. -In practical terms, the difference between writing: +The difference between writing: =begin programlisting @@ -263,18 +258,21 @@ X> Within a module, any code outside of functions executes when you C it, because of the implicit C Perl adds around the C and C -(L). Any code outside of a function but inside the module will -execute I the C call occurs. If you C the module, +(L). Any code outside of a function but inside the module will +execute I the C call occurs. If you C the module, there is no implicit C block. The execution of code outside of functions will happen at the I of parsing. -Also beware of the interaction between lexical I (the association -of a name with a scope) and lexical I. The former happens during -compilation, while the latter occurs at the point of execution. This code has -a subtle bug: +Beware of the interaction between lexical I (the association of a +name with a scope) and lexical I. The former happens during +compilation, while the latter occurs at the point of execution. This code has a +subtle bug: + +X> =begin programlisting + # adds a require() method to UNIVERSAL use UNIVERSAL::require; # buggy; do not use @@ -302,11 +300,10 @@ X X Unlike installing function references to populate namespaces and to create -methods, there's no simple default way to create classes in Perl 5. -Fortunately, a mature and powerful distribution is available from the CPAN to -do just this. C is the library which makes Moose (L) -possible. It provides a I--a mechanism for creating and -manipulating an object system in terms of itself. +methods, there's no simple way to create classes programmatically in Perl 5. +Moose comes to the rescue, with its bundled C library. It provides +a I--a mechanism for creating and manipulating an object +system in terms of itself. Rather than writing your own fragile string C code or trying to poke into symbol tables manually, you can manipulate the entities and abstractions of @@ -325,7 +322,7 @@ To create a class: X X -You can add attributes and methods to this class when you create it: +Add attributes and methods to this class when you create it: =begin programlisting @@ -368,5 +365,8 @@ after you've created it: =end programlisting -You can similarly create and manipulate and introspect attributes and methods -with C and C. +X> +X> + +Similarly C and C allow you to +create and manipulate and introspect attributes and methods. diff --git a/sections/distributions.pod b/sections/distributions.pod index 7b198cf1..9a128998 100644 --- a/sections/distributions.pod +++ b/sections/distributions.pod @@ -4,46 +4,39 @@ Z X -A I is a collection of one or more modules (L) which -forms a single redistributable, testable, and installable unit. Effectively -it's a collection of module and metadata. - -The easiest way to manage software configuration, building, distribution, -testing, and installation even within your organization is to create -distributions compatible with the CPAN. The conventions of the CPAN--how to -package a distribution, how to resolve its dependencies, where to install -software, how to verify that it works, how to display documentation, how to -manage a repository--have all arisen from the rough consensus of thousands of -contributors working on tens of thousands of projects. - -In particular, the copious amount of testing and reporting and dependency -checking achieved by CPAN developers exceeds the available information and -quality of work in any other language community. A distribution built to CPAN -standards can be tested on several versions of Perl 5 on several different -hardware platforms within a few hours of its uploading--all without human -intervention. +The easiest way to manage software configuration, building, packaging, testing, +and installation is to follow the CPAN's distribution conventions. A +I is a collection of metadata and one or more modules +(L) which forms a single redistributable, testable, and installable +unit. + +These guidelines--how to package a distribution, how to resolve its +dependencies, where to install software, how to verify that it works, how to +display documentation, how to manage a repository--have all arisen from the +rough consensus of thousands of contributors working on tens of thousands of +projects. A distribution built to CPAN standards can be tested on several +versions of Perl 5 on several different hardware platforms within a few hours +of its uploading, with errors reported automatically to authors--all without +human intervention. You may choose never to release any of your code as public CPAN distributions, -but you can reuse existing CPAN tools and designs as possible. The combination -of intelligent defaults and customizability are likely to meet your specific -needs. +but you can reuse CPAN tools and conventions. =head2 Attributes of a Distribution -A distribution obviously includes one or more modules. It also includes -several other files and directories: +Besides one or more modules, a distribution includes several other files and +directories: =over 4 -=item * F or F, the program used to configure, build, -test, bundle, and install the distribution. +=item * F or F, a driver program used to configure, +build, test, bundle, and install the distribution. -=item * F, a list of all files contained in the distribution. This -helps packaging tools produce an entire tarball and helps to verify that -recipients of the tarball have all of the necessary files. +=item * F, a list of all files contained in the distribution. This +helps tools verify that a bundle is complete. -=item * F and/or F, a file containing metadata about the distribution and its -dependencies. +=item * F and/or F, a file containing metadata about the +distribution and its dependencies. =item * F, a description of the distribution, its intent, and its copyright and licensing information. @@ -58,44 +51,37 @@ copyright and licensing information. X -Additionally, a well-formed distribution must contain a unique name and single -version number (often taken from its primary module). Any well-formed -distribution you download from the public CPAN should conform to these -standards--and the CPANTS service evaluates the kwaliteeN of all CPAN distributions and recommends packaging improvements. +A well-formed distribution must contain a unique name and single version number +(often taken from its primary module). Any distribution you download from the +public CPAN should conform to these standards. The public CPANTS service +(U) evaluates each uploaded distribution against +packaging guidelines and conventions and recommends improvements. =head2 CPAN Tools for Managing Distributions -The Perl 5 core includes several tools to manage distributions--not just -installing them from the CPAN, but developing and managing your own: +The Perl 5 core includes several tools to install, develop, and manage your own +distributions: X> +X> =over 4 -=item * C is the official CPAN client. While by default it installs -distributions from the public CPAN, you can point it to your own repository +=item * C is the official CPAN client; C is an alternative. +They are largely equivalent. While by default these clients install +distributions from the public CPAN, you can point them to your own repository instead of or in addition to the public repository. -X> - -=item * C is an alternate CPAN client with a different design -approach. It does some things better than C, but they are largely -equivalent at this point. Use whichever you prefer. - X> =item * C is a pure-Perl tool suite for configuring, building, -installing, and testing distributions. It works with the F file -mentioned earlier. +installing, and testing distributions. It works with F files. X> -=item * C is an older, legacy tool which C -intends to replace. It is still in wide use, though it is in maintenance mode -and receives only the most critical bug fixes. It works with the -F file mentioned earlier. +=item * C is a legacy tool which C intends +to replace. It is still in wide use, though it is in maintenance mode and +receives only critical bug fixes. It works with F files. X> @@ -105,28 +91,29 @@ module used to write automated tests for Perl software. X> X> -=item * C and C (L) are the tools used to -run tests and to interpret and report their results. +=item * C and C (L) run tests and +interpret and report their results. =back In addition, several non-core CPAN modules make your life easier as a developer: -X> +X> +X +X =over 4 -=item * C is a new utility which provides almost -configuration-free use of the public CPAN. It fulfills 90% of your needs to -find and install modules. +=item * C provides almost configuration-free use of the public +CPAN. It provides the most common 90% of what a CPAN client needs. -X> +X> +X =item * C helps you to manage multiple installations of Perl 5. -This is very useful to use a newer version than the system version or to -isolate distributions you've installed for one application from distributions -you've installed for another. +Install new versions of Perl 5 for testing or production, or to isolate +applications and their dependencies. X> X> @@ -136,13 +123,13 @@ X> into this repository and manage which versions of the public modules are available in your organization. -X> -X> +X> +X> X> -=item * C is a toolkit for managing distributions by automating -away common tasks. While it can use either C or -C, it can replace I use of them directly. +=item * C automates away common distribution tasks tasks. While it +uses either C or C, it can replace I +use of them directly. See U for an interactive tutorial. X> @@ -154,40 +141,41 @@ data on any failures. =head2 Designing Distributions +X> + The process of designing a distribution could fill a book (see Sam Tregar's I), but a few design principles will help you. -Start with a utility such as C or C from the -CPAN. The initial cost of learning the configuration and rules may seem like a -steep investment, but the benefit of having everything set up the right way -(and in the case of C, I going out of date) relieves you of -much tedious bookkeeping. +Start with a utility such as C or C. The initial +cost of learning the configuration and rules may seem like a steep investment, +but the benefit of having everything set up the right way (and in the case of +C, I going out of date) relieves you of much tedious +bookkeeping. -Then consider several rules. +Then consider several rules: =over 4 -=item * I That -purpose may be to process a particular type of data file or to gather together -several related distributions into a single installable bundle. Decomposing -your software into individual bundles allows you to manage their dependencies -appropriately and to respect their encapsulation. +=item * I That purpose +may even include gathering several related distributions into a single +installable bundle. Decomposing your software into individual distributions +allows you to manage their dependencies appropriately and to respect their +encapsulation. -=item * I Version numbers -must always increase. The semantic version policy (U) is +=item * I Version numbers +must always increase. The semantic version policy (U) is sane and compatible with the Perl 5 approach. -=item * I A comprehensive +=item * I A comprehensive automated test suite can verify that you maintain this API across versions. If you use a local CPAN mirror to install your own distributions, you can re-use the CPAN infrastructure for testing distributions and their dependencies. You get easy access to integration testing across reusable components. =item * I Managing software effectively requires you to know when it works -and how it fails if it fails. +valuable.> The CPAN infrastructure supports automated test reporting. Use it! -=item * I Avoid the use of global -symbols and default exports; allow people to use only what they need and do not +=item * I Avoid the use of global +symbols and default exports; allow people to use only what they need. Do not pollute their namespaces. =back diff --git a/sections/files.pod b/sections/files.pod index 847a28da..7d706cef 100644 --- a/sections/files.pod +++ b/sections/files.pod @@ -2,11 +2,8 @@ Z -Most programs deal with the outside world in some fashion, and much of that -interaction takes place with files: reading them, writing them, manipulating -them in some other fashion. Perl's early history as a language for system -administration and text processing has produced a language very well suited for -file manipulation. +Most programs must interact with the real world somehow. Most programs must +read, write, and otherwise manipulate files. Perl's origin as a tool for system administrators have produced a language well suited for text processing. =head2 Input and Output @@ -19,18 +16,14 @@ X> X> X> -The primary mechanism of interacting with the world outside of a program is -through a I. Filehandles represent the state of some channel of -input or output, such as the standard input or output of a program, a file from -or to which to read or write, and the position in a given file. Every Perl 5 -program has three standard filehandles available, C (the input to the -program), C (the output from the program), and C (the error -output from the program). - -By default, everything you C or C goes to C, while errors -and warnings and everything you C goes to C. This separation -of output allows you to redirect useful output and errors to two different -places--an output file and error logs, for example. +A I represents the current state of one specific channel of input +or output. Every Perl 5 program has three standard filehandles available, +C (the input to the program), C (the output from the program), +and C (the error output from the program). By default, everything you +C or C goes to C, while errors and warnings and everything +you C goes to C. This separation of output allows you to +redirect useful output and errors to two different places--an output file and +error logs, for example. =begin sidebar @@ -38,20 +31,18 @@ X> X> X> -The special C filehandle represents the current file. When Perl finishes -compiling the file, it leaves the package global C available and open at -the end of the compilation unit I the file has a C<__DATA__> or C<__END__> -section at the end. If you store string data after C<__DATA__> or C<__END__>, -you can read that from the C filehandle. This is useful for short, -self-contained programs. C describes this feature in more -detail. +The special package global C filehandle represents the current file. When +Perl finishes compiling the file, it leaves C available and open at the +end of the compilation unit I the file has a C<__DATA__> or C<__END__> +section. Any text which occurs after that token is available for reading from +C. This is useful for short, self-contained programs. See C for more details. =end sidebar X> -Besides the standard filehandles, you can open your own filehandles with the -C builtin. To open a file for reading: +Use the C builtin to get a filehandle. To open a file for reading: =begin programlisting @@ -60,11 +51,14 @@ C builtin. To open a file for reading: =end programlisting -The first operand is a lexical which will hold the opened filehandle. The +The first operand is a lexical which will contain the resulting filehandle. The second operand is the I, which determines the type of the filehandle -operation. The final operand is the name of the file. If the C fails, -the C clause will throw an exception, with the contents of C<$!> giving -the reason why the open failed. +operation. The final operand is the name of the file. If the C fails, the +C clause will throw an exception, with the contents of C<$!> giving the +reason why the open failed. + +You may also open files for writing, appending, reading and writing, and more +(L). =begin table File Modes @@ -108,7 +102,7 @@ file otherwise. =end table -Besides files, you can open filehandles to scalars: +You can even create filehandles which read from or write to plain Perl scalars: =begin programlisting @@ -123,38 +117,42 @@ Besides files, you can open filehandles to scalars: Such filehandles support all of the existing file modes. -You may encounter older code which uses the two-argument form of C: +X> + +C offers far more details about more exotic uses of +C, including its ability to launch and control other processes, as well +as the use of C for finer-grained control over input and output. +C includes working code for many common IO tasks. + +=head3 Two-argument C + +Older code often uses the two-argument form of C, which jams the file +mode with the name of the file to open: =begin programlisting - open my $fh, "> $some_file" + open my $fh, B<< "> $some_file" >> or die "Cannot write to '$some_file': $!\n"; =end programlisting -The lack of clean separation between the intended file mode and the name of the -file allows the possibility of unintentional behaviorsN when interpolating untrusted input into the second operand. You -can safely replace the two-argument form of open with the three-argument form -in every case without any loss of feature. +Thus Perl must extract the file mode from the filename, and therein lies +potential problems. Anytime Perl has to guess at what you mean, you run the +risk that it may guess incorrectly. Worse, if C<$some_file> came from untrusted +user input, you have a potential security problem, as any unexpected characters +could change how your program behaves. -X> +The three-argument C is a safer replacement for this code. -C offers far more details about more exotic uses of -C, including its ability to launch and control other processes, as well -as the use of C for finer-grained control over input and output. -C includes working code for many common IO tasks. +=head3 Reading from Files X> X<<< C<< <> >>; circumfix readline operator >>> X<<< operators; C<< <> >> >>> -=head3 Reading from Files - -Given a filehandle opened for input, read from it with the C -operator, also written as C<< <> >>. The most common idiom is to read a line -at a time in a C loop: +Given a filehandle opened for input, read from it with the C builtin, +also written as C<< <> >>. A common idiom reads a line at a time in a +C loop: =begin programlisting @@ -173,20 +171,42 @@ at a time in a C loop: X> In scalar context, C iterates through the lines of the file until it -reaches the end of the file (C). Each iteration returns the next line. -After reaching the end of the file, each iteration returns C. This +reaches the end of the file (C). Each iteration returns the next line. +After reaching the end of the file, each iteration returns C. This C idiom explicitly checks the definedness of the variable used for -iteration, such that only the end of file condition ends the loop. +iteration, such that only the end of file condition ends the loop. In other +words, this is shorthand for: + +=begin programlisting + + use autodie; + + open my $fh, '<', 'some_file'; + + while (defined($_ = <$fh>)) + { + chomp; + say "Read a line '$_'"; + last if eof $fh; + } + +=end programlisting + +=begin tip Why use C and not C? + +C imposes list context on its operand, which reads the entire file before +processing any of it. This may use a lot of memory for large files. + +=end tip X> Every line read from C includes the character or characters which -mark the end of a line. In most cases, this is a platform-specific sequence +mark the end of a line. In most cases, this is a platform-specific sequence consisting of a newline (C<\n>), a carriage return (C<\r>), or a combination of -the two (C<\r\n>). Use C to remove your platform's specific newline -sequence. +the two (C<\r\n>). Use C to remove it. -With everything all together, the cleanest way to read from files in Perl 5 is: +The cleanest way to read a file line-by-line in Perl 5 is: =begin programlisting @@ -204,19 +224,19 @@ With everything all together, the cleanest way to read from files in Perl 5 is: X> -If you're not reading I data--instead reading I data--use -C on the filehandle before reading from or writing to it. This -builtin tells Perl to treat all of the filehandle's data as pure data. Perl -will not modify it in any fashion, as it might for platform portability. -Although Unix-like platforms may not to I C in this case, -portable programs use it anyway (L). +Perl accesses files in text mode by default. If you're reading I data, +such as a media file or a compressed file--use C before performing any +IO. This will force Perl to treat the file data as pure data, without modifying +it in any wayN into the +platform-specific newline sequence.>. While Unix-like platforms may not always +I C, portable programs play it safe (L). =head3 Writing to Files X> X> -Given a filehandle open for output, you may C or C to it: +Given a filehandle open for output, C or C to it: =begin programlisting @@ -245,19 +265,29 @@ X> X> X> -You may write an entire list of values to C or C, in which case -Perl 5 uses the magic global C<$,> as the separator between list values. Perl -also uses any value of C<$\> as the final argument to C or C. +Both C and C take a list of operands. Perl 5 uses the magic global +C<$,> as the separator between list values. Perl also uses any value of C<$\> +as the final argument to C or C. Thus these two lines of code +produce the same result: + +=begin programlisting + + my @princes = qw( Corwin Eric Random ... ); + + print @princes; + print join( $,, @princes ) . $\; + +=end programlisting =head3 Closing Files X> -When you've finished working with a file, you may C it explicitly or -allow its filehandle to go out of scope, in which case Perl will close it for -you. The benefit of calling C explicitly is that you can check for--and -recover from--specific errors, such as running out of space on a storage device -or a broken network connection. +When you've finished working with a file, C its filehandle explicitly or +allow it to go out of scope. Perl will close it for you. The benefit of calling +C explicitly is that you can check for--and recover from--specific +errors, such as running out of space on a storage device or a broken network +connection. As usual, C handles these checks for you: @@ -288,16 +318,18 @@ C uses the current contents of C<$/> as the line-ending sequence. The value of this variable defaults to the most appropriate line-ending character sequence for text files on your current platform. In truth, the word I is a misnomer. You can set C<$/> to contain any sequence of -charactersN<... but never a regular expression, because Perl 5 does not support -that.>. This is useful for highly-structured data in which you want to read a -I at a time. +charactersN<... but, sadly, never a regular expression. Perl 5 does not support +that.>. This is useful for highly-structured data in which you want to read a +I at a time. Given a file with records separated by two blank lines, +set C<$/> to C<\n\n> to read a record at a time. C on a record read from +the file will remove the double-newline sequence. X> X> X -By default, Perl uses I, where it performs IO only when it has -enough data to exceed a threshold. This allows Perl to batch up expensive IO +Perl I its output by default, performing IO only when its pending +output exceeds a size threshold. This allows Perl to batch up expensive IO operations instead of always writing very small amounts of data. Yet sometimes you want to send data as soon as you have it without waiting for that buffering--especially if you're writing a command-line filter connected to @@ -308,17 +340,24 @@ filehandle. When set to a non-zero value, Perl will flush the output after each write to the filehandle. When set to a zero value, Perl will use its default buffering strategy. -X> -X; C> +=begin sidebar + +Files default to a fully-buffered strategy. C when connected to an +active terminal--and I another program--uses a line-buffered strategy, +such that Perl will flush C every time it encounters a newline in the +output. + +=end sidebar + +X> +X; C> In lieu of the global variable, use the C method on a lexical -filehandle. Be sure to load C first, as you cannot call the -methods it provides on lexical filehandles otherwise: +filehandle: =begin programlisting use autodie; - use FileHandle; open my $fh, '>', 'pecan.log'; $fh->autoflush( 1 ); @@ -327,32 +366,36 @@ methods it provides on lexical filehandles otherwise: =end programlisting -X; C> -X; C> -X> -X> +X> -Once you have loaded C, you may also use its C -and C methods instead of C<$.> and C<$/> -respectively. To use the C method on filehandles, load -C, and so on. See C, C, -and C for more information. +As of Perl 5.14, you can use any method provided by C on a +filehandle. You do not need to load C explicitly. =begin sidebar -X> -C has superseded C in Perl 5.12. +X> +In Perl 5.12, you must load C yourself. In Perl 5.10 and earlier, you +must load C instead. =end sidebar +X; C> +X; C> +X> +X; C> + +C provides several methods, including C and +C methods to access C<$.> and C<$/>, as well as +C. See C, C, and C for more information. + =head2 Directories and Paths X> -You may also manipulate directories and file paths with Perl 5. Working with -directories is similar to working with files, except that you cannot I -to directoriesN. Open -a directory handle with C: +Working with directories is similar to working with files, except that you +cannot I to directoriesN. Open a directory handle with the C builtin: =begin programlisting @@ -364,7 +407,7 @@ a directory handle with C: X> -The C builtin reads from a directory. As with C, you may +The C builtin reads from a directory. As with C, you may iterate over the contents of directories one at a time or you may assign them to a list in one swoop: @@ -381,8 +424,7 @@ to a list in one swoop: =end programlisting -As a new feature available in 5.12, C in a C will set C<$_>, -just as does C in C: +Perl 5.12 added a feature where C in a C sets C<$_>: =begin programlisting @@ -404,9 +446,9 @@ X