← Back to branch summary

~ubuntu-branches/debian/jessie/libperl5i-perl/jessie

« back to all changes in this revision

Viewing changes to .pc/spelling.patch/lib/perl5i.pm

  • Committer: Bazaar Package Importer
  • Author(s): gregor herrmann, Jonathan Yu, gregor herrmann
  • Date: 2011-03-11 17:36:50 UTC
  • mfrom: (1.1.2 upstream)
  • Revision ID: james.westby@ubuntu.com-20110311173650-ehi4t5vp3anyf0hg
Tags: 2.6.0-1
[ Jonathan Yu ]
* New upstream release
* Standards-Version 3.9.1 (no changes)
* Bump to debhelper 8
* Add myself to Uploaders and Copyright
* Update dependencies per upstream
* No longer install README, it is autogenerated from pod2text
* Rewrite control description

[ gregor herrmann ]
* Add /me to Uploaders.
* Add build dependency on libtest-exception-perl.
* Add a patch to fix some spelling errors.

Show diffs side-by-side

added added

removed removed

Lines of Context:
.pc/spelling.patch/lib/perl5i.pm
 
1
package perl5i;
 
2
 
 
3
######################################
 
4
# The real code is in perl5i::2      #
 
5
# Please patch that                  #
 
6
######################################
 
7
 
 
8
use strict;
 
9
use perl5i::VERSION; our $VERSION = perl5i::VERSION->VERSION;
 
10
 
 
11
my $Latest = perl5i::VERSION->latest;
 
12
 
 
13
sub import {
 
14
    require Carp;
 
15
    Carp::croak(<<END);
 
16
perl5i will break compatibility in the future, you can't just "use perl5i".
 
17
 
 
18
Instead, "use $Latest" which will guarantee compatibility with all
 
19
features supplied in that major version.
 
20
 
 
21
Type "perldoc perl5i" for details in the section "Using perl5i".
 
22
END
 
23
}
 
24
 
 
25
1;
 
26
 
 
27
__END__
 
28
 
 
29
=encoding utf8
 
30
 
 
31
=head1 NAME
 
32
 
 
33
perl5i - Fix as much of Perl 5 as possible in one pragma
 
34
 
 
35
=head1 SYNOPSIS
 
36
 
 
37
  use perl5i::2;
 
38
 
 
39
  or
 
40
 
 
41
  $ perl5i your_script.pl
 
42
 
 
43
=head1 DESCRIPTION
 
44
 
 
45
Perl 5 has a lot of warts.  There's a lot of individual modules and
 
46
techniques out there to fix those warts.  perl5i aims to pull the best
 
47
of them together into one module so you can turn them on all at once.
 
48
 
 
49
This includes adding features, changing existing core functions and
 
50
changing defaults.  It will likely not be 100% backwards compatible
 
51
with Perl 5, though it will be 99%, perl5i will try to have a lexical
 
52
effect.
 
53
 
 
54
Please add to this imaginary world and help make it real, either by
 
55
telling me what Perl looks like in your imagination
 
56
(F<http://github.com/schwern/perl5i/issues>) or make a fork (forking on
 
57
github is like a branch you control) and implement it yourself.
 
58
 
 
59
 
 
60
=head1 Using perl5i
 
61
 
 
62
Because perl5i I<plans> to be incompatible in the future, you do not
 
63
simply C<use perl5i>.  You must declare which major version of perl5i
 
64
you are using.  You do this like so:
 
65
 
 
66
    # Use perl5i major version 2
 
67
    use perl5i::2;
 
68
 
 
69
Thus the code you write with, for example, C<perl5i::2> will always
 
70
remain compatible even as perl5i moves on.
 
71
 
 
72
If you want to be daring, you can C<use perl5i::latest> to get the
 
73
latest version.
 
74
 
 
75
If you want your module to depend on perl5i, you should depend on the
 
76
versioned class.  For example, depend on C<perl5i::2> and not
 
77
C<perl5i>.
 
78
 
 
79
See L</VERSIONING> for more information about perl5i's versioning
 
80
scheme.
 
81
 
 
82
 
 
83
=head1 What it does
 
84
 
 
85
perl5i enables each of these modules and adds/changes these functions.
 
86
We'll provide a brief description here, but you should look at each of
 
87
their documentation for full details.
 
88
 
 
89
 
 
90
=head2 The Meta Object
 
91
 
 
92
Every object (and everything is an object) now has a meta object
 
93
associated with it.  Using the meta object you can ask things about
 
94
the object which were previously over complicated.  For example...
 
95
 
 
96
    # the object's class
 
97
    my $class = $obj->mo->class;
 
98
 
 
99
    # its parent classes
 
100
    my @isa = $obj->mo->isa;
 
101
 
 
102
    # the complete inheritance hierarchy
 
103
    my @complete_isa = $obj->mo->linear_isa;
 
104
 
 
105
    # the reference type of the object
 
106
    my $reftype = $obj->mo->reftype;
 
107
 
 
108
A meta object is used to avoid polluting the global method space.
 
109
C<mo> was chosen to avoid clashing with Moose's meta object.
 
110
 
 
111
See L<perl5i::Meta> for complete details.
 
112
 
 
113
 
 
114
=head2 Subroutine and Method Signatures
 
115
 
 
116
perl5i makes it easier to declare what parameters a subroutine takes.
 
117
 
 
118
    func hello($place) {
 
119
        say "Hello, $place!\n";
 
120
    }
 
121
 
 
122
    method get($key) {
 
123
        return $self->{$key};
 
124
    }
 
125
 
 
126
    method new($class: %args) {
 
127
        return bless \%args, $class;
 
128
    }
 
129
 
 
130
C<func> and C<method> define subroutines as C<sub> does, with some
 
131
extra conveniences.
 
132
 
 
133
The signature syntax is currently very simple.  The content will be
 
134
assigned from @_.  This:
 
135
 
 
136
    func add($this, $that) {
 
137
        return $this + $that;
 
138
    }
 
139
 
 
140
is equivalent to:
 
141
 
 
142
    sub add {
 
143
        my($this, $that) = @_;
 
144
        return $this + $that;
 
145
    }
 
146
 
 
147
C<method> defines a method.  This is the same as a subroutine, but the
 
148
first argument, the I<invocant>, will be removed and made into
 
149
C<$self>.
 
150
 
 
151
    method get($key) {
 
152
        return $self->{$key};
 
153
    }
 
154
 
 
155
    sub get {
 
156
        my $self = shift;
 
157
        my($key) = @_;
 
158
        return $self->{$key};
 
159
    }
 
160
 
 
161
Methods have a special bit of syntax.  If the first item in the
 
162
siganture is C<$var:> it will change the variable used to store the
 
163
invocant.
 
164
 
 
165
    method new($class: %args) {
 
166
        return bless $class, \%args;
 
167
    }
 
168
 
 
169
is equivalent to:
 
170
 
 
171
    sub new {
 
172
        my $class = shift;
 
173
        my %args = @_;
 
174
        return bless $class, \%args;
 
175
    }
 
176
 
 
177
Anonymous functions and methods work, too.
 
178
 
 
179
    my $code = func($message) { say $message };
 
180
 
 
181
Guarantees include:
 
182
 
 
183
  @_ will not be modified except by removing the invocant
 
184
 
 
185
Future versions of perl5i will add to the signature syntax and
 
186
capabilities.  Planned expansions include:
 
187
 
 
188
  Signature validation
 
189
  Signature documentation
 
190
  Named parameters
 
191
  Required parameters
 
192
  Read only parameters
 
193
  Aliased parameters
 
194
  Anonymous method and function declaration
 
195
  Variable method and function names
 
196
  Parameter traits
 
197
  Traditional prototypes
 
198
 
 
199
See L<http://github.com/schwern/perl5i/issues/labels/syntax#issue/19> for
 
200
more details about future expansions.
 
201
 
 
202
The equivalencies above should only be taken for illustrative
 
203
purposes, they are not guaranteed to be literally equivalent.
 
204
 
 
205
Note that while all parameters are optional by default, the number of
 
206
parameters will eventually be enforced.  For example, right now this
 
207
will work:
 
208
 
 
209
    func add($this, $that) { return $this + $that }
 
210
 
 
211
    say add(1,2,3);  # says 3
 
212
 
 
213
The extra argument is ignored.  In future versions of perl5i this will
 
214
be a runtime error.
 
215
 
 
216
 
 
217
=head3 Signature Introspection
 
218
 
 
219
The signature of a subroutine defined with C<func> or C<method> can be
 
220
queried by calling the C<signature> method on the code reference.
 
221
 
 
222
    func hello($greeting, $place) { say "$greeting, $place" }
 
223
 
 
224
    my $code = \&hello;
 
225
    say $code->signature->num_positional_params;  # prints 2
 
226
 
 
227
Functions defined with C<sub> will not have a signature.
 
228
 
 
229
See L<perl5i::Signature> for more details.
 
230
 
 
231
 
 
232
=head2 Autoboxing
 
233
 
 
234
L<autobox> allows methods to be defined for and called on most
 
235
unblessed variables.  This means you can call methods on ordinary
 
236
strings, lists and hashes!  It also means perl5i can add a lot of
 
237
functionality without polluting the global namespace.
 
238
 
 
239
L<autobox::Core> wraps a lot of Perl's built in functions so they can
 
240
be called as methods on unblessed variables.  C<< @a->pop >> for example.
 
241
 
 
242
=head3 alias()
 
243
 
 
244
    $scalar_reference->alias( @identifiers );
 
245
    @alias->alias( @identifiers );
 
246
    %hash->alias( @identifiers );
 
247
    (\&code)->alias( @identifiers );
 
248
 
 
249
Aliases a variable to a new global name.
 
250
 
 
251
    my $code = sub { 42 };
 
252
    $code->alias( "foo" );
 
253
    say foo();        # prints 42
 
254
 
 
255
It will work on everything except scalar references.
 
256
 
 
257
    our %stuff;
 
258
    %other_hash->alias( "stuff" );  # %stuff now aliased to %other_hash
 
259
 
 
260
It is not a copy, changes to one will change the other.
 
261
 
 
262
    my %things = (foo => 23);
 
263
    our %stuff;
 
264
    %things->alias( "stuff" );  # alias %things to %stuff
 
265
    $stuff{foo} = 42;           # change %stuff
 
266
    say $things{foo};           # and it will show up in %things
 
267
 
 
268
Multiple @identifiers will be joined with '::' and used as the fully
 
269
qualified name for the alias.
 
270
 
 
271
    my $class = "Some::Class";
 
272
    my $name  = "foo";
 
273
    sub { 99 }->alias( $class, $name );
 
274
    say Some::Class->foo;  # prints 99
 
275
 
 
276
If there is just one @identifier and it has no "::" in it, the current
 
277
caller will be prepended.  C<< $thing->alias("name") >> is shorthand for
 
278
C<< $thing->alias(CLASS, "name") >>
 
279
 
 
280
Due to limitations in autobox, non-reference scalars cannot be
 
281
aliased.  Alias a scalar ref instead.
 
282
 
 
283
    my $thing = 23;
 
284
    $thing->alias("foo");  # error
 
285
 
 
286
    my $thing = \23;
 
287
    $thing->alias("foo");  # $foo is now aliased to $thing
 
288
 
 
289
This is basically a nicer way to say:
 
290
 
 
291
    no strict 'refs';
 
292
    *{$package . '::'. $name} = $reference;
 
293
 
 
294
 
 
295
=head2 Scalar Autoboxing
 
296
 
 
297
perl5i adds some methods to scalars of its own.
 
298
 
 
299
=head3 center()
 
300
 
 
301
    my $centered_string = $string->center($length);
 
302
    my $centered_string = $string->center($length, $character);
 
303
 
 
304
Centers $string between $character.  $centered_string will be of
 
305
length $length.
 
306
 
 
307
C<$character> defaults to " ".
 
308
 
 
309
    say "Hello"->center(10);        # "   Hello  ";
 
310
    say "Hello"->center(10, '-');   # "---Hello--";
 
311
 
 
312
C<center()> will never truncate C<$string>.  If $length is less
 
313
than C<< $string->length >> it will just return C<$string>.
 
314
 
 
315
    say "Hello"->center(4);        # "Hello";
 
316
 
 
317
=head3 round
 
318
 
 
319
    my $rounded_number = $number->round;
 
320
 
 
321
Round to the nearest integer.
 
322
 
 
323
=head3 round_up
 
324
 
 
325
=head3 ceil
 
326
 
 
327
    my $new_number = $number->round_up;
 
328
 
 
329
Rounds the $number towards infinity.
 
330
 
 
331
    2.45->round_up;   # 3
 
332
  (-2.45)->round_up;  # -2
 
333
 
 
334
ceil() is a synonym for round_up().
 
335
 
 
336
 
 
337
=head3 round_down
 
338
 
 
339
=head3 floor
 
340
 
 
341
    my $new_number = $number->round_down;
 
342
 
 
343
Rounds the $number towards negative infinity.
 
344
 
 
345
    2.45->round_down;  # 2
 
346
  (-2.45)->round_down; # -3
 
347
 
 
348
floor() is a synonyn for round_down().
 
349
 
 
350
 
 
351
=head3 is_number
 
352
 
 
353
    $is_a_number = $thing->is_number;
 
354
 
 
355
Returns true if $thing is a number understood by Perl.
 
356
 
 
357
    12.34->is_number;           # true
 
358
    "12.34"->is_number;         # also true
 
359
    "eleven"->is_number;        # false
 
360
 
 
361
=head3 is_positive
 
362
 
 
363
    $is_positive = $thing->is_positive;
 
364
 
 
365
Returns true if $thing is a positive number.
 
366
 
 
367
0 is not positive.
 
368
 
 
369
=head3 is_negative
 
370
 
 
371
    $is_negative = $thing->is_negative;
 
372
 
 
373
Returns true if $thing is a negative number.
 
374
 
 
375
0 is not negative.
 
376
 
 
377
=head3 is_even
 
378
 
 
379
    $is_even = $thing->is_even;
 
380
 
 
381
Returns true if $thing is an even integer.
 
382
 
 
383
=head3 is_odd
 
384
 
 
385
    $is_odd = $thing->is_odd;
 
386
 
 
387
Returns true if $thing is an odd integer.
 
388
 
 
389
=head3 is_integer
 
390
 
 
391
    $is_an_integer = $thing->is_integer;
 
392
 
 
393
Returns true if $thing is an integer.
 
394
 
 
395
    12->is_integer;             # true
 
396
    12.34->is_integer;          # false
 
397
    "eleven"->is_integer;       # false
 
398
 
 
399
=head3 is_int
 
400
 
 
401
A synonym for is_integer
 
402
 
 
403
=head3 is_decimal
 
404
 
 
405
    $is_a_decimal_number = $thing->is_decimal;
 
406
 
 
407
Returns true if $thing is a decimal number.
 
408
 
 
409
    12->is_decimal;             # false
 
410
    12.34->is_decimal;          # true
 
411
    ".34"->is_decimal;          # true
 
412
    "point five"->is_decimal;   # false
 
413
 
 
414
=head3 require
 
415
 
 
416
    my $module = $module->require;
 
417
 
 
418
Will C<require> the given $module.  This avoids funny things like
 
419
C<eval qq[require $module] or die $@>.  It accepts only module names.
 
420
 
 
421
On failure it will throw an exception, just like C<require>.  On a
 
422
success it returns the $module.  This is mostly useful so that you can
 
423
immediately call $module's C<import> method to emulate a C<use>.
 
424
 
 
425
    # like "use $module qw(foo bar);" if that worked
 
426
    $module->require->import(qw(foo bar));
 
427
 
 
428
    # like "use $module;" if that worked
 
429
    $module->require->import;
 
430
 
 
431
=head3 wrap()
 
432
 
 
433
    my $wrapped = $string->wrap( width => $cols, separator => $sep );
 
434
 
 
435
Wraps $string to width $cols, breaking lines at word boundries using
 
436
separator $sep.
 
437
 
 
438
If no width is given, $cols defaults to 76. Default line separator is
 
439
the newline character "\n".
 
440
 
 
441
See L<Text::Wrap> for details.
 
442
 
 
443
=head3 ltrim()
 
444
 
 
445
=head3 rtrim()
 
446
 
 
447
=head3 trim()
 
448
 
 
449
    my $trimmed = $string->trim;
 
450
    my $trimmed = $string->trim($character_set);
 
451
 
 
452
Trim whitespace.  ltrim() trims off the start of the string (left),
 
453
rtrim() off the end (right) and trim() off both the start and end.
 
454
 
 
455
    my $string = '    testme'->ltrim;        # 'testme'
 
456
    my $string = 'testme    '->rtrim;        # 'testme'
 
457
    my $string = '    testme    '->trim;     # 'testme'
 
458
 
 
459
They all take an optional $character_set which will determine what
 
460
characters should be trimmed.  It follows regex character set syntax
 
461
so C<A-Z> will trim everything from A to Z.  Defaults to C<\s>,
 
462
whitespace.
 
463
 
 
464
    my $string = '-> test <-'->trim('-><');  # ' test '   
 
465
 
 
466
 
 
467
=head3 title_case()
 
468
 
 
469
    my $name = 'joe smith'->title_case;   # Joe Smith
 
470
 
 
471
Will uppercase every word character that follows a wordbreak character.
 
472
 
 
473
 
 
474
=head3 path2module()
 
475
 
 
476
    my $module = $path->path2module;
 
477
 
 
478
Given a relative $path it will return the Perl module this represents.
 
479
For example,
 
480
 
 
481
    "Foo/Bar.pm"->path2module;  # "Foo::Bar"
 
482
 
 
483
It will throw an exception if given something which could not be a
 
484
path to a Perl module.
 
485
 
 
486
=head3 module2path()
 
487
 
 
488
    my $path = $module->module2path;
 
489
 
 
490
Will return the relative $path in which the Perl $module can be found.
 
491
For example,
 
492
 
 
493
    "Foo::Bar"->module2path;  # "Foo/Bar.pm"
 
494
 
 
495
 
 
496
=head3 group_digits
 
497
 
 
498
    my $number_grouped     = $number->group_digits;
 
499
    my $number_grouped     = $number->group_digits(\%options);
 
500
 
 
501
Turns a number like 1234567 into a string like 1,234,567 known as "digit grouping".
 
502
 
 
503
It honors your current locale to determine the separator and grouping.
 
504
This can be overriden using C<%options>.
 
505
 
 
506
NOTE: many systems do not have their numeric locales set properly
 
507
 
 
508
=over 4
 
509
 
 
510
=item separator
 
511
 
 
512
The character used to separate groups.  Defaults to "thousands_sep" in
 
513
your locale or "," if your locale doesn't specify.
 
514
 
 
515
=item decimal_point
 
516
 
 
517
The decimal point character.  Defaults to "decimal_point" in your
 
518
locale or "." if your locale does not specify.
 
519
 
 
520
=item grouping
 
521
 
 
522
How many numbers in a group?  Defaults to "grouping" in your locale or
 
523
3 if your locale doesn't specify.
 
524
 
 
525
Note: we don't honor the full grouping locale, its a wee bit too complicated.
 
526
 
 
527
=item currency
 
528
 
 
529
If true, it will treat the number as currency and use the monetary
 
530
locale settings.  "mon_thousands_sep" instead of "thousands_sep" and
 
531
"mon_grouping" instead of "grouping".
 
532
 
 
533
 
 
534
=back
 
535
 
 
536
    1234->group_digits;                      # 1,234 (assuming US locale)
 
537
    1234->group_digits( separator => "." );  # 1.234
 
538
 
 
539
 
 
540
=head3 commify
 
541
 
 
542
    my $number_grouped = $number->commify;
 
543
    my $number_grouped = $number->commify(\%options);
 
544
 
 
545
commify() is just like group_digits() but it is not locale aware.  It
 
546
is useful when you want a predictable result regardless of the user's
 
547
locale settings.
 
548
 
 
549
C<%options> defaults to C<< ( separator => ",", grouping => 3, decimal_point => "." ) >>.
 
550
Each key will be overriden individually.
 
551
 
 
552
    1234->commify;                      # 1,234
 
553
    1234->commify({ separator => "." });  # 1.234
 
554
 
 
555
 
 
556
=head2 List Autoboxing
 
557
 
 
558
All the functions from L<List::Util> and select ones from
 
559
L<List::MoreUtils> are all available as methods on unblessed arrays and array refs.
 
560
 
 
561
first, max, maxstr, min, minstr, minmax, shuffle, reduce, sum, any,
 
562
all, none, true, false, uniq and mesh.
 
563
 
 
564
The have all been altered to return array refs where applicable in
 
565
order to allow chaining.
 
566
 
 
567
    @array->grep(sub{ $_->is_number })->sum->say;
 
568
 
 
569
=head3 foreach()
 
570
 
 
571
    @array->foreach( func($item) { ... } );
 
572
 
 
573
Works like the built in C<foreach>, calls the code block for each
 
574
element of @array passing it into the block.
 
575
 
 
576
    @array->foreach( func($item) { say $item } );  # print each item
 
577
 
 
578
It will pass in as many elements as the code block accepts.  This
 
579
allows you to iterate through an array 2 at a time, or 3 or 4 or
 
580
whatever.
 
581
 
 
582
    my @names = ("Joe", "Smith", "Jim", "Dandy", "Jane", "Lane");
 
583
    @names->foreach( func($fname, $lname) {
 
584
        say "Person: $fname $lname";
 
585
    });
 
586
 
 
587
A normal subroutine with no signature will get one at a time.
 
588
 
 
589
If @array is not a multiple of the iteration (for example, @array has
 
590
5 elements and you ask 2 at a time) the behavior is currently undefined.
 
591
 
 
592
 
 
593
=head3 diff()
 
594
 
 
595
Calculate the difference between two (or more) arrays:
 
596
 
 
597
    my @a = ( 1, 2, 3 );
 
598
    my @b = ( 3, 4, 5 );
 
599
 
 
600
    my @diff_a = @a->diff(\@b) # [ 1, 2 ]
 
601
    my @diff_b = @b->diff(\@a) # [ 4, 5 ]
 
602
 
 
603
Diff returns all elements in array C<@a> that are not present in array
 
604
C<@b>. Item order is not considered: two identical elements in both
 
605
arrays will be recognized as such disregarding their index.
 
606
 
 
607
    [ qw( foo bar ) ]->diff( [ qw( bar foo ) ] ) # empty, they are equal
 
608
 
 
609
For comparing more than two arrays:
 
610
 
 
611
    @a->diff(\@b, \@c, ... )
 
612
 
 
613
All comparisons are against the base array (C<@a> in this example). The
 
614
result will be composed of all those elements that were present in C<@a>
 
615
and in none other.
 
616
 
 
617
It also works with nested data structures; it will traverse them
 
618
depth-first to assess whether they are identical or not. For instance:
 
619
 
 
620
    [ [ 'foo ' ], { bar => 1 } ]->diff([ 'foo' ]) # [ { bar => 1 } ]
 
621
 
 
622
In the case of overloaded objects (i.e., L<DateTime>, L<URI>,
 
623
L<Path::Class>, etc.), it tries its best to treat them as strings or numbers.
 
624
 
 
625
    my $uri  = URI->new("http://www.perl.com");
 
626
    my $uri2 = URI->new("http://www.perl.com");
 
627
 
 
628
    [ $uri ]->diff( [ "http://www.perl.com" ] ); # empty, they are equal
 
629
    [ $uri ]->diff( [ $uri2 ] );                 # empty, they are equal
 
630
 
 
631
 
 
632
=head3 intersect()
 
633
 
 
634
    my @a = (1 .. 10);
 
635
    my @b = (5 .. 15);
 
636
 
 
637
    my @intersection = @a->intersect(\@b) # [ 5 .. 10 ];
 
638
 
 
639
Performs intersection between arrays, returning those elements that are
 
640
present in all of the argument arrays simultaneously.
 
641
 
 
642
As with C<diff()>, it works with any number of arrays, nested data
 
643
structures of arbitrary depth, and handles overloaded objects
 
644
graciously.
 
645
 
 
646
=head3 ltrim()
 
647
 
 
648
=head3 rtrim()
 
649
 
 
650
=head3 trim()
 
651
 
 
652
    my @trimmed = @list->trim;
 
653
    my @trimmed = @list->trim($character_set);
 
654
 
 
655
Trim whitespace from each element of an array.  Each works just like
 
656
their scalar counterpart.
 
657
 
 
658
    my @trimmed = [ '   foo', 'bar   ' ]->ltrim;  # [ 'foo', 'bar   ' ]
 
659
    my @trimmed = [ '   foo', 'bar   ' ]->rtrim;  # [ '   foo', 'bar' ]
 
660
    my @trimmed = [ '   foo', 'bar   ' ]->trim;   # [ 'foo', 'bar'    ]
 
661
 
 
662
As with the scalar trim() methods, they all take an optional $character_set
 
663
which will determine what characters should be trimmed.
 
664
 
 
665
    my @trimmed = ['-> foo <-', '-> bar <-']->trim('-><'); # [' foo ', ' bar ']
 
666
 
 
667
 
 
668
=head2 Hash Autoboxing
 
669
 
 
670
=head3 flip()
 
671
 
 
672
Exchanges values for keys in a hash.
 
673
 
 
674
    my %things = ( foo => 1, bar => 2, baz => 5 );
 
675
    my %flipped = %things->flip; # { 1 => foo, 2 => bar, 5 => baz }
 
676
 
 
677
If there is more than one occurence of a certain value, any one of the
 
678
keys may end up as the value.  This is because of the random ordering
 
679
of hash keys.
 
680
 
 
681
    # Could be { 1 => foo }, { 1 => bar }, or { 1 => baz }
 
682
    { foo => 1, bar => 1, baz => 1 }->flip;
 
683
 
 
684
Because hash references cannot usefully be keys, it will not work on
 
685
nested hashes.
 
686
 
 
687
    { foo => [ 'bar', 'baz' ] }->flip; # dies
 
688
 
 
689
 
 
690
=head3 merge()
 
691
 
 
692
Recursively merge two or more hashes together using L<Hash::Merge::Simple>.
 
693
 
 
694
    my $a = { a => 1 };
 
695
    my $b = { b => 2, c => 3 };
 
696
 
 
697
    $a->merge($b); # { a => 1, b => 2, c => 3 }
 
698
 
 
699
For conflicting keys, rightmost precedence is used:
 
700
 
 
701
    my $a = { a => 1 };
 
702
    my $b = { a => 100, b => 2};
 
703
 
 
704
    $a->merge($b); # { a => 100, b => 2 }
 
705
    $b->merge($a); # { a => 1,   b => 2 }
 
706
 
 
707
It also works with nested hashes, although it won't attempt to merge
 
708
array references or objects. For more information, look at the
 
709
L<Hash::Merge::Simple> docs.
 
710
 
 
711
=head3 diff()
 
712
 
 
713
    my %staff    = ( bob => 42, martha => 35, timmy => 23 );
 
714
    my %promoted = ( timmy => 23 );
 
715
 
 
716
    %staff->diff(\%promoted); # { bob => 42, martha => 35 }
 
717
 
 
718
Returns the key/value pairs present in the first hash that are not
 
719
present in the subsequent hash arguments.  Otherwise works as
 
720
C<< @array->diff >>.
 
721
 
 
722
=head3 intersect()
 
723
 
 
724
    %staff->intersect(\%promoted); # { timmy => 23 }
 
725
 
 
726
Returns the key/value pairs that are present simultaneously in all the
 
727
hash arguments.  Otherwise works as C<< @array->intersect >>.
 
728
 
 
729
=head2 Code autoboxing
 
730
 
 
731
=head3 signature
 
732
 
 
733
    my $sig = $code->signature;
 
734
 
 
735
You can query the signature of any code reference defined with C<func>
 
736
or C<method>.  See L<Signature Introspection> for details.
 
737
 
 
738
If C<$code> has a signature, returns an object representing C<$code>'s
 
739
signature.  See L<perl5i::Signature> for details.  Otherwise it
 
740
returns nothing.
 
741
 
 
742
 
 
743
=head2 caller()
 
744
 
 
745
L<Perl6::Caller> causes C<caller> to return an object in scalar
 
746
context.
 
747
 
 
748
=head2 die()
 
749
 
 
750
C<die> now always returns an exit code of 255 instead of trying to use
 
751
C<$!> or C<$?> which makes the exit code unpredictable.  If you want
 
752
to exit with a message and a special exit code, use C<warn> then
 
753
C<exit>.
 
754
 
 
755
=head2 utf8
 
756
 
 
757
L<utf8> lets you put UTF8 encoded strings into your source code.
 
758
This means UTF8 variable and method names, strings and regexes.
 
759
 
 
760
It means strings will be treated as a set of characters rather than a
 
761
set of bytes.  For example, C<length> will return the number of
 
762
characters, not the number of bytes.
 
763
 
 
764
    length("perl5i is MËTÁŁ");  # 15, not 18
 
765
 
 
766
C<@ARGV> will be read as UTF8.
 
767
 
 
768
STDOUT, STDIN, STDERR and all newly opened filehandles will have UTF8
 
769
encoding turned on.  Consequently, if you want to output raw bytes to
 
770
a file, such as outputting an image, you must set C<< binmode $fh >>.
 
771
 
 
772
=head2 capture()
 
773
 
 
774
    my($stdout, $stderr) = capture { ... } %options;
 
775
    my $stdout = capture { ... } %options;
 
776
 
 
777
C<capture()> lets you capture all output to C<STDOUT> and C<STDERR> in
 
778
any block of code.
 
779
 
 
780
    # $out = "Hello"
 
781
    # $err = "Bye"
 
782
    my($out, $err) = capture {
 
783
        print "Hello";
 
784
        print STDERR "Bye";
 
785
    };
 
786
 
 
787
If called in scalar context, it will only return C<STDOUT> and silence C<STDERR>.
 
788
 
 
789
    # $out = "Hello"
 
790
    my $out = capture {
 
791
        print "Hello";
 
792
        warn "oh god";
 
793
    };
 
794
 
 
795
C<capture> takes some options.
 
796
 
 
797
=over 4
 
798
 
 
799
=item B<tee>
 
800
 
 
801
tee will cause output to be captured yet still printed.
 
802
 
 
803
    my $out = capture { print "Hi" } tee => 1;
 
804
 
 
805
=item B<merge>
 
806
 
 
807
merge will merge C<STDOUT> and C<STDERR> into one variable.
 
808
 
 
809
    # $out = "HiBye"
 
810
    my $out = capture {
 
811
        print "Hi";
 
812
        print STDERR "Bye";
 
813
    } merge => 1;
 
814
 
 
815
=back
 
816
 
 
817
=head2 Carp
 
818
 
 
819
C<croak> and C<carp> from L<Carp> are always available.
 
820
 
 
821
=head2 Child
 
822
 
 
823
L<Child> provides the C<child> function which is a better way to do forking.
 
824
 
 
825
C<child> creates and starts a child process, and returns an
 
826
L<Child::Link::Proc> object which is a better interface for managing the child
 
827
process. The only required argument is a codeblock, which is called in the new
 
828
process. exit() is automatically called for you after the codeblock returns.
 
829
 
 
830
    my $proc = child {
 
831
        my $parent = shift;
 
832
        ...
 
833
    };
 
834
 
 
835
You can also request a pipe for IPC:
 
836
 
 
837
    my $proc = child {
 
838
        my $parent = shift;
 
839
 
 
840
        $parent->say("Message");
 
841
        my $reply = $parent->read();
 
842
 
 
843
        ...
 
844
    } pipe => 1;
 
845
 
 
846
    my $message = $proc->read();
 
847
    $proc->say("reply");
 
848
 
 
849
API Overview: (See L<Child> for more information)
 
850
 
 
851
=over 4
 
852
 
 
853
=item $proc->is_complete()
 
854
 
 
855
=item $proc->wait()
 
856
 
 
857
=item $proc->kill($SIG)
 
858
 
 
859
=item $proc->pid()
 
860
 
 
861
=item $proc->exit_status()
 
862
 
 
863
=item $parent->pid()
 
864
 
 
865
=item $parent->detach()
 
866
 
 
867
=item $proc_or_parent->read()
 
868
 
 
869
=item $proc_or_parent->write( @MESSAGES )
 
870
 
 
871
=item $proc_or_parent->say( @MESSAGES )
 
872
 
 
873
=back
 
874
 
 
875
=head2 English
 
876
 
 
877
L<English> gives English names to the punctuation variables; for
 
878
instance, C<<$@>> is also C<<$EVAL_ERROR>>.  See L<perlvar> for
 
879
details.
 
880
 
 
881
It does B<not> load the regex variables which affect performance.
 
882
C<$PREMATCH>, C<$MATCH>, and C<$POSTMATCH> will not exist.  See
 
883
the C<p> modifier in L<perlre> for a better alternative.
 
884
 
 
885
=head2 Modern::Perl
 
886
 
 
887
L<Modern::Perl> turns on strict and warnings, enables all the 5.10
 
888
features like C<given/when>, C<say> and C<state>, and enables C3
 
889
method resolution order.
 
890
 
 
891
=head2 CLASS
 
892
 
 
893
Provides C<CLASS> and C<$CLASS> alternatives to C<__PACKAGE__>.
 
894
 
 
895
=head2 File::chdir
 
896
 
 
897
L<File::chdir> gives you C<$CWD> representing the current working
 
898
directory and it's assignable to C<chdir>.  You can also localize it
 
899
to safely chdir inside a scope.
 
900
 
 
901
=head2 File::stat
 
902
 
 
903
L<File::stat> causes C<stat> to return an object in scalar context.
 
904
 
 
905
=head2 DateTime
 
906
 
 
907
C<time>, C<localtime>, and C<gmtime> are replaced with DateTime
 
908
objects.  They will all act like the core functions.
 
909
 
 
910
    # Sat Jan 10 13:37:04 2004
 
911
    say scalar gmtime(2**30);
 
912
 
 
913
    # 2004
 
914
    say gmtime(2**30)->year;
 
915
 
 
916
    # 2009 (when this was written)
 
917
    say time->year;
 
918
 
 
919
 
 
920
=head2 Time::y2038
 
921
 
 
922
C<gmtime()> and C<localtime()> will now safely work with dates beyond
 
923
the year 2038 and before 1901.  The exact range is not defined, but we
 
924
guarantee at least up to 2**47 and back to year 1.
 
925
 
 
926
 
 
927
=head2 IO::Handle
 
928
 
 
929
Turns filehandles into objects so you can call methods on them.  The
 
930
biggest one is C<autoflush> rather than mucking around with C<$|> and
 
931
C<select>.
 
932
 
 
933
    $fh->autoflush(1);
 
934
 
 
935
 
 
936
=head2 autodie
 
937
 
 
938
L<autodie> causes system and file calls which can fail
 
939
(C<open>, C<system>, and C<chdir>, for example) to die when they fail.
 
940
This means you don't have to put C<or die> at the end of every system
 
941
call, but you do have to wrap it in an C<eval> block if you want to
 
942
trap the failure.
 
943
 
 
944
autodie's default error messages are pretty smart.
 
945
 
 
946
All of autodie will be turned on.
 
947
 
 
948
 
 
949
=head2 autovivification
 
950
 
 
951
L<autovivification> fixes the bug/feature where this:
 
952
 
 
953
    $hash = {};
 
954
    $hash->{key1}{key2};
 
955
 
 
956
Results in C<< $hash->{key1} >> coming into existence.  That will no longer
 
957
happen.
 
958
 
 
959
=head2 No indirect object syntax
 
960
 
 
961
perl5i turns indirect object syntax, ie. C<new $obj>, into a compile
 
962
time error.  Indirect object syntax is largely unnecessary and
 
963
removing it avoids a number of ambiguous cases where Perl will
 
964
mistakenly try to turn a function call into an indirect method call.
 
965
 
 
966
See L<indirect> for details.
 
967
 
 
968
=head2 want()
 
969
 
 
970
C<want()> generalizes the mechanism of the wantarray function, allowing a
 
971
function to determine the context it's being called in.  Want distinguishes
 
972
not just scalar v. array context, but void, lvalue, rvalue, boolean, reference
 
973
context, and more.  See perldoc L<Want> for full details.
 
974
 
 
975
=head2 Try::Tiny
 
976
 
 
977
L<Try::Tiny> gives support for try/catch blocks as an alternative to
 
978
C<eval BLOCK>. This allows correct error handling with proper localization
 
979
of $@ and a nice syntax layer:
 
980
 
 
981
        # handle errors with a catch handler
 
982
        try {
 
983
                die "foo";
 
984
        } catch {
 
985
                warn "caught error: $_";
 
986
        };
 
987
 
 
988
        # just silence errors
 
989
        try {
 
990
                die "foo";
 
991
        };
 
992
 
 
993
See perldoc L<Try::Tiny> for details.
 
994
 
 
995
 
 
996
=head2 true
 
997
 
 
998
You no longer have to put a true value at the end of a module which uses perl5i.
 
999
 
 
1000
 
 
1001
=head2 Better load errors
 
1002
 
 
1003
Most of us have learned the meaning of the dreaded "Can't locate Foo.pm in
 
1004
@INC". Admittedly though, it's not the most helpful of the error messages. In
 
1005
perl5i we provide a much friendlier error message.
 
1006
 
 
1007
Example:
 
1008
 
 
1009
    Can't locate My/Module.pm in your Perl library.  You may need to install it
 
1010
    from CPAN or another repository.  Your library paths are:
 
1011
        Indented list of paths, 1 per line...
 
1012
 
 
1013
=head1 Command line program
 
1014
 
 
1015
There is a perl5i command line program installed with perl5i (Windows
 
1016
users get perl5i.bat).  This is handy for writing one liners.
 
1017
 
 
1018
    perl5i -e 'gmtime->year->say'
 
1019
 
 
1020
And you can use it on the C<#!> line.
 
1021
 
 
1022
    #!/usr/bin/perl5i
 
1023
 
 
1024
    gmtime->year->say;
 
1025
 
 
1026
 
 
1027
=head1 BUGS
 
1028
 
 
1029
Some parts are not lexical.  Some parts are package scoped.
 
1030
 
 
1031
If you're going to use two versions of perl5i together, we do not
 
1032
currently recommend having them in the same package.
 
1033
 
 
1034
See L<http://github.com/schwern/perl5i/issues/labels/bug> for a complete list.
 
1035
 
 
1036
Please report bugs at L<http://github.com/schwern/perl5i/issues/> or
 
1037
email L<mailto:perl5i@googlegroups.com>.
 
1038
 
 
1039
 
 
1040
=head1 VERSIONING
 
1041
 
 
1042
perl5i follows the Semantic Versioning policy, L<http://semver.org>.
 
1043
In short...
 
1044
 
 
1045
Versions will be of the form X.Y.Z.
 
1046
 
 
1047
0.Y.Z may change anything at any time.
 
1048
 
 
1049
Incrementing X (ie. 1.2.3 -> 2.0.0) indicates a backwards incompatible change.
 
1050
 
 
1051
Incrementing Y (ie. 1.2.3 -> 1.3.0) indicates a new feature.
 
1052
 
 
1053
Incrementing Z (ie. 1.2.3 -> 1.2.4) indicates a bug fix or other internal change.
 
1054
 
 
1055
 
 
1056
=head1 NOTES
 
1057
 
 
1058
Inspired by chromatic's L<Modern::Perl> and in particular
 
1059
F<http://www.modernperlbooks.com/mt/2009/04/ugly-perl-a-lesson-in-the-importance-of-language-design.html>.
 
1060
 
 
1061
I totally didn't come up with the "Perl 5 + i" joke.  I think it was
 
1062
Damian Conway.
 
1063
 
 
1064
 
 
1065
=head1 THANKS
 
1066
 
 
1067
Thanks to our contributors: Chas Owens, Darian Patrick, rjbs,
 
1068
chromatic, Ben Hengst, Bruno Vecchi and anyone else I've forgotten.
 
1069
 
 
1070
Thanks to Flavian and Matt Trout for their signature and
 
1071
L<Devel::Declare> work.
 
1072
 
 
1073
Thanks to all the CPAN authors upon whom this builds.
 
1074
 
 
1075
=head1 LICENSE
 
1076
 
 
1077
Copyright 2009-2010, Michael G Schwern <schwern@pobox.com>
 
1078
 
 
1079
This program is free software; you can redistribute it and/or
 
1080
modify it under the same terms as Perl itself.
 
1081
 
 
1082
See L<http://dev.perl.org/licenses/artistic.html>
 
1083
 
 
1084
 
 
1085
=head1 SEE ALSO
 
1086
 
 
1087
Repository:   L<http://github.com/schwern/perl5i/tree/master>
 
1088
Issues/Bugs:  L<http://github.com/schwern/perl5i/issues>
 
1089
IRC:          irc.perl.org on the #perl5i channel
 
1090
Mailing List: L<http://groups.google.com/group/perl5i/>
 
1091
 
 
1092
Frequently Asked Questions about perl5i: L<perl5ifaq>
 
1093
 
 
1094
Some modules with similar purposes include:
 
1095
L<Modern::Perl>, L<Common::Sense>
 
1096
 
 
1097
For a complete object declaration system, see L<Moose> and
 
1098
L<MooseX::Declare>.