Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 465 lines (294 sloc) 14.344 kB
932b6e7 @schwern Start writing perl5ifaq
schwern authored
1 =pod
2
c473c8d @avar Make perl5i MËTÁŁ, not MËTÁÅ: Set =encoding utf8 on POD
avar authored
3 =encoding utf8
4
932b6e7 @schwern Start writing perl5ifaq
schwern authored
5 =head1 NAME
6
7 perl5ifaq - Frequently Asked Questions about perl5i
8
9 =head1 Using perl5i
10
11 =head2 What is perl5i?
12
13 perl5i is a Perl module. It is short for "Perl 5 + i". The "+ i"
14 indicates a complex number, going off in a different direction than
15 traditional Perl 5 development.
16
17 =head2 What's the point of perl5i?
18
199b686 @schwern Finish up answering the questions in the FAQ.
schwern authored
19 perl5i is also about getting the defaults righter. Make Perl 5 DWIM
20 better, without having to load a dozen Perl modules.
21
932b6e7 @schwern Start writing perl5ifaq
schwern authored
22 perl5i was originally conceived after Schwern had a conversation with
23 a Ruby programmer who had a job writing Perl. He was listening to
24 their complaints about Perl and providing better solutions where
25 possible. What he found was a lot of the solutions were "go get this
26 module from CPAN" or "turn on this pragma". C<use strict>, C<use
27 warnings>, C<use autodie>, C<use autobox>, C<use List::Util>, C<use
28 DateTime>.
29
30 Not only does this cause you to litter your code with a dozen use
31 statements, it also requires tribal knowledge not neccessarily
199b686 @schwern Finish up answering the questions in the FAQ.
schwern authored
32 available to the new programmer. To use Perl 5 well requires an
33 experienced Perl programmer looking over your shoulder, giving you
34 advice.
35
36 For the experienced Perl 5 programmer, using perl5i means writing less
37 boilerplate code. It means not having to decide between doing it the
38 right way and doing it the convenient way. For example, you probably
39 should be using a proper exception handling module, but which one?
40 And then you have to get it and remember to load it. perl5i gives you
41 C<try> and C<catch> that are always there, there's no excuse not to
42 do it right.
932b6e7 @schwern Start writing perl5ifaq
schwern authored
43
00386d1 @schwern Explain the hopes that perl5i will serve as a testing ground for Perl 5.
schwern authored
44 In some ways, perl5i is "The Best of CPAN" in code form.
45
932b6e7 @schwern Start writing perl5ifaq
schwern authored
46
47 =head2 What's perl5i's relation to Perl 6?
48
49 perl5i steals liberally from Perl 6.
50
51 perl5i is not intended as a competitor to Perl 6 nor an abandonment.
7f09040 @brunoV minor typo fixes in perl5ifaq.pod
brunoV authored
52 But it's going to be a while before Perl 6 is production stable and
932b6e7 @schwern Start writing perl5ifaq
schwern authored
53 we've got to get some work done before Christmas.
54
55
00386d1 @schwern Explain the hopes that perl5i will serve as a testing ground for Perl 5.
schwern authored
56 =head2 What is perl5i's relation to Perl 5?
57
58 perl5i is in some ways a release valve for the frustration surrounding
59 Perl 5 development, particularly with regard to Perl 5's conservative
60 backwards compatibility requirements. Patching Perl 5 is also out of
61 the league of most Perl programmers (and a lot of C programmers).
62 Can't get a feature into Perl 5? Put it in perl5i.
63
64 Since it has a liberal compatibility policy, perl5i serves as a
65 testing ground for new features. It will let the community try out
66 new concepts in the wild and see how it works out. For example,
67 autoboxing has been available for years but was rejected from incusion
68 in Perl 5 in part because Perl 5 programmers do not grok the benefits
69 of everything being an object.
70
71
932b6e7 @schwern Start writing perl5ifaq
schwern authored
72 =head2 Is perl5i intended for production?
73
7f7ca78 @schwern Explain better why perl5i is safe for production use.
schwern authored
74 Yes, the API is stable and its well tested. Its effects are mostly
75 lexical and incompatibilities are with obscure "features" that you're
76 probably not using.
77
78 Rather than reinventing the wheel, perl5i is mostly a wrapper around
79 stable, well understood CPAN modules. It avoids unstable magic.
199b686 @schwern Finish up answering the questions in the FAQ.
schwern authored
80
81 perl5i's interface is I<NOT> compatible between major versions, but
82 fear not! perl5i has an intentional backwards incompatibility plan so
83 that code written for one version will continue to work even after you
84 upgrade. Please read L<perl5i/Using perl5i> for details.
85
932b6e7 @schwern Start writing perl5ifaq
schwern authored
86
87 =head2 What's perl5i's performance like?
88
89 perl5i tries to make you only pay for what you use. It delays loading
90 most modules to keep startup time reasonable.
91
92 While we've been watching perl5i's weight, serious performance
93 optimization has not begun. Interface and correctness take priority.
94
95 Autoboxed methods carry a run-time performance penalty similar to a
96 normal method call. In general, because perl5i has to wrap much of
97 Perl 5 it will run slower. Whether this actually effects the
98 performance of your app should be determined by profiling your entire
99 app and not just benchmarking individual operators.
100
101 perl5i's true performance comes out in helping the programmer write
102 code faster and more consistently with less hand written code for
103 common tasks. In some cases we've discovered perl5i works faster than
104 the equivalent hand coded solution because perl5i can take advantage
105 of very clever CPAN modules written in XS. Of course, you can do that
106 without perl5i but we've done the research for you.
107
108
109 =head1 Coding with perl5i
110
199b686 @schwern Finish up answering the questions in the FAQ.
schwern authored
111 Here are some ways to do traditional Perl 5 things the perl5i way.
112
113
932b6e7 @schwern Start writing perl5ifaq
schwern authored
114 =head2 How do I tell if something is a number?
115
7f09040 @brunoV minor typo fixes in perl5ifaq.pod
brunoV authored
116 $thing->is_number; # it's something Perl thinks is a number
117 $thing->is_positive; # it's a positive number
118 $thing->is_negative; # it's a negative number
119 $thing->is_integer; # it's an integer, no decimal part
8f1067c @ezarko Added is_even and is_odd [github 143]
ezarko authored
120 $thing->is_even; # it's an even integer
121 $thing->is_odd; # it's an odd integer
7f09040 @brunoV minor typo fixes in perl5ifaq.pod
brunoV authored
122 $thing->is_decimal; # it's a decimal number
932b6e7 @schwern Start writing perl5ifaq
schwern authored
123
199b686 @schwern Finish up answering the questions in the FAQ.
schwern authored
124 This will work even if $thing is a reference (they will all return
125 false).
126
932b6e7 @schwern Start writing perl5ifaq
schwern authored
127
128 =head2 How do I get the difference between two arrays?
129
7f09040 @brunoV minor typo fixes in perl5ifaq.pod
brunoV authored
130 my @diff = @array1->diff(\@array2);
932b6e7 @schwern Start writing perl5ifaq
schwern authored
131
a4a0cfe @brunoV fix typo in perl5ifaq
brunoV authored
132 Will return the elements in @array1 which are not in @array2.
932b6e7 @schwern Start writing perl5ifaq
schwern authored
133
134
69923ac @schwern Add (and test) some perl5ifaq entries about hashes.
schwern authored
135 =head2 How do I merge two hashes?
136
137 If you don't mind overwriting one hash, and want to do a shallow
138 merge, then use a hash slice.
139
140 @hash1{ keys %hash2 } = values %hash2;
141
142 If you want to do a shallow copy but want to preserve the original
143 hashes, copy the first hash and then do the hash slice technique.
144
145 my %merged = %hash1;
146 @merged{ keys %hash2 } = values %hash2;
147
148 If you want to do a recursive merge, merging any subhashes, use the
149 C<merge> method.
150
151 my %hash1 = ( a => 1, b => { foo => 23 } );
152 my %hash2 = ( a => 100, b => { bar => 42 } );
153
154 # %hash1 is now ( a => 100, b => { foo => 23, bar => 42 } )
155 %hash1->merge(\%hash2);
156
157
158 =head2 How can I get the unique keys from multiple hashes?
159
160 If the hashes are small, extract the keys into an array and use the
161 C<uniq> method.
162
163 my @keys = (%hash1->keys, %hash2->keys);
164 my @uniq = @keys->uniq;
165
166 If the hashes contain a lot of keys, you can save memory by not
167 building the intermediate @keys.
168
169 my %seen;
170 for my $hash (\%hash1, \%hash2) {
171 $hash->each( func($key) {
172 $seen{$key} = 1;
173 });
174 }
175
176 my @uniq = %seen->keys;
177
178
4f8dc11 @schwern Add "how do I iterate over more than one item at a time" FAQ
schwern authored
179 =head2 How do I iterate through an array more than one at a time?
180
181 Pass the C<foreach> method a function which takes more than one
182 parameter. C<foreach> will iterate over the appropriate number of
183 items.
184
185 # Iterate two at a time.
186 @array->foreach( func($x,$y) { say "x: $x, y: $y" };
187
188 See L<perl5i/foreach> for details.
189
190
932b6e7 @schwern Start writing perl5ifaq
schwern authored
191 =head2 How do I get information about the current date?
192
193 localtime(), gmtime() and time() all return L<DateTime> objects in
194 scalar context.
195
7f09040 @brunoV minor typo fixes in perl5ifaq.pod
brunoV authored
196 No more mucking around with C<$year += 1900>. It's simply:
932b6e7 @schwern Start writing perl5ifaq
schwern authored
197
198 my $now = localtime;
199 my $year = $now->year;
200
201 Or even:
202
203 my $year = localtime->year;
204
205 The name of the current month can be gotten with:
206
207 my $month_name = localtime->month_name;
208
209 You have the full range of L<DateTime> features available.
210
211
e09f0ef @schwern Fill in more FAQ questions.
schwern authored
212 =head2 How do I alias a variable?
213
214 You call the C<alias()> method on the variable you want to alias.
215
216 Here's an example turning an anonymous subroutine into a named method.
217
218 my $class = "Some::Class";
219 my $name = "method_name";
220 my $code = sub { ... };
221 $code->alias($class, $name);
222
223 C<< Some::Class->method_name >> will now call the C<$code>.
224
225 This works for arrays, hashes and scalars. See L<perl5i/alias()> for
226 details.
227
228
229 =head2 How do I use a module from a variable?
230
cb67d0b @schwern Eliminate load() and add a much simpler require(). [github 107]
schwern authored
231 Call the L<require> method on that variable.
e09f0ef @schwern Fill in more FAQ questions.
schwern authored
232
233 my $module = "Some::Module";
cb67d0b @schwern Eliminate load() and add a much simpler require(). [github 107]
schwern authored
234 $module->require;
235
236 If you want to import symbols, you can call import as well.
237
238 $module->require->import;
239
240 See L<perl5i/require> for details.
e09f0ef @schwern Fill in more FAQ questions.
schwern authored
241
242
243 =head2 How do I strip whitespace off a string?
244
245 Use the C<trim()> method.
246
247 my $string = " some stuff ";
248 $string = $string->trim; # $string is now "some stuff"
249
250 See L<perl5i/trim()> for details.
251
252 =head2 How do I find information about my caller?
253
254 C<caller()> returns an object in scalar context which you can query
255 for information.
256
257 my $caller = caller();
258 printf "Something something something dark side at %s line %d.\n",
259 $caller->filename, $caller->line;
260
261 =head2 How do I write my code in UTF8?
262
263 perl5i enables UTF8 processing of code, arguments, strings and
264 filehandles. Working with UTF8 should just work.
265
266 =head2 How do I read/write a non-UTF8 file?
267
268 Since all filehandles are treated as UTF8, if you want to work on
269 non-UTF8 data you will have to say so explicitly. Usually this
270 involves calling C<binmode> on the filehandle.
271
272 Here's an example of writing an image file.
273
274 open my $fh, ">", $image_file;
275 binmode $fh;
276 print $fh $image_data;
277
278 Here's an example of Latin-1.
279
280 open my $fh, ">", $file;
281 binmode $fh, ":encoding(Latin-1)";
282 print $fh $text;
283
596871f @raforg Fixed three grammatical errors ("not to you[r] liking", "temporar[il]…
raforg authored
284 If UTF8 is not to your liking you can switch the default encoding of
e09f0ef @schwern Fill in more FAQ questions.
schwern authored
285 newly opened filehandles with the C<open> pragma.
286
287 use open ":encoding(Latin-1)"; # new filehandles will be Latin-1
288 use open ":std"; # so will STDOUT, STDERR and STDIN
289
290 See L<perl5i/utf8> for details.
291
292 =head2 How do I get the name of the current class?
293
294 The $CLASS variable and CLASS constant are exported by perl5i and it
295 contains the name of the current class.
296
297 CLASS->class_method(@args);
56be957 @schwern Change "print" in docs to "say"
schwern authored
298 say "OMG! You're using class $CLASS.";
e09f0ef @schwern Fill in more FAQ questions.
schwern authored
299
300 See L<per5i/CLASS> for details.
301
302 =head2 How do I get the current directory?
303
304 Simply read $CWD. See L<perl5i/File::chdir> for details.
305
596871f @raforg Fixed three grammatical errors ("not to you[r] liking", "temporar[il]…
raforg authored
306 =head2 How do I temporarily change the directory?
e09f0ef @schwern Fill in more FAQ questions.
schwern authored
307
7f09040 @brunoV minor typo fixes in perl5ifaq.pod
brunoV authored
308 If a function has to change directory, it's polite to change it back
e09f0ef @schwern Fill in more FAQ questions.
schwern authored
309 before returning. perl5i provides C<local $CWD> to accomplish this.
310
311 sub do_things {
312 local $CWD = "some/subdir";
313 ... do unspeakable things in some/subdir ...
314 return $whatever;
315 }
316
317 chdir "/some/path";
318 do_things(); # do_things operates in /some/path/some/subdir
56be957 @schwern Change "print" in docs to "say"
schwern authored
319 say $CWD; # prints /some/path
e09f0ef @schwern Fill in more FAQ questions.
schwern authored
320
321 Even if the code in do_things() dies, it will still return to the
322 original directory.
323
324 See L<perl5i/File::chdir> for details.
325
326 =head2 How do I catch an exception?
327
328 Use C<try/catch>.
329
330 try { some_code() }
331 catch { warn "some_code() didn't work because: $_" };
332
333 See L<perl5i/Try::Tiny> for details.
334
335
fb1292b @schwern Add capture() entries to perl5ifaq based on perlfaq8 questions.
schwern authored
336 =head2 How do I get the output of C<system>?
337
338 Use C<capture>.
339
340 my $output = capture {
341 system "command", "and", "some", "arguments";
342 };
343
344 See L<perl5i/capture()>.
345
346
347 =head2 How can I capture STDERR?
348
349 Use C<capture>.
350
351 my($stdout, $stderr) = capture {
352 ...anything run in here will have STDOUT and STDERR captured.
353 };
354
355 This will capture C<STDOUT> and C<STDERR> separately. To capture them
356 together in one variable, use the C<merge> option.
357
358 my $output = capture {
359 ...anything run in here will have STDOUT and STDERR captured...
360 } merge => 1;
361
362 See L<perl5i/capture()>.
363
364
365 =head2 How can I call backticks without shell processing?
366
367 You can't. What you can do instead is use C<capture> and C<system>
368 with multiple arguments.
369
370 my $output = capture {
371 system $command, @options;
372 };
373
374 See L<perl5i/capture()>.
375
376
932b6e7 @schwern Start writing perl5ifaq
schwern authored
377 =head2 How do I make my distribution depend on perl5i?
378
379 perl5i is not backwards compatible across major versions. This is why
a623168 @schwern Create version 2.
schwern authored
380 when you use perl5i you use a major version such as C<use perl5i::2>.
932b6e7 @schwern Start writing perl5ifaq
schwern authored
381 This guarantees that code you write will continue to work even after
382 perl5i has changed.
383
384 When depending on perl5i, depend on the specific major version. That
a623168 @schwern Create version 2.
schwern authored
385 is, depend on C<perl5i::2> and not C<perl5i>. This is because older
69de7b9 @gregoa POD spelling fixes from Debian [rt.cpan.org 71254]
gregoa authored
386 versions will eventually be spun out into their own separate
932b6e7 @schwern Start writing perl5ifaq
schwern authored
387 distributions to avoid cluttering the main dist. If you depend on
a623168 @schwern Create version 2.
schwern authored
388 C<perl5i::2> then the CPAN shell will always be able to find it.
932b6e7 @schwern Start writing perl5ifaq
schwern authored
389
390
8387d5c @schwern FAQ on how to make perlcritic aware of perl5i
schwern authored
391 =head2 How do I make perlcritic recognize perl5i?
392
393 perl5i turns on strict and warnings, but by default perlcritic does
394 not recognize this. You can add perl5i to the default set of modules
395 in your F<.perlcriticrc>.
396
397 [TestingAndDebugging::RequireUseWarnings]
398 equivalent_modules = perl5i::2
399
400 [TestingAndDebugging::RequireUseStrict]
401 equivalent_modules = perl5i::2
402
403
932b6e7 @schwern Start writing perl5ifaq
schwern authored
404 =head1 perl5i Development
405
406 =head2 Where can I find out more about perl5i?
407
78a91d6 @schwern Remove references to IRC, mailing list. Add wiki, twitter.
schwern authored
408 You can follow perl5i development on Twitter at L<http://twitter.com/perl5i>,
83aebda @schwern The repository has moved to evalEmpire.
schwern authored
409 our Github page at L<https://github.com/evalEmpire/perl5i> and wiki at
410 L<https://github.com/evalEmpire/perl5i/wiki>. Discussions on IRC are on
990a7da @schwern Put the IRC channel back.
schwern authored
411 L<irc://irc.perl.org> on channel #perl5i.
932b6e7 @schwern Start writing perl5ifaq
schwern authored
412
413
414 =head2 I have a great idea I want to add! How can I help?
415
416 Wonderful! Let us know. The best way is to create an issue in the
83aebda @schwern The repository has moved to evalEmpire.
schwern authored
417 issue tracker at L<http://github.com/evalEmpire/perl5i/issues>. Think of
932b6e7 @schwern Start writing perl5ifaq
schwern authored
418 it less as an issue tracker and more of a web forum with great
419 tagging.
420
38458f4 @schwern Encourage users to send us their problems with Perl 5.
schwern authored
421 What is particularly useful to perl5i is to hear about problems you'd
422 like solved. Tell us about a simple problem that you had to write too
423 much code to solve, or load too many modules, or that had too many
424 caveats.
425
932b6e7 @schwern Start writing perl5ifaq
schwern authored
426 Finally, if you just want to write some code, you can fork and work on
83aebda @schwern The repository has moved to evalEmpire.
schwern authored
427 it at L<http://github.com/evalEmpire/perl5i>. Full details on our
932b6e7 @schwern Start writing perl5ifaq
schwern authored
428 patching policy can be read at
83aebda @schwern The repository has moved to evalEmpire.
schwern authored
429 L<http://github.com/evalEmpire/perl5i/raw/master/PATCHING>.
932b6e7 @schwern Start writing perl5ifaq
schwern authored
430
431 We'd like to hear from you. Don't worry if you're doing it right,
432 come talk with us.
433
434
435 =head2 Why doesn't perl5i use Moose?
436
437 We'd love to, but L<Moose> more than doubles perl5i's startup time.
438
439 In addition, simply using Moose doesn't buy you much. Like perl5i, it
440 is one line to fix much of Perl's OO woes. But even Moose needs
441 fixing. What we would really like is to be able to conditionally use
442 L<MooseX::Declare> which fixes Perl's OO syntax as well as provides
443 some better Moose defaults. But that has the double whammy of using
444 L<Devel::Declare> and L<Moose>.
445
446
447 =head2 Why doesn't perl5i use Class::MOP?
448
449 L<Class::MOP> is more about method declaration and dispatch. Our
450 meta-object is more about things you want to do to every object but
451 don't want to pollute the UNIVERSAL namespace with.
452
453
454 =head2 perl5i has too many dependencies!
455
456 That's not a question. Eventually, perl5i will look into a bundling
596871f @raforg Fixed three grammatical errors ("not to you[r] liking", "temporar[il]…
raforg authored
457 solution to ease the dependency hell it's rapidly descending into. In
932b6e7 @schwern Start writing perl5ifaq
schwern authored
458 general we've favored using a CPAN module over writing it ourselves so
459 maintenance can be distributed.
460
461 We monitor the health of our dependencies and try to pick ones which
462 are solid or fix those which fail too often.
463
464 =cut
Something went wrong with that request. Please try again.