Merge pull request #2530 from ugexe/current-distribution

Add docs on $?DISTRIBUTION

Author: JJ

doc/Language/variables.pod6

@@ -1136,19 +1136,20 @@ L<C<line>|/type/CallFrame#method_line> methods, respectively.
 =head3 Other compile-time variables:
 
 X<|$?PACKAGE>X<|$?MODULE>X<|$?CLASS>X<|$?ROLE>
-X<|$?GRAMMAR>X<|$?TABSTOP>X<|$?NL>X<|$?ENC>
+X<|$?GRAMMAR>X<|$?TABSTOP>X<|$?NL>X<|$?ENC>X<|$?DISTRIBUTION>
 
 The following compile time variables allow for a deeper introspection:
 
 =for table
-    $?PACKAGE   Which package am I in?
-    $?MODULE    Which module am I in?
-    $?CLASS     Which class am I in? (as variable)
-    $?ROLE      Which role am I in? (as variable)
-    $?GRAMMAR   Which grammar am I in?
-    $?TABSTOP   How many spaces is a tab in a heredoc or virtual margin?
-    $?NL        What a vertical newline "\n" means: LF, CR or CRLF
-    $?ENC       Default encoding of various IO methods, e.g., Str.encode, Buf.decode
+    $?PACKAGE        Which package am I in?
+    $?MODULE         Which module am I in?
+    $?CLASS          Which class am I in? (as variable)
+    $?ROLE           Which role am I in? (as variable)
+    $?GRAMMAR        Which grammar am I in?
+    $?TABSTOP        How many spaces is a tab in a heredoc or virtual margin?
+    $?NL             What a vertical newline "\n" means: LF, CR or CRLF
+    $?ENC            Default encoding of various IO methods, e.g., Str.encode, Buf.decode
+    $?DISTRIBUTION   The L<Distribution|/type/Distribution> of the current compilation unit.
 
 With particular regard to the C<$?NL>, see the  L<newline pragma|/language/pragmas>.
 
@@ -1189,6 +1190,27 @@ for '.' {
 }
 =end code
 
+=head3 X<$?DISTRIBUTION>
+
+C<$?DISTRIBUTION> provides access to the L<Distribution|/type/Distribution>
+of the current compilation unit. This gives module authors a way to reference
+other files in the distribution by their original relative path names, or to
+view the meta data, without needing to know the underlying file structure (such as
+how C<CompUnit::Repository::Installation> changes the file layout on installation).
+
+=begin code
+unit module MyFoo;
+
+sub module-version {
+    say "MyFoo is version:";
+    say $?DISTRIBUTION.meta<ver>;
+}
+
+sub module-source {
+    say "MyFoo source code:";
+    say $?DISTRIBUTION.content('lib/MyFoo.pm6');
+}
+=end code
 
 =head2 Dynamic variables