[perl #22011] [PATCH] pod/perlmod.pod (v5.8.0)

[perl5.git] / pod / perlmod.pod

diff --git a/pod/perlmod.pod b/pod/perlmod.pod
index b27ee85..a216457 100644 (file)
--- a/pod/perlmod.pod
+++ b/pod/perlmod.pod
@@ -33,7 +33,7 @@ preferred delimiter, in part because it's more readable to humans, and
 in part because it's more readable to B<emacs> macros.  It also makes C++
 programmers feel like they know what's going on--as opposed to using the
 single quote as separator, which was there to make Ada programmers feel
 in part because it's more readable to B<emacs> macros.  It also makes C++
 programmers feel like they know what's going on--as opposed to using the
 single quote as separator, which was there to make Ada programmers feel

-like they knew what's going on.  Because the old-fashioned syntax is still
+like they knew what was going on.  Because the old-fashioned syntax is still

 supported for backwards compatibility, if you try to use a string like
 C<"This is $owner's house">, you'll be accessing C<$owner::s>; that is,
 the $s variable in package C<owner>, which is probably not what you meant.
 supported for backwards compatibility, if you try to use a string like
 C<"This is $owner's house">, you'll be accessing C<$owner::s>; that is,
 the $s variable in package C<owner>, which is probably not what you meant.


@@ -45,7 +45,7 @@ name lookups, however.  There are no relative packages: all symbols
 are either local to the current package, or must be fully qualified
 from the outer package name down.  For instance, there is nowhere
 within package C<OUTER> that C<$INNER::var> refers to
 are either local to the current package, or must be fully qualified
 from the outer package name down.  For instance, there is nowhere
 within package C<OUTER> that C<$INNER::var> refers to

-C<$OUTER::INNER::var>.  It would treat package C<INNER> as a totally
+C<$OUTER::INNER::var>.  C<INNER> refers to a totally

 separate global package.
 
 Only identifiers starting with letters (or underscore) are stored
 separate global package.
 
 Only identifiers starting with letters (or underscore) are stored


@@ -53,7 +53,7 @@ in a package's symbol table.  All other symbols are kept in package
 C<main>, including all punctuation variables, like $_.  In addition,
 when unqualified, the identifiers STDIN, STDOUT, STDERR, ARGV,
 ARGVOUT, ENV, INC, and SIG are forced to be in package C<main>,
 C<main>, including all punctuation variables, like $_.  In addition,
 when unqualified, the identifiers STDIN, STDOUT, STDERR, ARGV,
 ARGVOUT, ENV, INC, and SIG are forced to be in package C<main>,

-even when used for other purposes than their built-in one.  If you
+even when used for other purposes than their built-in ones.  If you

 have a package called C<m>, C<s>, or C<y>, then you can't use the
 qualified form of an identifier because it would be instead interpreted
 as a pattern match, a substitution, or a transliteration.
 have a package called C<m>, C<s>, or C<y>, then you can't use the
 qualified form of an identifier because it would be instead interpreted
 as a pattern match, a substitution, or a transliteration.


@@ -61,7 +61,8 @@ as a pattern match, a substitution, or a transliteration.
 Variables beginning with underscore used to be forced into package
 main, but we decided it was more useful for package writers to be able
 to use leading underscore to indicate private variables and method names.
 Variables beginning with underscore used to be forced into package
 main, but we decided it was more useful for package writers to be able
 to use leading underscore to indicate private variables and method names.

-$_ is still global though.  See also
+However, variables and functions named with a single C<_>, such as
+$_ and C<sub _>, are still forced into the package C<main>.  See also

 L<perlvar/"Technical Note on the Syntax of Variable Names">.
 
 C<eval>ed strings are compiled in the package in which the eval() was
 L<perlvar/"Technical Note on the Syntax of Variable Names">.
 
 C<eval>ed strings are compiled in the package in which the eval() was


@@ -76,7 +77,7 @@ expressions in the context of the C<main> package (or wherever you came
 from).  See L<perldebug>.
 
 The special symbol C<__PACKAGE__> contains the current package, but cannot
 from).  See L<perldebug>.
 
 The special symbol C<__PACKAGE__> contains the current package, but cannot

-(easily) be used to construct variables.
+(easily) be used to construct variable names.

 
 See L<perlsub> for other scoping issues related to my() and local(),
 and L<perlref> regarding closures.
 
 See L<perlsub> for other scoping issues related to my() and local(),
 and L<perlref> regarding closures.


@@ -152,7 +153,7 @@ it was exported:
     @EXPORT = qw($FOO); # Usual form, can't be localized
     @EXPORT = qw(*FOO); # Can be localized
 
     @EXPORT = qw($FOO); # Usual form, can't be localized
     @EXPORT = qw(*FOO); # Can be localized
 

-You can work around the first case by using the fully qualified name 
+You can work around the first case by using the fully qualified name

 (C<$Package::FOO>) where you need a local value, or by overriding it
 by saying C<*FOO = *Package::FOO> in your script.
 
 (C<$Package::FOO>) where you need a local value, or by overriding it
 by saying C<*FOO = *Package::FOO> in your script.
 


@@ -184,7 +185,7 @@ Another use of symbol tables is for making "constant" scalars.
 Now you cannot alter C<$PI>, which is probably a good thing all in all.
 This isn't the same as a constant subroutine, which is subject to
 optimization at compile-time.  A constant subroutine is one prototyped
 Now you cannot alter C<$PI>, which is probably a good thing all in all.
 This isn't the same as a constant subroutine, which is subject to
 optimization at compile-time.  A constant subroutine is one prototyped

-to take no arguments and to return a constant expression.  See 
+to take no arguments and to return a constant expression.  See

 L<perlsub> for details on these.  The C<use constant> pragma is a
 convenient shorthand for these.
 
 L<perlsub> for details on these.  The C<use constant> pragma is a
 convenient shorthand for these.
 


@@ -303,7 +304,7 @@ is not.
 There is no special class syntax in Perl, but a package may act
 as a class if it provides subroutines to act as methods.  Such a
 package may also derive some of its methods from another class (package)
 There is no special class syntax in Perl, but a package may act
 as a class if it provides subroutines to act as methods.  Such a
 package may also derive some of its methods from another class (package)

-by listing the other package name(s) in its global @ISA array (which 
+by listing the other package name(s) in its global @ISA array (which

 must be a package global, not a lexical).
 
 For more on this, see L<perltoot> and L<perlobj>.
 must be a package global, not a lexical).
 
 For more on this, see L<perltoot> and L<perlobj>.


@@ -311,10 +312,10 @@ For more on this, see L<perltoot> and L<perlobj>.
 =head2 Perl Modules
 
 A module is just a set of related functions in a library file, i.e.,
 =head2 Perl Modules
 
 A module is just a set of related functions in a library file, i.e.,

-a Perl package with the same name as the file.  It is specifically 
+a Perl package with the same name as the file.  It is specifically

 designed to be reusable by other modules or programs.  It may do this
 by providing a mechanism for exporting some of its symbols into the
 designed to be reusable by other modules or programs.  It may do this
 by providing a mechanism for exporting some of its symbols into the

-symbol table of any package using it.  Or it may function as a class
+symbol table of any package using it, or it may function as a class

 definition and make its semantics available implicitly through
 method calls on the class and its objects, without explicitly
 exporting anything.  Or it can do a little of both.
 definition and make its semantics available implicitly through
 method calls on the class and its objects, without explicitly
 exporting anything.  Or it can do a little of both.


@@ -429,7 +430,7 @@ if you're a classicist).
 The two statements:
 
     require SomeModule;
 The two statements:
 
     require SomeModule;

-    require "SomeModule.pm";           
+    require "SomeModule.pm";

 
 differ from each other in two ways.  In the first case, any double
 colons in the module name, such as C<Some::Module>, are translated
 
 differ from each other in two ways.  In the first case, any double
 colons in the module name, such as C<Some::Module>, are translated


@@ -461,7 +462,7 @@ In general, C<use Module ()> is recommended over C<require Module>,
 because it determines module availability at compile time, not in the
 middle of your program's execution.  An exception would be if two modules
 each tried to C<use> each other, and each also called a function from
 because it determines module availability at compile time, not in the
 middle of your program's execution.  An exception would be if two modules
 each tried to C<use> each other, and each also called a function from

-that other module.  In that case, it's easy to use C<require>s instead.
+that other module.  In that case, it's easy to use C<require> instead.

 
 Perl packages may be nested inside other package names, so we can have
 package names containing C<::>.  But if we used that package name
 
 Perl packages may be nested inside other package names, so we can have
 package names containing C<::>.  But if we used that package name


@@ -481,17 +482,20 @@ autoloading, the user can say just C<use POSIX> to get it all.
 
 =head2 Making your module threadsafe
 
 
 =head2 Making your module threadsafe
 

-Perl has since 5.6.0 support for a new type of threads called
-interpreter threads. These threads can be used explicitly and implicitly.
+Since 5.6.0, Perl has had support for a new type of threads called
+interpreter threads (ithreads). These threads can be used explicitly
+and implicitly.

 
 Ithreads work by cloning the data tree so that no data is shared
 
 Ithreads work by cloning the data tree so that no data is shared

-between different threads. These threads can be used using the threads
-module or by doing fork() on win32 (fake fork() support). When a thread is
-cloned all perl data is cloned, however non perl data cannot be cloned.
-Perl after 5.7.2 has support for the C<CLONE> keyword. C<CLONE> will be
-executed once for every package that has it defined (or inherits it).
-It will be called in the context of the new thread, so all modifications
-are made in the new area.
+between different threads. These threads can be used by using the C<threads>
+module or by doing fork() on win32 (fake fork() support). When a
+thread is cloned all Perl data is cloned, however non-Perl data cannot
+be cloned automatically.  Perl after 5.7.2 has support for the C<CLONE>
+special subroutine .  In C<CLONE> you can do whatever you need to do,
+like for example handle the cloning of non-Perl data, if necessary.
+C<CLONE> will be executed once for every package that has it defined
+(or inherits it).  It will be called in the context of the new thread,
+so all modifications are made in the new area.

 
 If you want to CLONE all objects you will need to keep track of them per
 package. This is simply done using a hash and Scalar::Util::weaken().
 
 If you want to CLONE all objects you will need to keep track of them per
 package. This is simply done using a hash and Scalar::Util::weaken().


@@ -501,7 +505,7 @@ package. This is simply done using a hash and Scalar::Util::weaken().
 See L<perlmodlib> for general style issues related to building Perl
 modules and classes, as well as descriptions of the standard library
 and CPAN, L<Exporter> for how Perl's standard import/export mechanism
 See L<perlmodlib> for general style issues related to building Perl
 modules and classes, as well as descriptions of the standard library
 and CPAN, L<Exporter> for how Perl's standard import/export mechanism

-works, L<perltoot> and L<perltootc> for an in-depth tutorial on
+works, L<perltoot> and L<perltooc> for an in-depth tutorial on

 creating classes, L<perlobj> for a hard-core reference document on
 objects, L<perlsub> for an explanation of functions and scoping,
 and L<perlxstut> and L<perlguts> for more information on writing
 creating classes, L<perlobj> for a hard-core reference document on
 objects, L<perlsub> for an explanation of functions and scoping,
 and L<perlxstut> and L<perlguts> for more information on writing