From 818effc8dfd8e1580b124df9d86e716aa524f0e7 Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Sun, 18 Feb 2024 15:45:02 -0800 Subject: [PATCH] cpan/perlfaq - Update to version 5.20240218 5.20240218 2024-02-18 17:37:25Z * add entry for "UTF-8 string" in perlglossary (PR#99, Felipe Gasper) * update the bug tracker advice to de-emphasize rt.cpan.org (PR#107, brian d foy) * plug CLDR::Number instead of Number::Format in perlfaq5 (PR#108, brian d foy) * misc code sample fixes in perlfaq4 (PR#109, brian d foy) * minor wording fixes in perlfaq5 (Karen Etheridge) * fix assertion about Python and closures (PR#114, E. Choroba) * improve the section on uniq perlfaq4 (PR#116, E. Choroba) * remove mention of Perl 4 in perlfaq1 (PR#113, Joelle Maslak) * document that smartmatch, given and when will be removed in Perl 5.42 (PR#115, Philippe Bruhat (BooK)) --- Porting/Maintainers.pl | 3 +- cpan/perlfaq/lib/perlfaq.pm | 2 +- cpan/perlfaq/lib/perlfaq.pod | 10 ++--- cpan/perlfaq/lib/perlfaq1.pod | 24 +---------- cpan/perlfaq/lib/perlfaq2.pod | 49 +++++++++++++++------ cpan/perlfaq/lib/perlfaq3.pod | 2 +- cpan/perlfaq/lib/perlfaq4.pod | 72 +++++++++++++++++++------------ cpan/perlfaq/lib/perlfaq5.pod | 44 +++++++++++++++---- cpan/perlfaq/lib/perlfaq6.pod | 2 +- cpan/perlfaq/lib/perlfaq7.pod | 12 +++--- cpan/perlfaq/lib/perlfaq8.pod | 4 +- cpan/perlfaq/lib/perlfaq9.pod | 2 +- cpan/perlfaq/lib/perlglossary.pod | 14 +++++- 13 files changed, 145 insertions(+), 95 deletions(-) diff --git a/Porting/Maintainers.pl b/Porting/Maintainers.pl index adc6df140d..2fa65f60f0 100755 --- a/Porting/Maintainers.pl +++ b/Porting/Maintainers.pl @@ -907,8 +907,7 @@ our %Modules = ( }, 'perlfaq' => { - 'DISTRIBUTION' => 'ETHER/perlfaq-5.20230812.tar.gz', - 'SYNCINFO' => 'jkeenan on Wed Aug 16 18:13:51 2023', + 'DISTRIBUTION' => 'ETHER/perlfaq-5.20240218.tar.gz', 'FILES' => q[cpan/perlfaq], 'EXCLUDED' => [ qr/^inc/, qr/^xt/, qr{^t/00-} ], }, diff --git a/cpan/perlfaq/lib/perlfaq.pm b/cpan/perlfaq/lib/perlfaq.pm index 588cd31961..3ab13bf1aa 100644 --- a/cpan/perlfaq/lib/perlfaq.pm +++ b/cpan/perlfaq/lib/perlfaq.pm @@ -2,6 +2,6 @@ use strict; use warnings; package perlfaq; -our $VERSION = '5.20230812'; +our $VERSION = '5.20240218'; 1; diff --git a/cpan/perlfaq/lib/perlfaq.pod b/cpan/perlfaq/lib/perlfaq.pod index fd5beef7fb..d9edf8e9c1 100644 --- a/cpan/perlfaq/lib/perlfaq.pod +++ b/cpan/perlfaq/lib/perlfaq.pod @@ -4,7 +4,7 @@ perlfaq - Frequently asked questions about Perl =head1 VERSION -version 5.20230812 +version 5.20240218 =head1 DESCRIPTION @@ -88,10 +88,6 @@ Which version of Perl should I use? =item * -What are Perl 4, Perl 5, or Raku (Perl 6)? - -=item * - What is Raku (Perl 6)? =item * @@ -720,7 +716,7 @@ How can I translate tildes (~) in a filename? =item * -How come when I open a file read-write it wipes it out? +When I open a file read-write, why does it wipe it out? =item * @@ -1079,7 +1075,7 @@ How do I find out which operating system I'm running under? =item * -How come exec() doesn't return? +Why does exec() not return? =item * diff --git a/cpan/perlfaq/lib/perlfaq1.pod b/cpan/perlfaq/lib/perlfaq1.pod index e555ca6c06..ea40b79b84 100644 --- a/cpan/perlfaq/lib/perlfaq1.pod +++ b/cpan/perlfaq/lib/perlfaq1.pod @@ -4,7 +4,7 @@ perlfaq1 - General Questions About Perl =head1 VERSION -version 5.20230812 +version 5.20240218 =head1 DESCRIPTION @@ -123,28 +123,6 @@ current stable release of Perl. =back -=head2 What are Perl 4, Perl 5, or Raku (Perl 6)? - -In short, Perl 4 is the parent to both Perl 5 and Raku (formerly known as -Perl 6). Perl 5 is the older sibling, and though they are different languages, -someone who knows one will spot many similarities in the other. - -The number after Perl (i.e. the 5 after Perl 5) is the major release -of the perl interpreter as well as the version of the language. Each -major version has significant differences that earlier versions cannot -support. - -The current major release of Perl is Perl 5, first released in -1994. It can run scripts from the previous major release, Perl 4 -(March 1991), but has significant differences. - -Raku is a reinvention of Perl, a language in the same lineage but -not compatible. The two are complementary, not mutually exclusive. Raku is -not meant to replace Perl, and vice versa. See L -below to find out more. - -See L for a history of Perl revisions. - =head2 What is Raku (Perl 6)? Raku (formerly known as Perl 6) was I described as the community's diff --git a/cpan/perlfaq/lib/perlfaq2.pod b/cpan/perlfaq/lib/perlfaq2.pod index 866de5f0a5..3ad0f1c079 100644 --- a/cpan/perlfaq/lib/perlfaq2.pod +++ b/cpan/perlfaq/lib/perlfaq2.pod @@ -8,7 +8,7 @@ perlfaq2 - Obtaining and Learning about Perl =head1 VERSION -version 5.20230812 +version 5.20240218 =head1 DESCRIPTION @@ -221,25 +221,46 @@ First, ensure that you've found an actual bug. Second, ensure you've found an actual bug. If you've found a bug with the perl interpreter or one of the modules -in the standard library (those that come with Perl), you can submit a +in the standard library (those that come with Perl), submit a bug report to the GitHub issue tracker at L. To determine if a module came with your version of Perl, you can -install and use the L module. It has the information -about the modules (with their versions) included with each release -of Perl. +install and use L. It knows the modules (with their +versions) included with each release of Perl: -Every CPAN module has a bug tracker set up in RT, L. -You can submit bugs to RT either through its web interface or by -email. To email a bug report, send it to -bug-Edistribution-nameE@rt.cpan.org . For example, if you -wanted to report a bug in L, you could send a message to -bug-Business-ISBN@rt.cpan.org . + $ corelist File::Copy + Data for 2023-07-02 + File::Copy was first released with perl 5.002 -Some modules might have special reporting requirements, such as a -GitHub or Google Code tracking system, so you should check the -module documentation too. + $ corelist Business::ISBN + Data for 2023-07-02 + Business::ISBN was not in CORE (or so I think) + +If the module does not come with Perl, report its issues +using the tool that the particular module author decided to use, such as +a GitHub or Google Code. The quickest way may be to check the MetaCPAN +page for the module (for example, +L), which shows the denoted +bugtracker in the left sidebar as the "Issues" link. + +Also check the module's documentation, F, the build files +(F or C), or F files. Although +many module authors follow the same pattern, some have their own way. +Use the directions you find. + +Sometimes the module author does not declare a bugtracker. For a long +time, everyone assumed that the CPAN Request Tracker +(L) was the bugtracker since every distribution had +an RT queue generated automatically. In somes cases, the author might +use CPAN RT. They also might have not declared a different +bugtracker but don't use CPAN RT. + +Submit bugs to RT either through its web interface, +L, or by email. Send email to I<< +bug-Edistribution-nameE@rt.cpan.org >>. For example, if you +wanted to report a bug in the example module L, you could send +a message to I. =head1 AUTHOR AND COPYRIGHT diff --git a/cpan/perlfaq/lib/perlfaq3.pod b/cpan/perlfaq/lib/perlfaq3.pod index f9ae5b0d43..6877c2d1b4 100644 --- a/cpan/perlfaq/lib/perlfaq3.pod +++ b/cpan/perlfaq/lib/perlfaq3.pod @@ -4,7 +4,7 @@ perlfaq3 - Programming Tools =head1 VERSION -version 5.20230812 +version 5.20240218 =head1 DESCRIPTION diff --git a/cpan/perlfaq/lib/perlfaq4.pod b/cpan/perlfaq/lib/perlfaq4.pod index 46ea5e7973..9c5489bba7 100644 --- a/cpan/perlfaq/lib/perlfaq4.pod +++ b/cpan/perlfaq/lib/perlfaq4.pod @@ -4,7 +4,7 @@ perlfaq4 - Data Manipulation =head1 VERSION -version 5.20230812 +version 5.20240218 =head1 DESCRIPTION @@ -886,39 +886,57 @@ X X X X (contributed by brian d foy) Damian Conway's L handles all of the thinking -for you. +for you: use Text::Autoformat; - my $x = "Dr. Strangelove or: How I Learned to Stop ". - "Worrying and Love the Bomb"; + my $s = "Going to the desert with a camel"; - print $x, "\n"; + printf "%-10s %s\n", "original:", $s; for my $style (qw( sentence title highlight )) { - print autoformat($x, { case => $style }), "\n"; + printf "%-10s %s\n", + "$style:", + autoformat($s, { case => $style }) =~ s/\R+\z//r; } -How do you want to capitalize those words? +Each style has a different idea of what if should do with small words: - FRED AND BARNEY'S LODGE # all uppercase - Fred And Barney's Lodge # title case - Fred and Barney's Lodge # highlight case + original: Going to the desert with a camel + sentence: Going to the desert with a camel + title: Going To The Desert With A Camel + highlight: Going to the Desert with a Camel -It's not as easy a problem as it looks. How many words do you think -are in there? Wait for it... wait for it.... If you answered 5 -you're right. Perl words are groups of C<\w+>, but that's not what -you want to capitalize. How is Perl supposed to know not to capitalize -that C after the apostrophe? You could try a regular expression: +Trying this yourself in a simple regex has more than a few pitfalls. +Perl "words" are groups of C<\w+>, but that's not what you want to +capitalize. Some of those characters aren't even letters. What if you +used a word boundary, C<\b>? - $string =~ s/ ( - (^\w) #at the beginning of the line - | # or - (\s\w) #preceded by whitespace - ) - /\U$1/xg; + my $string = "A camel's journey"; + $string =~ s/\b(\w)/\U$1/g; # A Camel'S Journey + +How is Perl supposed to know not to capitalize that C? You could work +harder to look for preceding whitespace or the beginning of the string: + + $string =~ s/( (?:^|\s) \w ) /\U$1/xg; # A Camel's Journey + +Or maybe you match the entire group, lowercase it all (C), then +uppercase the first letter (C<\u>): $string =~ s/([\w']+)/\u\L$1/g; -Now, what if you don't want to capitalize that "and"? Just use +Each of these have their annoying edge cases. Perl v5.22 added fancier +Unicode word and sentence boundaries to fix this sort of problem. The +C<\b{wb}> word boundary ignores some things that it doesn't think start +or end "human" words: + + use v5.22; + my $string = "A camel's journey"; + $string =~ s/\b{wb}(\w)/\U$1/g; # A Camel's Journey + +The details are in Unicode Technical Report #29 +(L), and you should make sure that +its idea of a word boundary corresponds to yours. + +Now, what if you don't want to capitalize that "and" or "the"? Just use L and get on with the next problem. :) =head2 How can I split a [character]-delimited string except when inside [character]? @@ -1459,18 +1477,18 @@ elements. my @unique = keys %hash; If you want to use a module, try the C function from -L. In list context it returns the unique elements, +L. In list context it returns the unique elements, preserving their order in the list. In scalar context, it returns the number of unique elements. - use List::MoreUtils qw(uniq); + use List::Util qw(uniq); - my @unique = uniq( 1, 2, 3, 4, 4, 5, 6, 5, 7 ); # 1,2,3,4,5,6,7 - my $unique = uniq( 1, 2, 3, 4, 4, 5, 6, 5, 7 ); # 7 + my @unique = uniq( 1, 2, 3, 4, 4, 5, 6, 5, 8 ); # 1,2,3,4,5,6,8 + my $unique = uniq( 1, 2, 3, 4, 4, 5, 6, 5, 8 ); # 7 You can also go through each element and skip the ones you've seen before. Use a hash to keep track. The first time the loop sees an -element, that element has no key in C<%Seen>. The C statement +element, that element has no key in C<%seen>. The C statement creates the key and immediately uses its value, which is C, so the loop continues to the C and increments the value for that key. The next time the loop sees that same element, its key exists in diff --git a/cpan/perlfaq/lib/perlfaq5.pod b/cpan/perlfaq/lib/perlfaq5.pod index 16553b789e..cad9cc8ff2 100644 --- a/cpan/perlfaq/lib/perlfaq5.pod +++ b/cpan/perlfaq/lib/perlfaq5.pod @@ -4,7 +4,7 @@ perlfaq5 - Files and Formats =head1 VERSION -version 5.20230812 +version 5.20240218 =head1 DESCRIPTION @@ -708,12 +708,38 @@ X (contributed by brian d foy and Benjamin Goldberg) -You can use L to separate places in a number. -It handles locale information for those of you who want to insert -full stops instead (or anything else that they want to use, -really). +The L module (the Unicode Common Locale Data Repository) +knows how to format numbers based on a locale to use its +digit grouping and separator: -This subroutine will add commas to your number: + use CLDR::Number; + + my $number = 1234567890; + + foreach my $locale ( qw(en-US de-DE en-IN) ) { + my $cldr = CLDR::Number->new( locale => $locale ); + my $decimal = $cldr->decimal_formatter; + printf "%-5s %s\n", $locale, $decimal->format( $number ); + } + +The output shows the same number formatted according to each locale's +rules. The bare C uses commas between groups of three, the C +uses dots and groups of three, and the C uses the 3:2:2 rule with +commas: + + en-US 1,234,567,890 + de-DE 1.234.567.890 + en-IN 1,23,45,67,890 + +L has many more advanced features to handle just about +anything that you might want. Olaf Alders' article "Stop Writing Your Own +Commify Functions" has more examples +(L). + +If you know exactly what you want, a simple subroutine might suffice. +This example will add separators to your number between groups of three +digits (or whatever grouping). This uses groups of three and a comma: sub commify { local $_ = shift; @@ -721,7 +747,7 @@ This subroutine will add commas to your number: return $_; } -This regex from Benjamin Goldberg will add commas to numbers: +This regex from Benjamin Goldberg does the same thing without the loop: s/(^[-+]?\d+?(?=(?>(?:\d{3})+)(?!\d))|\G\d{3}(?=\d))/$1,/g; @@ -762,7 +788,7 @@ Within Perl, you may use this directly: : ( $ENV{HOME} || $ENV{LOGDIR} ) }ex; -=head2 How come when I open a file read-write it wipes it out? +=head2 When I open a file read-write, why does it wipe it out? X X X X X Because you're using something like this, which truncates the file @@ -1494,7 +1520,7 @@ array in double quotes. You can send it to print without them: (contributed by brian d foy) The L module, which comes with Perl, does all of the hard -work to traverse a directory structure. It comes with Perl. You simply +work to traverse a directory structure. You simply call the C subroutine with a callback subroutine and the directories you want to traverse: diff --git a/cpan/perlfaq/lib/perlfaq6.pod b/cpan/perlfaq/lib/perlfaq6.pod index 820c70c189..8478df71c4 100644 --- a/cpan/perlfaq/lib/perlfaq6.pod +++ b/cpan/perlfaq/lib/perlfaq6.pod @@ -4,7 +4,7 @@ perlfaq6 - Regular Expressions =head1 VERSION -version 5.20230812 +version 5.20240218 =head1 DESCRIPTION diff --git a/cpan/perlfaq/lib/perlfaq7.pod b/cpan/perlfaq/lib/perlfaq7.pod index b2dc3a562c..5a1fb7a0a4 100644 --- a/cpan/perlfaq/lib/perlfaq7.pod +++ b/cpan/perlfaq/lib/perlfaq7.pod @@ -4,7 +4,7 @@ perlfaq7 - General Perl Language Issues =head1 VERSION -version 5.20230812 +version 5.20240218 =head1 DESCRIPTION @@ -266,10 +266,10 @@ binding). Closures are most often used in programming languages where you can have the return value of a function be itself a function, as you can in Perl. Note that some languages provide anonymous functions but are -not capable of providing proper closures: the Python language, for -example. For more information on closures, check out any textbook on -functional programming. Scheme is a language that not only supports -but encourages closures. +not capable of providing proper closures: for example Python 2. For +more information on closures, check out any textbook on functional +programming. Scheme is a language that not only supports but +encourages closures. Here's a classic non-closure function-generating function: @@ -696,7 +696,7 @@ details, see L. =head2 How do I create a switch or case statement? There is a given/when statement in Perl, but it is experimental and -likely to change in future. See L for more details. +will be removed in Perl 5.42. See L for more details. The general answer is to use a CPAN module such as L: diff --git a/cpan/perlfaq/lib/perlfaq8.pod b/cpan/perlfaq/lib/perlfaq8.pod index cf66f01476..a5c99c2a39 100644 --- a/cpan/perlfaq/lib/perlfaq8.pod +++ b/cpan/perlfaq/lib/perlfaq8.pod @@ -4,7 +4,7 @@ perlfaq8 - System Interaction =head1 VERSION -version 5.20230812 +version 5.20240218 =head1 DESCRIPTION @@ -23,7 +23,7 @@ The C<$^O> variable (C<$OSNAME> if you use C) contains an indication of the name of the operating system (not its release number) that your perl binary was built for. -=head2 How come exec() doesn't return? +=head2 Why does exec() not return? X X X X X (contributed by brian d foy) diff --git a/cpan/perlfaq/lib/perlfaq9.pod b/cpan/perlfaq/lib/perlfaq9.pod index 080ae1edf6..d1cef9a6fb 100644 --- a/cpan/perlfaq/lib/perlfaq9.pod +++ b/cpan/perlfaq/lib/perlfaq9.pod @@ -4,7 +4,7 @@ perlfaq9 - Web, Email and Networking =head1 VERSION -version 5.20230812 +version 5.20240218 =head1 DESCRIPTION diff --git a/cpan/perlfaq/lib/perlglossary.pod b/cpan/perlfaq/lib/perlglossary.pod index 8bd9aca247..6829a5d816 100644 --- a/cpan/perlfaq/lib/perlglossary.pod +++ b/cpan/perlfaq/lib/perlglossary.pod @@ -7,7 +7,7 @@ perlglossary - Perl Glossary =head1 VERSION -version 5.20230812 +version 5.20240218 =head1 DESCRIPTION @@ -3298,6 +3298,9 @@ called a “case structure”, named after the similar Pascal construct. Most switch statements in Perl are spelled C. See “The C statement” in Camel chapter 4, “Statements and Declarations”. +The C, C keywords and the smartmatch (C<~~>) operator will +be removed in Perl 5.42. + =item symbol Generally, XXany B or B. Often used @@ -3613,6 +3616,15 @@ characters with the General Category of Uppercase Letter, but any character with the Uppercase property, including some Letter Numbers and Symbols. Not to be confused with B. +=item UTF-8 string + +A L whose ordinals represent a valid sequence of UTF-8 bytes. +Sometimes called a "UTF-8 encoded string". + +(B This is unrelated to Perl’s internal +L<“UTF8 flag”|perlunifaq/What is "the UTF8 flag"?>, which only Perl itself +should usually care about. UTF-8 strings may have that flag set or unset.) + =back =head2 V