<commit_before>=begin pod

=TITLE Perl 6 variables

Variable names start with a special character called a I<sigil>, followed
optionally by a second special character named I<twigil>, and then an
I<identifer>.

=head1 Sigils

The sigil serves both as rough type constraint, and as an indicator
as to whether the contents of the variable flatten in list context. See also
the documentation in L<List>.

=begin table

    Sigil   Type constraint          Default type  Flattens  Assignment
    =====   ===============          ============  ========  ==========
    $       Mu (no type constraint)  Any           No        item
    &       Callable                 Callable      No        item
    @       Positional               Array         Yes       list
    %       Associative              Hash          Yes       list

=end table

Examples:

    my $square = 9 ** 2;
    my @array  = 1, 2, 3;   # Array-variable with three elements
    my %hash   = London => 'UK', Berlin => 'Germany';

There are two types of assignment, I<item assignment> and I<list assignment>.
Both use the equal sign C<=> as operator. The distinction whether an C<=>
means item or list assignment is based on the syntax of the left-hand side.
(TODO: explain in detail, or do that in L<operators>).

Item assignment places the value from the right-hand side into the variable
(container) on the left.

List assignment leaves the choice of what to do to the variable on the left.

For example L<Array> variables (C<@> sigil) empty themselves on list assignment,
and then put all the values from the right-hand side into themselves. Contrary
to item assignment, it means that the type of the variable on the left always
stays C<Array>, regardless of the type of the right-hand side.

Note that the item assignment has tighter precedence than list assigment, and
also tighter than the comma. See L<operators> for more details.

=head1 Twigils

Twigils influence the scoping of a variable

=begin table

    Twigil  Scope
    ======  =====
    *       dynamic
    !       attribute (class member)
    ?       compile-time "constant"
    .       method (not really a variable)
    <       index into match object (not really a variable)

=end table

=head2 *

Dynamic variables are looked up through the caller, not through the outer
scope.

    my $l  = 23;
    my $*d = 23;

    sub f() {
        say $l;     # 23
        say $*d;    # 42
    }

    {
        my $l  = 42;
        my $*d = 42;
        f();
    }


=head1 Special Variables

=head2 Often-Used Variables

# TODO: find a better heading

There are three special variables that are available in every block:

=begin table<commit_msg>[variables] elaborate dynamic variables example<commit_after>=begin pod

=TITLE Perl 6 variables

Variable names start with a special character called a I<sigil>, followed
optionally by a second special character named I<twigil>, and then an
I<identifer>.

=head1 Sigils

The sigil serves both as rough type constraint, and as an indicator
as to whether the contents of the variable flatten in list context. See also
the documentation in L<List>.

=begin table

    Sigil   Type constraint          Default type  Flattens  Assignment
    =====   ===============          ============  ========  ==========
    $       Mu (no type constraint)  Any           No        item
    &       Callable                 Callable      No        item
    @       Positional               Array         Yes       list
    %       Associative              Hash          Yes       list

=end table

Examples:

    my $square = 9 ** 2;
    my @array  = 1, 2, 3;   # Array-variable with three elements
    my %hash   = London => 'UK', Berlin => 'Germany';

There are two types of assignment, I<item assignment> and I<list assignment>.
Both use the equal sign C<=> as operator. The distinction whether an C<=>
means item or list assignment is based on the syntax of the left-hand side.
(TODO: explain in detail, or do that in L<operators>).

Item assignment places the value from the right-hand side into the variable
(container) on the left.

List assignment leaves the choice of what to do to the variable on the left.

For example L<Array> variables (C<@> sigil) empty themselves on list assignment,
and then put all the values from the right-hand side into themselves. Contrary
to item assignment, it means that the type of the variable on the left always
stays C<Array>, regardless of the type of the right-hand side.

Note that the item assignment has tighter precedence than list assigment, and
also tighter than the comma. See L<operators> for more details.

=head1 Twigils

Twigils influence the scoping of a variable

=begin table

    Twigil  Scope
    ======  =====
    *       dynamic
    !       attribute (class member)
    ?       compile-time "constant"
    .       method (not really a variable)
    <       index into match object (not really a variable)

=end table

=head2 *

Dynamic variables are looked up through the caller, not through the outer
scope. For example:

    my $lexical   = 1;
    my $*dynamic1 = 10;
    my $*dynamic2 = 100;

    sub say-all() {
        say "$lexical, $*dynamic1, $*dynamic2";
    }

    # prints 1, 10, 100
    say-all();

    {
        my $lexical   = 2;
        my $*dynamic1 = 11;
        $*dynamic2    = 101;

        # prints 1, 11, 101
        say-all();
    }

    # prints 1, 10, 101
    say-all();

The first time C<&say-all> is called, it prints "1, 10, 100" just as one would
expect. The second time though, it prints "1, 11, 101". This is because
C<$lexical> isn't looked up in the caller's scope but in the scope C<&say-all>
was defined in. The two dynamic variables are looked up in the callers scope and
therefore have the values 11 and 101. The third time C<&say-all> is called
C<$*dynamic1> isn't 11 anymore, but C<$*dynamic2> is still 101. This stems from
the fact that we declared a new dynamic variable C<$*dynamic1> in the block and
did not assign to the old variable as we did with C<$*dynamic2>.

=head1 Special Variables

=head2 Often-Used Variables

# TODO: find a better heading

There are three special variables that are available in every block:

=begin table
{'fraction_non_alphanumeric': 0.08458434221146086, 'fraction_numerical': 0.01549636803874092, 'mean_word_length': 2.6318874560375147, 'pattern_counts': {'":': 0, '<': 39, '<?xml version=': 0, '>': 41, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4072917', 'n_tokens_mistral': 1828, 'n_tokens_neox': 1673, 'n_words': 835}