r27324 - docs/Perl6/Spec

[pugs-c...@feather.perl6.nl]

Author: lwall
Date: 2009-06-30 18:14:08 +0200 (Tue, 30 Jun 2009)
New Revision: 27324

Modified:
docs/Perl6/Spec/S11-modules.pod
Log:
[S11] attempt to break down use/require further for ELISHEVA++

Modified: docs/Perl6/Spec/S11-modules.pod
===================================================================
--- docs/Perl6/Spec/S11-modules.pod 2009-06-30 16:09:36 UTC (rev 27323)
+++ docs/Perl6/Spec/S11-modules.pod 2009-06-30 16:14:08 UTC (rev 27324)
@@ -12,8 +12,8 @@

Created: 27 Oct 2004

- Last Modified: 29 Jun 2009
- Version: 29
+ Last Modified: 30 Jun 2009
+ Version: 30

=head1 Overview

@@ -162,6 +162,11 @@
need Sense;
Sense defines <common @horse>;

+These further break down into:
+
+ BEGIN MY::($_) := load_module(find_module_defining($_)) for <Sense>;
+ BEGIN MY.import_alias(Sense, <common @horse>);
+
=head2 Loading without importing
X<need>

@@ -177,6 +182,14 @@

use ACME::Rocket ();

+Saying
+
+ need A,B,C;
+
+is equivalent to:
+
+ BEGIN MY::($_) := load_module(find_module_defining($_)) for <A B C>;
+
=head2 Importing without loading
X<defines>

@@ -190,6 +203,10 @@
...
Factorial defines 'fact'; # imports the multi

+The last declaration is syntactic sugar for:
+
+ BEGIN MY.import_alias(Factorial, <fact>);
+
Despite having the form of an infix operator, this form functions as
a compile-time declarator, so that these notations can be combined:

@@ -197,16 +214,46 @@
enum Ness is export <Dilly String Putty>;
} defines <Ness>;

+This really means:

+ BEGIN MY.import_alias(
+ role Silly {
+ enum Ness is export <Dilly String Putty>;
+ },
+ <Ness>
+ );
+
=head1 Runtime Importation

Importing via C<require> also installs names into the current lexical scope by
default, but delays the actual binding till runtime:

require Sense <common @horse>;
+
+This means something like:
+
+ BEGIN MY.declare_stub_symbols('Sense', <common @horse>);
+ # run time!
+ MY.import_realias(:from(load_module(find_module_defining('Sense'))), 'Sense');
+ MY.import_realias(:from(Sense), <common @horse>);
+
+(The C<.import_realias> requires that the symbols to be imported already
+exist; this differs from C<.import_alias>, which requires that the
+imported symbols I<not> already exist in the target scope.)
+
+Alternately, a filename may be mentioned directly, which installs
+a package that is effectively that is anonymous to the current lexical
+scope, and may only be accessed by whatever global names the module
+installs:
+
require "/home/non/Sense.pm" <common @horse>;

-Only explicitly mentioned names may be so installed. In order
+which breaks down to:
+
+ BEGIN MY.declare_stub_symbols(<common @horse>);
+ MY.import_realias(:from(load_module("/home/non/Sense.pm")), <common @horse>);
+
+Only explicitly mentioned names may be so imported. In order
to protect the run-time sanctity of the lexical pad, it may not be
modified by C<require>. Tagsets are assumed to be unknown at compile
time, hence tagsets are not allowed in the default import list to