5to6-nutshell.pod6

=begin pod :tag<convert>

=TITLE Perl 5 to Perl 6 guide - Overview

=SUBTITLE How do I do what I used to do? (Perl 6 in a nutshell.)

This page attempts to index the changes in syntax and semantics from
Perl 5 to Perl 6. Whatever worked in Perl 5 and must be written differently
in Perl 6, should be listed here (whereas many I<new> Perl 6 features and
idioms won't be).

Hence this should not be mistaken for a beginner tutorial or a promotional
overview of Perl 6; it is intended as a technical reference for Perl 6
learners with a strong Perl 5 background and for anyone porting Perl 5 code
to Perl 6 (though note that L<#Automated Translation> might be more
convenient).

A note on semantics; when we say "now" in this document, we mostly just
mean "now that you are trying out Perl 6."  We don't mean to imply that
Perl 5 is now suddenly obsolete.  Quite the contrary, most of us love
Perl 5, and we expect Perl 5 to continue in use for a good many years.
Indeed, one of our more important goals has been to make interaction between
Perl 5 and Perl 6 run smoothly.  However, we do also like the design
decisions in Perl 6, which are certainly newer and arguably better
integrated than many of the historical design decisions in Perl 5.
So many of us do hope that over the next decade or two, Perl 6 will
become the more dominant language.  If you want to take "now" in that
future sense, that's okay too.  But we're not at all interested in the
either/or thinking that leads to fights.

=head1 CPAN

See L<https://modules.perl6.org/> .

If the module that you were using has not been converted to Perl 6, and no
alternative is listed in this document, then its use under Perl 6 may not
have been addressed yet.

The L<Inline::Perl5|https://github.com/niner/Inline-Perl5/> project makes
it possible to C<use> Perl 5 modules directly from Perl 6 code by using
an embedded instance of the C<perl> interpreter to run Perl 5 code.

This is as simple as:

=for code :skip-test<Inline module not always present when testing>
# the :from<Perl5> makes Perl 6 load Inline::Perl5 first (if installed)
# and then load the Scalar::Util module from Perl 5
use Scalar::Util:from<Perl5> <looks_like_number>;
say looks_like_number "foo";   # 0
say looks_like_number "42";    # 1

A number of Perl 5 modules have been ported to Perl 6, trying to maintain
the API of these modules as much as possible, as part of the CPAN Butterfly
Plan.  These can be found at L<https://modules.perl6.org/t/CPAN5>.

=head1 Syntax

=head2 Identifiers

In identifiers, Perl 6 allows the use of dashes (C<->), underscores (C<_>), apostrophes (C<'>), and alphanumerics:

    sub test-doesn't-hang { ... }
    my $ความสงบ = 42;
    my \Δ = 72; say 72 - Δ;

=head2 C«->» Method calls

If you've read any Perl 6 code at all, it's immediately obvious that
method call syntax now uses a dot instead of an arrow:

=for code :lang<perl5>
$person->name  # Perl 5
=for code :preamble<no strict;>
$person.name   # Perl 6

The dot notation is both easier to type and more of an industry standard.
But we also wanted to steal the arrow for something else.  (Concatenation
is now done with the C<~> operator, if you were wondering.)

To call a method whose name is not known until runtime:

=for code :lang<perl5>
$object->$methodname(@args);  # Perl 5
=for code :preamble<no strict;>
$object."$methodname"(@args); # Perl 6

If you leave out the quotes, then Perl 6 expects C<$methodname> to contain
a C<Method> object, rather than the simple string name of the method.  Yes,
B<everything> in Perl 6 can be considered an object.

=head2 Whitespace

Perl 5 allows a surprising amount of flexibility in the use of whitespace,
even with strict mode and warnings turned on:

=for code :lang<perl5>
# unidiomatic but valid Perl 5
say"Hello ".ucfirst  ($people
    [$ i]
    ->
    name)."!"if$greeted[$i]<1;

Perl 6 also endorses programmer freedom and creativity, but balanced
syntactic flexibility against its design goal of having a consistent,
deterministic, extensible grammar that supports single-pass parsing and
helpful error messages, integrates features like custom operators cleanly,
and doesn't lead programmers to accidentally misstate their intent.
Also, the practice of "code golf" is slightly de-emphasized; Perl 6 is
designed to be more concise in concepts than in keystrokes.

As a result, there are various places in the syntax where whitespace is
optional in Perl 5, but is either mandatory or forbidden in Perl 6. Many of
those restrictions are unlikely to concern much real-life Perl code (e.g.,
whitespace being disallowed between the sigil and name of a variable), but
there are a few that will unfortunately conflict with some Perl hackers'
habitual coding styles:

=begin item
I<No space allowed before the opening parenthesis of an argument list.>

=for code :lang<perl5>
substr ($s, 4, 1); # Perl 5 (in Perl 6 this would try to pass a single
                       #         argument of type List to substr)
=for code :preamble<no strict;>
substr($s, 4, 1);  # Perl 6
substr $s, 4, 1;   # Perl 6 - alternative parentheses-less style

Should this really be a problem for you, then you might want to have a look
at the C<Slang::Tuxic> module in the Perl 6 ecosystem: it changes the grammar
of Perl 6 in such a way that you B<can> have a space before the opening
parenthesis of an argument list.

=end item

=begin item
I<Space is B<required> immediately after keywords>

=for code :lang<perl5>
my($alpha, $beta);          # Perl 5, tries to call my() sub in Perl 6
=for code :preamble<no strict;>
my ($alpha, $beta);         # Perl 6

=for code :lang<perl5>
if($a < 0) { ... }          # Perl 5, dies in Perl 6
=for code :preamble<no strict;>
if ($a < 0) { ... }         # Perl 6
if $a < 0 { ... }           # Perl 6, more idiomatic

=for code :lang<perl5>
while($x-- > 5) { ... }     # Perl 5, dies in Perl 6
=for code :preamble<no strict;>
while ($x-- > 5) { ... }    # Perl 6
while $x-- > 5 { ... }      # Perl 6, more idiomatic

=end item

=begin item
I<No space allowed after a prefix operator, or before a
postfix/postcircumfix operator (including array/hash subscripts).>

=for code :lang<perl5>
$seen {$_} ++; # Perl 5
=for code :preamble<no strict;>
%seen{$_}++;   # Perl 6
=end item

=begin item
I<Space required before an infix operator if it would
conflict with an existing postfix/postcircumfix operator.>

=for code :lang<perl5>
$n<1;   # Perl 5 (in Perl 6 this would conflict with postcircumfix < >)
=for code :preamble<no strict;>
$n < 1; # Perl 6

=end item

=begin item
I<However, whitespace B<is allowed> before the period of a method call!>

=for code :lang<perl5>
# Perl 5
my @books = $xml
  ->parse_file($file)          # some comment
  ->findnodes("/library/book");

=for code :preamble<no strict;>
# Perl 6
my @books = $xml
  .parse-file($file)           # some comment
  .findnodes("/library/book");

=end item

However, note that you can use L<unspace|https://design.perl6.org/S02.html#Unspaces>
to add whitespace in Perl 6 code in places where it is otherwise not
allowed.

See also L<S03#Minimal whitespace DWIMmery|https://design.perl6.org/S03.html#Minimal_whitespace_DWIMmery> and
L<S04#Statement parsing|https://design.perl6.org/S04.html#Statement_parsing>
in the Perl 6 design docs.

=head2 Sigils

In Perl 5, arrays and hashes use changing sigils depending on how they are
being accessed. In Perl 6 the sigils are invariant, no matter how the
variable is being used - you can think of them as part of the variable's
name.

=head3 C<$> Scalar

The C<$> sigil is now always used with "scalar" variables (e.g. C<$name>),
and no longer for L<array indexing|#[]_Array_indexing/slicing> and L<Hash
indexing|#{}_Hash_indexing/slicing>.  That is, you can still use C<$x[1]>
and C<$x{"foo"}>, but it will act on $x, with no effect on a similarly
named @x or %x. Those would now be accessed with @x[1] and %x{"foo"}.

=head3 C<@> Array

The C<@> sigil is now always used with "array" variables (e.g. C<@months>,
C<@months[2]>, C<@months[2, 4]>), and no longer for L<value-slicing
hashes|#{}_Hash_indexing/slicing>.

=head3 C<%> Hash

The C<%> sigil is now always used with "hash" variables (e.g. C<%calories>,
C<%calories<apple>>, C<%calories<pear plum>>), and no longer for
L<key/value-slicing arrays|#[]_Array_indexing/slicing>.

=head3 C<&> Sub

The C<&> sigil is now used consistently (and without the help of a
backslash) to refer to the function object of a named subroutine/operator
without invoking it, i.e. to use the name as a "noun" instead of a "verb":

=for code :lang<perl5>
my $sub = \&foo; # Perl 5
=for code :preamble<sub foo {};>
my $sub = &foo;  # Perl 6

=for code :lang<perl5>
callback => sub { say @_ }  # Perl 5 - can't pass built-in sub directly
=for code
callback => &say            # Perl 6 - & gives "noun" form of any sub

Since Perl 6 does not allow adding/removing symbols in a lexical scope once
it has finished compiling, there is no equivalent to Perl 5's
C<undef &foo;>, and the closest equivalent to Perl 5's C<defined &foo>
would be C<defined ::('&foo')> (which uses the "dynamic symbol lookup"
syntax). However, you can declare a mutable named subroutine with
C<my &foo;> and then change its meaning at runtime by assigning to C<&foo>.

In Perl 5, the ampersand sigil can additionally be used to call subroutines
in special ways with subtly different behavior compared to normal sub
calls. In Perl 6 those special forms are no longer available:

=begin item
C<&foo(...)> I<for circumventing a function prototype>

In Perl 6 there are no prototypes, and it no longer
makes a difference whether you, say, pass a literal code block or a
variable holding a code object as an argument:

=for code :lang<perl5>
# Perl 5:
first_index { $_ > 5 } @values;
&first_index($coderef, @values); # (disabling the prototype that parses a
                                     # literal block as the first argument)
=for code
# Perl 6:
first { $_ > 5 }, @values, :k;   # the :k makes first return an index
first $coderef, @values, :k;
=end item

=begin item
C<&foo;> I<and> C<goto &foo;> I<for re-using the caller's argument list /
replacing the caller in the call stack>. Perl 6 can use either L<C<callsame>|/language/functions#index-entry-dispatch_callsame> for re-dispatching or L<C<nextsame>|/language/functions#index-entry-dispatch_nextsame> and L<C<nextwith>|/language/functions#index-entry-dispatch_nextwith>, which have no exact equivalent in Perl 5.

=begin comment
    # TODO: Suggest .nextsame and .nextwith once they've been implemented in Rakudo.
=end comment

=for code :lang<perl5>
sub foo { say "before"; &bar;     say "after" } # Perl 5
=for code
sub foo { say "before"; bar(|@_); say "after" } # Perl 6 - have to be explicit


=for code :lang<perl5>
sub foo { say "before"; goto &bar } # Perl 5
=begin code
proto foo (|) {*};
multi foo ( Any $n ) {
    say "Any"; say $n;
};
multi foo ( Int $n ) {
    say "Int"; callsame;
};
foo(3); # /language/functions#index-entry-dispatch_callsame
=end code

=end item

=head3 C<*> Glob

=comment TODO: Research what exact use-cases still need typeglobs in Perl 5
         today, and refactor this section to list them (with translations).

In Perl 5, the C<*> sigil referred to the GLOB structure that Perl uses to
store non-lexical variables, filehandles, subs, and formats.

(This should not be confused with the Perl 5 built-in C<glob()> function,
which reads filenames from a directory).

You are most likely to encounter a GLOB in code written on a early Perl
version that does not support lexical filehandles, when a filehandle needed
to be passed into a sub.

=for code :lang<perl5>
# Perl 5 - ancient method
sub read_2 {
    local (*H) = @_;
    return scalar(<H>), scalar(<H>);
}
open FILE, '<', $path or die;
my ($line1, $line2) = read_2(*FILE);

You should refactor your Perl 5 code to remove the need for the GLOB,
before translating into Perl 6.

=for code :lang<perl5>
# Perl 5 - modern use of lexical filehandles
sub read_2 {
    my ($fh) = @_;
    return scalar(<$fh>), scalar(<$fh>);
}
open my $in_file, '<', $path or die;
my ($line1, $line2) = read_2($in_file);

And here's just one possible Perl 6 translation:

=for code :preamble<no strict;>
# Perl 6
sub read-n($fh, $n) {
    return $fh.get xx $n;
}
my $in-file = open $path or die;
my ($line1, $line2) = read-n($in-file, 2);

=head2 [] Array indexing/slicing

Index and slice operations on arrays no longer inflect the variable's
L<sigil|#@_Array>, and adverbs can be used to control the type of slice:

=begin item
I<Indexing>

=for code :lang<perl5>
say $months[2]; # Perl 5
=for code :preamble<no strict;>
say @months[2]; # Perl 6 - @ instead of $
=end item

=begin item
I<Value-slicing>

=for code :preamble<no strict;>
say join ',', @months[6, 8..11]; # Perl 5 and Perl 6
=end item

=begin item
I<Key/value-slicing>

=for code :lang<perl5>
say join ',', %months[6, 8..11];    # Perl 5
=for code :preamble<no strict;>
say join ',', @months[6, 8..11]:kv; # Perl 6 - @ instead of %; use :kv adverb
=end item

Also note that the subscripting brackets are now a normal postcircumfix
operator rather than a special syntactic form, and thus L<checking for
existence of elements|#exists> and L<unsetting elements|#delete> is done
with adverbs.

=head2 {} Hash indexing/slicing

Index and slice operations on hashes no longer inflect the variable's
L<sigil|#%_Hash>, and adverbs can be used to control the type of slice.
Also, single-word subscripts are no longer magically autoquoted inside the
curly braces; instead, the new angle-brackets version is available which
always autoquotes its contents (using the same rules as the C<qw//> quoting
construct):

=begin item
I<Indexing>

=for code :lang<perl5>
say $calories{"apple"}; # Perl 5
=for code :preamble<no strict;>
say %calories{"apple"}; # Perl 6 - % instead of $

=for code :lang<perl5>
say $calories{apple};   # Perl 5
=for code :preamble<no strict;>
say %calories<apple>;   # Perl 6 - angle brackets; % instead of $
say %calories«"$key"»;  # Perl 6 - double angles interpolate as a list of Str
=end item

=begin item
I<Value-slicing>

=for code :lang<perl5>
say join ',', @calories{'pear', 'plum'}; # Perl 5
=for code :preamble<no strict;>
say join ',', %calories{'pear', 'plum'}; # Perl 6 - % instead of @
say join ',', %calories<pear plum>;      # Perl 6 (prettier version)
my $keys = 'pear plum';
say join ',', %calories«$keys»;          # Perl 6 the split is done after interpolation
=end item

=begin item
I<Key/value-slicing>

=for code :lang<perl5>
say join ',', %calories{'pear', 'plum'};    # Perl 5
=for code :preamble<no strict;>
say join ',', %calories{'pear', 'plum'}:kv; # Perl 6 - use :kv adverb
say join ',', %calories<pear plum>:kv;      # Perl 6 (prettier version)
=end item

Also note that the subscripting curly braces are now a normal postcircumfix
operator rather than a special syntactic form, and thus L<checking for
existence of keys|#exists> and L<removing keys|#delete> is done with
adverbs.

=head2 Creating references and using them

In Perl 5, references to anonymous arrays and hashes and subs are returned
during their creation. References to existing named variables and subs were
generated with the C<\> operator. the "referencing/dereferencing"
metaphor does not map cleanly to the actual Perl 6 container system,
so we will have to focus on the intent of the reference operators
instead of the actual syntax.

=for code :lang<perl5>
my $aref =     \@aaa  ; # Perl 5

This might be used for passing a reference to a routine, for instance. But in Perl 6, the default behavior is a pass by reference.

=begin code
my @a = 4,8,15;
(-> @array { @array[0] = 66})(@a);
say @a; #  OUTPUT: «[66 8 15]␤»
=end code

The declared C<@a> is passed by reference, and its first value modified inside the declared routine.

In Perl 5, the syntax for dereferencing an entire reference is the
type-sigil and curly braces, with the reference inside the curly braces. In Perl 6, this concept simply does not apply, since the I<reference> metaphor does not really apply.

In Perl 5, the arrow operator, C«->» , is used for single access to a
composite's reference or to call a sub through its reference. In Perl 6,
the dot operator C<.> is always used for object methods, but the rest does not really apply.

=for code :lang<perl5>
# Perl 5
    say $arrayref->[7];
    say $hashref->{'fire bad'};
    say $subref->($foo, $bar);

In relatively recent versions of Perl 5 (5.20 and later), a new feature allows the use of the arrow
operator for dereferencing:  see
L<Postfix Dereferencing|http://search.cpan.org/~shay/perl-5.20.1/pod/perl5200delta.pod#Experimental_Postfix_Dereferencing>. This
can be used to create an array from a scalar. This operation is
usually called I<decont>, as in decontainerization, and in Perl 6
methods such as C<.list> and C<.hash> are used:

=for code :lang<perl5>
# Perl 5.20
    use experimental qw< postderef >;
    my @a = $arrayref->@*;
    my %h = $hashref->%*;
    my @slice = $arrayref->@[3..7];

=for code :preamble<no strict;>
# Perl 6
    my @a = $contains-an-array.list;        # or @($arrayref)
    my %h = $contains-a-hash.hash;          # or %($hashref)

The "Zen" slice does the same thing:

=for code :preamble<no strict;>
# Perl 6
    my @a = $contains-an-array[];
    my %h = $contains-a-hash{};

See L<the "Containers" section of the documentation|/language/containers> for more information.

=head1 Operators

See L<S03/Operators|https://design.perl6.org/S03.html#Overview>
for full details on all operators.

Unchanged:

=item C<+> Numeric Addition
=item C<-> Numeric Subtraction
=item C<*> Numeric Multiplication
=item C</> Numeric Division
=item C<%> Numeric Modulus
=item C<**> Numeric Exponentiation
=item C<++> Numeric Increment
=item C<--> Numeric Decrement
=item C<! && || ^> Booleans, high-precedence
=item C<not and or xor> Booleans, low-precedence
=item C«== != < > <= >=»   Numeric comparisons
=item C<eq ne lt gt le ge>  String comparisons

=head2 C<,> (Comma) List Separator

Unchanged, but note that in order to flatten an array variable to a list (in
order to append or prefix more items) one should use the C<|> operator
(see also L<Slip|/type/Slip>). For instance:

=for code
my @numbers = 100, 200, 300;
my @more_numbers = 500, 600, 700;
my @all_numbers = |@numbers, 400, |@more_numbers;

That way one can concatenate arrays.

Note that one does not need to have any parentheses on the right hand side:
the List Separator takes care of creating the list, B<not> the parentheses!

=head2 C«<=> cmp» Three-way comparisons

In Perl 5, these operators returned -1, 0, or 1.
In Perl 6, they return C<Order::Less>, C<Order::Same>, or C<Order::More>.

C«cmp» is now named C«leg»; it forces string context for the comparison.

C«<=>» still forces numeric context.

C«cmp» in Perl 6 does either C«<=>» or C<leg>, depending on the existing
type of its arguments.

=head2 C<~~> Smartmatch operator

While the operator has not changed, the rules for what exactly is matched
depend on the types of both arguments, and those rules are far from
identical in Perl 5 and Perl 6. See L<~~|/routine/~~> and
L<S03/Smartmatching|https://design.perl6.org/S03.html#Smart_matching>

=head2 C<& | ^> String Bitwise ops
=head2 C<& | ^> Numeric Bitwise ops
=head2 C<& | ^> Boolean ops

In Perl 5, C<& | ^> were invoked according to the contents of their
arguments. For example, C<31 | 33> returns a different result than C<"31" |
"33">.

In Perl 6, those single-character ops have been removed, and replaced by
two-character ops which coerce their arguments to the needed context.

=begin code :skip-test
# Infix ops (two arguments; one on each side of the op)
+&  +|  +^  And Or Xor: Numeric
~&  ~|  ~^  And Or Xor: String
?&  ?|  ?^  And Or Xor: Boolean

# Prefix ops (one argument, after the op)
+^  Not: Numeric
~^  Not: String
?^  Not: Boolean (same as the ! op)
=end code

=head2 C«<< >>» Numeric shift left|right ops

Replaced by C«+<» and C«+>» .

=for code :lang<perl5>
say 42 << 3; # Perl 5
=for code
say 42 +< 3; # Perl 6

=head2 C«=>» Fat comma

In Perl 5, C«=>» acted just like a comma, but also quoted its left-hand
side.

In Perl 6, C«=>» is the L<Pair|/type/Pair> operator, which is quite different in
principle, but works the same in many situations.

If you were using C«=>» in hash initialization, or in passing arguments to
a sub that expects a hashref, then the usage is likely identical.

    sub get_the_loot { ... }; # Perl 6 stub
    # Works in Perl 5 and Perl 6
    my %hash = ( AAA => 1, BBB => 2 );
    get_the_loot( 'diamonds', { quiet_level => 'very', quantity => 9 }); # Note the curly braces

If you were using C«=>» as a convenient shortcut to not have to quote part
of a list, or in passing arguments to a sub that expects a flat list of
KEY, VALUE, KEY, VALUE, then continuing to use C«=>» may break your code.
The easiest workaround is to change the fat comma to a regular comma, and
manually add quotes to its left-hand side. Or, you can change the sub's API
to L<slurp a hash|/type/Signature#Slurpy_(A.K.A._Variadic)_Parameters>.
A better long-term solution is to change the sub's API to
expect L<Pair|/type/Pair>s; however, this requires you to change
all sub calls at once.

=begin code :lang<perl5>
# Perl 5
sub get_the_loot {
    my $loot = shift;
    my %options = @_;
    # ...
}
# Note: no curly braces in this sub call
get_the_loot( 'diamonds', quiet_level => 'very', quantity => 9 );
=end code

=begin code
# Perl 6, original API
sub get_the_loot( $loot, *%options ) { # The * means to slurp everything
    ...
}
get_the_loot( 'diamonds', quiet_level => 'very', quantity => 9 ); # Note: no curly braces in this API

# Perl 6, API changed to specify valid options
# The colon before the sigils means to expect a named variable,
# with the key having the same name as the variable.
sub get_the_loot( $loot, :$quiet_level?, :$quantity = 1 ) {
    # This version will check for unexpected arguments!
    ...
}
get_the_loot( 'diamonds', quietlevel => 'very' ); # Throws error for misspelled parameter name
=end code

=head2 C<? :> Ternary operator

The conditional operator C<? :> has been replaced
by C<?? !!>:

=for code :lang<perl5>
my $result = $score > 60 ?  'Pass' :  'Fail'; # Perl 5

=for code :preamble<my $score>
my $result = $score > 60 ?? 'Pass' !! 'Fail'; # Perl 6

=head2 C<.> (Dot) String Concatenation

Replaced by the tilde.

Mnemonic: think of "stitching" together the two strings with needle and thread.

=for code :lang<perl5>
$food = 'grape' . 'fruit'; # Perl 5
=for code :preamble<no strict;>
$food = 'grape' ~ 'fruit'; # Perl 6

=head2 C<x> List Repetition or String Repetition operator

In Perl 5, C<x> is the Repetition operator, which behaves differently in
scalar or list contexts:
=item in scalar context C<x> repeats a string;
=item in list context C<x> repeats a list, but only if the left argument
is parenthesized!

Perl 6 uses two different Repetition operators to achieve the above:
=item C<x> for string repetitions (in any context);
=item C<xx> for list repetitions (in any context).

Mnemonic: C<x> is short and C<xx> is long, so C<xx> is the one used for lists.

=for code :lang<perl5>
# Perl 5
    print '-' x 80;             # Print row of dashes
    @ones = (1) x 80;           # A list of 80 1's
    @ones = (5) x @ones;        # Set all elements to 5
=for code :preamble<no strict;>
# Perl 6
    print '-' x 80;             # Unchanged
    @ones = 1 xx 80;            # Parentheses no longer needed
    @ones = 5 xx @ones;         # Parentheses no longer needed


=head2 C<..> C<...> Two Dots or Three Dots, Range op or Flipflop op

In Perl 5, C<..> was one of two completely different operators, depending
on context.

In list context, C<..> is the familiar range operator. Ranges from Perl 5
code should B<not> require translation.

In scalar context, C<..> and C<...> were the little-known Flipflop
operators. They have been replaced by C<ff> and C<fff>.

=head2 String interpolation

In Perl 5, C<"${foo}s"> deliminates a variable name from regular text next to it.
In Perl 6, simply extend the curly braces to include the sigil too: C<"{$foo}s">.
This is in fact a very simple case of interpolating an expression.

=head1 Compound Statements

=head2 Conditionals

=head3 C<if> C<elsif> C<else> C<unless>

Mostly unchanged; parentheses around the conditions are now optional, but if
used, must not immediately follow the keyword, or it will be taken as a function
call instead.  Binding the conditional expression to a variable is also a little different:

=for code :lang<perl5>
if (my $x = dostuff()) {...}  # Perl 5
=for code :preamble<sub dostuff {};>
if dostuff() -> $x {...}      # Perl 6

(You can still use the C<my> form in Perl 6, but it will scope to the
outer block, not the inner.)

The C<unless> conditional only allows for a single block in Perl 6;
it does not allow for an C<elsif> or C<else> clause.

=head3 C<given>-C<when>

The C<given>-C<when> construct is like a chain of C<if>-C<elsif>-C<else>
statements or like the C<switch>-C<case> construct in e.g. C.  It has the
general structure:

=for code :lang<pseudo>
given EXPR {
    when EXPR { ... }
    when EXPR { ... }
    default { ... }
}

In its simplest form, the construct is as follows:

=for code :preamble<no strict;>
given $value {                   # assigns $_
    when "a match" {             # if $_ ~~ "a match"
        # do-something();
    }
    when "another match" {       # elsif $_ ~~ "another match"
        # do-something-else();
    }
    default {                    # else
        # do-default-thing();
    }
}

This is simple in the sense that a scalar value is matched in the C<when>
statements against C<$_>, which was set by the C<given>.  More generally,
the matches are actually smartmatches on C<$_> such that lookups using more
complex entities such as regexps can be used instead of scalar values.

See also the warnings on the smartmatch op above.

=head2 Loops

=head3 C<while> C<until>

Mostly unchanged; parentheses around the conditions are now optional, but if
used, must not immediately follow the keyword, or it will be taken as a function
call instead.  Binding the conditional expression to a variable is also a little different:

=for code :lang<perl5>
while (my $x = dostuff()) {...}  # Perl 5
=for code :preamble<sub dostuff {};>
while dostuff() -> $x {...}      # Perl 6

(You can still use the C<my> form in Perl 6, but it will scope to the
outer block, not the inner.)

Note that reading line-by-line from a filehandle has changed.

In Perl 5, it was done in a C<while> loop using the diamond operator. Using
C<for> instead of C<while> was a common bug, because the C<for> causes the
whole file to be sucked in at once, swamping the program's memory usage.

In Perl 6, C<for> statement is B<lazy>, so we read line-by-line in a C<for>
loop using the C<.lines> method.

=for code :lang<perl5>
while (<IN_FH>)  { } # Perl 5
=for code :preamble<no strict;>
for $IN_FH.lines { } # Perl 6

Also note that in Perl 6, lines are C<chomp>ed by default.

=head3 C<do> C<while>/C<until>

=begin code :lang<perl5>
# Perl 5
do {
    ...
} while $x < 10;

do {
    ...
} until $x >= 10;
=end code

The construct is still present, but C<do> was renamed to C<repeat>, to better
represent what the construct does:

=begin code :preamble<no strict;>
# Perl 6
repeat {
    ...
} while $x < 10;

repeat {
    ...
} until $x >= 10;
=end code

=head3 C<for> C<foreach>

Note first this common misunderstanding about the C<for> and C<foreach>
keywords. Many programmers think that they distinguish between the C-style
three-expression form and the list-iterator form; they do not! In fact,
the keywords are interchangeable; the Perl 5 compiler looks for the
semi-colons within the parentheses to determine which type of loop to parse.

The C-style three-factor form now uses the C<loop> keyword, and is
otherwise unchanged. The parentheses B<are> still required.

=for code :lang<perl5>
for  ( my $i = 1; $i <= 10; $i++ ) { ... } # Perl 5
=for code
loop ( my $i = 1; $i <= 10; $i++ ) { ... } # Perl 6


The loop-iterator form is named C<for> in Perl 6 and C<foreach> is no longer a keyword.
The C<for> loop has the following rules:
=item parentheses are optional;
=item the iteration variable, if any, has been moved from appearing before the list, to
appearing after the list and an added arrow operator;
=item the iteration variable is now always lexical: C<my> is neither needed nor
allowed;
=item the iteration variable is a I<read-only> alias to the current list element (in Perl 5
it is a I<read-write> alias!). If a read-write alias is required, change the C«->»  before the iteration
variable to a C«<->». When translating from Perl 5, inspect the use of the loop variable to decide if
read-write is needed.

=for code :lang<perl5>
for my $car (@cars)  {...} # Perl 5; read-write
=for code :preamble<no strict;>
for @cars  -> $car   {...} # Perl 6; read-only
for @cars <-> $car   {...} # Perl 6; read-write

If the default topic C<$_> is being used, it is also read-write.

=for code :lang<perl5>
for (@cars)      {...} # Perl 5; $_ is read-write
=for code :preamble<no strict;>
for @cars        {...} # Perl 6; $_ is read-write
for @cars <-> $_ {...} # Perl 6; $_ is also read-write

It is possible to consume more than one element of the list in each iteration simply specifying
more than one variable after the arrow operator:

=begin code
my @array = 1..10;
for @array -> $first, $second {
    say "First is $first, second is $second";
}
=end code

=head4 C<each>

Here is the equivalent to Perl 5’s C<while…each(%hash)> or C<while…each(@array)>
(i.e., iterating over both the keys/indices and values of a data structure) in
Perl 6:

=for code :lang<perl5>
while (my ($i, $v) = each(@array)) { ... } # Perl 5
=for code :preamble<no strict;>
for @array.kv -> $i, $v { ... } # Perl 6

=for code :lang<perl5>
while (my ($k, $v) = each(%hash)) { ... } # Perl 5
=for code :preamble<no strict;>
for %hash.kv -> $k, $v { ... } # Perl 6

=head2 Flow Control statements

Unchanged:

=item C<next>
=item C<last>
=item C<redo>

=head3 C<continue>

There is no longer a C<continue> block.
Instead, use a C<NEXT> block (phaser) within the body of the loop.

=for code :lang<perl5>
# Perl 5
    my $str = '';
    for (1..5) {
        next if $_ % 2 == 1;
        $str .= $_;
    }
    continue {
        $str .= ':'
    }

=for code
# Perl 6
    my $str = '';
    for 1..5 {
        next if $_ % 2 == 1;
        $str ~= $_;
        NEXT {
            $str ~= ':'
        }
    }

Please note that phasers don't really need a block.  This can be very handy
when you don't want another scope:

=for code
# Perl 6
    my $str = '';
    for 1..5 {
        next if $_ % 2 == 1;
        $str ~= $_;
        NEXT $str ~= ':';
    }


=head1 Functions

=comment NOTE FOR EDITORS: When adding functions, please place them in
                           alphabetical order.

=head2 Built-ins with bare blocks

Builtins that previously accepted a bare block followed, without
a comma, by the remainder of the arguments will now
require a comma between the block and the arguments e.g. C<map>, C<grep>,
etc.

=for code :lang<perl5>
my @results = grep { $_ eq "bars" } @foo; # Perl 5
=for code :preamble<no strict;>
my @results = grep { $_ eq "bars" }, @foo; # Perl 6


=head2 C<delete>

Turned into an adverb of the
L<C<{}> hash subscripting|#{}_Hash_indexing/slicing>
and L<C<[]> array subscripting|#[]_Array_indexing/slicing> operators.

=for code :lang<perl5>
my $deleted_value = delete $hash{$key};  # Perl 5
=for code :preamble<no strict;>
my $deleted_value = %hash{$key}:delete;  # Perl 6 - use :delete adverb

=for code :lang<perl5>
my $deleted_value = delete $array[$i];  # Perl 5
=for code :preamble<no strict;>
my $deleted_value = @array[$i]:delete;  # Perl 6 - use :delete adverb

=head2 C<exists>

Turned into an adverb of the
L<C<{}> hash subscripting|#{}_Hash_indexing/slicing>
and L<C<[]> array subscripting|#[]_Array_indexing/slicing> operators.

=for code :lang<perl5>
say "element exists" if exists $hash{$key};  # Perl 5
=for code :preamble<no strict;>
say "element exists" if %hash{$key}:exists;  # Perl 6 - use :exists adverb

=for code :lang<perl5>
say "element exists" if exists $array[$i];  # Perl 5
=for code :preamble<no strict;>
say "element exists" if @array[$i]:exists;  # Perl 6 - use :exists adverb

=head1 Regular Expressions ( Regex / Regexp )

=head2 Change C<=~> and C<!~> to C<~~> and C<!~~> .

In Perl 5, matches and substitutions are done against a variable using the
C<=~> regexp-binding op.

In Perl 6, the C<~~> smartmatch op is used instead.

=for code :lang<perl5>
next if $line  =~ /static/  ; # Perl 5
=for code :preamble<no strict;>
next if $line  ~~ /static/  ; # Perl 6

=for code :lang<perl5>
next if $line  !~ /dynamic/ ; # Perl 5
=for code :preamble<no strict;>
next if $line !~~ /dynamic/ ; # Perl 6

=for code :lang<perl5>
$line =~ s/abc/123/;          # Perl 5
=for code :preamble<no strict;>
$line ~~ s/abc/123/;          # Perl 6

Alternately, the new C<.match> and C<.subst> methods can be used. Note that
C<.subst> is non-mutating. See
L<S05/Substitution|https://design.perl6.org/S05.html#Substitution>.

=head2 Captures start with 0, not 1

=for code :lang<perl5>
/(.+)/ and print $1; # Perl 5
=for code
/(.+)/ and print $0; # Perl 6

=head2 Move modifiers

Move any modifiers from the end of the regex to the beginning. This may
require you to add the optional C<m> on a plain match like C«/abc/».

=for code :lang<perl5>
next if $line =~    /static/i ; # Perl 5
=for code :preamble<no strict;>
next if $line ~~ m:i/static/  ; # Perl 6

=head2 Add :P5 or :Perl5 adverb

If the actual regex is complex, you may want to use it as-is, by adding the
C<P5> modifier.

=for code :lang<perl5>
next if $line =~    m/[aeiou]/   ; # Perl 5
=for code :preamble<no strict;>
next if $line ~~ m:P5/[aeiou]/   ; # Perl 6, using P5 modifier
next if $line ~~ m/  <[aeiou]> / ; # Perl 6, native new syntax

Please note that the Perl 5 regular expression syntax dates from many years
ago and may lack features that have been added since the beginning of the
Perl 6 project.

=head2 Special matchers generally fall under the <> syntax

There are many cases of special matching syntax that Perl 5 regexes
support. They won't all be listed here, but often instead of being
surrounded by C<()>, the assertions will be surrounded by C«<>».

For character classes, this means that:

=item C<[abc]> becomes C«<[abc]>»

=item C<[^abc]> becomes C«<-[abc]>»

=item C<[a-zA-Z]> becomes C«<[a..zA..Z]>»

=item C<[[:upper:]]> becomes C«<:Upper>»

=item C<[abc[:upper:]]> becomes C«<[abc]+:Upper>»

For lookaround assertions:

=item C<(?=[abc])> becomes C«<?[abc]>»

=item C<(?=ar?bitrary* pattern)> becomes C«<before ar?bitrary* pattern>»

=item C<(?!=[abc])> becomes C«<![abc]>»

=item C<(?!=ar?bitrary* pattern)> becomes C«<!before ar?bitrary* pattern>»

=item C«(?<=ar?bitrary* pattern)» becomes C«<after ar?bitrary* pattern>»

=item C«(?<!ar?bitrary* pattern)» becomes C«<!after ar?bitrary* pattern>»

For more info see L«lookahead assertions|/language/regexes#Lookahead_assertions_<?before_pattern>».

(Unrelated to <> syntax, the "lookaround" C</foo\Kbar/> becomes C«/foo <( bar )> /»

=item C<(?(?{condition))yes-pattern|no-pattern)> becomes C«[ <?{condition}>
      yes-pattern | no-pattern ]»

=head2 Longest token matching (LTM) displaces alternation

In Perl 6 regexes, C<|> does LTM, which decides which alternation wins
an ambiguous match based off of a set of rules, rather than about which
was written first.

The simplest way to deal with this is just to change any C<|> in your
Perl 5 regex to a C<||>.

However, if a regex written with C<||> is inherited or composed into a grammar
that uses C<|> either by design or typo, the result may not work as expected.
So when the matching process becomes complex, you finally need to have some
understanding of both, especially how LTM strategy works. Besides, C<|> may be
a better choice for grammar reuse.

TODO more rules. Use L<< C<translate_regex.pl> from Blue Tiger|https://github.com/Util/Blue_Tiger/ >> in the meantime.

=head3 Comments

As with Perl 5, comments work as usual in regexes.

    / word #`(match lexical "word") /


=head1 Pragmas

=head3 C<strict>

Strict mode is now on by default.

=head3 C<warnings>

Warnings are now on by default.

C<no warnings> is currently L<NYI|/language/glossary#NYI>,
but putting things in a quietly {} block will silence.

=head3 C<autodie>

The functions which were altered by C<autodie> to throw exceptions on
error, now generally return C<Failure>s by default.  You can test a C<Failure>
for definedness / truthiness without any problem.  If you use the C<Failure>
in any other way, then the C<Exception> that was encapsulated by the C<Failure>
will be thrown.

=for code :lang<perl5>
# Perl 5
open my $i_fh, '<', $input_path;  # Fails silently on error
use autodie;
open my $o_fh, '>', $output_path; # Throws exception on error

=for code :preamble<no strict;>
# Perl 6
my $i_fh = open $input_path,  :r; # Returns Failure on error
my $o_fh = open $output_path, :w; # Returns Failure on error

Because you can check for truthiness without any problem, you can use the
result of an C<open> in an C<if> statement:

=for code :preamble<no strict;>
# Perl 6
if open($input_path,:r) -> $handle {
    .say for $handle.lines;
}
else {
    # gracefully handle the fact that the open() failed
}

=head3 C<base>
=head3 C<parent>

Both C<use base> and C<use parent> have been replaced in Perl 6 by the
C<is> keyword, in the class declaration.

=for code :lang<perl5>
# Perl 5
package Cat;
use base qw(Animal);

=for code :preamble<class Animal {}>
# Perl 6
class Cat is Animal {}

Note that the C<Animal> class must be B<known> at compilation time prior to
be able to inherit from it.

=head3 C<bigint> C<bignum> C<bigrat>

No longer relevant.

C<Int> is now arbitrary precision, as is the numerator of C<Rat> (the
denominator is limited to C<2**64>, after which it will automatically
upgrade to C<Num> to preserve performance).  If you want a C<Rat> with
an arbitrary-precision denominator, C<FatRat> is available.

=head3 X<C<constant>|constant>

In Perl 6, C<constant> is a declarator for variables, just like C<my>,
except the variable is permanently locked to the result of its
initialization expression (evaluated at compile time).

So, change the C«=>» to C<=>.

=for code :lang<perl5>
use constant DEBUG => 0; # Perl 5
=for code :preamble<no strict;>
constant DEBUG = 0;      # Perl 6

=for code :lang<perl5>
use constant pi => 4 * atan2(1, 1); # Perl 5
=for code
 tau, pi, e, i; # built-in constants in Perl 6
 τ, π, 𝑒        # and their unicode equivalents

=head3 C<encoding>

TODO Allows you to write your script in non-ascii or non-utf8

=head3 C<integer>

Perl pragma to use integer arithmetic instead of floating point.  There is
no such equivalent in Perl 6.  If you use native integers in your calculations,
then this will be the closest thing.

=for code
my int $foo = 42;
my int $bar = 666;
say $foo * $bar;    # uses native integer multiplication

=head3 C<lib>

Manipulate where modules are looked up at compile time.  The underlying logic
is B<very> different from Perl 5, but in most cases, C<use lib> in Perl 6
works the same as in Perl 5.

=head3 C<mro>

No longer relevant.

In Perl 6, method calls now always use the C3 method resolution order.
If you need to find out parent classes of a given class, you can invoke the
C<mro> meta-method thusly:

=for code :preamble<class Animal {}>
say Animal.^mro;    # .^ indicates calling a meta-method on the object

=head3 C<utf8>

No longer relevant.

In Perl 6, source code is expected to be in utf8 encoding.

=head3 C<vars>

Discouraged in Perl 5. See L<http://perldoc.perl.org/vars.html>.

You should refactor your Perl 5 code to remove the need for C<use vars>,
before translating into Perl 6.



=head1 Command-line flags

See
L<S19/commandline|https://design.perl6.org/S19.html#Command_Line_Elements>

Unchanged:

-c -e -h -I -n -p -S -T -v -V

=head3 C<-a>

Change your code to use C<.split> manually.

=head3 C<-F>

Change your code to use C<.split> manually.

=head3 C<-l>

This is now the default behavior.

=head3 C<-M> C<-m>

Only C<-M> remains. And, as you can no longer use the "no Module" syntax, the
use of C<-> with C<-M> to "no" a module is no longer available.

=head3 C<-E>

Since all features are already enabled, just use lowercase C<-e> .

=head3 C<-d>, C<-dt>, C<-d:foo>, C<-D>, etc.

Replaced with the C<++BUG> metasyntactic option.

=head3 -s

Switch parsing is now done by the parameter list of the C<MAIN> subroutine.

=for code :lang<perl5>
# Perl 5
    #!/usr/bin/perl -s
    if ($xyz) { print "$xyz\n" }
./example.pl -xyz=5
5

=for code
# Perl 6
    sub MAIN( Int :$xyz ) {
        say $xyz if $xyz.defined;
    }

=for code :lang<shell>
perl6 example.p6 --xyz=5
5
perl6 example.p6 -xyz=5
5

=item C<-t>

Removed.

=item C<-P> C<-u> C<-U> C<-W> C<-X>

Removed. See L<S19#Removed Syntactic Features|https://design.perl6.org/S19.html#Removed_Syntactic_Features>.

=item C<-w>

This is now the default behavior.

=head1 File-related operations

=head2 Reading the lines of a text file into an array

In Perl 5, a common idiom for reading the lines of a text file goes
something like this:

=for code :lang<perl5>
open my $fh, "<", "file" or die "$!";
my @lines = <$fh>;                # lines are NOT chomped
close $fh;

In Perl 6, this has been simplified to

    my @lines = "file".IO.lines;  # auto-chomped

Do I<not> be tempted to try slurping in a file and splitting the resulting
string on newlines as this will give an array with a trailing empty element,
which is one more than you probably expect (it's also more complicated),
e.g.:

    # initialize the file to read
    spurt "test-file", q:to/END/;
    first line
    second line
    third line
    END
    # read the file
    my @lines = "test-file".IO.slurp.split(/\n/);
    say @lines.elems;    #-> 4

If for some reason you do want to slurp the file first, then you can call
the C<lines> method on the result of C<slurp> instead:

    my @lines = "test-file".IO.slurp.lines;  # also auto-chomps

=head2 Trapping the standard output of executables.

Whereas in Perl 5 you would do:

=for code :lang<perl5>
my $arg = 'Hello';
my $captured = `echo \Q$arg\E`;
my $captured = qx(echo \Q$arg\E);

Or using String::ShellQuote (because C<\Q…\E> is not completely right):

=for code :lang<perl5>
my $arg = shell_quote 'Hello';
my $captured = `echo $arg`;
my $captured = qx(echo $arg);

In Perl 6, you will probably want to run commands without using the shell:

    my $arg = 'Hello';
    my $captured = run('echo', $arg, :out).out.slurp-rest;
    my $captured = run(«echo "$arg"», :out).out.slurp-rest;

You can also use the shell if you really want to:

    my $arg = 'Hello';
    my $captured = shell("echo $arg", :out).out.slurp-rest;
    my $captured = qqx{echo $arg};

But beware that in this case there is B<no protection at all>! C<run> does
not use the shell, so there is no need to escape the arguments (arguments
are passed directly). If you are using C<shell> or C<qqx>, then everything
ends up being one long string which is then passed to the shell. Unless you
validate your arguments very carefully, there is a high chance to introduce
shell injection vulnerabilities with such code.

=head1 Environment variables

=head2 Perl module library path

In Perl 5 one of the environment variables to specify extra search paths for
Perl modules is C<PERL5LIB>.

=for code :lang<shell>
$ PERL5LIB="/some/module/lib" perl program.pl

In Perl 6 this is similar, one merely needs to change a number!  As you
probably guessed, you just need to use X<C<PERL6LIB>|PERL6LIB>:

=for code :lang<shell>
$ PERL6LIB="/some/module/lib" perl6 program.p6

In Perl 5 one uses the ':' (colon) as a directory separator for C<PERL5LIB>, but in
Perl 6 one uses the ',' (comma).  For example:

=for code :lang<shell>
$ export PERL5LIB=/module/dir1:/module/dir2;

but

=for code :lang<shell>
$ export PERL6LIB=/module/dir1,/module/dir2;

(Perl 6 does not recognize either the C<PERL5LIB> or the older Perl environment
variable C<PERLLIB>.)

As with Perl 5, if you don't specify C<PERL6LIB>, you need to specify the
library path within the program via the C<use lib> pragma:

=for code :lang<perl5>
use lib '/some/module/lib'

Note that C<PERL6LIB> is more of a developer convenience in Perl 6 (as
opposed to the equivalent usage of C<PERL5LIB> in Perl5) and shouldn't be
used by module consumers as it could be removed in the future.  This is
because Perl 6's module loading isn't directly compatible with operating
system paths.

=head1 Misc.

=head2 C<'0'> is True

Unlike Perl 5, a string containing nothing but zero ('0') is C<True>. As Perl 6
has types in core, that makes more sense. This also means the common pattern:

=for code :lang<perl5>
... if defined $x and length $x; # or just length() in modern perls

In Perl 6 becomes a simple

=for code :preamble<no strict;>
... if $x;

=head2 C<dump>

Gone.

The Perl 6 design allows for automatic transparent saving-and-loading of
compiled bytecode.

Rakudo supports this only for modules so far.

=head2 AUTOLOAD

The L«C<FALLBACK> method|/language/typesystem#index-entry-FALLBACK_(method)»
provides similar functionality.

=head2 Importing specific functions from a module
X<|import>

In Perl 5 it is possible to selectively import functions from a given module
like so:

=for code :lang<perl5>
use ModuleName qw{foo bar baz};

In Perl 6 one specifies the functions which are to be exported by using the
C<is export> role on the relevant subs and I<all> subs with this role are
then exported.  Hence, the following module C<Bar> exports the subs C<foo>
and C<bar> but not C<baz>:

=begin code :skip-test
unit module Bar;

sub foo($a) is export { say "foo $a" }
sub bar($b) is export { say "bar $b" }
sub baz($z) { say "baz $z" }
=end code

To use this module, simply C<use Bar> and the functions C<foo> and C<bar>
will be available

=for code :skip-test
use Bar;
foo(1);    #=> "foo 1"
bar(2);    #=> "bar 2"

If one tries to use C<baz> an "Undeclared routine" error is raised at compile time.

So, how does one recreate the Perl 5 behaviour of being able to selectively
import functions?  For this one needs to define an C<EXPORT> sub inside the
module which specifies the functions to be exported and remove the C<module Bar> statement.

The module C<Bar> now is merely a file called C<Bar.pm> with the following contents:

=begin code :preamble<no strict;>
use v6.c;

sub EXPORT(*@import-list) {
    my %exportable-subs =
        '&foo' => &foo,
        '&bar' => &bar,
        ;
    my %subs-to-export;
    for @import-list -> $import {
        if grep $sub-name, %exportable-subs.keys {
            %subs-to-export{$sub-name} = %exportable-subs{$sub-name};
        }
    }
    return %subs-to-export;
}

sub foo($a, $b, $c) { say "foo, $a, $b, $c" }
sub bar($a) { say "bar, $a" }
sub baz($z) { say "baz, $z" }
=end code

Note that the subs are no longer explicitly exported via the C<is export>
role.  We are defining an C<EXPORT> sub which specifies the subs in the
module we want to be available for export and then we are populating a hash
containing the subs which will actually be exported.  The C<@import-list> is
set by the C<use> statement in the calling code thus allowing us to
selectively import the subs made available by the module.

So, to import only the C<foo> routine, we do the following in the calling code:

=for code :skip-test
use Bar <foo>;
foo(1);       #=> "foo 1"

Here we see that even though C<bar> is able to be exported, if we don't
explicitly import it, it's not available for use.  Hence this causes an
"Undeclared routine" error at compile time:

=for code :skip-test
use Bar <foo>;
foo(1);
bar(5);       #!> "Undeclared routine: bar used at line 3"

however, this will work

=for code :skip-test
use Bar <foo bar>;
foo(1);       #=> "foo 1"
bar(5);       #=> "bar 5"

Note also that C<baz> remains unimportable even if specified in the C<use>
statement:

=for code :skip-test
use Bar <foo bar baz>;
baz(3);       #!> "Undeclared routine: baz used at line 2"

In order to get this to work, one obviously has to jump through many hoops.
In the standard use-case where one specifies the functions to be exported
via the C<is export> role, Perl 6 automatically creates the C<EXPORT> sub in
the correct manner for you, so one should consider very carefully whether or
not writing one's own C<EXPORT> routine is worthwhile.

=head2 Importing groups of specific functions from a module

If you would like to export groups of functions from a module, you just
need to assign names to the groups, and the rest will work automagically.
When you specify C<is export> in a sub declaration, you are in fact adding
this subroutine to the C<:DEFAULT> export group.  But you can add a subroutine
to another group, or to multiple groups:

=for code :skip-test
unit module Bar;
sub foo() is export { }                   # added by default to :DEFAULT
sub bar() is export(:FNORBL) { }          # added to the FNORBL export group
sub baz() is export(:DEFAULT:FNORBL) { }  # added to both

So now you can use the C<Bar> module like this:

=for code :skip-test
use Bar;                     # imports foo / baz
use Bar :FNORBL;             # imports bar / baz
use Bar :ALL;                # imports foo / bar / baz

Note that C<:ALL> is an auto-generated group that encompasses B<all>
subroutines that have an C<is export> trait.

=head1 Core modules

=head3 C<Data::Dumper>

In Perl 5, the L<Data::Dumper|https://metacpan.org/pod/Data::Dumper>
module was used for serialization, and for
debugging views of program data structures by the programmer.

In Perl 6, these tasks are accomplished with the C<.perl> method, which
every object has.

=begin code :lang<perl5>
# Given:
    my @array_of_hashes = (
        { NAME => 'apple',   type => 'fruit' },
        { NAME => 'cabbage', type => 'no, please no' },
    );
# Perl 5
    use Data::Dumper;
    $Data::Dumper::Useqq = 1;
    print Dumper \@array_of_hashes; # Note the backslash.
=end code

=for code :preamble<no strict;>
# Perl 6
say @array_of_hashes.perl; # .perl on the array, not on its reference.


In Perl 5, Data::Dumper has a more complex optional calling convention,
which allows for naming the VARs.

In Perl 6, placing a colon in front of the variable's sigil turns it into a
Pair, with a key of the var name, and a value of the var value.

=begin code :lang<perl5>
# Given:
    my ( $foo, $bar ) = ( 42, 44 );
    my @baz = ( 16, 32, 64, 'Hike!' );
# Perl 5
    use Data::Dumper;
    print Data::Dumper->Dump(
        [     $foo, $bar, \@baz   ],
        [ qw(  foo   bar   *baz ) ],
    );
# Output
#    $foo = 42;
#    $bar = 44;
#    @baz = (
#             16,
#             32,
#             64,
#             'Hike!'
#           );
=end code

=begin code :preamble<no strict;>
# Perl 6
say [ :$foo, :$bar, :@baz ].perl;
# OUTPUT: «["foo" => 42, "bar" => 44, "baz" => [16, 32, 64, "Hike!"]]␤»
=end code

There is also a Rakudo-specific debugging aid for developers called C<dd> (Tiny
Data Dumper, so tiny it lost the "t").  This will print the C<.perl>
representation plus some extra information that could be introspected, of the
given variables on STDERR:

=begin code :preamble<no strict;> :ok-test<dd>
# Perl 6
dd $foo, $bar, @baz;
# OUTPUT: «Int $foo = 42␤Int $bar = 44␤Array @baz = [16, 32, 64, "Hike!"]␤»
=end code

=head3 C<Getopt::Long>

Switch parsing is now done by the parameter list of the C<MAIN> subroutine.

=begin code :lang<perl5>
# Perl 5
    use 5.010;
    use Getopt::Long;
    GetOptions(
        'length=i' => \( my $length = 24       ), # numeric
        'file=s'   => \( my $data = 'file.dat' ), # string
        'verbose'  => \( my $verbose           ), # flag
    ) or die;
    say $length;
    say $data;
    say 'Verbosity ', ($verbose ? 'on' : 'off') if defined $verbose;
perl example.pl
    24
    file.dat
perl example.pl --file=foo --length=42 --verbose
    42
    foo
    Verbosity on

perl example.pl --length=abc
    Value "abc" invalid for option length (number expected)
    Died at c.pl line 3.
=end code

=begin code
# Perl 6
    sub MAIN( Int :$length = 24, :file($data) = 'file.dat', Bool :$verbose ) {
        say $length if $length.defined;
        say $data   if $data.defined;
        say 'Verbosity ', ($verbose ?? 'on' !! 'off');
    }
=end code

=begin code :lang<shell>
perl6 example.p6
    24
    file.dat
    Verbosity off
perl6 example.p6 --file=foo --length=42 --verbose
    42
    foo
    Verbosity on
perl6 example.p6 --length=abc
    Usage:
      c.p6 [--length=<Int>] [--file=<Any>] [--verbose]
=end code

Note that Perl 6 auto-generates a full usage message on error in
command-line parsing.




=head1 Automated Translation

A quick way to find the Perl 6 version of a Perl 5 construct, is to run it
through an automated translator.

B<NOTE:> None of these translators are yet complete.

=head2 Blue Tiger

This project is dedicated to automated modernization of Perl code. It does
not (yet) have a web front-end, and so must be locally installed to be
useful. It also contains a separate program to translate Perl 5 regexes
into Perl 6.

L<https://github.com/Util/Blue_Tiger/>

=head2 Perlito

Online Translator!

This project is a suite of Perl cross-compilers, including Perl 5-to-6
translation. It has a web front-end, and so can be used without
installation. It only supports a subset of Perl 5 syntax so far.

L<http://fglock.github.io/Perlito/perlito/perlito5.html>

=head2 MAD

Larry Wall's own code for translating Perl 5 to Perl 6 has bit-rotted, and
is not (currently) viable on recent releases of Perl 5.

MAD (Misc Attribute Definition) is a configuration option when building
Perl from a source distribution. The C<perl> executable analyses and
translates your Perl sourcecode into an op-tree, and then executes the
program by walking the op-tree. Normally, most of the details from the
analysis are thrown away during this process. When MAD is enabled, the
C<perl> executable will save those details to an XML file, which can then be
read and further processed into Perl 6 code by a MAD parser.

Please consult #perl6 to find out the best release of Perl 5 to use for
your MAD science experiments.

=head2 Perl-ToPerl6

Jeff Goff's Perl::ToPerl6 module for Perl 5 is designed around
Perl::Critic's framework. It aims to convert Perl5 to compilable (if not
necessarily running) Perl 6 code with the bare minimum of changes. Code
transformers are configurable and pluggable, so you can create and
contribute your own transformers, and customize existing transformers to
your own needs. You can install the latest release from CPAN, or follow
the project live on GitHub. An online converter may become available at
some point.

=head1 Other sources of translation knowledge

=item L<https://perlgeek.de/en/article/5-to-6>
=item L<https://github.com/Util/Blue_Tiger/>
=item L<https://perl6advent.wordpress.com/2011/12/23/day-23-idiomatic-perl-6/>
=item L<http://www.perlfoundation.org/perl6/index.cgi?perl_6_delta_tablet>

=end pod

=begin comments

### Guidelines for contributions:

Headers should contain the text that a Perl 5 user might search for, since
those headings will be in the Table of Contents generated for the top of
the document.

We use POD =item instead of =head3 or =head4 for unchanged bits that need
not appear in the table of contents.

This article does not describe the additions to syntax, nor details of
possible improvements. For example, C<0 + $string> still works, even though
we would write it as C<+$string> now. (Blue Tiger will offer a Perl
Modernization guide, with step-by-step procedures for translation, along
with details of new idioms and "better ways to do it")

Example code and links to other documents should be favored over long
explanations of details better found elsewhere.

Finally, if a real user asks a P5->P6 question not answered here, please
add it to the document, even if we don't have a good answer yet. That will
be better than losing the information about a real need.

=end comments

# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6