=head1 NAME

Perl 6 Basics

=head1 PREAMBLE

use v6;

=head1 LANGUAGE

en

=head1 ABSTRACT

An overview of the most important features of Perl 6.

=head1 DESCRIPTION

In this tutorial, we will go through all the main features of Perl 6 such as variables,
scopes, classes, regexes and control structures. Knowledge of Perl 5 is not required for
working with this document, although it is assumed that you have basic understanding
of what programming is.

All examples in the sections below can be run in place, modified as desired and tested
again. Generally, the output of the examples does not present in the text to encourage
you running tests :-)

=head1 TUTORIAL

=head2 Basic control structures

=head2 Variables and sigils

=head2 Twigils

=head2 Scope declarators

=head2 Lexical variables

Lexical variables belong to their scope. If it is defined within a block of code
(for instance, inside a subroutine), it is only visible and accessible inside it.

    {
        my $x = 42;
        say $x; # OK
    }

    #say $x; # Not OK

The second attempt to use C<$x> here will fail because there is no such variable
outside the block above.

Similarly, it works with variables defined inside subroutines:

    sub f() {
        my $x = 42;
        say $x;
    }

    f(); # OK
    #say $x; # Error

Nothing changes when the variable is declared as a C<state> one:

    sub f() {
        state $x = 42;
        say $x;
    }

    f(); # OK
    #say $x; # Error

Note that if you create a closure, the actual scope of a variable will be extended.
In the following example a subroutine returns a block containing its lexical variable.
Thus, it can be used later in the programme outside the subroutine where the variable
was declared:

    sub seq($init) {
        my $c = $init;

        return {$c++};
    }

    my $a = seq(1);

    say $a(); # 1
    say $a(); # 2
    say $a(); # 3

Each time, the C<$a()> call increments exactly the same variable, only visible
inside the C<seq()> subroutine.

Moreover, it is possible to create more than one closures, each containing its
own container with the counter:

    sub seq($init) {
        my $c = $init;

        return {$c++};
    }

    my $a = seq(1);
    my $b = seq(42);

    say $a(); # 1
    say $a(); # 2
    say $b(); # 42
    say $a(); # 3
    say $b(); # 43

In Perl 6, the operations returning dynamicly-behaving blocks with lexically-defined
variables are called I<lexotic>. These are C<return>, C<next>, C<last>, C<redo> and C<goto>.

=head2 Dynamic variables

Dynamic variables are variables whose actual scope may change depending on when
you access this variable. Dynamic variables names contain a twigil C<*>,
for example: C<$*x>.

In the following code snippet, C<$*var> is the dynamic variable. In either subroutine,
C<a()> or C<b()> it is declared as a lexical variable using the C<my> keyword.
Although when it is red inside the C<echo()> subroutine, its actual scope will be
different.

    sub alpha {
        my $*var = 'Alpha';

        echo();
    }

    sub beta {
        my $*var = 'Beta';

        echo();
    }

    sub echo() {
        say $*var;
    }

    alpha(); # Alpha
    beta();  # Beta

There are predefined dynamic variables, like those for the standard IO file handles:
C<$*IN>, C<$*OUT>, and C<$*ERR>.

=head2 Basic types (strings, numbers)

=head2 Basic file IO

=head2 Basic OO

=head2 Basic multi dispatch

Multi dispatch allows to overload function names and let the types of its argument to
determin which one is actually called.

    multi sub twice(Int $x) {
        return $x * 2;
    }

    multi sub twice(Str $s) {
        return "$s, $s";
    }

    say twice(42); # 84
    say twice("hi"); # hi, hi

Here, the two subs with the same name expect arguments of different types, C<Int> and
C<Str>, respectively. Thus the call of C<twice> leads to execution of either C<twice(Int)>
or C<twice(Str)>.

The keyword C<multi> is obligatory to tell the compiler that this sub may be overloaded.
Would you omit C<multi>, you will get a compile error C<Redeclaration of routine twice>.

=head2 Basic regex support

=head2 Subroutines

=head2 Blocks

=head2 Arrow blocks (lambdas)

Arrow blocks, or pointy blocks, or lambdas define an anonymous sub with only a few
characters required to type:

    my $cube = -> $x {$x ** 3};
    say $cube(3); # 27

Here, the arrow block has its argument C<$x>, whose usage is exactly the same as with
regular subs. Likewise in subs, no C<my> keyword is required for declaring the arguments.

Arrow blocks are a common thing to use in loops. 

    for 1..10 -> $c {
        say $c;
    }

An arrow block is being called at each iteration, and the value is passed through the
C<$c> variable.

It is possible to have more than one argument in an arrow block. For example, let's convert
the two examples above.

First, implement the exponentiation function, which accept both base and exponent values:

    my $pow = -> $x, $p {$x ** $p};
    say $pow(2, 15); # 32768

Then, modify a loop to take two values at a time:

    for 1..10 -> $i, $j {
        say $i + $j;
    }

This time, the loop body will be executed five times instead of the previous ten.

=head2 Placeholder blocks

Anonumous blocks not only can contain the code but also can make use of parameters passed
to them. Unlike the L<Arrow blocks (lambdas)>, you don't need lising all the arguments but
rather may use them directly when they are needed.

Placeholder varialbes go with the caret twigil, for example: C<$^x> and are ordered
according to their Unicode order. Thus, a block using variables, C<$^x> and C<$^y>,
expects C<$^x> to be the first parameter and C<$^y> to be the second one:

    my $pow = {$^x ** $^y};
    say $pow(3, 4); # 81

Similarly, placeholder blocks can be used in loops:

    for 0..9 {
        say $^n2, $^n1;
    }

In this example, C<$^n2> is the second argument and C<$^n1> is the first. Thus, the block
consumes two items at a moment, and the loop will be repeated five times, and the first pass
will print C<10>.

Note that there is no arrow anymore before the start of the block. Presence of the arrow
would suggest the presence of implicitly spelled arguments.

Placeholder variables can be named. In this case instead of the caret a semicolon (C<:>)
is used as a twigil:

    my $pow = {$:base ** $:exp};
    say $pow(:base(25), :exp(2)); # 625

Now, it does not matter in which order you pass the values to the function. The following
call gives exactly the same result:

    my $pow = {$:base ** $:exp};
    say $pow(:exp(2), :base(25)); # 625

=head2 Special variables

=head2 EVAL

C<EVAL> accepts the code and executes it. Here's the simplest example:

    say EVAL('12 + 13'); # 25

It's important to remember that C<EVAL> will not hide exeptions. The following code will
produce an error:

    my $zero = 0;
    my $inf = EVAL('42 / $zero');
    say $inf;

Note that if you do not use the result of the C<EVAL> block, which failed througing an
exception (in the previous example it is enough to comment out the last line printing
the result), an exception will not break the programme:

    my $zero = 0;
    my $inf = EVAL('42 / $zero');
    #say $inf;
    say "ok"; # OK, it works

=head2 Constant declarations

=head2 State variables

A variable in a sub may be declared using the C<state> keyword instead of C<my>. In this case
it will be created and initialized once, and its value will be saved between subsequent calls
of that function.

    sub cnt() {
        state $c = 0;

        return $c++;
    }

    say cnt(); # 0
    say cnt(); # 1
    say cnt(); # 2

The C<state> variable still remains lexically scoped, and thus is not accessible outside of the
block where it was defined.

With the state variables, the example demonstrated in the L<Lexical variables> section,
will not work: there will exist only one instance of the variable:

    sub seq($init) {
        state $c = $init;

        return {$c++};
    }

    my $a = seq(1);
    my $b = seq(42);

    say $a(); # 1
    say $a(); # 2
    say $b(); # 3
    say $a(); # 4
    say $b(); # 5

=head2 Loops as list generators

=head2 Labeled loops

Nested loops can of couse contain labels, which will make it easier to break inner cycles.
There are two ways of specifying labels when using C<last>, C<next> and C<redo>: either
traditional syntax like C<next LABEL>:

    START: for 1..5 -> $n {
        for 'a'..'e' -> $c {
           next START if $n == $c.ord - 'a'.ord;
           say $n, $c;
        }
    }

or object-oriented one: C<LABEL.next>.

    START: for 1..5 -> $n {
        for 'a'..'e' -> $c {
           START.next if $n == $c.ord - 'a'.ord;
           say $n, $c;
        }
    }

=head1 AUTHOR

Andrew Shitov, C<andy@shitov.ru>