Nicholas Clark
2009-04-21 09:50:14 UTC
In perl.git, the branch blead has been updated
<http://perl5.git.perl.org/perl.git/commitdiff/7eb47696deb9a7343fb4847f7342919a6df59e21?hp=da09dfe31dd61a9d5a3c2d9d69e3d674b6c642ac>
- Log -----------------------------------------------------------------
commit 7eb47696deb9a7343fb4847f7342919a6df59e21
Author: Nicholas Clark <***@ccl4.org>
Date: Tue Apr 21 10:49:10 2009 +0100
Build perltoc.pod, rather than shipping it. This way it can't get out of date.
-----------------------------------------------------------------------
Summary of changes:
MANIFEST | 1 -
Makefile.SH | 9 +-
pod.lst | 2 +-
pod/buildtoc | 6 +-
pod/perltoc.pod |38414 ----------------------------------------------
vms/descrip_mms.template | 9 +-
win32/Makefile | 5 +-
win32/makefile.mk | 5 +-
8 files changed, 26 insertions(+), 38425 deletions(-)
delete mode 100644 pod/perltoc.pod
diff --git a/MANIFEST b/MANIFEST
index a4427d8..69084ba 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -3617,7 +3617,6 @@ pod/perlsub.pod Perl subroutines
pod/perlsyn.pod Perl syntax
pod/perlthrtut.pod Perl threads tutorial
pod/perltie.pod Perl objects hidden behind simple variables
-pod/perltoc.pod Perl documentation table of contents
pod/perltodo.pod Perl things to do
pod/perltooc.pod Perl OO tutorial, part 2
pod/perltoot.pod Perl OO tutorial, part 1
diff --git a/Makefile.SH b/Makefile.SH
index 7cb0004..f7ec252 100644
--- a/Makefile.SH
+++ b/Makefile.SH
@@ -454,7 +454,8 @@ mini_obj = $(obj1) $(obj2) $(obj3) $(ARCHOBJS)
ndt_obj = $(obj0) $(obj1) $(obj2) $(obj3) $(ARCHOBJS)
obj = $(ndt_obj) $(DTRACE_O)
-generated_pods = extra.pods pod/perlapi.pod pod/perldelta.pod pod/perlintern.pod
+perltoc_pod_prereqs = extra.pods pod/perlapi.pod pod/perldelta.pod pod/perlintern.pod
+generated_pods = pod/perltoc.pod $(perltoc_pod_prereqs)
lintflags = \
-b \
@@ -971,6 +972,12 @@ uni.data: miniperl$(EXE_EXT) $(CONFIGPM) lib/unicore/mktables
cd lib/unicore && $(LDLIBPTH) $(RUN) ../../miniperl$(EXE_EXT) -I../../lib mktables -w
touch uni.data
+# perl$(EXE_EXT) and ext because buildtoc uses Text::Wrap uses re
+# But also this ensures that all extensions are built before we try to scan
+# them, which picks up Devel::PPPort's documentation.
+pod/perltoc.pod: $(perltoc_pod_prereqs) perl$(EXE_EXT) ext pod/buildtoc
+ $(RUN) ./perl$(EXE_EXT) -Ilib pod/buildtoc --build-toc -q
+
pod/perlapi.pod pod/perlintern.pod: miniperl$(EXE_EXT) autodoc.pl embed.fnc
$(RUN) ./miniperl$(EXE_EXT) -Ilib autodoc.pl
diff --git a/pod.lst b/pod.lst
index 50e5c88..a0c5d90 100644
--- a/pod.lst
+++ b/pod.lst
@@ -11,7 +11,7 @@ h Overview
perl Perl overview (this section)
perlintro Perl introduction for beginners
- perltoc Perl documentation table of contents
+g perltoc Perl documentation table of contents
h Tutorials
diff --git a/pod/buildtoc b/pod/buildtoc
index 50120ea..e80dae0 100644
--- a/pod/buildtoc
+++ b/pod/buildtoc
@@ -699,8 +699,10 @@ sub do_unix {
my $makefile_SH = join '', @_;
die "$0: $name contains NUL bytes" if $makefile_SH =~ /\0/;
- $makefile_SH =~ s{^(generated_pods = extra.pods).*}
- {join ' ', $1, map "pod/$_", sort keys %Generated, keys %Copies}mge;
+ $makefile_SH =~ s{^(perltoc_pod_prereqs = extra.pods).*}
+ {join ' ', $1, map "pod/$_",
+ sort keys %Copies, grep {!/perltoc/} keys %Generated
+ }mge;
# pod/perldelta.pod: pod/perl511delta.pod
# cd pod && $(LNS) perl511delta.pod perldelta.pod
diff --git a/pod/perltoc.pod b/pod/perltoc.pod
deleted file mode 100644
index 209e6f6..0000000
--- a/pod/perltoc.pod
+++ /dev/null
@@ -1,38414 +0,0 @@
-
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is autogenerated by buildtoc from all the other pods.
-# Edit those files and run buildtoc --build-toc to effect changes.
-
-=head1 NAME
-
-perltoc - perl documentation table of contents
-
-=head1 DESCRIPTION
-
-This page provides a brief table of contents for the rest of the Perl
-documentation set. It is meant to be scanned quickly or grepped
-through to locate the proper section you're looking for.
-
-=head1 BASIC DOCUMENTATION
-
-=head2 perl - Practical Extraction and Report Language
-
-=over 4
-
-=item SYNOPSIS
-
-=over 4
-
-=item Overview
-
-=item Tutorials
-
-=item Reference Manual
-
-=item Internals and C Language Interface
-
-=item Miscellaneous
-
-=item Language-Specific
-
-=item Platform-Specific
-
-=back
-
-=item DESCRIPTION
-
-=item AVAILABILITY
-
-=item ENVIRONMENT
-
-=item AUTHOR
-
-=item FILES
-
-=item SEE ALSO
-
-=item DIAGNOSTICS
-
-=item BUGS
-
-=item NOTES
-
-=back
-
-=head2 perlintro -- a brief introduction and overview of Perl
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item What is Perl?
-
-=item Running Perl programs
-
-=item Safety net
-
-=item Basic syntax overview
-
-=item Perl variable types
-
-Scalars, Arrays, Hashes
-
-=item Variable scoping
-
-=item Conditional and looping constructs
-
-if, while, for, foreach
-
-=item Builtin operators and functions
-
-Arithmetic, Numeric comparison, String comparison, Boolean logic,
-Miscellaneous
-
-=item Files and I/O
-
-=item Regular expressions
-
-Simple matching, Simple substitution, More complex regular expressions,
-Parentheses for capturing, Other regexp features
-
-=item Writing subroutines
-
-=item OO Perl
-
-=item Using Perl modules
-
-=back
-
-=item AUTHOR
-
-=back
-
-=head2 perlreftut - Mark's very short tutorial about references
-
-=over 4
-
-=item DESCRIPTION
-
-=item Who Needs Complicated Data Structures?
-
-=item The Solution
-
-=item Syntax
-
-=over 4
-
-=item Making References
-
-=item Using References
-
-=item An Example
-
-=item Arrow Rule
-
-=back
-
-=item Solution
-
-=item The Rest
-
-=item Summary
-
-=item Credits
-
-=over 4
-
-=item Distribution Conditions
-
-=back
-
-=back
-
-=head2 perldsc - Perl Data Structures Cookbook
-
-=over 4
-
-=item DESCRIPTION
-
-arrays of arrays, hashes of arrays, arrays of hashes, hashes of hashes,
-more elaborate constructs
-
-=item REFERENCES
-X<reference> X<dereference> X<dereferencing> X<pointer>
-
-=item COMMON MISTAKES
-
-=item CAVEAT ON PRECEDENCE
-X<dereference, precedence> X<dereferencing, precedence>
-
-=item WHY YOU SHOULD ALWAYS C<use strict>
-
-=item DEBUGGING
-X<data structure, debugging> X<complex data structure, debugging>
-X<AoA, debugging> X<HoA, debugging> X<AoH, debugging> X<HoH, debugging>
-X<array of arrays, debugging> X<hash of arrays, debugging>
-X<array of hashes, debugging> X<hash of hashes, debugging>
-
-=item CODE EXAMPLES
-
-=item ARRAYS OF ARRAYS
-X<array of arrays> X<AoA>
-
-=over 4
-
-=item Declaration of an ARRAY OF ARRAYS
-
-=item Generation of an ARRAY OF ARRAYS
-
-=item Access and Printing of an ARRAY OF ARRAYS
-
-=back
-
-=item HASHES OF ARRAYS
-X<hash of arrays> X<HoA>
-
-=over 4
-
-=item Declaration of a HASH OF ARRAYS
-
-=item Generation of a HASH OF ARRAYS
-
-=item Access and Printing of a HASH OF ARRAYS
-
-=back
-
-=item ARRAYS OF HASHES
-X<array of hashes> X<AoH>
-
-=over 4
-
-=item Declaration of an ARRAY OF HASHES
-
-=item Generation of an ARRAY OF HASHES
-
-=item Access and Printing of an ARRAY OF HASHES
-
-=back
-
-=item HASHES OF HASHES
-X<hash of hashes> X<HoH>
-
-=over 4
-
-=item Declaration of a HASH OF HASHES
-
-=item Generation of a HASH OF HASHES
-
-=item Access and Printing of a HASH OF HASHES
-
-=back
-
-=item MORE ELABORATE RECORDS
-X<record> X<structure> X<struct>
-
-=over 4
-
-=item Declaration of MORE ELABORATE RECORDS
-
-=item Declaration of a HASH OF COMPLEX RECORDS
-
-=item Generation of a HASH OF COMPLEX RECORDS
-
-=back
-
-=item Database Ties
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=back
-
-=head2 perllol - Manipulating Arrays of Arrays in Perl
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Declaration and Access of Arrays of Arrays
-
-=item Growing Your Own
-
-=item Access and Printing
-
-=item Slices
-
-=back
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=back
-
-=head2 perlrequick - Perl regular expressions quick start
-
-=over 4
-
-=item DESCRIPTION
-
-=item The Guide
-
-=over 4
-
-=item Simple word matching
-
-=item Using character classes
-
-=item Matching this or that
-
-=item Grouping things and hierarchical matching
-
-=item Extracting matches
-
-=item Matching repetitions
-
-=item More matching
-
-=item Search and replace
-
-=item The split operator
-
-=back
-
-=item BUGS
-
-=item SEE ALSO
-
-=item AUTHOR AND COPYRIGHT
-
-=over 4
-
-=item Acknowledgments
-
-=back
-
-=back
-
-=head2 perlretut - Perl regular expressions tutorial
-
-=over 4
-
-=item DESCRIPTION
-
-=item Part 1: The basics
-
-=over 4
-
-=item Simple word matching
-
-=item Using character classes
-
-=item Matching this or that
-
-=item Grouping things and hierarchical matching
-
-=item Extracting matches
-
-=item Backreferences
-
-=item Relative backreferences
-
-=item Named backreferences
-
-=item Alternative capture group numbering
-
-=item Position information
-
-=item Non-capturing groupings
-
-=item Matching repetitions
-
-=item Possessive quantifiers
-
-=item Building a regexp
-
-=item Using regular expressions in Perl
-
-=back
-
-=item Part 2: Power tools
-
-=over 4
-
-=item More on characters, strings, and character classes
-
-=item Compiling and saving regular expressions
-
-=item Composing regular expressions at runtime
-
-=item Embedding comments and modifiers in a regular expression
-
-=item Looking ahead and looking behind
-
-=item Using independent subexpressions to prevent backtracking
-
-=item Conditional expressions
-
-=item Defining named patterns
-
-=item Recursive patterns
-
-=item A bit of magic: executing Perl code in a regular expression
-
-=item Backtracking control verbs
-
-=item Pragmas and debugging
-
-=back
-
-=item BUGS
-
-=item SEE ALSO
-
-=item AUTHOR AND COPYRIGHT
-
-=over 4
-
-=item Acknowledgments
-
-=back
-
-=back
-
-=head2 perlboot - Beginner's Object-Oriented Tutorial
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item If we could talk to the animals...
-
-=item Introducing the method invocation arrow
-
-=item Invoking a barnyard
-
-=item The extra parameter of method invocation
-
-=item Calling a second method to simplify things
-
-=item Inheriting the windpipes
-
-=item A few notes about @ISA
-
-=item Overriding the methods
-
-=item Starting the search from a different place
-
-=item The SUPER way of doing things
-
-=item Let's review...
-
-=item A horse is a horse, of course of course -- or is it?
-
-=item Invoking an instance method
-
-=item Accessing the instance data
-
-=item How to build a horse
-
-=item Inheriting the constructor
-
-=item Making a method work with either classes or instances
-
-=item Adding parameters to a method
-
-=item More interesting instances
-
-=item A horse of a different color
-
-=item Summary
-
-=back
-
-=item SEE ALSO
-
-=item COPYRIGHT
-
-=back
-
-=head2 perltoot - Tom's object-oriented tutorial for perl
-
-=over 4
-
-=item DESCRIPTION
-
-=item Creating a Class
-
-=over 4
-
-=item Object Representation
-
-=item Class Interface
-
-=item Constructors and Instance Methods
-
-=item Planning for the Future: Better Constructors
-
-=item Destructors
-
-=item Other Object Methods
-
-=back
-
-=item Class Data
-
-=over 4
-
-=item Accessing Class Data
-
-=item Debugging Methods
-
-=item Class Destructors
-
-=item Documenting the Interface
-
-=back
-
-=item Aggregation
-
-=item Inheritance
-
-=over 4
-
-=item Overridden Methods
-
-=item Multiple Inheritance
-
-=item UNIVERSAL: The Root of All Objects
-
-=item Deeper UNIVERSAL details
-
-=back
-
-=item Alternate Object Representations
-
-=over 4
-
-=item Arrays as Objects
-
-=item Closures as Objects
-
-=back
-
-=item AUTOLOAD: Proxy Methods
-
-=over 4
-
-=item Autoloaded Data Methods
-
-=item Inherited Autoloaded Data Methods
-
-=back
-
-=item Metaclassical Tools
-
-=over 4
-
-=item Class::Struct
-
-=item Data Members as Variables
-
-=back
-
-=item NOTES
-
-=over 4
-
-=item Object Terminology
-
-=back
-
-=item SEE ALSO
-
-=item AUTHOR AND COPYRIGHT
-
-=item COPYRIGHT
-
-=over 4
-
-=item Acknowledgments
-
-=back
-
-=back
-
-=head2 perltooc - Tom's OO Tutorial for Class Data in Perl
-
-=over 4
-
-=item DESCRIPTION
-
-=item Class Data in a Can
-
-=item Class Data as Package Variables
-
-=over 4
-
-=item Putting All Your Eggs in One Basket
-
-=item Inheritance Concerns
-
-=item The Eponymous Meta-Object
-
-=item Indirect References to Class Data
-
-=item Monadic Classes
-
-=item Translucent Attributes
-
-=back
-
-=item Class Data as Lexical Variables
-
-=over 4
-
-=item Privacy and Responsibility
-
-=item File-Scoped Lexicals
-
-=item More Inheritance Concerns
-
-=item Locking the Door and Throwing Away the Key
-
-=item Translucency Revisited
-
-=back
-
-=item NOTES
-
-=item SEE ALSO
-
-=item AUTHOR AND COPYRIGHT
-
-=item ACKNOWLEDGEMENTS
-
-=item HISTORY
-
-=back
-
-=head2 perlbot - Bag'o Object Tricks (the BOT)
-
-=over 4
-
-=item DESCRIPTION
-
-=item OO SCALING TIPS
-
-=item INSTANCE VARIABLES
-
-=item SCALAR INSTANCE VARIABLES
-
-=item INSTANCE VARIABLE INHERITANCE
-
-=item OBJECT RELATIONSHIPS
-
-=item OVERRIDING SUPERCLASS METHODS
-
-=item USING RELATIONSHIP WITH SDBM
-
-=item THINKING OF CODE REUSE
-
-=item CLASS CONTEXT AND THE OBJECT
-
-=item INHERITING A CONSTRUCTOR
-
-=item DELEGATION
-
-=item SEE ALSO
-
-=back
-
-=head2 perlperf - Perl Performance and Optimization Techniques
-
-=over 4
-
-=item DESCRIPTION
-
-=item OVERVIEW
-
-=over 4
-
-=item ONE STEP SIDEWAYS
-
-=item ONE STEP FORWARD
-
-=item ANOTHER STEP SIDEWAYS
-
-=back
-
-=item GENERAL GUIDELINES
-
-=item BENCHMARKS
-
-=over 4
-
-=item Assigning and Dereferencing Variables.
-
-=item Search and replace or tr
-
-=back
-
-=item PROFILING TOOLS
-
-=over 4
-
-=item Devel::DProf
-
-=item Devel::Profiler
-
-=item Devel::SmallProf
-
-=item Devel::FastProf
-
-=item Devel::NYTProf
-
-=back
-
-=item SORTING
-
-Elapsed Real Time, User CPU Time, System CPU Time
-
-=item LOGGING
-
-=over 4
-
-=item Logging if DEBUG (constant)
-
-=back
-
-=item POSTSCRIPT
-
-=item SEE ALSO
-
-=over 4
-
-=item PERLDOCS
-
-=item MAN PAGES
-
-=item MODULES
-
-=item URLS
-
-=back
-
-=item AUTHOR
-
-=back
-
-=head2 perlstyle - Perl style guide
-
-=over 4
-
-=item DESCRIPTION
-
-=back
-
-=head2 perlcheat - Perl 5 Cheat Sheet
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item The sheet
-
-=back
-
-=item ACKNOWLEDGEMENTS
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 perltrap - Perl traps for the unwary
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Awk Traps
-
-=item C/C++ Traps
-
-=item Sed Traps
-
-=item Shell Traps
-
-=item Perl Traps
-
-=item Perl4 to Perl5 Traps
-
-Discontinuance, Deprecation, and BugFix traps, Parsing Traps, Numerical
-Traps, General data type traps, Context Traps - scalar, list contexts,
-Precedence Traps, General Regular Expression Traps using s///, etc,
-Subroutine, Signal, Sorting Traps, OS Traps, DBM Traps, Unclassified Traps
-
-=item Discontinuance, Deprecation, and BugFix traps
-
-Symbols starting with "_" no longer forced into main, Double-colon valid
-package separator in variable name, 2nd and 3rd args to C<splice()> are now
-in scalar context, Can't do C<goto> into a block that is optimized away,
-Can't use whitespace as variable name or quote delimiter, C<while/if BLOCK
-BLOCK> gone, C<**> binds tighter than unary minus, C<foreach> changed when
-iterating over a list, C<split> with no args behavior changed, B<-e>
-behavior fixed, C<push> returns number of elements in resulting list, Some
-error messages differ, C<split()> honors subroutine args, Bugs removed
-
-=item Parsing Traps
-
-Space between . and = triggers syntax error, Better parsing in perl 5,
-Function parsing, String interpolation of C<$#array> differs, Perl guesses
-on C<map>, C<grep> followed by C<{> if it starts BLOCK or hash ref
-
-=item Numerical Traps
-
-Formatted output and significant digits, Auto-increment operator over
-signed int limit deleted, Assignment of return values from numeric equality
-tests doesn't work, Bitwise string ops
-
-=item General data type traps
-
-Negative array subscripts now count from the end of array, Setting
-C<$#array> lower now discards array elements, Hashes get defined before
-use, Glob assignment from localized variable to variable, Assigning
-C<undef> to glob, Changes in unary negation (of strings), Modifying of
-constants prohibited, C<defined $var> behavior changed, Variable Suicide
-
-=item Context Traps - scalar, list contexts
-
-Elements of argument lists for formats evaluated in list context,
-C<caller()> returns false value in scalar context if no caller present,
-Comma operator in scalar context gives scalar context to args, C<sprintf()>
-prototyped as C<($;@)>
-
-=item Precedence Traps
-
-LHS vs. RHS of any assignment operator, Semantic errors introduced due to
-precedence, Precedence of assignment operators same as the precedence of
-assignment, C<open> requires parentheses around filehandle, C<$:>
-precedence over C<$::> gone, Precedence of file test operators documented,
-C<keys>, C<each>, C<values> are regular named unary operators
-
-=item General Regular Expression Traps using s///, etc.
-
-C<s'$lhs'$rhs'> interpolates on either side, C<m//g> attaches its state to
-the searched string, C<m//o> used within an anonymous sub, C<$+> isn't set
-to whole match, Substitution now returns null string if it fails,
-C<s`lhs`rhs`> is now a normal substitution, Stricter parsing of variables
-in regular expressions, C<m?x?> matches only once, Failed matches don't
-reset the match variables
-
-=item Subroutine, Signal, Sorting Traps
-
-Barewords that used to look like strings look like subroutine calls,
-Reverse is no longer allowed as the name of a sort subroutine, C<warn()>
-won't let you specify a filehandle
-
-=item OS Traps
-
-SysV resets signal handler correctly, SysV C<seek()> appends correctly
-
-=item Interpolation Traps
-
-C<@> always interpolates an array in double-quotish strings, Double-quoted
-strings may no longer end with an unescaped $, Arbitrary expressions are
-evaluated inside braces within double quotes, C<$$x> now tries to
-dereference $x, Creation of hashes on the fly with C<eval "EXPR"> requires
-protection, Bugs in earlier perl versions, Array and hash brackets during
-interpolation, Interpolation of C<\$$foo{bar}>, C<qq()> string passed to
-C<eval> will not find string terminator
-
-=item DBM Traps
-
-Perl5 must have been linked with same dbm/ndbm as the default for
-C<dbmopen()>, DBM exceeding limit on the key/value size will cause perl5 to
-exit immediately
-
-=item Unclassified Traps
-
-C<require>/C<do> trap using returned value, C<split> on empty string with
-LIMIT specified
-
-=back
-
-=back
-
-=head2 perldebtut - Perl debugging tutorial
-
-=over 4
-
-=item DESCRIPTION
-
-=item use strict
-
-=item Looking at data and -w and v
-
-=item help
-
-=item Stepping through code
-
-=item Placeholder for a, w, t, T
-
-=item REGULAR EXPRESSIONS
-
-=item OUTPUT TIPS
-
-=item CGI
-
-=item GUIs
-
-=item SUMMARY
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item CONTRIBUTORS
-
-=back
-
-=head2 perlfaq - frequently asked questions about Perl
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Where to get the perlfaq
-
-=item How to contribute to the perlfaq
-
-=item What will happen if you mail your Perl programming problems to the
-authors?
-
-=back
-
-=item CREDITS
-
-=item AUTHOR AND COPYRIGHT
-
-=item Table of Contents
-
-perlfaq - this document, perlfaq1 - General Questions About Perl, perlfaq2
-- Obtaining and Learning about Perl, perlfaq3 - Programming Tools, perlfaq4
-- Data Manipulation, perlfaq5 - Files and Formats, perlfaq6 - Regular
-Expressions, perlfaq7 - General Perl Language Issues, perlfaq8 - System
-Interaction, perlfaq9 - Networking
-
-=item The Questions
-
-=over 4
-
-=item L<perlfaq1>: General Questions About Perl
-
-=item L<perlfaq2>: Obtaining and Learning about Perl
-
-=item L<perlfaq3>: Programming Tools
-
-=item L<perlfaq4>: Data Manipulation
-
-=item L<perlfaq5>: Files and Formats
-
-=item L<perlfaq6>: Regular Expressions
-
-=item L<perlfaq7>: General Perl Language Issues
-
-=item L<perlfaq8>: System Interaction
-
-=item L<perlfaq9>: Networking
-
-=back
-
-=back
-
-=head2 perlfaq1 - General Questions About Perl
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item What is Perl?
-
-=item Who supports Perl? Who develops it? Why is it free?
-
-=item Which version of Perl should I use?
-
-=item What are Perl 4, Perl 5, or Perl 6?
-
-=item What was Ponie?
-
-=item What is Perl 6?
-
-=item How stable is Perl?
-
-=item Is Perl difficult to learn?
-
-=item How does Perl compare with other languages like Java, Python, REXX,
-Scheme, or Tcl?
-
-=item Can I do [task] in Perl?
-
-=item When shouldn't I program in Perl?
-
-=item What's the difference between "perl" and "Perl"?
-
-=item Is it a Perl program or a Perl script?
-
-=item What is a JAPH?
-
-=item Where can I get a list of Larry Wall witticisms?
-
-=item How can I convince others to use Perl?
-
-http://perltraining.com.au/whyperl.html,
-http://www.perl.org/advocacy/whyperl.html
-
-=back
-
-=item REVISION
-
-=item AUTHOR AND COPYRIGHT
-
-=back
-
-=head2 perlfaq2 - Obtaining and Learning about Perl
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item What machines support perl? Where do I get it?
-
-=item How can I get a binary version of perl?
-
-=item I don't have a C compiler. How can I build my own Perl interpreter?
-
-=item I copied the perl binary from one machine to another, but scripts
-don't work.
-
-=item I grabbed the sources and tried to compile but gdbm/dynamic
-loading/malloc/linking/... failed. How do I make it work?
-
-=item What modules and extensions are available for Perl? What is CPAN?
-What does CPAN/src/... mean?
-
-=item Is there an ISO or ANSI certified version of Perl?
-
-=item Where can I get information on Perl?
-
-=item What are the Perl newsgroups on Usenet? Where do I post questions?
-
-=item Where should I post source code?
-
-=item Perl Books
-
-References, Tutorials, Task-Oriented, Special Topics
-
-=item Which magazines have Perl content?
-
-=item What mailing lists are there for Perl?
-
-=item Where are the archives for comp.lang.perl.misc?
-
-=item Where can I buy a commercial version of perl?
-
-=item Where do I send bug reports?
-
-=item What is perl.com? Perl Mongers? pm.org? perl.org? cpan.org?
-
-=back
-
-=item REVISION
-
-=item AUTHOR AND COPYRIGHT
-
-=back
-
-=head2 perlfaq3 - Programming Tools
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item How do I do (anything)?
-
-=item How can I use Perl interactively?
-
-=item Is there a Perl shell?
-
-=item How do I find which modules are installed on my system?
-
-=item How do I debug my Perl programs?
-
-=item How do I profile my Perl programs?
-
-=item How do I cross-reference my Perl programs?
-
-=item Is there a pretty-printer (formatter) for Perl?
-
-=item Is there a ctags for Perl?
-
-=item Is there an IDE or Windows Perl Editor?
-
-Eclipse, Enginsite, Komodo, Open Perl IDE, OptiPerl, PerlBuilder,
-visiPerl+, Visual Perl, Zeus, GNU Emacs, MicroEMACS, XEmacs, Jed, Elvis,
-Vile, Vim, Codewright, MultiEdit, SlickEdit, Bash, Ksh, Tcsh, Zsh, Affrus,
-Alpha, BBEdit and BBEdit Lite
-
-=item Where can I get Perl macros for vi?
-
-=item Where can I get perl-mode for emacs?
-
-=item How can I use curses with Perl?
-
-=item How can I write a GUI (X, Tk, Gtk, etc.) in Perl?
-X<GUI> X<Tk> X<Wx> X<WxWidgets> X<Gtk> X<Gtk2> X<CamelBones> X<Qt>
-
-Tk, Wx, Gtk and Gtk2, Win32::GUI, CamelBones, Qt, Athena
-
-=item How can I make my Perl program run faster?
-
-=item How can I make my Perl program take less memory?
-
-Don't slurp!, Use map and grep selectively, Avoid unnecessary quotes and
-stringification, Pass by reference, Tie large variables to disk
-
-=item Is it safe to return a reference to local or lexical data?
-
-=item How can I free an array or hash so my program shrinks?
-
-=item How can I make my CGI script more efficient?
-
-=item How can I hide the source for my Perl program?
-
-=item How can I compile my Perl program into byte code or C?
-
-=item How can I get C<#!perl> to work on [MS-DOS,NT,...]?
-
-=item Can I write useful Perl programs on the command line?
-
-=item Why don't Perl one-liners work on my DOS/Mac/VMS system?
-
-=item Where can I learn about CGI or Web programming in Perl?
-
-=item Where can I learn about object-oriented Perl programming?
-
-=item Where can I learn about linking C with Perl?
-
-=item I've read perlembed, perlguts, etc., but I can't embed perl in my C
-program; what am I doing wrong?
-
-=item When I tried to run my script, I got this message. What does it mean?
-
-=item What's MakeMaker?
-
-=back
-
-=item REVISION
-
-=item AUTHOR AND COPYRIGHT
-
-=back
-
-=head2 perlfaq4 - Data Manipulation
-
-=over 4
-
-=item DESCRIPTION
-
-=item Data: Numbers
-
-=over 4
-
-=item Why am I getting long decimals (eg, 19.9499999999999) instead of the
-numbers I should be getting (eg, 19.95)?
-
-=item Why is int() broken?
-
-=item Why isn't my octal data interpreted correctly?
-
-=item Does Perl have a round() function? What about ceil() and floor()?
-Trig functions?
-
-=item How do I convert between numeric representations/bases/radixes?
-
-How do I convert hexadecimal into decimal, How do I convert from decimal to
-hexadecimal, How do I convert from octal to decimal, How do I convert from
-decimal to octal, How do I convert from binary to decimal, How do I convert
-from decimal to binary
-
-=item Why doesn't & work the way I want it to?
-
-=item How do I multiply matrices?
-
-=item How do I perform an operation on a series of integers?
-
-=item How can I output Roman numerals?
-
-=item Why aren't my random numbers random?
-
-=item How do I get a random number between X and Y?
-
-=back
-
-=item Data: Dates
-
-=over 4
-
-=item How do I find the day or week of the year?
-
-=item How do I find the current century or millennium?
-
-=item How can I compare two dates and find the difference?
-
-=item How can I take a string and turn it into epoch seconds?
-
-=item How can I find the Julian Day?
-
-=item How do I find yesterday's date?
-
-=item Does Perl have a Year 2000 problem? Is Perl Y2K compliant?
-
-=item Does Perl have a Year 2038 problem?
-
-=back
-
-=item Data: Strings
-
-=over 4
-
-=item How do I validate input?
-
-=item How do I unescape a string?
-
-=item How do I remove consecutive pairs of characters?
-
-=item How do I expand function calls in a string?
-
-=item How do I find matching/nesting anything?
-
-=item How do I reverse a string?
-
-=item How do I expand tabs in a string?
-
-=item How do I reformat a paragraph?
-
-=item How can I access or change N characters of a string?
-
-=item How do I change the Nth occurrence of something?
-
-=item How can I count the number of occurrences of a substring within a
-string?
-
-=item How do I capitalize all the words on one line?
-
-=item How can I split a [character] delimited string except when inside
-[character]?
-
-=item How do I strip blank space from the beginning/end of a string?
-
-=item How do I pad a string with blanks or pad a number with zeroes?
-
-=item How do I extract selected columns from a string?
-
-=item How do I find the soundex value of a string?
-
-=item How can I expand variables in text strings?
-
-=item What's wrong with always quoting "$vars"?
-
-=item Why don't my E<lt>E<lt>HERE documents work?
-
-There must be no space after the E<lt>E<lt> part, There (probably) should
-be a semicolon at the end, You can't (easily) have any space in front of
-the tag
-
-=back
-
-=item Data: Arrays
-
-=over 4
-
-=item What is the difference between a list and an array?
-
-=item What is the difference between $array[1] and @array[1]?
-
-=item How can I remove duplicate elements from a list or array?
-
-=item How can I tell whether a certain element is contained in a list or
-array?
-
-=item How do I compute the difference of two arrays? How do I compute the
-intersection of two arrays?
-
-=item How do I test whether two arrays or hashes are equal?
-
-=item How do I find the first array element for which a condition is true?
-
-=item How do I handle linked lists?
-
-=item How do I handle circular lists?
-
-=item How do I shuffle an array randomly?
-
-=item How do I process/modify each element of an array?
-
-=item How do I select a random element from an array?
-
-=item How do I permute N elements of a list?
-X<List::Permuter> X<permute> X<Algorithm::Loops> X<Knuth>
-X<The Art of Computer Programming> X<Fischer-Krause>
-
-=item How do I sort an array by (anything)?
-
-=item How do I manipulate arrays of bits?
-
-=item Why does defined() return true on empty arrays and hashes?
-
-=back
-
-=item Data: Hashes (Associative Arrays)
-
-=over 4
-
-=item How do I process an entire hash?
-
-=item What happens if I add or remove keys from a hash while iterating over
-it?
-
-=item How do I look up a hash element by value?
-
-=item How can I know how many entries are in a hash?
-
-=item How do I sort a hash (optionally by value instead of key)?
-
-=item How can I always keep my hash sorted?
-X<hash tie sort DB_File Tie::IxHash>
-
-=item What's the difference between "delete" and "undef" with hashes?
-
-=item Why don't my tied hashes make the defined/exists distinction?
-
-=item How do I reset an each() operation part-way through?
-
-=item How can I get the unique keys from two hashes?
-
-=item How can I store a multidimensional array in a DBM file?
-
-=item How can I make my hash remember the order I put elements into it?
-
-=item Why does passing a subroutine an undefined element in a hash create
-it?
-
-=item How can I make the Perl equivalent of a C structure/C++ class/hash or
-array of hashes or arrays?
-
-=item How can I use a reference as a hash key?
-
-=back
-
-=item Data: Misc
-
-=over 4
-
-=item How do I handle binary data correctly?
-
-=item How do I determine whether a scalar is a number/whole/integer/float?
-
-=item How do I keep persistent data across program calls?
-
-=item How do I print out or copy a recursive data structure?
-
-=item How do I define methods for every class/object?
-
-=item How do I verify a credit card checksum?
-
-=item How do I pack arrays of doubles or floats for XS code?
-
-=back
-
-=item REVISION
-
-=item AUTHOR AND COPYRIGHT
-
-=back
-
-=head2 perlfaq5 - Files and Formats
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item How do I flush/unbuffer an output filehandle? Why must I do this?
-X<flush> X<buffer> X<unbuffer> X<autoflush>
-
-=item How do I change, delete, or insert a line in a file, or append to the
-beginning of a file?
-X<file, editing>
-
-=item How do I count the number of lines in a file?
-X<file, counting lines> X<lines> X<line>
-
-=item How can I use Perl's C<-i> option from within a program?
-X<-i> X<in-place>
-
-=item How can I copy a file?
-X<copy> X<file, copy>
-
-=item How do I make a temporary file name?
-X<file, temporary>
-
-=item How can I manipulate fixed-record-length files?
-X<fixed-length> X<file, fixed-length records>
-
-=item How can I make a filehandle local to a subroutine? How do I pass
-filehandles between subroutines? How do I make an array of filehandles?
-X<filehandle, local> X<filehandle, passing> X<filehandle, reference>
-
-=item How can I use a filehandle indirectly?
-X<filehandle, indirect>
-
-=item How can I set up a footer format to be used with write()?
-X<footer>
-
-=item How can I write() into a string?
-X<write, into a string>
-
-=item How can I open a filehandle to a string?
-X<string>, X<open>, X<IO::Scalar>, X<filehandle>
-
-=item How can I output my numbers with commas added?
-X<number, commify>
-
-=item How can I translate tildes (~) in a filename?
-X<tilde> X<tilde expansion>
-
-=item How come when I open a file read-write it wipes it out?
-X<clobber> X<read-write> X<clobbering> X<truncate> X<truncating>
-
-=item Why do I sometimes get an "Argument list too long" when I use
-E<lt>*E<gt>?
-X<argument list too long>
-
-=item Is there a leak/bug in glob()?
-X<glob>
-
-=item How can I open a file with a leading ">" or trailing blanks?
-X<filename, special characters>
-
-=item How can I reliably rename a file?
-X<rename> X<mv> X<move> X<file, rename> X<ren>
-
-=item How can I lock a file?
-X<lock> X<file, lock> X<flock>
-
-=item Why can't I just open(FH, "E<gt>file.lock")?
-X<lock, lockfile race condition>
-
-=item I still don't get locking. I just want to increment the number in
-the file. How can I do this?
-X<counter> X<file, counter>
-
-=item All I want to do is append a small amount of text to the end of a
-file. Do I still have to use locking?
-X<append> X<file, append>
-
-=item How do I randomly update a binary file?
-X<file, binary patch>
-
-=item How do I get a file's timestamp in perl?
-X<timestamp> X<file, timestamp>
-
-=item How do I set a file's timestamp in perl?
-X<timestamp> X<file, timestamp>
-
-=item How do I print to more than one file at once?
-X<print, to multiple files>
-
-=item How can I read in an entire file all at once?
-X<slurp> X<file, slurping>
-
-=item How can I read in a file by paragraphs?
-X<file, reading by paragraphs>
-
-=item How can I read a single character from a file? From the keyboard?
-X<getc> X<file, reading one character at a time>
-
-=item How can I tell whether there's a character waiting on a filehandle?
-
-=item How do I do a C<tail -f> in perl?
-X<tail> X<IO::Handle> X<File::Tail> X<clearerr>
-
-=item How do I dup() a filehandle in Perl?
-X<dup>
-
-=item How do I close a file descriptor by number?
-X<file, closing file descriptors> X<POSIX> X<close>
-
-=item Why can't I use "C:\temp\foo" in DOS paths? Why doesn't
-`C:\temp\foo.exe` work?
-X<filename, DOS issues>
-
-=item Why doesn't glob("*.*") get all the files?
-X<glob>
-
-=item Why does Perl let me delete read-only files? Why does C<-i> clobber
-protected files? Isn't this a bug in Perl?
-
-=item How do I select a random line from a file?
-X<file, selecting a random line>
-
-=item Why do I get weird spaces when I print an array of lines?
-
-=back
-
-=item REVISION
-
-=item AUTHOR AND COPYRIGHT
-
-=back
-
-=head2 perlfaq6 - Regular Expressions
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item How can I hope to use regular expressions without creating illegible
-and unmaintainable code?
-X<regex, legibility> X<regexp, legibility>
-X<regular expression, legibility> X</x>
-
-Comments Outside the Regex, Comments Inside the Regex, Different Delimiters
-
-=item I'm having trouble matching over more than one line. What's wrong?
-X<regex, multiline> X<regexp, multiline> X<regular expression, multiline>
-
-=item How can I pull out lines between two patterns that are themselves on
-different lines?
-X<..>
-
-=item I put a regular expression into $/ but it didn't work. What's wrong?
-X<$/, regexes in> X<$INPUT_RECORD_SEPARATOR, regexes in>
-X<$RS, regexes in>
-
-=item How do I substitute case insensitively on the LHS while preserving
-case on the RHS?
-X<replace, case preserving> X<substitute, case preserving>
-X<substitution, case preserving> X<s, case preserving>
-
-=item How can I make C<\w> match national character sets?
-X<\w>
-
-=item How can I match a locale-smart version of C</[a-zA-Z]/>?
-X<alpha>
-
-=item How can I quote a variable to use in a regex?
-X<regex, escaping> X<regexp, escaping> X<regular expression, escaping>
-
-=item What is C</o> really for?
-X</o, regular expressions> X<compile, regular expressions>
-
-=item How do I use a regular expression to strip C style comments from a
-file?
-
-=item Can I use Perl regular expressions to match balanced text?
-X<regex, matching balanced test> X<regexp, matching balanced test>
-X<regular expression, matching balanced test>
-
-=item What does it mean that regexes are greedy? How can I get around it?
-X<greedy> X<greediness>
-
-=item How do I process each word on each line?
-X<word>
-
-=item How can I print out a word-frequency or line-frequency summary?
-
-=item How can I do approximate matching?
-X<match, approximate> X<matching, approximate>
-
-=item How do I efficiently match many regular expressions at once?
-X<regex, efficiency> X<regexp, efficiency>
-X<regular expression, efficiency>
-
-=item Why don't word-boundary searches with C<\b> work for me?
-X<\b>
-
-=item Why does using $&, $`, or $' slow my program down?
-X<$MATCH> X<$&> X<$POSTMATCH> X<$'> X<$PREMATCH> X<$`>
-
-=item What good is C<\G> in a regular expression?
-X<\G>
-
-=item Are Perl regexes DFAs or NFAs? Are they POSIX compliant?
-X<DFA> X<NFA> X<POSIX>
-
-=item What's wrong with using grep in a void context?
-X<grep>
-
-=item How can I match strings with multibyte characters?
-X<regex, and multibyte characters> X<regexp, and multibyte characters>
-X<regular expression, and multibyte characters> X<martian> X<encoding,
-Martian>
-
-=item How do I match a regular expression that's in a variable?
-X<regex, in variable> X<eval> X<regex> X<quotemeta> X<\Q, regex>
-X<\E, regex>, X<qr//>
-
-=back
-
-=item REVISION
-
-=item AUTHOR AND COPYRIGHT
-
-=back
-
-=head2 perlfaq7 - General Perl Language Issues
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Can I get a BNF/yacc/RE for the Perl language?
-
-=item What are all these $@%&* punctuation signs, and how do I know when to
-use them?
-
-=item Do I always/never have to quote my strings or use semicolons and
-commas?
-
-=item How do I skip some return values?
-
-=item How do I temporarily block warnings?
-
-=item What's an extension?
-
-=item Why do Perl operators have different precedence than C operators?
-
-=item How do I declare/create a structure?
-
-=item How do I create a module?
-
-=item How do I adopt or take over a module already on CPAN?
-
-=item How do I create a class?
-
-=item How can I tell if a variable is tainted?
-
-=item What's a closure?
-
-=item What is variable suicide and how can I prevent it?
-
-=item How can I pass/return a {Function, FileHandle, Array, Hash, Method,
-Regex}?
-
-Passing Variables and Functions, Passing Filehandles, Passing Regexes,
-Passing Methods
-
-=item How do I create a static variable?
-
-=item What's the difference between dynamic and lexical (static) scoping?
-Between local() and my()?
-
-=item How can I access a dynamic variable while a similarly named lexical
-is in scope?
-
-=item What's the difference between deep and shallow binding?
-
-=item Why doesn't "my($foo) = E<lt>FILEE<gt>;" work right?
-
-=item How do I redefine a builtin function, operator, or method?
-
-=item What's the difference between calling a function as &foo and foo()?
-
-=item How do I create a switch or case statement?
-
-=item How can I catch accesses to undefined variables, functions, or
-methods?
-
-=item Why can't a method included in this same file be found?
-
-=item How can I find out my current package?
-
-=item How can I comment out a large block of perl code?
-
-=item How do I clear a package?
-
-=item How can I use a variable as a variable name?
-
-=item What does "bad interpreter" mean?
-
-=back
-
-=item REVISION
-
-=item AUTHOR AND COPYRIGHT
-
-=back
-
-=head2 perlfaq8 - System Interaction
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item How do I find out which operating system I'm running under?
-
-=item How come exec() doesn't return?
-
-=item How do I do fancy stuff with the keyboard/screen/mouse?
-
-Keyboard, Screen, Mouse
-
-=item How do I print something out in color?
-
-=item How do I read just one key without waiting for a return key?
-
-=item How do I check whether input is ready on the keyboard?
-
-=item How do I clear the screen?
-
-=item How do I get the screen size?
-
-=item How do I ask the user for a password?
-
-=item How do I read and write the serial port?
-
-lockfiles, open mode, end of line, flushing output, non-blocking input
-
-=item How do I decode encrypted password files?
-
-=item How do I start a process in the background?
-
-STDIN, STDOUT, and STDERR are shared, Signals, Zombies
-
-=item How do I trap control characters/signals?
-
-=item How do I modify the shadow password file on a Unix system?
-
-=item How do I set the time and date?
-
-=item How can I sleep() or alarm() for under a second?
-X<Time::HiRes> X<BSD::Itimer> X<sleep> X<select>
-
-=item How can I measure time under a second?
-X<Time::HiRes> X<BSD::Itimer> X<sleep> X<select>
-
-=item How can I do an atexit() or setjmp()/longjmp()? (Exception handling)
-
-=item Why doesn't my sockets program work under System V (Solaris)? What
-does the error message "Protocol not supported" mean?
-
-=item How can I call my system's unique C functions from Perl?
-
-=item Where do I get the include files to do ioctl() or syscall()?
-
-=item Why do setuid perl scripts complain about kernel problems?
-
-=item How can I open a pipe both to and from a command?
-
-=item Why can't I get the output of a command with system()?
-
-=item How can I capture STDERR from an external command?
-
-=item Why doesn't open() return an error when a pipe open fails?
-
-=item What's wrong with using backticks in a void context?
-
-=item How can I call backticks without shell processing?
-
-=item Why can't my script read from STDIN after I gave it EOF (^D on Unix,
-^Z on MS-DOS)?
-
-=item How can I convert my shell script to perl?
-
-=item Can I use perl to run a telnet or ftp session?
-
-=item How can I write expect in Perl?
-
-=item Is there a way to hide perl's command line from programs such as
-"ps"?
-
-=item I {changed directory, modified my environment} in a perl script. How
-come the change disappeared when I exited the script? How do I get my
-changes to be visible?
-
-Unix
-
-=item How do I close a process's filehandle without waiting for it to
-complete?
-
-=item How do I fork a daemon process?
-
-=item How do I find out if I'm running interactively or not?
-
-=item How do I timeout a slow event?
-
-=item How do I set CPU limits?
-X<BSD::Resource> X<limit> X<CPU>
-
-=item How do I avoid zombies on a Unix system?
-
-=item How do I use an SQL database?
-
-=item How do I make a system() exit on control-C?
-
-=item How do I open a file without blocking?
-
-=item How do I tell the difference between errors from the shell and perl?
-
-=item How do I install a module from CPAN?
-
-=item What's the difference between require and use?
-
-=item How do I keep my own module/library directory?
-
-=item How do I add the directory my program lives in to the module/library
-search path?
-
-=item How do I add a directory to my include path (@INC) at runtime?
-
-the PERLLIB environment variable, the PERL5LIB environment variable, the
-perl -Idir command line flag, the use lib pragma:
-
-=item What is socket.ph and where do I get it?
-
-=back
-
-=item REVISION
-
-=item AUTHOR AND COPYRIGHT
-
-=back
-
-=head2 perlfaq9 - Networking
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item What is the correct form of response from a CGI script?
-
-=item My CGI script runs from the command line but not the browser. (500
-Server Error)
-
-=item How can I get better error messages from a CGI program?
-
-=item How do I remove HTML from a string?
-
-=item How do I extract URLs?
-
-=item How do I download a file from the user's machine? How do I open a
-file on another machine?
-
-=item How do I make an HTML pop-up menu with Perl?
-
-=item How do I fetch an HTML file?
-
-=item How do I automate an HTML form submission?
-
-=item How do I decode or create those %-encodings on the web?
-
-=item How do I redirect to another page?
-
-=item How do I put a password on my web pages?
-
-=item How do I edit my .htpasswd and .htgroup files with Perl?
-
-=item How do I make sure users can't enter values into a form that cause my
-CGI script to do bad things?
-
-=item How do I parse a mail header?
-
-=item How do I decode a CGI form?
-
-=item How do I check a valid mail address?
-
-=item How do I decode a MIME/BASE64 string?
-
-=item How do I return the user's mail address?
-
-=item How do I send mail?
-
-=item How do I use MIME to make an attachment to a mail message?
-
-=item How do I read mail?
-
-=item How do I find out my hostname, domainname, or IP address?
-X<hostname, domainname, IP address, host, domain, hostfqdn, inet_ntoa,
-gethostbyname, Socket, Net::Domain, Sys::Hostname>
-
-=item How do I fetch a news article or the active newsgroups?
-
-=item How do I fetch/put an FTP file?
-
-=item How can I do RPC in Perl?
-
-=back
-
-=item REVISION
-
-=item AUTHOR AND COPYRIGHT
-
-=back
-
-=head2 perlsyn - Perl syntax
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Declarations
-X<declaration> X<undef> X<undefined> X<uninitialized>
-
-=item Comments
-X<comment> X<#>
**** PATCH TRUNCATED AT 2000 LINES -- 36569 NOT SHOWN ****
--
Perl5 Master Repository
<http://perl5.git.perl.org/perl.git/commitdiff/7eb47696deb9a7343fb4847f7342919a6df59e21?hp=da09dfe31dd61a9d5a3c2d9d69e3d674b6c642ac>
- Log -----------------------------------------------------------------
commit 7eb47696deb9a7343fb4847f7342919a6df59e21
Author: Nicholas Clark <***@ccl4.org>
Date: Tue Apr 21 10:49:10 2009 +0100
Build perltoc.pod, rather than shipping it. This way it can't get out of date.
-----------------------------------------------------------------------
Summary of changes:
MANIFEST | 1 -
Makefile.SH | 9 +-
pod.lst | 2 +-
pod/buildtoc | 6 +-
pod/perltoc.pod |38414 ----------------------------------------------
vms/descrip_mms.template | 9 +-
win32/Makefile | 5 +-
win32/makefile.mk | 5 +-
8 files changed, 26 insertions(+), 38425 deletions(-)
delete mode 100644 pod/perltoc.pod
diff --git a/MANIFEST b/MANIFEST
index a4427d8..69084ba 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -3617,7 +3617,6 @@ pod/perlsub.pod Perl subroutines
pod/perlsyn.pod Perl syntax
pod/perlthrtut.pod Perl threads tutorial
pod/perltie.pod Perl objects hidden behind simple variables
-pod/perltoc.pod Perl documentation table of contents
pod/perltodo.pod Perl things to do
pod/perltooc.pod Perl OO tutorial, part 2
pod/perltoot.pod Perl OO tutorial, part 1
diff --git a/Makefile.SH b/Makefile.SH
index 7cb0004..f7ec252 100644
--- a/Makefile.SH
+++ b/Makefile.SH
@@ -454,7 +454,8 @@ mini_obj = $(obj1) $(obj2) $(obj3) $(ARCHOBJS)
ndt_obj = $(obj0) $(obj1) $(obj2) $(obj3) $(ARCHOBJS)
obj = $(ndt_obj) $(DTRACE_O)
-generated_pods = extra.pods pod/perlapi.pod pod/perldelta.pod pod/perlintern.pod
+perltoc_pod_prereqs = extra.pods pod/perlapi.pod pod/perldelta.pod pod/perlintern.pod
+generated_pods = pod/perltoc.pod $(perltoc_pod_prereqs)
lintflags = \
-b \
@@ -971,6 +972,12 @@ uni.data: miniperl$(EXE_EXT) $(CONFIGPM) lib/unicore/mktables
cd lib/unicore && $(LDLIBPTH) $(RUN) ../../miniperl$(EXE_EXT) -I../../lib mktables -w
touch uni.data
+# perl$(EXE_EXT) and ext because buildtoc uses Text::Wrap uses re
+# But also this ensures that all extensions are built before we try to scan
+# them, which picks up Devel::PPPort's documentation.
+pod/perltoc.pod: $(perltoc_pod_prereqs) perl$(EXE_EXT) ext pod/buildtoc
+ $(RUN) ./perl$(EXE_EXT) -Ilib pod/buildtoc --build-toc -q
+
pod/perlapi.pod pod/perlintern.pod: miniperl$(EXE_EXT) autodoc.pl embed.fnc
$(RUN) ./miniperl$(EXE_EXT) -Ilib autodoc.pl
diff --git a/pod.lst b/pod.lst
index 50e5c88..a0c5d90 100644
--- a/pod.lst
+++ b/pod.lst
@@ -11,7 +11,7 @@ h Overview
perl Perl overview (this section)
perlintro Perl introduction for beginners
- perltoc Perl documentation table of contents
+g perltoc Perl documentation table of contents
h Tutorials
diff --git a/pod/buildtoc b/pod/buildtoc
index 50120ea..e80dae0 100644
--- a/pod/buildtoc
+++ b/pod/buildtoc
@@ -699,8 +699,10 @@ sub do_unix {
my $makefile_SH = join '', @_;
die "$0: $name contains NUL bytes" if $makefile_SH =~ /\0/;
- $makefile_SH =~ s{^(generated_pods = extra.pods).*}
- {join ' ', $1, map "pod/$_", sort keys %Generated, keys %Copies}mge;
+ $makefile_SH =~ s{^(perltoc_pod_prereqs = extra.pods).*}
+ {join ' ', $1, map "pod/$_",
+ sort keys %Copies, grep {!/perltoc/} keys %Generated
+ }mge;
# pod/perldelta.pod: pod/perl511delta.pod
# cd pod && $(LNS) perl511delta.pod perldelta.pod
diff --git a/pod/perltoc.pod b/pod/perltoc.pod
deleted file mode 100644
index 209e6f6..0000000
--- a/pod/perltoc.pod
+++ /dev/null
@@ -1,38414 +0,0 @@
-
-# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-# This file is autogenerated by buildtoc from all the other pods.
-# Edit those files and run buildtoc --build-toc to effect changes.
-
-=head1 NAME
-
-perltoc - perl documentation table of contents
-
-=head1 DESCRIPTION
-
-This page provides a brief table of contents for the rest of the Perl
-documentation set. It is meant to be scanned quickly or grepped
-through to locate the proper section you're looking for.
-
-=head1 BASIC DOCUMENTATION
-
-=head2 perl - Practical Extraction and Report Language
-
-=over 4
-
-=item SYNOPSIS
-
-=over 4
-
-=item Overview
-
-=item Tutorials
-
-=item Reference Manual
-
-=item Internals and C Language Interface
-
-=item Miscellaneous
-
-=item Language-Specific
-
-=item Platform-Specific
-
-=back
-
-=item DESCRIPTION
-
-=item AVAILABILITY
-
-=item ENVIRONMENT
-
-=item AUTHOR
-
-=item FILES
-
-=item SEE ALSO
-
-=item DIAGNOSTICS
-
-=item BUGS
-
-=item NOTES
-
-=back
-
-=head2 perlintro -- a brief introduction and overview of Perl
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item What is Perl?
-
-=item Running Perl programs
-
-=item Safety net
-
-=item Basic syntax overview
-
-=item Perl variable types
-
-Scalars, Arrays, Hashes
-
-=item Variable scoping
-
-=item Conditional and looping constructs
-
-if, while, for, foreach
-
-=item Builtin operators and functions
-
-Arithmetic, Numeric comparison, String comparison, Boolean logic,
-Miscellaneous
-
-=item Files and I/O
-
-=item Regular expressions
-
-Simple matching, Simple substitution, More complex regular expressions,
-Parentheses for capturing, Other regexp features
-
-=item Writing subroutines
-
-=item OO Perl
-
-=item Using Perl modules
-
-=back
-
-=item AUTHOR
-
-=back
-
-=head2 perlreftut - Mark's very short tutorial about references
-
-=over 4
-
-=item DESCRIPTION
-
-=item Who Needs Complicated Data Structures?
-
-=item The Solution
-
-=item Syntax
-
-=over 4
-
-=item Making References
-
-=item Using References
-
-=item An Example
-
-=item Arrow Rule
-
-=back
-
-=item Solution
-
-=item The Rest
-
-=item Summary
-
-=item Credits
-
-=over 4
-
-=item Distribution Conditions
-
-=back
-
-=back
-
-=head2 perldsc - Perl Data Structures Cookbook
-
-=over 4
-
-=item DESCRIPTION
-
-arrays of arrays, hashes of arrays, arrays of hashes, hashes of hashes,
-more elaborate constructs
-
-=item REFERENCES
-X<reference> X<dereference> X<dereferencing> X<pointer>
-
-=item COMMON MISTAKES
-
-=item CAVEAT ON PRECEDENCE
-X<dereference, precedence> X<dereferencing, precedence>
-
-=item WHY YOU SHOULD ALWAYS C<use strict>
-
-=item DEBUGGING
-X<data structure, debugging> X<complex data structure, debugging>
-X<AoA, debugging> X<HoA, debugging> X<AoH, debugging> X<HoH, debugging>
-X<array of arrays, debugging> X<hash of arrays, debugging>
-X<array of hashes, debugging> X<hash of hashes, debugging>
-
-=item CODE EXAMPLES
-
-=item ARRAYS OF ARRAYS
-X<array of arrays> X<AoA>
-
-=over 4
-
-=item Declaration of an ARRAY OF ARRAYS
-
-=item Generation of an ARRAY OF ARRAYS
-
-=item Access and Printing of an ARRAY OF ARRAYS
-
-=back
-
-=item HASHES OF ARRAYS
-X<hash of arrays> X<HoA>
-
-=over 4
-
-=item Declaration of a HASH OF ARRAYS
-
-=item Generation of a HASH OF ARRAYS
-
-=item Access and Printing of a HASH OF ARRAYS
-
-=back
-
-=item ARRAYS OF HASHES
-X<array of hashes> X<AoH>
-
-=over 4
-
-=item Declaration of an ARRAY OF HASHES
-
-=item Generation of an ARRAY OF HASHES
-
-=item Access and Printing of an ARRAY OF HASHES
-
-=back
-
-=item HASHES OF HASHES
-X<hash of hashes> X<HoH>
-
-=over 4
-
-=item Declaration of a HASH OF HASHES
-
-=item Generation of a HASH OF HASHES
-
-=item Access and Printing of a HASH OF HASHES
-
-=back
-
-=item MORE ELABORATE RECORDS
-X<record> X<structure> X<struct>
-
-=over 4
-
-=item Declaration of MORE ELABORATE RECORDS
-
-=item Declaration of a HASH OF COMPLEX RECORDS
-
-=item Generation of a HASH OF COMPLEX RECORDS
-
-=back
-
-=item Database Ties
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=back
-
-=head2 perllol - Manipulating Arrays of Arrays in Perl
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Declaration and Access of Arrays of Arrays
-
-=item Growing Your Own
-
-=item Access and Printing
-
-=item Slices
-
-=back
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=back
-
-=head2 perlrequick - Perl regular expressions quick start
-
-=over 4
-
-=item DESCRIPTION
-
-=item The Guide
-
-=over 4
-
-=item Simple word matching
-
-=item Using character classes
-
-=item Matching this or that
-
-=item Grouping things and hierarchical matching
-
-=item Extracting matches
-
-=item Matching repetitions
-
-=item More matching
-
-=item Search and replace
-
-=item The split operator
-
-=back
-
-=item BUGS
-
-=item SEE ALSO
-
-=item AUTHOR AND COPYRIGHT
-
-=over 4
-
-=item Acknowledgments
-
-=back
-
-=back
-
-=head2 perlretut - Perl regular expressions tutorial
-
-=over 4
-
-=item DESCRIPTION
-
-=item Part 1: The basics
-
-=over 4
-
-=item Simple word matching
-
-=item Using character classes
-
-=item Matching this or that
-
-=item Grouping things and hierarchical matching
-
-=item Extracting matches
-
-=item Backreferences
-
-=item Relative backreferences
-
-=item Named backreferences
-
-=item Alternative capture group numbering
-
-=item Position information
-
-=item Non-capturing groupings
-
-=item Matching repetitions
-
-=item Possessive quantifiers
-
-=item Building a regexp
-
-=item Using regular expressions in Perl
-
-=back
-
-=item Part 2: Power tools
-
-=over 4
-
-=item More on characters, strings, and character classes
-
-=item Compiling and saving regular expressions
-
-=item Composing regular expressions at runtime
-
-=item Embedding comments and modifiers in a regular expression
-
-=item Looking ahead and looking behind
-
-=item Using independent subexpressions to prevent backtracking
-
-=item Conditional expressions
-
-=item Defining named patterns
-
-=item Recursive patterns
-
-=item A bit of magic: executing Perl code in a regular expression
-
-=item Backtracking control verbs
-
-=item Pragmas and debugging
-
-=back
-
-=item BUGS
-
-=item SEE ALSO
-
-=item AUTHOR AND COPYRIGHT
-
-=over 4
-
-=item Acknowledgments
-
-=back
-
-=back
-
-=head2 perlboot - Beginner's Object-Oriented Tutorial
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item If we could talk to the animals...
-
-=item Introducing the method invocation arrow
-
-=item Invoking a barnyard
-
-=item The extra parameter of method invocation
-
-=item Calling a second method to simplify things
-
-=item Inheriting the windpipes
-
-=item A few notes about @ISA
-
-=item Overriding the methods
-
-=item Starting the search from a different place
-
-=item The SUPER way of doing things
-
-=item Let's review...
-
-=item A horse is a horse, of course of course -- or is it?
-
-=item Invoking an instance method
-
-=item Accessing the instance data
-
-=item How to build a horse
-
-=item Inheriting the constructor
-
-=item Making a method work with either classes or instances
-
-=item Adding parameters to a method
-
-=item More interesting instances
-
-=item A horse of a different color
-
-=item Summary
-
-=back
-
-=item SEE ALSO
-
-=item COPYRIGHT
-
-=back
-
-=head2 perltoot - Tom's object-oriented tutorial for perl
-
-=over 4
-
-=item DESCRIPTION
-
-=item Creating a Class
-
-=over 4
-
-=item Object Representation
-
-=item Class Interface
-
-=item Constructors and Instance Methods
-
-=item Planning for the Future: Better Constructors
-
-=item Destructors
-
-=item Other Object Methods
-
-=back
-
-=item Class Data
-
-=over 4
-
-=item Accessing Class Data
-
-=item Debugging Methods
-
-=item Class Destructors
-
-=item Documenting the Interface
-
-=back
-
-=item Aggregation
-
-=item Inheritance
-
-=over 4
-
-=item Overridden Methods
-
-=item Multiple Inheritance
-
-=item UNIVERSAL: The Root of All Objects
-
-=item Deeper UNIVERSAL details
-
-=back
-
-=item Alternate Object Representations
-
-=over 4
-
-=item Arrays as Objects
-
-=item Closures as Objects
-
-=back
-
-=item AUTOLOAD: Proxy Methods
-
-=over 4
-
-=item Autoloaded Data Methods
-
-=item Inherited Autoloaded Data Methods
-
-=back
-
-=item Metaclassical Tools
-
-=over 4
-
-=item Class::Struct
-
-=item Data Members as Variables
-
-=back
-
-=item NOTES
-
-=over 4
-
-=item Object Terminology
-
-=back
-
-=item SEE ALSO
-
-=item AUTHOR AND COPYRIGHT
-
-=item COPYRIGHT
-
-=over 4
-
-=item Acknowledgments
-
-=back
-
-=back
-
-=head2 perltooc - Tom's OO Tutorial for Class Data in Perl
-
-=over 4
-
-=item DESCRIPTION
-
-=item Class Data in a Can
-
-=item Class Data as Package Variables
-
-=over 4
-
-=item Putting All Your Eggs in One Basket
-
-=item Inheritance Concerns
-
-=item The Eponymous Meta-Object
-
-=item Indirect References to Class Data
-
-=item Monadic Classes
-
-=item Translucent Attributes
-
-=back
-
-=item Class Data as Lexical Variables
-
-=over 4
-
-=item Privacy and Responsibility
-
-=item File-Scoped Lexicals
-
-=item More Inheritance Concerns
-
-=item Locking the Door and Throwing Away the Key
-
-=item Translucency Revisited
-
-=back
-
-=item NOTES
-
-=item SEE ALSO
-
-=item AUTHOR AND COPYRIGHT
-
-=item ACKNOWLEDGEMENTS
-
-=item HISTORY
-
-=back
-
-=head2 perlbot - Bag'o Object Tricks (the BOT)
-
-=over 4
-
-=item DESCRIPTION
-
-=item OO SCALING TIPS
-
-=item INSTANCE VARIABLES
-
-=item SCALAR INSTANCE VARIABLES
-
-=item INSTANCE VARIABLE INHERITANCE
-
-=item OBJECT RELATIONSHIPS
-
-=item OVERRIDING SUPERCLASS METHODS
-
-=item USING RELATIONSHIP WITH SDBM
-
-=item THINKING OF CODE REUSE
-
-=item CLASS CONTEXT AND THE OBJECT
-
-=item INHERITING A CONSTRUCTOR
-
-=item DELEGATION
-
-=item SEE ALSO
-
-=back
-
-=head2 perlperf - Perl Performance and Optimization Techniques
-
-=over 4
-
-=item DESCRIPTION
-
-=item OVERVIEW
-
-=over 4
-
-=item ONE STEP SIDEWAYS
-
-=item ONE STEP FORWARD
-
-=item ANOTHER STEP SIDEWAYS
-
-=back
-
-=item GENERAL GUIDELINES
-
-=item BENCHMARKS
-
-=over 4
-
-=item Assigning and Dereferencing Variables.
-
-=item Search and replace or tr
-
-=back
-
-=item PROFILING TOOLS
-
-=over 4
-
-=item Devel::DProf
-
-=item Devel::Profiler
-
-=item Devel::SmallProf
-
-=item Devel::FastProf
-
-=item Devel::NYTProf
-
-=back
-
-=item SORTING
-
-Elapsed Real Time, User CPU Time, System CPU Time
-
-=item LOGGING
-
-=over 4
-
-=item Logging if DEBUG (constant)
-
-=back
-
-=item POSTSCRIPT
-
-=item SEE ALSO
-
-=over 4
-
-=item PERLDOCS
-
-=item MAN PAGES
-
-=item MODULES
-
-=item URLS
-
-=back
-
-=item AUTHOR
-
-=back
-
-=head2 perlstyle - Perl style guide
-
-=over 4
-
-=item DESCRIPTION
-
-=back
-
-=head2 perlcheat - Perl 5 Cheat Sheet
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item The sheet
-
-=back
-
-=item ACKNOWLEDGEMENTS
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
-=head2 perltrap - Perl traps for the unwary
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Awk Traps
-
-=item C/C++ Traps
-
-=item Sed Traps
-
-=item Shell Traps
-
-=item Perl Traps
-
-=item Perl4 to Perl5 Traps
-
-Discontinuance, Deprecation, and BugFix traps, Parsing Traps, Numerical
-Traps, General data type traps, Context Traps - scalar, list contexts,
-Precedence Traps, General Regular Expression Traps using s///, etc,
-Subroutine, Signal, Sorting Traps, OS Traps, DBM Traps, Unclassified Traps
-
-=item Discontinuance, Deprecation, and BugFix traps
-
-Symbols starting with "_" no longer forced into main, Double-colon valid
-package separator in variable name, 2nd and 3rd args to C<splice()> are now
-in scalar context, Can't do C<goto> into a block that is optimized away,
-Can't use whitespace as variable name or quote delimiter, C<while/if BLOCK
-BLOCK> gone, C<**> binds tighter than unary minus, C<foreach> changed when
-iterating over a list, C<split> with no args behavior changed, B<-e>
-behavior fixed, C<push> returns number of elements in resulting list, Some
-error messages differ, C<split()> honors subroutine args, Bugs removed
-
-=item Parsing Traps
-
-Space between . and = triggers syntax error, Better parsing in perl 5,
-Function parsing, String interpolation of C<$#array> differs, Perl guesses
-on C<map>, C<grep> followed by C<{> if it starts BLOCK or hash ref
-
-=item Numerical Traps
-
-Formatted output and significant digits, Auto-increment operator over
-signed int limit deleted, Assignment of return values from numeric equality
-tests doesn't work, Bitwise string ops
-
-=item General data type traps
-
-Negative array subscripts now count from the end of array, Setting
-C<$#array> lower now discards array elements, Hashes get defined before
-use, Glob assignment from localized variable to variable, Assigning
-C<undef> to glob, Changes in unary negation (of strings), Modifying of
-constants prohibited, C<defined $var> behavior changed, Variable Suicide
-
-=item Context Traps - scalar, list contexts
-
-Elements of argument lists for formats evaluated in list context,
-C<caller()> returns false value in scalar context if no caller present,
-Comma operator in scalar context gives scalar context to args, C<sprintf()>
-prototyped as C<($;@)>
-
-=item Precedence Traps
-
-LHS vs. RHS of any assignment operator, Semantic errors introduced due to
-precedence, Precedence of assignment operators same as the precedence of
-assignment, C<open> requires parentheses around filehandle, C<$:>
-precedence over C<$::> gone, Precedence of file test operators documented,
-C<keys>, C<each>, C<values> are regular named unary operators
-
-=item General Regular Expression Traps using s///, etc.
-
-C<s'$lhs'$rhs'> interpolates on either side, C<m//g> attaches its state to
-the searched string, C<m//o> used within an anonymous sub, C<$+> isn't set
-to whole match, Substitution now returns null string if it fails,
-C<s`lhs`rhs`> is now a normal substitution, Stricter parsing of variables
-in regular expressions, C<m?x?> matches only once, Failed matches don't
-reset the match variables
-
-=item Subroutine, Signal, Sorting Traps
-
-Barewords that used to look like strings look like subroutine calls,
-Reverse is no longer allowed as the name of a sort subroutine, C<warn()>
-won't let you specify a filehandle
-
-=item OS Traps
-
-SysV resets signal handler correctly, SysV C<seek()> appends correctly
-
-=item Interpolation Traps
-
-C<@> always interpolates an array in double-quotish strings, Double-quoted
-strings may no longer end with an unescaped $, Arbitrary expressions are
-evaluated inside braces within double quotes, C<$$x> now tries to
-dereference $x, Creation of hashes on the fly with C<eval "EXPR"> requires
-protection, Bugs in earlier perl versions, Array and hash brackets during
-interpolation, Interpolation of C<\$$foo{bar}>, C<qq()> string passed to
-C<eval> will not find string terminator
-
-=item DBM Traps
-
-Perl5 must have been linked with same dbm/ndbm as the default for
-C<dbmopen()>, DBM exceeding limit on the key/value size will cause perl5 to
-exit immediately
-
-=item Unclassified Traps
-
-C<require>/C<do> trap using returned value, C<split> on empty string with
-LIMIT specified
-
-=back
-
-=back
-
-=head2 perldebtut - Perl debugging tutorial
-
-=over 4
-
-=item DESCRIPTION
-
-=item use strict
-
-=item Looking at data and -w and v
-
-=item help
-
-=item Stepping through code
-
-=item Placeholder for a, w, t, T
-
-=item REGULAR EXPRESSIONS
-
-=item OUTPUT TIPS
-
-=item CGI
-
-=item GUIs
-
-=item SUMMARY
-
-=item SEE ALSO
-
-=item AUTHOR
-
-=item CONTRIBUTORS
-
-=back
-
-=head2 perlfaq - frequently asked questions about Perl
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Where to get the perlfaq
-
-=item How to contribute to the perlfaq
-
-=item What will happen if you mail your Perl programming problems to the
-authors?
-
-=back
-
-=item CREDITS
-
-=item AUTHOR AND COPYRIGHT
-
-=item Table of Contents
-
-perlfaq - this document, perlfaq1 - General Questions About Perl, perlfaq2
-- Obtaining and Learning about Perl, perlfaq3 - Programming Tools, perlfaq4
-- Data Manipulation, perlfaq5 - Files and Formats, perlfaq6 - Regular
-Expressions, perlfaq7 - General Perl Language Issues, perlfaq8 - System
-Interaction, perlfaq9 - Networking
-
-=item The Questions
-
-=over 4
-
-=item L<perlfaq1>: General Questions About Perl
-
-=item L<perlfaq2>: Obtaining and Learning about Perl
-
-=item L<perlfaq3>: Programming Tools
-
-=item L<perlfaq4>: Data Manipulation
-
-=item L<perlfaq5>: Files and Formats
-
-=item L<perlfaq6>: Regular Expressions
-
-=item L<perlfaq7>: General Perl Language Issues
-
-=item L<perlfaq8>: System Interaction
-
-=item L<perlfaq9>: Networking
-
-=back
-
-=back
-
-=head2 perlfaq1 - General Questions About Perl
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item What is Perl?
-
-=item Who supports Perl? Who develops it? Why is it free?
-
-=item Which version of Perl should I use?
-
-=item What are Perl 4, Perl 5, or Perl 6?
-
-=item What was Ponie?
-
-=item What is Perl 6?
-
-=item How stable is Perl?
-
-=item Is Perl difficult to learn?
-
-=item How does Perl compare with other languages like Java, Python, REXX,
-Scheme, or Tcl?
-
-=item Can I do [task] in Perl?
-
-=item When shouldn't I program in Perl?
-
-=item What's the difference between "perl" and "Perl"?
-
-=item Is it a Perl program or a Perl script?
-
-=item What is a JAPH?
-
-=item Where can I get a list of Larry Wall witticisms?
-
-=item How can I convince others to use Perl?
-
-http://perltraining.com.au/whyperl.html,
-http://www.perl.org/advocacy/whyperl.html
-
-=back
-
-=item REVISION
-
-=item AUTHOR AND COPYRIGHT
-
-=back
-
-=head2 perlfaq2 - Obtaining and Learning about Perl
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item What machines support perl? Where do I get it?
-
-=item How can I get a binary version of perl?
-
-=item I don't have a C compiler. How can I build my own Perl interpreter?
-
-=item I copied the perl binary from one machine to another, but scripts
-don't work.
-
-=item I grabbed the sources and tried to compile but gdbm/dynamic
-loading/malloc/linking/... failed. How do I make it work?
-
-=item What modules and extensions are available for Perl? What is CPAN?
-What does CPAN/src/... mean?
-
-=item Is there an ISO or ANSI certified version of Perl?
-
-=item Where can I get information on Perl?
-
-=item What are the Perl newsgroups on Usenet? Where do I post questions?
-
-=item Where should I post source code?
-
-=item Perl Books
-
-References, Tutorials, Task-Oriented, Special Topics
-
-=item Which magazines have Perl content?
-
-=item What mailing lists are there for Perl?
-
-=item Where are the archives for comp.lang.perl.misc?
-
-=item Where can I buy a commercial version of perl?
-
-=item Where do I send bug reports?
-
-=item What is perl.com? Perl Mongers? pm.org? perl.org? cpan.org?
-
-=back
-
-=item REVISION
-
-=item AUTHOR AND COPYRIGHT
-
-=back
-
-=head2 perlfaq3 - Programming Tools
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item How do I do (anything)?
-
-=item How can I use Perl interactively?
-
-=item Is there a Perl shell?
-
-=item How do I find which modules are installed on my system?
-
-=item How do I debug my Perl programs?
-
-=item How do I profile my Perl programs?
-
-=item How do I cross-reference my Perl programs?
-
-=item Is there a pretty-printer (formatter) for Perl?
-
-=item Is there a ctags for Perl?
-
-=item Is there an IDE or Windows Perl Editor?
-
-Eclipse, Enginsite, Komodo, Open Perl IDE, OptiPerl, PerlBuilder,
-visiPerl+, Visual Perl, Zeus, GNU Emacs, MicroEMACS, XEmacs, Jed, Elvis,
-Vile, Vim, Codewright, MultiEdit, SlickEdit, Bash, Ksh, Tcsh, Zsh, Affrus,
-Alpha, BBEdit and BBEdit Lite
-
-=item Where can I get Perl macros for vi?
-
-=item Where can I get perl-mode for emacs?
-
-=item How can I use curses with Perl?
-
-=item How can I write a GUI (X, Tk, Gtk, etc.) in Perl?
-X<GUI> X<Tk> X<Wx> X<WxWidgets> X<Gtk> X<Gtk2> X<CamelBones> X<Qt>
-
-Tk, Wx, Gtk and Gtk2, Win32::GUI, CamelBones, Qt, Athena
-
-=item How can I make my Perl program run faster?
-
-=item How can I make my Perl program take less memory?
-
-Don't slurp!, Use map and grep selectively, Avoid unnecessary quotes and
-stringification, Pass by reference, Tie large variables to disk
-
-=item Is it safe to return a reference to local or lexical data?
-
-=item How can I free an array or hash so my program shrinks?
-
-=item How can I make my CGI script more efficient?
-
-=item How can I hide the source for my Perl program?
-
-=item How can I compile my Perl program into byte code or C?
-
-=item How can I get C<#!perl> to work on [MS-DOS,NT,...]?
-
-=item Can I write useful Perl programs on the command line?
-
-=item Why don't Perl one-liners work on my DOS/Mac/VMS system?
-
-=item Where can I learn about CGI or Web programming in Perl?
-
-=item Where can I learn about object-oriented Perl programming?
-
-=item Where can I learn about linking C with Perl?
-
-=item I've read perlembed, perlguts, etc., but I can't embed perl in my C
-program; what am I doing wrong?
-
-=item When I tried to run my script, I got this message. What does it mean?
-
-=item What's MakeMaker?
-
-=back
-
-=item REVISION
-
-=item AUTHOR AND COPYRIGHT
-
-=back
-
-=head2 perlfaq4 - Data Manipulation
-
-=over 4
-
-=item DESCRIPTION
-
-=item Data: Numbers
-
-=over 4
-
-=item Why am I getting long decimals (eg, 19.9499999999999) instead of the
-numbers I should be getting (eg, 19.95)?
-
-=item Why is int() broken?
-
-=item Why isn't my octal data interpreted correctly?
-
-=item Does Perl have a round() function? What about ceil() and floor()?
-Trig functions?
-
-=item How do I convert between numeric representations/bases/radixes?
-
-How do I convert hexadecimal into decimal, How do I convert from decimal to
-hexadecimal, How do I convert from octal to decimal, How do I convert from
-decimal to octal, How do I convert from binary to decimal, How do I convert
-from decimal to binary
-
-=item Why doesn't & work the way I want it to?
-
-=item How do I multiply matrices?
-
-=item How do I perform an operation on a series of integers?
-
-=item How can I output Roman numerals?
-
-=item Why aren't my random numbers random?
-
-=item How do I get a random number between X and Y?
-
-=back
-
-=item Data: Dates
-
-=over 4
-
-=item How do I find the day or week of the year?
-
-=item How do I find the current century or millennium?
-
-=item How can I compare two dates and find the difference?
-
-=item How can I take a string and turn it into epoch seconds?
-
-=item How can I find the Julian Day?
-
-=item How do I find yesterday's date?
-
-=item Does Perl have a Year 2000 problem? Is Perl Y2K compliant?
-
-=item Does Perl have a Year 2038 problem?
-
-=back
-
-=item Data: Strings
-
-=over 4
-
-=item How do I validate input?
-
-=item How do I unescape a string?
-
-=item How do I remove consecutive pairs of characters?
-
-=item How do I expand function calls in a string?
-
-=item How do I find matching/nesting anything?
-
-=item How do I reverse a string?
-
-=item How do I expand tabs in a string?
-
-=item How do I reformat a paragraph?
-
-=item How can I access or change N characters of a string?
-
-=item How do I change the Nth occurrence of something?
-
-=item How can I count the number of occurrences of a substring within a
-string?
-
-=item How do I capitalize all the words on one line?
-
-=item How can I split a [character] delimited string except when inside
-[character]?
-
-=item How do I strip blank space from the beginning/end of a string?
-
-=item How do I pad a string with blanks or pad a number with zeroes?
-
-=item How do I extract selected columns from a string?
-
-=item How do I find the soundex value of a string?
-
-=item How can I expand variables in text strings?
-
-=item What's wrong with always quoting "$vars"?
-
-=item Why don't my E<lt>E<lt>HERE documents work?
-
-There must be no space after the E<lt>E<lt> part, There (probably) should
-be a semicolon at the end, You can't (easily) have any space in front of
-the tag
-
-=back
-
-=item Data: Arrays
-
-=over 4
-
-=item What is the difference between a list and an array?
-
-=item What is the difference between $array[1] and @array[1]?
-
-=item How can I remove duplicate elements from a list or array?
-
-=item How can I tell whether a certain element is contained in a list or
-array?
-
-=item How do I compute the difference of two arrays? How do I compute the
-intersection of two arrays?
-
-=item How do I test whether two arrays or hashes are equal?
-
-=item How do I find the first array element for which a condition is true?
-
-=item How do I handle linked lists?
-
-=item How do I handle circular lists?
-
-=item How do I shuffle an array randomly?
-
-=item How do I process/modify each element of an array?
-
-=item How do I select a random element from an array?
-
-=item How do I permute N elements of a list?
-X<List::Permuter> X<permute> X<Algorithm::Loops> X<Knuth>
-X<The Art of Computer Programming> X<Fischer-Krause>
-
-=item How do I sort an array by (anything)?
-
-=item How do I manipulate arrays of bits?
-
-=item Why does defined() return true on empty arrays and hashes?
-
-=back
-
-=item Data: Hashes (Associative Arrays)
-
-=over 4
-
-=item How do I process an entire hash?
-
-=item What happens if I add or remove keys from a hash while iterating over
-it?
-
-=item How do I look up a hash element by value?
-
-=item How can I know how many entries are in a hash?
-
-=item How do I sort a hash (optionally by value instead of key)?
-
-=item How can I always keep my hash sorted?
-X<hash tie sort DB_File Tie::IxHash>
-
-=item What's the difference between "delete" and "undef" with hashes?
-
-=item Why don't my tied hashes make the defined/exists distinction?
-
-=item How do I reset an each() operation part-way through?
-
-=item How can I get the unique keys from two hashes?
-
-=item How can I store a multidimensional array in a DBM file?
-
-=item How can I make my hash remember the order I put elements into it?
-
-=item Why does passing a subroutine an undefined element in a hash create
-it?
-
-=item How can I make the Perl equivalent of a C structure/C++ class/hash or
-array of hashes or arrays?
-
-=item How can I use a reference as a hash key?
-
-=back
-
-=item Data: Misc
-
-=over 4
-
-=item How do I handle binary data correctly?
-
-=item How do I determine whether a scalar is a number/whole/integer/float?
-
-=item How do I keep persistent data across program calls?
-
-=item How do I print out or copy a recursive data structure?
-
-=item How do I define methods for every class/object?
-
-=item How do I verify a credit card checksum?
-
-=item How do I pack arrays of doubles or floats for XS code?
-
-=back
-
-=item REVISION
-
-=item AUTHOR AND COPYRIGHT
-
-=back
-
-=head2 perlfaq5 - Files and Formats
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item How do I flush/unbuffer an output filehandle? Why must I do this?
-X<flush> X<buffer> X<unbuffer> X<autoflush>
-
-=item How do I change, delete, or insert a line in a file, or append to the
-beginning of a file?
-X<file, editing>
-
-=item How do I count the number of lines in a file?
-X<file, counting lines> X<lines> X<line>
-
-=item How can I use Perl's C<-i> option from within a program?
-X<-i> X<in-place>
-
-=item How can I copy a file?
-X<copy> X<file, copy>
-
-=item How do I make a temporary file name?
-X<file, temporary>
-
-=item How can I manipulate fixed-record-length files?
-X<fixed-length> X<file, fixed-length records>
-
-=item How can I make a filehandle local to a subroutine? How do I pass
-filehandles between subroutines? How do I make an array of filehandles?
-X<filehandle, local> X<filehandle, passing> X<filehandle, reference>
-
-=item How can I use a filehandle indirectly?
-X<filehandle, indirect>
-
-=item How can I set up a footer format to be used with write()?
-X<footer>
-
-=item How can I write() into a string?
-X<write, into a string>
-
-=item How can I open a filehandle to a string?
-X<string>, X<open>, X<IO::Scalar>, X<filehandle>
-
-=item How can I output my numbers with commas added?
-X<number, commify>
-
-=item How can I translate tildes (~) in a filename?
-X<tilde> X<tilde expansion>
-
-=item How come when I open a file read-write it wipes it out?
-X<clobber> X<read-write> X<clobbering> X<truncate> X<truncating>
-
-=item Why do I sometimes get an "Argument list too long" when I use
-E<lt>*E<gt>?
-X<argument list too long>
-
-=item Is there a leak/bug in glob()?
-X<glob>
-
-=item How can I open a file with a leading ">" or trailing blanks?
-X<filename, special characters>
-
-=item How can I reliably rename a file?
-X<rename> X<mv> X<move> X<file, rename> X<ren>
-
-=item How can I lock a file?
-X<lock> X<file, lock> X<flock>
-
-=item Why can't I just open(FH, "E<gt>file.lock")?
-X<lock, lockfile race condition>
-
-=item I still don't get locking. I just want to increment the number in
-the file. How can I do this?
-X<counter> X<file, counter>
-
-=item All I want to do is append a small amount of text to the end of a
-file. Do I still have to use locking?
-X<append> X<file, append>
-
-=item How do I randomly update a binary file?
-X<file, binary patch>
-
-=item How do I get a file's timestamp in perl?
-X<timestamp> X<file, timestamp>
-
-=item How do I set a file's timestamp in perl?
-X<timestamp> X<file, timestamp>
-
-=item How do I print to more than one file at once?
-X<print, to multiple files>
-
-=item How can I read in an entire file all at once?
-X<slurp> X<file, slurping>
-
-=item How can I read in a file by paragraphs?
-X<file, reading by paragraphs>
-
-=item How can I read a single character from a file? From the keyboard?
-X<getc> X<file, reading one character at a time>
-
-=item How can I tell whether there's a character waiting on a filehandle?
-
-=item How do I do a C<tail -f> in perl?
-X<tail> X<IO::Handle> X<File::Tail> X<clearerr>
-
-=item How do I dup() a filehandle in Perl?
-X<dup>
-
-=item How do I close a file descriptor by number?
-X<file, closing file descriptors> X<POSIX> X<close>
-
-=item Why can't I use "C:\temp\foo" in DOS paths? Why doesn't
-`C:\temp\foo.exe` work?
-X<filename, DOS issues>
-
-=item Why doesn't glob("*.*") get all the files?
-X<glob>
-
-=item Why does Perl let me delete read-only files? Why does C<-i> clobber
-protected files? Isn't this a bug in Perl?
-
-=item How do I select a random line from a file?
-X<file, selecting a random line>
-
-=item Why do I get weird spaces when I print an array of lines?
-
-=back
-
-=item REVISION
-
-=item AUTHOR AND COPYRIGHT
-
-=back
-
-=head2 perlfaq6 - Regular Expressions
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item How can I hope to use regular expressions without creating illegible
-and unmaintainable code?
-X<regex, legibility> X<regexp, legibility>
-X<regular expression, legibility> X</x>
-
-Comments Outside the Regex, Comments Inside the Regex, Different Delimiters
-
-=item I'm having trouble matching over more than one line. What's wrong?
-X<regex, multiline> X<regexp, multiline> X<regular expression, multiline>
-
-=item How can I pull out lines between two patterns that are themselves on
-different lines?
-X<..>
-
-=item I put a regular expression into $/ but it didn't work. What's wrong?
-X<$/, regexes in> X<$INPUT_RECORD_SEPARATOR, regexes in>
-X<$RS, regexes in>
-
-=item How do I substitute case insensitively on the LHS while preserving
-case on the RHS?
-X<replace, case preserving> X<substitute, case preserving>
-X<substitution, case preserving> X<s, case preserving>
-
-=item How can I make C<\w> match national character sets?
-X<\w>
-
-=item How can I match a locale-smart version of C</[a-zA-Z]/>?
-X<alpha>
-
-=item How can I quote a variable to use in a regex?
-X<regex, escaping> X<regexp, escaping> X<regular expression, escaping>
-
-=item What is C</o> really for?
-X</o, regular expressions> X<compile, regular expressions>
-
-=item How do I use a regular expression to strip C style comments from a
-file?
-
-=item Can I use Perl regular expressions to match balanced text?
-X<regex, matching balanced test> X<regexp, matching balanced test>
-X<regular expression, matching balanced test>
-
-=item What does it mean that regexes are greedy? How can I get around it?
-X<greedy> X<greediness>
-
-=item How do I process each word on each line?
-X<word>
-
-=item How can I print out a word-frequency or line-frequency summary?
-
-=item How can I do approximate matching?
-X<match, approximate> X<matching, approximate>
-
-=item How do I efficiently match many regular expressions at once?
-X<regex, efficiency> X<regexp, efficiency>
-X<regular expression, efficiency>
-
-=item Why don't word-boundary searches with C<\b> work for me?
-X<\b>
-
-=item Why does using $&, $`, or $' slow my program down?
-X<$MATCH> X<$&> X<$POSTMATCH> X<$'> X<$PREMATCH> X<$`>
-
-=item What good is C<\G> in a regular expression?
-X<\G>
-
-=item Are Perl regexes DFAs or NFAs? Are they POSIX compliant?
-X<DFA> X<NFA> X<POSIX>
-
-=item What's wrong with using grep in a void context?
-X<grep>
-
-=item How can I match strings with multibyte characters?
-X<regex, and multibyte characters> X<regexp, and multibyte characters>
-X<regular expression, and multibyte characters> X<martian> X<encoding,
-Martian>
-
-=item How do I match a regular expression that's in a variable?
-X<regex, in variable> X<eval> X<regex> X<quotemeta> X<\Q, regex>
-X<\E, regex>, X<qr//>
-
-=back
-
-=item REVISION
-
-=item AUTHOR AND COPYRIGHT
-
-=back
-
-=head2 perlfaq7 - General Perl Language Issues
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Can I get a BNF/yacc/RE for the Perl language?
-
-=item What are all these $@%&* punctuation signs, and how do I know when to
-use them?
-
-=item Do I always/never have to quote my strings or use semicolons and
-commas?
-
-=item How do I skip some return values?
-
-=item How do I temporarily block warnings?
-
-=item What's an extension?
-
-=item Why do Perl operators have different precedence than C operators?
-
-=item How do I declare/create a structure?
-
-=item How do I create a module?
-
-=item How do I adopt or take over a module already on CPAN?
-
-=item How do I create a class?
-
-=item How can I tell if a variable is tainted?
-
-=item What's a closure?
-
-=item What is variable suicide and how can I prevent it?
-
-=item How can I pass/return a {Function, FileHandle, Array, Hash, Method,
-Regex}?
-
-Passing Variables and Functions, Passing Filehandles, Passing Regexes,
-Passing Methods
-
-=item How do I create a static variable?
-
-=item What's the difference between dynamic and lexical (static) scoping?
-Between local() and my()?
-
-=item How can I access a dynamic variable while a similarly named lexical
-is in scope?
-
-=item What's the difference between deep and shallow binding?
-
-=item Why doesn't "my($foo) = E<lt>FILEE<gt>;" work right?
-
-=item How do I redefine a builtin function, operator, or method?
-
-=item What's the difference between calling a function as &foo and foo()?
-
-=item How do I create a switch or case statement?
-
-=item How can I catch accesses to undefined variables, functions, or
-methods?
-
-=item Why can't a method included in this same file be found?
-
-=item How can I find out my current package?
-
-=item How can I comment out a large block of perl code?
-
-=item How do I clear a package?
-
-=item How can I use a variable as a variable name?
-
-=item What does "bad interpreter" mean?
-
-=back
-
-=item REVISION
-
-=item AUTHOR AND COPYRIGHT
-
-=back
-
-=head2 perlfaq8 - System Interaction
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item How do I find out which operating system I'm running under?
-
-=item How come exec() doesn't return?
-
-=item How do I do fancy stuff with the keyboard/screen/mouse?
-
-Keyboard, Screen, Mouse
-
-=item How do I print something out in color?
-
-=item How do I read just one key without waiting for a return key?
-
-=item How do I check whether input is ready on the keyboard?
-
-=item How do I clear the screen?
-
-=item How do I get the screen size?
-
-=item How do I ask the user for a password?
-
-=item How do I read and write the serial port?
-
-lockfiles, open mode, end of line, flushing output, non-blocking input
-
-=item How do I decode encrypted password files?
-
-=item How do I start a process in the background?
-
-STDIN, STDOUT, and STDERR are shared, Signals, Zombies
-
-=item How do I trap control characters/signals?
-
-=item How do I modify the shadow password file on a Unix system?
-
-=item How do I set the time and date?
-
-=item How can I sleep() or alarm() for under a second?
-X<Time::HiRes> X<BSD::Itimer> X<sleep> X<select>
-
-=item How can I measure time under a second?
-X<Time::HiRes> X<BSD::Itimer> X<sleep> X<select>
-
-=item How can I do an atexit() or setjmp()/longjmp()? (Exception handling)
-
-=item Why doesn't my sockets program work under System V (Solaris)? What
-does the error message "Protocol not supported" mean?
-
-=item How can I call my system's unique C functions from Perl?
-
-=item Where do I get the include files to do ioctl() or syscall()?
-
-=item Why do setuid perl scripts complain about kernel problems?
-
-=item How can I open a pipe both to and from a command?
-
-=item Why can't I get the output of a command with system()?
-
-=item How can I capture STDERR from an external command?
-
-=item Why doesn't open() return an error when a pipe open fails?
-
-=item What's wrong with using backticks in a void context?
-
-=item How can I call backticks without shell processing?
-
-=item Why can't my script read from STDIN after I gave it EOF (^D on Unix,
-^Z on MS-DOS)?
-
-=item How can I convert my shell script to perl?
-
-=item Can I use perl to run a telnet or ftp session?
-
-=item How can I write expect in Perl?
-
-=item Is there a way to hide perl's command line from programs such as
-"ps"?
-
-=item I {changed directory, modified my environment} in a perl script. How
-come the change disappeared when I exited the script? How do I get my
-changes to be visible?
-
-Unix
-
-=item How do I close a process's filehandle without waiting for it to
-complete?
-
-=item How do I fork a daemon process?
-
-=item How do I find out if I'm running interactively or not?
-
-=item How do I timeout a slow event?
-
-=item How do I set CPU limits?
-X<BSD::Resource> X<limit> X<CPU>
-
-=item How do I avoid zombies on a Unix system?
-
-=item How do I use an SQL database?
-
-=item How do I make a system() exit on control-C?
-
-=item How do I open a file without blocking?
-
-=item How do I tell the difference between errors from the shell and perl?
-
-=item How do I install a module from CPAN?
-
-=item What's the difference between require and use?
-
-=item How do I keep my own module/library directory?
-
-=item How do I add the directory my program lives in to the module/library
-search path?
-
-=item How do I add a directory to my include path (@INC) at runtime?
-
-the PERLLIB environment variable, the PERL5LIB environment variable, the
-perl -Idir command line flag, the use lib pragma:
-
-=item What is socket.ph and where do I get it?
-
-=back
-
-=item REVISION
-
-=item AUTHOR AND COPYRIGHT
-
-=back
-
-=head2 perlfaq9 - Networking
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item What is the correct form of response from a CGI script?
-
-=item My CGI script runs from the command line but not the browser. (500
-Server Error)
-
-=item How can I get better error messages from a CGI program?
-
-=item How do I remove HTML from a string?
-
-=item How do I extract URLs?
-
-=item How do I download a file from the user's machine? How do I open a
-file on another machine?
-
-=item How do I make an HTML pop-up menu with Perl?
-
-=item How do I fetch an HTML file?
-
-=item How do I automate an HTML form submission?
-
-=item How do I decode or create those %-encodings on the web?
-
-=item How do I redirect to another page?
-
-=item How do I put a password on my web pages?
-
-=item How do I edit my .htpasswd and .htgroup files with Perl?
-
-=item How do I make sure users can't enter values into a form that cause my
-CGI script to do bad things?
-
-=item How do I parse a mail header?
-
-=item How do I decode a CGI form?
-
-=item How do I check a valid mail address?
-
-=item How do I decode a MIME/BASE64 string?
-
-=item How do I return the user's mail address?
-
-=item How do I send mail?
-
-=item How do I use MIME to make an attachment to a mail message?
-
-=item How do I read mail?
-
-=item How do I find out my hostname, domainname, or IP address?
-X<hostname, domainname, IP address, host, domain, hostfqdn, inet_ntoa,
-gethostbyname, Socket, Net::Domain, Sys::Hostname>
-
-=item How do I fetch a news article or the active newsgroups?
-
-=item How do I fetch/put an FTP file?
-
-=item How can I do RPC in Perl?
-
-=back
-
-=item REVISION
-
-=item AUTHOR AND COPYRIGHT
-
-=back
-
-=head2 perlsyn - Perl syntax
-
-=over 4
-
-=item DESCRIPTION
-
-=over 4
-
-=item Declarations
-X<declaration> X<undef> X<undefined> X<uninitialized>
-
-=item Comments
-X<comment> X<#>
**** PATCH TRUNCATED AT 2000 LINES -- 36569 NOT SHOWN ****
--
Perl5 Master Repository