=head1 NAME

Perl6::Perl5::Differences -- Differences between Perl 5 and Perl 6

=head1 DESCRIPTION

This document is intended to be used by Perl 5 programmers who are new to Perl
6 and just want a quick overview of the main differences.  More detail on
everything can be found in the language reference, which have been linked to
throughout.

This list is currently known to be incomplete.

=cut

# S02

=head1 Bits and Pieces

=head2 Sigils

Where you used to say:

    my @fruits = ("apple", "pear", "banana");
    print $fruit[0], "\n";

You would now say:

    my @fruits = "apple", "pear", "banana";
    say @fruit[0];

Or even use the C<< <> >> operator, which replaces C<qw()>:

    my @fruits = <apple pear banana>;

Note that the sigil for fetching a single element has changed from C<$>
to C<@>; perhaps a better way to think of it is that the sigil of a
variable is now a part of its name, so it never changes in subscripting.

The same applies to hashes:

    say "There are %days{'February'} days in February";

Again, there is a shorter form:

    say "There are %days<February> days in February";

For details, see L<S02/"Names and Variables">.

=head2 Global variables have a twigil

Yes, a twigil. It's the second character in the variable name. For globals,
it's a C<*>

    Was:    $ENV{FOO}
    Now:    %*ENV<FOO>

For details, see L<S02/"Names and Variables">.

=head2 New ways of referring to array and hash elements

Number of elements in an array:

    Was:    $#array+1 or scalar(@array)
    Now:    @array.elems

Index of last element in an array:

    Was:    $#array
    Now:    @array.end

Therefore, last element in an array:

    Was:    $array[$#array]
    Now:    @array[@array.end]
            @array[*-1]              # beware of the "whatever"-star

For details, see L<S02/"Built-In Data Types">

=head2 The double-underscore keywords are gone

    Old                 New
    ---                 ---
    __LINE__            $?LINE
    __FILE__            $?FILE
    __PACKAGE__         $?PACKAGE
    __END__             =begin END
    __DATA__            =begin DATA

See L<S02/"double-underscore forms are going away"> for details. The C<?>
twigil refers to data that is known at compile time.

=head2 Context

There are still three main contexts, void, item (formerly scalar) and list.
Aditionally there are more specialized contexts, and operators that force that
context.

    my @array = 1, 2, 3;

    # generic item context
    my $a = @array; say $a.WHAT;    # prints Array

    # string context
    say ~@array;                    # "1 2 3"

    # numeric context
    say +@array;                    # 3

    # boolean context
    my $is-nonempty = ?@array;

Apostrophes C<'> and dashes C<-> are allowed as part of identifiers, as long as
they appear between two letters.

=cut

# S03

=head1 Operators

A comprehensive list of operator changes is documented at L<S03/"Changes to
Perl 5 operators"> and L<S03/"New operators">.

Some highlights:

=head2 C<qw()> changes; new interpolating form

    Was:    qw(foo)
    Now:    <foo>

    Was:    ("foo", (split ' ', $bar), "bat")
    Now:    <<foo $bar bat>>

Quoting operators now have modifiers that can be used with them (much like
regexes and substitutions in Perl 5), and you can even define your own quoting
operators.  See L<S03> for details.

Note that C<()> as a subscript is now a sub call, so instead of C<qw(a b)> you
would write C<< qw<a b> >> or C<qw[a b]> (if you don't like plain C<< <a b>
>>), that is).

=head2 Other important operator changes

String concatenation is now done with C<~>.

Regex match is done with the smart match operator C<~~>, the perl 5 match
operator C<=~> is gone.

    if "abc" ~~ m/a/ { ... }

C<|> and C<&> as infix operators now construct junctions. The binary AND and
binary OR operators are split into string and numeric operators, that is C<~&>
is binary string AND, C<+&> is binary numeric AND, C<~|> is binary string OR
etc.

    Was: $foo & 1;
    Now: $foo +& 1;

The bitwise operators are now prefixed with a +, ~ or ? depending if the
data type is a number, string or boolean.

    Was: $foo << 42;
    Now: $foo +< 42;

The assignment operators have been changed in a similar vein:

    Was: $foo <<= 42;
    Now: $foo +<= 42;

Parenthesis don't construct lists, they merely group. Lists are
constructed with the comma operator. It has tighter precedence than the list
assignment operator, which allows you to write lists on the right hand side
without parens:

    my @list = 1, 2, 3;     # @list really has three elements

The arrow operator C<< -> >> for dereferencing is gone. Since
everything is an object, and derferencing parenthesis are just method calls
with syntactic sugar, you can directly use the appropriate pair of
parentheses for either indexing or method calls:

    my $aoa = [[1, 2, 3], [4, 5, 6], [7, 8, 9]];
    say $aoa[1][0];         # 4

    my $s = sub { say "hi" };
    $s();
    # or
    $s.();
    $lol.[1][0]

=cut

# S04

=head1 Blocks and Statements

See L<S04> for the full specification of blocks and statements in Perl6.

=head2 You don't need parens on control structure conditions

    Was:    if ($a < $b) { ... }
    Now:    if  $a < $b  { ... }

Likewise for C<while>, C<for>, etc. If you insist on using parens, make sure
there's a space after the C<if>, otherwise it's a sub call.

=head2 eval {} is now try {}

Using C<eval> on a block is now replaced with C<try>.

    Was:  eval {
            # ...
          };
          if ($@) {
            warn "oops: $@";
          }
    Now:  try  {
             # ...
             CATCH { warn "oops: $!" }
          }

CATCH provides more flexiblity in handling errors.
See L<S04/"Exception_handlers"> for details.

=head2 foreach becomes for

    Was:    foreach (@whatever) { ... }
    Now:    for @whatever       { ... }

Also, the way of assigning to something other than C<$_> has changed:

    Was:    foreach my $x (@whatever) { ... }
    Now:    for @whatever -> $x       { ... }

This can be extended to take more than one element at a time:

    Was:    while (my($age, $sex, $location) = splice @whatever, 0, 3) { ... }
    Now:    for @whatever -> $age, $sex, $location { ... }

(Except the C<for> version does not destroy the array.)

See L<S04/"The for statement"> and L<S29/"each"> for details.

=head2 for becomes loop

    Was:    for  ($i=0; $i<10; $i++) { ... }
    Now:    loop ($i=0; $i<10; $i++) { ... }

C<loop> can also be used for infinite loops:

    Was:    while (1) { ... }
    Now:    loop { ... }

=cut

# S05

=head1 Regexes and Rules

Here's a simple translation of a Perl5 regular expression to Perl6:

    Was:    $str =~ m/^\d{2,5}\s/i
    Now:    $str ~~ m:P5:i/^\d{2,5}\s/

The C<:P5> modifier is there because the standard Perl6 syntax is rather
different, and 'P5' notes a Perl5 compatibility syntax.  For a substitution:

    Was:    $str =~ s/(a)/$1/e;
    Now:    $str ~~ s:P5/(a)/{$0}/;

Notice that C<$1> starts at C<$0> now, and C</e> is gone
in favor of the embedded closure notation.

For the full specification, see L<S05>. See also:

The related Apocalypse, which justifies the changes:

  http://dev.perl.org/perl6/doc/design/apo/A05.html

And the related Exegesis, which explains it more detail:

  http://dev.perl.org/perl6/doc/design/exe/E05.html

=cut

# S06

=head1 Subroutines

=head1 Formats

Formats will be handled by external libraries.

=cut

#S10

=head1 Packages

=cut

#S11

=head1 Modules

=cut

#S12

=head1 Objects

Perl 6 has a "real" object system, with key words for classes, methods and
attributes. Public attributes have the C<.> twigil, private ones the C<!>
twigil.

    class YourClass {
        has $!private;
        has @.public;

        # and with write accessor
        has $.stuff is rw;

        method do_something {
            if self.can('bark') {
                say "Something doggy";
            }
        }
    }

=head2 Method invocation changes from -> to .

    Was:    $object->method
    Now:    $object.method

=head2 Dynamic method calls distinguish symbolic refs from hard refs

  Was: $self->$method()
  Now: $self.$method()      # hard ref
  Now: $self."$method"()    # symbolic ref

=cut

#S13

=head1 Overloading

Since both builtin functions and operators are multi subs and methods,
changing their behaviour for particular types is a simple as adding the
appropriate multi subs and methods. If you want these to be globally
available, you have to put them into the C<GLOBAL> namespace:

    multi sub GLOBAL::uc(TurkishStr $str) { ... }

    # "overload" the string concatenation:
    multi sub infix:<~>(TurkishStr $us, TurkishStr $them) { ... }

If you want to offer a type cast to a particular type, just provide a method
with the same name as the type you want to cast to.

    sub needs_bar(Bar $x) { ... }
    class Foo {
        ...
        # coercion to type Bar:
        method Bar { ... }
    }

    needs_bar(Foo.new);         # coerces to Bar

=head2 Offering Hash and List semantics

If you want to write a class whose objects can be assigned to a variable with
the C<@> sigil, you have to implement the C<Positional> roles. Likewise, for
the C<%> sigil you need to do the C<Associative> role. The C<&> sigil implies
C<Callable>.

The roles provides the operators C<< postcircumfix:<[ ]> >> (Positional; for
array indexing), C<< postcircumfix:<{ }> >>
(Associative) and C<< postcircumfix:<()> >> (Callable). The are technically
just methods with a fancy syntax.
You should override these to provide meaningful semantics.

    class OrderedHash does Associative {
        multi method postcircumfix:<{ }>(Int $index) {
            # code for accessing single hash elements here
        }
        multi method postcircumfix:<{ }>(*@@slice) {
            # code for accessing hash slices here
        }
        ...
    }

    my %orderedHash = OrderedHash.new();
    say %orderedHash{'a'};

See L<S13> for all the gory details.

=cut

#S16

=head2 Chaining file test operators has changed

    Was: if (-r $file && -x _) {...}
    Now: if $file ~~ :r & :x  {...}

For details, see L<S03/"Changes to Perl 5 operators"/"The filetest operators now return a result that is both a boolean">

=cut

#S26

# XXX needs some brave rewrite


=head1 Builtin Functions

A number of builtins have been removed. For details, see:

L<S29/"Obsolete">

=head2 References are gone (or: everything is a reference)

C<Capture> objects fill the ecological niche of references in Perl 6.
You can think of them as "fat" references, that is, references that
can capture not only the current identity of a single object, but
also the relative identities of several related objects.  Conversely,
you can think of Perl 5 references as a degenerate form of C<Capture>
when you want to refer only to a single item.

  Was: ref $foo eq 'HASH'
  Now: $foo ~~ Hash

  Was: @new = (ref $old eq 'ARRAY' ) ? @$old : ($old);
  Now: @new = @$old;

  Was: %h = ( k => \@a );
  Now: %h = ( k => @a );

To pass an argument to modify by reference:

  Was: sub foo {...};        foo(\$bar)
  Now: sub foo ($bar is rw); foo($bar)

The "obsolete" reference above has the details. Also, look for
I<Capture> under L<S02/"Names_and_Variables">, or at the Capture FAQ,
L<Perl6::FAQ::Capture>.

=head2 say()

This is a version of C<print> that auto-appends a newline:

    Was:    print "Hello, world!\n";
    Now:    say   "Hello, world!";

Since you want to do that so often anyway, it seemed like a handy thing
to make part of the language.

=head2 wantarray() is gone

C<wantarray> is gone. In Perl 6, context flows outwards, which means that a
routine does not know which context it is in.

Instead you should return objects that do the right thing in every context.

=head1 Unfiled

=head2 Hash elements no longer auto-quote

Hash elements no longer auto-quote:

    Was:    $days{February}
    Now:    %days{'February'}
    Or:     %days<February>
    Or:     %days<<February>>

The curly-bracket forms still work, but curly-brackets are more
distinctly block-related now, so in fact what you've got there is a
block that returns the value "February".  The C<<>> and C<<<>>> forms
are in fact just quoting mechanisms being used as subscripts (see below).

=head2 Built-in functions are now methods

Most built-in functions are now methods of built-in classes such
as C<String>, C<Array>, etc.

    Was:    my $len = length($string);
    Now:    my $len = $string.chars;

    Was:    print sort(@array);
    Now:    print @array.sort;
            @array.sort.print;

You can still say C<sort(@array)> if you prefer the non-OO idiom.

=head1 MISCELLANEOUS

Bits that can be file elsewhere.

=head2 Command-line arguments

The command-line arguments are now in C<@*ARGS>, not C<@ARGV>.  Note the
C<*> twigil because C<@*ARGS> is a global.

=head1 AUTHORS

Kirrily "Skud" Robert, C<< <skud@cpan.org> >>,
Mark Stosberg,
Moritz Lenz,
Trey Harris,
Andy Lester