[variables] expand scope

talk about variables in general, not just special variables.
Adds a section about sigils, and explain the * twigil

Author: moritz

lib/variables.pod

@@ -1,6 +1,80 @@
 =begin pod
 
-=head1 perlvar - list of known magical variables
+=TITLE Perl 6 variables
+
+Variable names start with a special character called a I<sigil>, followed
+optionally by a second special character named C<twigil>, and then an
+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
+    =====   ===============          ============  ========
+    $       Mu (no type constraint)  Any           No
+    &       Callable                 Callable      No
+    @       Positional               Array         Yes
+    %       Associative              Hash          Yes
+
+=end table
+
+Examples:
+
+    my $square = 9 ** 2;
+    my @array  = 1, 2, 3;   # Array-variable with three elements
+    my %hash   = London => 'UK', Berlin => 'Germany';
+
+Assignment to C<%> and C<@>-sigiled variables is special-cased
+syntactically. Instead of replacing the variable on the left-hand side with
+those of the right-hand side, it empties the variable, and fills it
+again with the values from the right-hand side.
+
+    my $item = (1, 2); say $item.WHAT;   # Parcel()
+    my @arr  = (1, 2); say @arr.WHAT;    # Array()
+    my %hash = (1, 2); asy %hash.WHAT;   # Hash()
+
+=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