=begin pod :kind("Language") :subkind("Language") :category("migration")

=TITLE Perl to Raku guide - syntax

=SUBTITLE Syntactic differences between Perl and Raku

perlsyn - Perl syntax

=head1 DESCRIPTION

A (hopefully) comprehensive description of the differences between
Perl and Raku with regards to the syntax elements described in the
perlsyn document.

=head1 NOTE

I will I<not> be explaining Raku syntax in detail. This document is an
attempt to guide you from how things work in Perl to the equivalents
in Raku. For full documentation on the Raku syntax, please see the
Raku documentation.

=head1 Free form

Raku is still I<largely> free form. However, there are a few instances
where the presence or lack of whitespace is now significant. For
instance, in Perl, you can omit a space following a keyword (e. g.
C<<while($x < 5)>> or C<my($x, $y)>). In Raku, that space is required,
thus C<<while ($x < 5)>> or C<my ($x, $y)>. In Raku, however, you can
omit the parentheses altogether: C<< while $x < 5 >>. This holds for
C<if>, C<for>, etc.

Oddly, in Perl, you can leave spaces between an array or hash and its
subscript, and before a postfix operator. So C<$seen {$_} ++> is valid.
No more. That would now have to be C<%seen{$_}++>.

If it makes you feel better, you can use backslashes to "unspace" whitespace,
so you can use whitespace where it would otherwise be forbidden.

See L<Whitespace|/language/5to6-nutshell#Whitespace> for details.

=head2 Declarations

As noted in the L<Functions|/language/5to6-perlfunc> guide, there is no C<undef>
in Raku. A declared, but
uninitialized scalar variable will evaluate to its type. In other words, C<my
$x;say $x;> will give you "(Any)". C<my Int $y;say $y;> will give you "(Int)".

=head2 Comments

C<#> starts a comment that runs to the end of the line as in Perl.

Embedded comments start with a hash character and a backtick (C<#`>), followed by an
opening bracketing character, and continue to the matching closing bracketing
character. Like so:

=begin code

if #`( why would I ever write an inline comment here? ) True {
    say "something stupid";
}
=end code

As in Perl, you can use pod directives to create multiline comments, with
C<=begin comment> before and C<=end comment> after the comment.

=head2 Truth and falsehood

The one difference between Perl truth and Raku truth is that,
unlike Perl, Raku treats the string C<"0"> as true. Numeric C<0>
is still false, and you can use prefix C<+> to coerce string C<"0"> to
numeric to get it to be false. Raku, additionally has an actual
Boolean type, so, in many cases, True and False may be available to
you without having to worry about what values count as true and false.

=head2 Statement modifiers

Mostly, statement modifiers still work, with a few exceptions.

First, C<for> loops are exclusively what were known in Perl as
C<foreach> loops and C<for> is not used for C-style C<for> loops in Raku. To get that behavior, you want C<loop>. C<loop> cannot be used as a
statement modifier.

In Raku, you cannot use the form C<do {...} while $x>. You will want
to replace C<do> in that form with C<repeat>. Similarly for C<do {...}
until $x>.

=head2 Compound statements

The big change from Perl is that C<given> is not experimental or disabled by
default in Raku. For the details on C<given> see
L<this page|/language/control#given>.

=head2 Loop control

C<next>, C<last>, and C<redo> have not changed from Perl to Raku.

C<continue>, however, does not exist in Raku. You would use a C<NEXT>
block in the body of the loop.

=begin code :lang<perl>

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

=end code

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

=head2 For loops

As noted above, C-style C<for> loops are not called C<for> loops in
Raku. They are just C<loop> loops. To write an infinite loop, you do
not need to use the C idiom of C<loop (;;) {...}>, but may just omit
the spec completely: C<loop {...}>

=head2 Foreach loops

In Perl, C<for>, in addition to being used for C-style C<for> loops, is a
synonym for C<foreach>. In Raku, C<for> is just used for C<foreach> style
loops.

=head2 Switch statements

Raku has actual switch statements, provided by C<given> with the individual
cases handled by C<when> and C<default>. The basic syntax is:

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

The full details can be found
L<here|/language/control#given>.

=head2 Goto

C<goto> is currently not implemented (yet).  Labels B<are> implemented, and
can be used as a target for C<next>, C<last> and C<redo>:

=begin code
FOO:                         # Labels end with colons, like in Perl
for ^10 {
    say "outer for before";
    for ^10 {
        say "inner for";
        last FOO;
    }
    say "outer for after";   # Will not show because of the "last"
}
# outer for before
# inner for
=end code

For what is planned for C<goto>, see L<https://design.raku.org/S04.html#The_goto_statement>.

=head2 Ellipsis statement

C<...> (along with C<!!!> and C<???>) are used to create stub
declarations. This is a bit more complicated than the use of C<...> in
Perl, so you'll probably want to look at
L<https://design.raku.org/S06.html#Stub_declarations> for the gory
details. That said, there doesn't seem to be an I<obvious> reason why it
shouldn't still fulfill the role it did in Perl, despite its role
being expanded in Raku.

=head2 PODs: embedded documentation

Pod has changed between Perl and Raku. Probably the biggest
difference is that you need to enclose your pod between C<=begin pod>
and C<=end pod> directives. There are a few tweaks here and there as
well. For instance, as I have discovered while writing these documents,
the vertical bar ("|") is significant in C<< X<> >> codes, and it's not
clear how to get a literal "|" into them. Your best bet may be to use
the Raku interpreter to check your pod. You can do this by using the
C<--doc> switch. E. g. C<raku --doc Whatever.pod>. This will output any
problems to standard error. (Depending on how/where you've installed
C<raku>, you may need to specify the location of C<Pod::To::Text>.)
Details on Raku-style pod is at L<https://design.raku.org/S26.html>.

=end pod

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