This file is indexed.

/usr/share/perl5/perl5ifaq.pod is in libperl5i-perl 2.13.2-1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
=pod

=encoding utf8

=head1 NAME

perl5ifaq - Frequently Asked Questions about perl5i

=head1 Using perl5i

=head2 What is perl5i?

perl5i is a Perl module.  It is short for "Perl 5 + i".  The "+ i"
indicates a complex number, going off in a different direction than
traditional Perl 5 development.

=head2 What's the point of perl5i?

perl5i is also about getting the defaults righter.  Make Perl 5 DWIM
better, without having to load a dozen Perl modules.

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 "go get this
module from CPAN" or "turn on this pragma".  C<use strict>, C<use
warnings>, C<use autodie>, C<use autobox>, C<use List::Util>, C<use
DateTime>.

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.

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
C<try> and C<catch> that are always there, there's no excuse not to
do it right.

In some ways, perl5i is "The Best of CPAN" in code form.


=head2 What's perl5i's relation to Perl 6?

perl5i steals liberally from Perl 6.

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.


=head2 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.

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.


=head2 Is perl5i intended for production?

Yes, the API is stable and its well tested.  Its effects are mostly
lexical and incompatibilities are with obscure "features" that you're
probably not using.

Rather than reinventing the wheel, perl5i is mostly a wrapper around
stable, well understood CPAN modules.  It avoids unstable magic.

perl5i's interface is I<NOT> 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<perl5i/Using perl5i> for details.


=head2 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.

While we've been watching perl5i's weight, serious performance
optimization has not begun.  Interface and correctness take priority.

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.

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 CPAN modules written in XS.  Of course, you can do that
without perl5i but we've done the research for you.


=head1 Coding with perl5i

Here are some ways to do traditional Perl 5 things the perl5i way.


=head2 How do I tell if something is a number?

  $thing->is_number;     # it's something Perl thinks is a number
  $thing->is_positive;   # it's a positive number
  $thing->is_negative;   # it's a negative number
  $thing->is_integer;    # it's an integer, no decimal part
  $thing->is_even;       # it's an even integer
  $thing->is_odd;        # it's an odd integer
  $thing->is_decimal;    # it's a decimal number

This will work even if $thing is a reference (they will all return
false).


=head2 How do I get the difference between two arrays?

  my @diff = @array1->diff(\@array2);

Will return the elements in @array1 which are not in @array2.


=head2 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.

    @hash1{ keys %hash2 } = values %hash2;

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.

    my %merged = %hash1;
    @merged{ keys %hash2 } = values %hash2;

If you want to do a recursive merge, merging any subhashes, use the
C<merge> method.

    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(\%hash2);


=head2 How can I get the unique keys from multiple hashes?

If the hashes are small, extract the keys into an array and use the
C<uniq> method.

    my @keys = (%hash1->keys, %hash2->keys);
    my @uniq = @keys->uniq;

If the hashes contain a lot of keys, you can save memory by not
building the intermediate @keys.

    my %seen;
    for my $hash (\%hash1, \%hash2) {
        $hash->each( func($key) {
            $seen{$key} = 1;
        });
    }

    my @uniq = %seen->keys;


=head2 How do I iterate through an array more than one at a time?

Pass the C<foreach> method a function which takes more than one
parameter.  C<foreach> will iterate over the appropriate number of
items.

  # Iterate two at a time.
  @array->foreach( func($x,$y) { say "x: $x, y: $y" };

See L<perl5i/foreach> for details.


=head2 How do I get information about the current date?

localtime(), gmtime() and time() all return L<DateTime> objects in
scalar context.

No more mucking around with C<$year += 1900>.  It's simply:

    my $now = localtime;
    my $year = $now->year;

Or even:

    my $year = localtime->year;

The name of the current month can be gotten with:

    my $month_name = localtime->month_name;

You have the full range of L<DateTime> features available.


=head2 How do I alias a variable?

You call the C<alias()> method on the variable you want to alias.

Here's an example turning an anonymous subroutine into a named method.

    my $class = "Some::Class";
    my $name = "method_name";
    my $code = sub { ... };
    $code->alias($class, $name);

C<< Some::Class->method_name >> will now call the C<$code>.

This works for arrays, hashes and scalars.  See L<perl5i/alias()> for
details.


=head2 How do I use a module from a variable?

Call the L<require> method on that variable.

    my $module = "Some::Module";
    $module->require;

If you want to import symbols, you can call import as well.

    $module->require->import;

See L<perl5i/require> for details.


=head2 How do I strip whitespace off a string?

Use the C<trim()> method.

    my $string = "  some stuff  ";
    $string = $string->trim;  # $string is now "some stuff"

See L<perl5i/trim()> for details.

=head2 How do I find information about my caller?

C<caller()> returns an object in scalar context which you can query
for information.

    my $caller = caller();
    printf "Something something something dark side at %s line %d.\n",
        $caller->filename, $caller->line;

=head2 How do I write my code in UTF8?

perl5i enables UTF8 processing of code, arguments, strings and
filehandles.  Working with UTF8 should just work.

=head2 How do I read/write a non-UTF8 file?

Since all filehandles are treated as UTF8, if you want to work on
non-UTF8 data you will have to say so explicitly.  Usually this
involves calling C<binmode> on the filehandle.

Here's an example of writing an image file.

    open my $fh, ">", $image_file;
    binmode $fh;
    print $fh $image_data;

Here's an example of Latin-1.

    open my $fh, ">", $file;
    binmode $fh, ":encoding(Latin-1)";
    print $fh $text;

If UTF8 is not to your liking you can switch the default encoding of
newly opened filehandles with the C<open> pragma.

    use open ":encoding(Latin-1)";  # new filehandles will be Latin-1
    use open ":std";                # so will STDOUT, STDERR and STDIN

See L<perl5i/utf8> for details.

=head2 How do I get the name of the current class?

The $CLASS variable and CLASS constant are exported by perl5i and it
contains the name of the current class.

    CLASS->class_method(@args);
    say "OMG! You're using class $CLASS.";

See L<per5i/CLASS> for details.

=head2 How do I get the current directory?

Simply read $CWD.  See L<perl5i/File::chdir> for details.

=head2 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 C<local $CWD> to accomplish this.

    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

Even if the code in do_things() dies, it will still return to the
original directory.

See L<perl5i/File::chdir> for details.

=head2 How do I catch an exception?

Use C<try/catch>.

    try   { some_code() }
    catch { warn "some_code() didn't work because: $_" };

See L<perl5i/Try::Tiny> for details.


=head2 How do I get the output of C<system>?

Use C<capture>.

    my $output = capture {
        system "command", "and", "some", "arguments";
    };

See L<perl5i/capture()>.


=head2 How can I capture STDERR?

Use C<capture>.

    my($stdout, $stderr) = capture {
        ...anything run in here will have STDOUT and STDERR captured.
    };

This will capture C<STDOUT> and C<STDERR> separately.  To capture them
together in one variable, use the C<merge> option.

    my $output = capture {
        ...anything run in here will have STDOUT and STDERR captured...
    } merge => 1;

See L<perl5i/capture()>.


=head2 How can I call backticks without shell processing?

You can't.  What you can do instead is use C<capture> and C<system>
with multiple arguments.

    my $output = capture {
        system $command, @options;
    };

See L<perl5i/capture()>.


=head2 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 C<use perl5i::2>.
This guarantees that code you write will continue to work even after
perl5i has changed.

When depending on perl5i, depend on the specific major version.  That
is, depend on C<perl5i::2> and not C<perl5i>.  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
C<perl5i::2> then the CPAN shell will always be able to find it.


=head2 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 F<.perlcriticrc>.

    [TestingAndDebugging::RequireUseWarnings]
    equivalent_modules = perl5i::2

    [TestingAndDebugging::RequireUseStrict]
    equivalent_modules = perl5i::2


=head1 perl5i Development

=head2 Where can I find out more about perl5i?

You can follow perl5i development on Twitter at L<http://twitter.com/perl5i>,
our Github page at L<https://github.com/evalEmpire/perl5i> and wiki at 
L<https://github.com/evalEmpire/perl5i/wiki>.  Discussions on IRC are on
L<irc://irc.perl.org> on channel #perl5i.


=head2 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 L<http://github.com/evalEmpire/perl5i/issues>.  Think of
it less as an issue tracker and more of a web forum with great
tagging.

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.

Finally, if you just want to write some code, you can fork and work on
it at L<http://github.com/evalEmpire/perl5i>.  Full details on our
patching policy can be read at
L<http://github.com/evalEmpire/perl5i/raw/master/PATCHING>.

We'd like to hear from you.  Don't worry if you're doing it right,
come talk with us.


=head2 Why doesn't perl5i use Moose?

We'd love to, but L<Moose> more than doubles perl5i's startup time.

In addition, simply using Moose doesn't buy you much.  Like perl5i, it
is one line to fix much of Perl's OO woes.  But even Moose needs
fixing.  What we would really like is to be able to conditionally use
L<MooseX::Declare> which fixes Perl's OO syntax as well as provides
some better Moose defaults.  But that has the double whammy of using
L<Devel::Declare> and L<Moose>.


=head2 Why doesn't perl5i use Class::MOP?

L<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 UNIVERSAL namespace with.


=head2 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 CPAN module over writing it ourselves so
maintenance can be distributed.

We monitor the health of our dependencies and try to pick ones which
are solid or fix those which fail too often.

=cut