=begin pod :kind("Type") :subkind("class") :category("basic")

=TITLE class Label

=SUBTITLE Tagged location in the source code

    class Label {}

Labels are used in Raku to tag loops so that you can specify the one you want
to jump to with statements such as C<last>. You can use it to jump out of loops
and get to outer ones, instead of just exiting the current loop or going to the
statement before.

=begin code :skip-test<compile time error>
USERS:          # the label
for @users -> $u {
    for $u.pets -> $pet {
        # usage of a label
        next USERS if $pet.barks;
    }
    say "None of {$u}'s pets barks";
}
say USERS.^name;        # OUTPUT: «Label␤»
=end code

Those label are objects of type C<Label>, as shown in the last statement. Labels
can be used in any loop construct, as long as they appear right before the loop
statement.

=begin code
my $x = 0;
my $y = 0;
my $t = '';
A: while $x++ < 2 {
    $t ~= "A$x";
    B: while $y++ < 2 {
        $t ~= "B$y";
        redo A if $y++ == 1;
        last A
    }
}
say $t; # OUTPUT: «A1B1A1A2»
=end code

Putting them on the line before the loop or the same line is optional. C<Label>s
must follow the syntax of
L<ordinary identifiers|/language/syntax#Ordinary_identifiers>,
although traditionally we
will use the latin alphabet in uppercase so that they stand out in the source.
You can use, however, other alphabets like here:

    駱駝道: while True {
      say 駱駝道.name;
      last 駱駝道;
    }


=head1 Methods

=head2 method name

Defined as:

    method name()

Not terribly useful, returns the name of the defined label:

    A: while True {
      say A.name; # OUTPUT: «A»
      last A;
    }


=head2 method next

Defined as:

    method next(Label:)

Begin the next iteration of the loop associated with the label.

    MY-LABEL:
    for 1..10 {
        next MY-LABEL if $_ < 5;
        print "$_ ";
    }

    # OUTPUT: «5 6 7 8 9 10 »

=head2 method redo

Defined as:

    method redo(Label:)

Repeat the same iteration of the loop associated with the label.

    my $has-repeated = False;

    MY-LABEL:
    for 1..10 {
        print "$_ ";
        if $_ == 5 {
            LEAVE $has-repeated = True;
            redo MY-LABEL unless $has-repeated;
        }
    }

    # OUTPUT: «1 2 3 4 5 5 6 7 8 9 10 »

=head2 method last

Defined as:

    method last(Label:)

Terminate the execution of the loop associated with the label.

    MY-LABEL:
    for 1..10 {
        last MY-LABEL if $_ > 5;
        print "$_ ";
    }

    # OUTPUT: «1 2 3 4 5 »

=end pod

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