Perl5i

NAME

perl5i - Fix as much of Perl 5 as possible in one pragma

SYNOPSIS

  use perl5i::2;

  or

  $ perl5i your_script.pl

DESCRIPTION

Perl 5 has a lot of warts. There's a lot of individual modules and
techniques out there to fix those warts. perl5i aims to pull the best
of them together into one module so you can turn them on all at once.

This includes adding features, changing existing core functions and
changing defaults. It will likely not be 100% backwards compatible with
Perl 5, though it will be 99%, perl5i will try to have a lexical
effect.

Please add to this imaginary world and help make it real, either by
telling me what Perl looks like in your imagination
(http://github.com/evalEmpire/perl5i/issues) or make a fork (forking on
github is like a branch you control) and implement it yourself.

Rationale

Changing perl 5 core is a slow and difficult process. Perl 5 aims to be
compatible with ancient versions which means it is mostly stuck with
design, decisions and defaults made way back in the 90's.

There are modules in CPAN to solve or ease many of those issues but
many people don't know about them or don't know which ones to use.

Documentation and books are updated slowly and don't usually keep up;
this information becomes some sort of community knowledge, invisible
from the wider audience.

Even if you know a solution, having to decide everytime which module to
use and enable it individually might be enough for you to give up and
just do things the old way.

Perl5i brings all this community knowledge in a coherent way, in
something like 'the best of CPAN', enabled with a single command.

You don't need to know all it does nor how it does it, you just use
perl5i::2 on your code and you automatically get a modern environment,
with perl defaults, problems and inconsistencies fixed.

You can refer beginers to perl5i and they can benefit from it without
needing to become a perl guru first.

Using perl5i

Because perl5i plans to be incompatible in the future, you do not
simply use perl5i. You must declare which major version of perl5i you
are using. You do this like so:

    # Use perl5i major version 2
    use perl5i::2;

Thus the code you write with, for example, perl5i::2 will always remain
compatible even as perl5i moves on.

If you want to be daring, you can use perl5i::latest to get the latest
version. This will automatically happen if the program is -e. This lets
you do slightly less typing for one-liners like perl -Mperl5i -e ...

If you want your module to depend on perl5i, you should depend on the
versioned class. For example, depend on perl5i::2 and not perl5i.

See "VERSIONING" for more information about perl5i's versioning scheme.

What it does

perl5i enables each of these modules and adds/changes these functions.
We'll provide a brief description here, but you should look at each of
their documentation for full details.

The Meta Object

Every object (and everything is an object) now has a meta object
associated with it. Using the meta object you can ask things about the
object which were previously over complicated. For example...

    # the object's class
    my $class = $obj->mo->class;

    # its parent classes
    my @isa = $obj->mo->isa;

    # the complete inheritance hierarchy
    my @complete_isa = $obj->mo->linear_isa;

    # the reference type of the object
    my $reftype = $obj->mo->reftype;

A meta object is used to avoid polluting the global method space. mo
was chosen to avoid clashing with Moose's meta object.

See perl5i::Meta for complete details.

Subroutine and Method Signatures

perl5i makes it easier to declare what parameters a subroutine takes.

    func hello($place) {
        say "Hello, $place!\n";
    }

    method get($key) {
        return $self->{$key};
    }

    method new($class: %args) {
        return bless \%args, $class;
    }

func and method define subroutines as sub does, with some extra
conveniences.

The signature syntax is currently very simple. The content will be
assigned from @_. This:

    func add($this, $that) {
        return $this + $that;
    }

is equivalent to:

    sub add {
        my($this, $that) = @_;
        return $this + $that;
    }

method defines a method. This is the same as a subroutine, but the
first argument, the invocant, will be removed and made into $self.

    method get($key) {
        return $self->{$key};
    }

    sub get {
        my $self = shift;
        my($key) = @_;
        return $self->{$key};
    }

Methods have a special bit of syntax. If the first item in the
signature is $var: it will change the variable used to store the
invocant.

    method new($class: %args) {
        return bless \%args, $class;
    }

is equivalent to:

    sub new {
        my $class = shift;
        my %args = @_;
        return bless \%args, $class;
    }

Anonymous functions and methods work, too.

    my $code = func($message) { say $message };

Guarantees include:

  @_ will not be modified except by removing the invocant

Future versions of perl5i will add to the signature syntax and
capabilities. Planned expansions include:

  Signature validation
  Signature documentation
  Named parameters
  Required parameters
  Read only parameters
  Aliased parameters
  Anonymous method and function declaration
  Variable method and function names
  Parameter traits
  Traditional prototypes

See http://github.com/evalEmpire/perl5i/issues/labels/syntax#issue/19
for more details about future expansions.

The equivalencies above should only be taken for illustrative purposes,
they are not guaranteed to be literally equivalent.

Note that while all parameters are optional by default, the number of
parameters will eventually be enforced. For example, right now this
will work:

    func add($this, $that) { return $this + $that }

    say add(1,2,3);  # says 3

The extra argument is ignored. In future versions of perl5i this will
be a runtime error.

Signature Introspection

The signature of a subroutine defined with func or method can be
queried by calling the signature method on the code reference.

    func hello($greeting, $place) { say "$greeting, $place" }

    my $code = \&hello;
    say $code->signature->num_positional_params;  # prints 2

Functions defined with sub will not have a signature.

See perl5i::Signature for more details.

Autoboxing

autobox allows methods to be defined for and called on most unblessed
variables. This means you can call methods on ordinary strings, lists
and hashes! It also means perl5i can add a lot of functionality without
polluting the global namespace.

autobox::Core wraps a lot of Perl's built in functions so they can be
called as methods on unblessed variables. @a->pop for example.

alias

    $scalar_reference->alias( @identifiers );
    @alias->alias( @identifiers );
    %hash->alias( @identifiers );
    (\&code)->alias( @identifiers );

Aliases a variable to a new global name.

    my $code = sub { 42 };
    $code->alias( "foo" );
    say foo();        # prints 42

It will work on everything except scalar references.

    our %stuff;
    %other_hash->alias( "stuff" );  # %stuff now aliased to %other_hash

It is not a copy, changes to one will change the other.

    my %things = (foo => 23);
    our %stuff;
    %things->alias( "stuff" );  # alias %things to %stuff
    $stuff{foo} = 42;           # change %stuff
    say $things{foo};           # and it will show up in %things

Multiple @identifiers will be joined with '::' and used as the fully
qualified name for the alias.

    my $class = "Some::Class";
    my $name  = "foo";
    sub { 99 }->alias( $class, $name );
    say Some::Class->foo;  # prints 99

If there is just one @identifier and it has no "::" in it, the current
caller will be prepended. $thing->alias("name") is shorthand for
$thing->alias(CLASS, "name")

Due to limitations in autobox, non-reference scalars cannot be aliased.
Alias a scalar ref instead.

    my $thing = 23;
    $thing->alias("foo");  # error

    my $thing = \23;
    $thing->alias("foo");  # $foo is now aliased to $thing

This is basically a nicer way to say:

    no strict 'refs';
    *{$package . '::'. $name} = $reference;

Scalar Autoboxing

All of the methods provided by autobox::Core are available from perl5i.

in addition, perl5i adds some methods of its own.

path

    my $object = $path->path;

Creates a Path::Tiny $object for the given file or directory $path.

    my $path = "/foo/bar/baz.txt"->path;
    my $content = $path->slurp;

center

    my $centered_string = $string->center($length);
    my $centered_string = $string->center($length, $character);

Centers $string between $character. $centered_string will be of length
$length.

$character defaults to " ".

    say "Hello"->center(10);        # "   Hello  ";
    say "Hello"->center(10, '-');   # "---Hello--";

center() will never truncate $string. If $length is less than
$string->length it will just return $string.

    say "Hello"->center(4);        # "Hello";

round

    my $rounded_number = $number->round;

Round to the nearest integer.

round_up

ceil

    my $new_number = $number->round_u