.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "perl5ifaq 3pm" .TH perl5ifaq 3pm "2019-07-29" "perl v5.28.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" perl5ifaq \- Frequently Asked Questions about perl5i .SH "Using perl5i" .IX Header "Using perl5i" .SS "What is perl5i?" .IX Subsection "What is perl5i?" perl5i is a Perl module. It is short for \*(L"Perl 5 + i\*(R". The \*(L"+ i\*(R" indicates a complex number, going off in a different direction than traditional Perl 5 development. .SS "What's the point of perl5i?" .IX Subsection "What's the point of perl5i?" perl5i is also about getting the defaults righter. Make Perl 5 \s-1DWIM\s0 better, without having to load a dozen Perl modules. .PP perl5i was originally conceived after Schwern had a conversation with a Ruby programmer who had a job writing Perl. He was listening to their complaints about Perl and providing better solutions where possible. What he found was a lot of the solutions were \*(L"go get this module from \s-1CPAN\*(R"\s0 or \*(L"turn on this pragma\*(R". \f(CW\*(C`use strict\*(C'\fR, \f(CW\*(C`use warnings\*(C'\fR, \f(CW\*(C`use autodie\*(C'\fR, \f(CW\*(C`use autobox\*(C'\fR, \f(CW\*(C`use List::Util\*(C'\fR, \f(CW\*(C`use DateTime\*(C'\fR. .PP Not only does this cause you to litter your code with a dozen use statements, it also requires tribal knowledge not necessarily available to the new programmer. To use Perl 5 well requires an experienced Perl programmer looking over your shoulder, giving you advice. .PP For the experienced Perl 5 programmer, using perl5i means writing less boilerplate code. It means not having to decide between doing it the right way and doing it the convenient way. For example, you probably should be using a proper exception handling module, but which one? And then you have to get it and remember to load it. perl5i gives you \&\f(CW\*(C`try\*(C'\fR and \f(CW\*(C`catch\*(C'\fR that are always there, there's no excuse not to do it right. .PP In some ways, perl5i is \*(L"The Best of \s-1CPAN\*(R"\s0 in code form. .SS "What's perl5i's relation to Perl 6?" .IX Subsection "What's perl5i's relation to Perl 6?" perl5i steals liberally from Perl 6. .PP perl5i is not intended as a competitor to Perl 6 nor an abandonment. But it's going to be a while before Perl 6 is production stable and we've got to get some work done before Christmas. .SS "What is perl5i's relation to Perl 5?" .IX Subsection "What is perl5i's relation to Perl 5?" perl5i is in some ways a release valve for the frustration surrounding Perl 5 development, particularly with regard to Perl 5's conservative backwards compatibility requirements. Patching Perl 5 is also out of the league of most Perl programmers (and a lot of C programmers). Can't get a feature into Perl 5? Put it in perl5i. .PP Since it has a liberal compatibility policy, perl5i serves as a testing ground for new features. It will let the community try out new concepts in the wild and see how it works out. For example, autoboxing has been available for years but was rejected from incusion in Perl 5 in part because Perl 5 programmers do not grok the benefits of everything being an object. .SS "Is perl5i intended for production?" .IX Subsection "Is perl5i intended for production?" Yes, the \s-1API\s0 is stable and its well tested. Its effects are mostly lexical and incompatibilities are with obscure \*(L"features\*(R" that you're probably not using. .PP Rather than reinventing the wheel, perl5i is mostly a wrapper around stable, well understood \s-1CPAN\s0 modules. It avoids unstable magic. .PP perl5i's interface is \fI\s-1NOT\s0\fR compatible between major versions, but fear not! perl5i has an intentional backwards incompatibility plan so that code written for one version will continue to work even after you upgrade. Please read \*(L"Using perl5i\*(R" in perl5i for details. .SS "What's perl5i's performance like?" .IX Subsection "What's perl5i's performance like?" perl5i tries to make you only pay for what you use. It delays loading most modules to keep startup time reasonable. .PP While we've been watching perl5i's weight, serious performance optimization has not begun. Interface and correctness take priority. .PP Autoboxed methods carry a run-time performance penalty similar to a normal method call. In general, because perl5i has to wrap much of Perl 5 it will run slower. Whether this actually effects the performance of your app should be determined by profiling your entire app and not just benchmarking individual operators. .PP perl5i's true performance comes out in helping the programmer write code faster and more consistently with less hand written code for common tasks. In some cases we've discovered perl5i works faster than the equivalent hand coded solution because perl5i can take advantage of very clever \s-1CPAN\s0 modules written in \s-1XS.\s0 Of course, you can do that without perl5i but we've done the research for you. .SH "Coding with perl5i" .IX Header "Coding with perl5i" Here are some ways to do traditional Perl 5 things the perl5i way. .SS "How do I tell if something is a number?" .IX Subsection "How do I tell if something is a number?" .Vb 7 \& $thing\->is_number; # it\*(Aqs something Perl thinks is a number \& $thing\->is_positive; # it\*(Aqs a positive number \& $thing\->is_negative; # it\*(Aqs a negative number \& $thing\->is_integer; # it\*(Aqs an integer, no decimal part \& $thing\->is_even; # it\*(Aqs an even integer \& $thing\->is_odd; # it\*(Aqs an odd integer \& $thing\->is_decimal; # it\*(Aqs a decimal number .Ve .PP This will work even if \f(CW$thing\fR is a reference (they will all return false). .SS "How do I get the difference between two arrays?" .IX Subsection "How do I get the difference between two arrays?" .Vb 1 \& my @diff = @array1\->diff(\e@array2); .Ve .PP Will return the elements in \f(CW@array1\fR which are not in \f(CW@array2\fR. .SS "How do I merge two hashes?" .IX Subsection "How do I merge two hashes?" If you don't mind overwriting one hash, and want to do a shallow merge, then use a hash slice. .PP .Vb 1 \& @hash1{ keys %hash2 } = values %hash2; .Ve .PP If you want to do a shallow copy but want to preserve the original hashes, copy the first hash and then do the hash slice technique. .PP .Vb 2 \& my %merged = %hash1; \& @merged{ keys %hash2 } = values %hash2; .Ve .PP If you want to do a recursive merge, merging any subhashes, use the \&\f(CW\*(C`merge\*(C'\fR method. .PP .Vb 2 \& my %hash1 = ( a => 1, b => { foo => 23 } ); \& my %hash2 = ( a => 100, b => { bar => 42 } ); \& \& # %hash1 is now ( a => 100, b => { foo => 23, bar => 42 } ) \& %hash1\->merge(\e%hash2); .Ve .SS "How can I get the unique keys from multiple hashes?" .IX Subsection "How can I get the unique keys from multiple hashes?" If the hashes are small, extract the keys into an array and use the \&\f(CW\*(C`uniq\*(C'\fR method. .PP .Vb 2 \& my @keys = (%hash1\->keys, %hash2\->keys); \& my @uniq = @keys\->uniq; .Ve .PP If the hashes contain a lot of keys, you can save memory by not building the intermediate \f(CW@keys\fR. .PP .Vb 6 \& my %seen; \& for my $hash (\e%hash1, \e%hash2) { \& $hash\->each( func($key) { \& $seen{$key} = 1; \& }); \& } \& \& my @uniq = %seen\->keys; .Ve .SS "How do I iterate through an array more than one at a time?" .IX Subsection "How do I iterate through an array more than one at a time?" Pass the \f(CW\*(C`foreach\*(C'\fR method a function which takes more than one parameter. \f(CW\*(C`foreach\*(C'\fR will iterate over the appropriate number of items. .PP .Vb 2 \& # Iterate two at a time. \& @array\->foreach( func($x,$y) { say "x: $x, y: $y" }; .Ve .PP See \*(L"foreach\*(R" in perl5i for details. .SS "How do I get information about the current date?" .IX Subsection "How do I get information about the current date?" \&\fBlocaltime()\fR, \fBgmtime()\fR and \fBtime()\fR all return DateTime objects in scalar context. .PP No more mucking around with \f(CW\*(C`$year += 1900\*(C'\fR. It's simply: .PP .Vb 2 \& my $now = localtime; \& my $year = $now\->year; .Ve .PP Or even: .PP .Vb 1 \& my $year = localtime\->year; .Ve .PP The name of the current month can be gotten with: .PP .Vb 1 \& my $month_name = localtime\->month_name; .Ve .PP You have the full range of DateTime features available. .SS "How do I alias a variable?" .IX Subsection "How do I alias a variable?" You call the \f(CW\*(C`alias()\*(C'\fR method on the variable you want to alias. .PP Here's an example turning an anonymous subroutine into a named method. .PP .Vb 4 \& my $class = "Some::Class"; \& my $name = "method_name"; \& my $code = sub { ... }; \& $code\->alias($class, $name); .Ve .PP \&\f(CW\*(C`Some::Class\->method_name\*(C'\fR will now call the \f(CW$code\fR. .PP This works for arrays, hashes and scalars. See \*(L"\fBalias()\fR\*(R" in perl5i for details. .SS "How do I use a module from a variable?" .IX Subsection "How do I use a module from a variable?" Call the require method on that variable. .PP .Vb 2 \& my $module = "Some::Module"; \& $module\->require; .Ve .PP If you want to import symbols, you can call import as well. .PP .Vb 1 \& $module\->require\->import; .Ve .PP See \*(L"require\*(R" in perl5i for details. .SS "How do I strip whitespace off a string?" .IX Subsection "How do I strip whitespace off a string?" Use the \f(CW\*(C`trim()\*(C'\fR method. .PP .Vb 2 \& my $string = " some stuff "; \& $string = $string\->trim; # $string is now "some stuff" .Ve .PP See \*(L"\fBtrim()\fR\*(R" in perl5i for details. .SS "How do I find information about my caller?" .IX Subsection "How do I find information about my caller?" \&\f(CW\*(C`caller()\*(C'\fR returns an object in scalar context which you can query for information. .PP .Vb 3 \& my $caller = caller(); \& printf "Something something something dark side at %s line %d.\en", \& $caller\->filename, $caller\->line; .Ve .SS "How do I write my code in \s-1UTF8\s0?" .IX Subsection "How do I write my code in UTF8?" perl5i enables \s-1UTF8\s0 processing of code, arguments, strings and filehandles. Working with \s-1UTF8\s0 should just work. .SS "How do I read/write a non\-UTF8 file?" .IX Subsection "How do I read/write a non-UTF8 file?" Since all filehandles are treated as \s-1UTF8,\s0 if you want to work on non\-UTF8 data you will have to say so explicitly. Usually this involves calling \f(CW\*(C`binmode\*(C'\fR on the filehandle. .PP Here's an example of writing an image file. .PP .Vb 3 \& open my $fh, ">", $image_file; \& binmode $fh; \& print $fh $image_data; .Ve .PP Here's an example of Latin\-1. .PP .Vb 3 \& open my $fh, ">", $file; \& binmode $fh, ":encoding(Latin\-1)"; \& print $fh $text; .Ve .PP If \s-1UTF8\s0 is not to your liking you can switch the default encoding of newly opened filehandles with the \f(CW\*(C`open\*(C'\fR pragma. .PP .Vb 2 \& use open ":encoding(Latin\-1)"; # new filehandles will be Latin\-1 \& use open ":std"; # so will STDOUT, STDERR and STDIN .Ve .PP See \*(L"utf8\*(R" in perl5i for details. .SS "How do I get the name of the current class?" .IX Subsection "How do I get the name of the current class?" The \f(CW$CLASS\fR variable and \s-1CLASS\s0 constant are exported by perl5i and it contains the name of the current class. .PP .Vb 2 \& CLASS\->class_method(@args); \& say "OMG! You\*(Aqre using class $CLASS."; .Ve .PP See \*(L"\s-1CLASS\*(R"\s0 in per5i for details. .SS "How do I get the current directory?" .IX Subsection "How do I get the current directory?" Simply read \f(CW$CWD\fR. See \*(L"File::chdir\*(R" in perl5i for details. .SS "How do I temporarily change the directory?" .IX Subsection "How do I temporarily change the directory?" If a function has to change directory, it's polite to change it back before returning. perl5i provides \f(CW\*(C`local $CWD\*(C'\fR to accomplish this. .PP .Vb 5 \& sub do_things { \& local $CWD = "some/subdir"; \& ... do unspeakable things in some/subdir ... \& return $whatever; \& } \& \& chdir "/some/path"; \& do_things(); # do_things operates in /some/path/some/subdir \& say $CWD; # prints /some/path .Ve .PP Even if the code in \fBdo_things()\fR dies, it will still return to the original directory. .PP See \*(L"File::chdir\*(R" in perl5i for details. .SS "How do I catch an exception?" .IX Subsection "How do I catch an exception?" Use \f(CW\*(C`try/catch\*(C'\fR. .PP .Vb 2 \& try { some_code() } \& catch { warn "some_code() didn\*(Aqt work because: $_" }; .Ve .PP See \*(L"Try::Tiny\*(R" in perl5i for details. .ie n .SS "How do I get the output of ""system""?" .el .SS "How do I get the output of \f(CWsystem\fP?" .IX Subsection "How do I get the output of system?" Use \f(CW\*(C`capture\*(C'\fR. .PP .Vb 3 \& my $output = capture { \& system "command", "and", "some", "arguments"; \& }; .Ve .PP See \*(L"\fBcapture()\fR\*(R" in perl5i. .SS "How can I capture \s-1STDERR\s0?" .IX Subsection "How can I capture STDERR?" Use \f(CW\*(C`capture\*(C'\fR. .PP .Vb 3 \& my($stdout, $stderr) = capture { \& ...anything run in here will have STDOUT and STDERR captured. \& }; .Ve .PP This will capture \f(CW\*(C`STDOUT\*(C'\fR and \f(CW\*(C`STDERR\*(C'\fR separately. To capture them together in one variable, use the \f(CW\*(C`merge\*(C'\fR option. .PP .Vb 3 \& my $output = capture { \& ...anything run in here will have STDOUT and STDERR captured... \& } merge => 1; .Ve .PP See \*(L"\fBcapture()\fR\*(R" in perl5i. .SS "How can I call backticks without shell processing?" .IX Subsection "How can I call backticks without shell processing?" You can't. What you can do instead is use \f(CW\*(C`capture\*(C'\fR and \f(CW\*(C`system\*(C'\fR with multiple arguments. .PP .Vb 3 \& my $output = capture { \& system $command, @options; \& }; .Ve .PP See \*(L"\fBcapture()\fR\*(R" in perl5i. .SS "How do I make my distribution depend on perl5i?" .IX Subsection "How do I make my distribution depend on perl5i?" perl5i is not backwards compatible across major versions. This is why when you use perl5i you use a major version such as \f(CW\*(C`use perl5i::2\*(C'\fR. This guarantees that code you write will continue to work even after perl5i has changed. .PP When depending on perl5i, depend on the specific major version. That is, depend on \f(CW\*(C`perl5i::2\*(C'\fR and not \f(CW\*(C`perl5i\*(C'\fR. This is because older versions will eventually be spun out into their own separate distributions to avoid cluttering the main dist. If you depend on \&\f(CW\*(C`perl5i::2\*(C'\fR then the \s-1CPAN\s0 shell will always be able to find it. .SS "How do I make perlcritic recognize perl5i?" .IX Subsection "How do I make perlcritic recognize perl5i?" perl5i turns on strict and warnings, but by default perlcritic does not recognize this. You can add perl5i to the default set of modules in your \fI.perlcriticrc\fR. .PP .Vb 2 \& [TestingAndDebugging::RequireUseWarnings] \& equivalent_modules = perl5i::2 \& \& [TestingAndDebugging::RequireUseStrict] \& equivalent_modules = perl5i::2 .Ve .SH "perl5i Development" .IX Header "perl5i Development" .SS "Where can I find out more about perl5i?" .IX Subsection "Where can I find out more about perl5i?" You can follow perl5i development on Twitter at , our Github page at and wiki at . Discussions on \s-1IRC\s0 are on on channel #perl5i. .SS "I have a great idea I want to add! How can I help?" .IX Subsection "I have a great idea I want to add! How can I help?" Wonderful! Let us know. The best way is to create an issue in the issue tracker at . Think of it less as an issue tracker and more of a web forum with great tagging. .PP What is particularly useful to perl5i is to hear about problems you'd like solved. Tell us about a simple problem that you had to write too much code to solve, or load too many modules, or that had too many caveats. .PP Finally, if you just want to write some code, you can fork and work on it at . Full details on our patching policy can be read at . .PP We'd like to hear from you. Don't worry if you're doing it right, come talk with us. .SS "Why doesn't perl5i use Moose?" .IX Subsection "Why doesn't perl5i use Moose?" We'd love to, but Moose more than doubles perl5i's startup time. .PP In addition, simply using Moose doesn't buy you much. Like perl5i, it is one line to fix much of Perl's \s-1OO\s0 woes. But even Moose needs fixing. What we would really like is to be able to conditionally use MooseX::Declare which fixes Perl's \s-1OO\s0 syntax as well as provides some better Moose defaults. But that has the double whammy of using Devel::Declare and Moose. .SS "Why doesn't perl5i use Class::MOP?" .IX Subsection "Why doesn't perl5i use Class::MOP?" Class::MOP is more about method declaration and dispatch. Our meta-object is more about things you want to do to every object but don't want to pollute the \s-1UNIVERSAL\s0 namespace with. .SS "perl5i has too many dependencies!" .IX Subsection "perl5i has too many dependencies!" That's not a question. Eventually, perl5i will look into a bundling solution to ease the dependency hell it's rapidly descending into. In general we've favored using a \s-1CPAN\s0 module over writing it ourselves so maintenance can be distributed. .PP We monitor the health of our dependencies and try to pick ones which are solid or fix those which fail too often.