(paritially) document class Variable

Author: moritz

htmlify.p6

@@ -33,7 +33,7 @@ sub url-munge($_) {
 my @menu =
     ('language',''         ) => (),
     ('type', 'Types'       ) => <basic composite domain-specific exceptions>,
-    ('routine', 'Routines' ) => <sub method term operator>,
+    ('routine', 'Routines' ) => <sub method term operator trait>,
 #    ('module', 'Modules'   ) => (),
 #    ('formalities',''      ) => ();
 ;

lib/Type/Variable.pod

@@ -0,0 +1,59 @@
+=begin pod
+
+=TITLE class Variable
+
+=SUBTITLE Object representation of a variable for use in traits
+
+    class Variable { ... }
+
+Variables have a wealth of compile-time information, but at run time, accesses
+to to a variable usually act on the value stored inside the variable, not the
+variable itself.
+
+Class C<Variable> holds the compile-time information that traits can use to
+introspect and manipulate variables.
+
+=head1 Routines
+
+=head2 method name
+
+    method name(Variable:D: str)
+
+Returns the name of the variable, including the sigil.
+
+=head2 trait is default
+
+    multi sub trait_mod:<is>(Variable:D, :$default!)
+
+Sets the default value with which a variable is initialized, and to which it
+is reset when Nil is assigned to it.
+
+    my Int $x is default(42);
+    say $x;     # 42
+    $x = 5;
+    say $x;     # 5
+    # explicit reset:
+    $x = Nil;
+    say $x;     # 42
+
+=head2 trait is dynamic
+
+    multi sub trait_mod:<is>(Variable:D, :$dynamic)
+
+Marks a variable as dynamic, that is, accessible from inner dynamic scopes
+without being in an inner lexical scope.
+
+=begin code :allow<B L>
+    sub introspect() {
+        say B<$CALLER::x>;
+    }
+    my $x B<is dynamic> = 23;
+    introspect;         # 23
+    {
+        # not dynamic
+        my $x;
+        introspect()    # dies with an exception of L<type X::Caller::NotDynamic|/type/X::CallerNotDynamic>
+    }
+=end code
+
+=end pod