Author: chip
Date: Sun Apr 16 20:33:54 2006
New Revision: 12283
Modified:
trunk/docs/pdds/pdd21_namespaces.pod
Log:
* Added requirement that <compiler>."load_library"() throw an exception on
failure. Also noted that the exception is only covering for the lack of a
universal error PMC, which I would prefer for this API if I had it. >>TODO
* Eliminated "::" from the document except in Perl code examples. People are
going to keep imitating those colons if we leave them in.
Question for readers: is "use tcl:Foo::Bar" (note the single colon) standard
Perl 6 or did some other editor make that up? Perspiring minds want to know.
* Clarified but did not change suggestions on typed interface for Perl.
(Doesn't mean they won't change eventually; Audrey Tang has suggested
semantics that could sidestep many sigil issues. In any case, these are
just suggestions.)
* [cosmetic] Rewrapped at correct width.
Modified: trunk/docs/pdds/pdd21_namespaces.pod
==============================================================================
--- trunk/docs/pdds/pdd21_namespaces.pod (original)
+++ trunk/docs/pdds/pdd21_namespaces.pod Sun Apr 16 20:33:54 2006
@@ -47,12 +47,18 @@
initialize the runtime current namespace as well as determine where to store
compiled symbols.)
-=head2 namespace separator: "::"
+=head2 namespace indexing syntax
-In this document, "::" indicates namespace nesting. For example, "a::b" means
-"the namespace 'b' inside the namespace 'a'". In Parrot, nesting is actually
-denoted by other means (e.g. multidimensional hash keys), but writing ["a";
"b"]
-is harder to both write and read.
+Namespaces are denoted in Parrot as either simple strings or (potentially)
+multimentional hash keys.
+
+A non-nested namespace may appear in Parrot source code as the string
+C<"a"> or the key C<["a"]>.
+
+A nested namespace "b" inside the namespace "a" will appear as the key
+C<["a"; "b"]>.
+
+(There is no limit to namespace nesting.)
=head1 IMPLEMENTATION
@@ -79,6 +85,11 @@
unicode encoding. The reasons for these restrictions is to allow compilers
to remain completely ignorant of each other.
+=item True Root Namespace
+
+The true root namespace is available only via introspection with the
+C<interpinfo> opcode, e.g. C<$P0 = interpinfo .NAMESPACE_ROOT>.
+
=item HLL Implementation Namespaces
Each HLL must store implementation internals (private items) in a namespace
@@ -148,8 +159,9 @@
Store $P0 as a variable under the name of $S0.
-IMPLEMENTATION NOTE: perl6::namespace.add_var may choose to check which parts
-of the variable interface are implemented by $P0 so it can decide on an
+IMPLEMENTATION NOTE: Perl namespace implementations may choose to implement
+add_var() by checking what which parts of the variable interface are
+implemented by $P0 (scalar, array, and/or hash) so it can decide on an
appropriate sigil.
=item del_namespace($S0)
@@ -168,9 +180,11 @@
Find the sub, namespace, or variable named $S0.
-IMPLEMENTATION NOTE: perl6::namespace.find_var should check all variable
-sigils, but the order is not to be counted on by users. If you're planning to
-let Python code see your module, don't have both C<our $A> and C<our @A>.
+IMPLEMENTATION NOTE: Perl namespace implementations should implement
+find_var() to check all variable sigils, but the order is not to be counted on
+by users. If you're planning to let Python code see your module, you should
+avoid exporting both C<our $A> and C<our @A>. (Well, you might want to
+consider not exporting variables at all, but that's a style issue.)
=item export_to($P0, $P1)
@@ -188,10 +202,16 @@
For example, Perl's pragmata are implemented as exports, and they don't
actually export anything.
-IMPLEMENTATION EXAMPLES: Perl 6 C<use tcl:Some::Module 'c*'> will import all
-the commands that start with 'c' from the given Tcl namespace into the current
-Perl namespace. Regardless of whether 'c*' is a Perl 6 style export pattern,
-it I<is> a valid Tcl export pattern.
+IMPLEMENTATION EXAMPLES: Suppose a Perl program were to import some Tcl module
+with an import pattern of "c*" -- something that might be expressed in Perl 6
+as C<use tcl:Some::Module 'c*'>. This operation would import all the commands
+that start with 'c' from the given Tcl namespace into the current Perl
+namespace. This is so because, regardless of whether 'c*' is a Perl 6 style
+export pattern, it I<is> a valid Tcl export pattern.
+
+{XXX - Is the ':' for HLL approved or just proposed? Somebody familiar with
+Perl 6 please fix the example in the preceding paragraph to use the currently
+planned syntax for importing modules from other languages.}
IMPLEMENTATION NOTE: Most namespace export_to implementations will restrict
themselves to using the typed interface on the target namespace. However,
@@ -211,8 +231,9 @@
=item $P0 = name()
-Returns the name of the namespace as an array of strings. So
perl5:Some::Module
-would return an array containing "perl5", "Some", "Module".
+Returns the name of the namespace as an array of strings. So if the current
+language is Perl 5 and the current Perl 5 namespace is "Some::Module" (that's
+Perl 5 syntax), then name() returns an array of "perl5", "Some", "Module".
NOTE: This is a naive method. It does not account for any aliasing.
@@ -224,11 +245,20 @@
=over 4
-=item load_library($P0)
+=item load_library($P0, $P1)
Ask this compiler to load a library/module named by the elements of the array
-in $P0. So perl5:Some::Module should be loaded using (in pseudo Perl 6):
-C<perl5.load_library(["Some", "Module"])>.
+in $P0, with optional control information in $P1.
+
+For example, Perl 5's module named "Some::Module" should be loaded using (in
+pseudo Perl 6): C<perl5.load_library(["Some", "Module"], null)>.
+
+The meaning of $P1 is compiler-specific. The only universal legal value is
+Null, which requests a "normal" load. The meaning of "normal" varies, but
+the ideal would be to perform only the minimal actions required.
+
+On failure, an exception is thrown. {XXX - I'd settle for a universal error
+pmc interface. Hm, sounds like a new pdd. >>TODO}
=back
@@ -329,9 +359,9 @@
$a = 'x';
${"Foo::$a"} = 5;
-The Foo:: namespace is created at run-time (without any optimizations). In
these
-cases, Parrot should create the namespace based on the HLL of the PIR
subroutine
-that calls the store function.
+The Foo:: namespace is created at run-time (without any optimizations). In
+these cases, Parrot should create the namespace based on the HLL of the PIR
+subroutine that calls the store function.
.HLL "Perl5", "perl5_group"
.sub main :main
@@ -352,8 +382,9 @@
store_global $P2, $S0, $P3
.end
-In this case, C<store_global> should see that it was called from "main", which
is
-in a Perl5 namespace, so "Foo::" should be also created as a Perl 5 namespace.
+In this case, C<store_global> should see that it was called from "main", which
+is in a Perl5 namespace, so it will create the "Foo" namespace as a Perl5
+namespace.
=head1 LANGUAGE NOTES
@@ -417,10 +448,10 @@
=head3 Cross-language Exportation
-Perl:
+Perl5:
#!/usr/bin/perl
- use tcl:Some::Module 'w*';
+ use tcl:Some::Module 'w*'; # XXX - is ':' after HLL standard Perl 6?
write("this is a tcl command");
PIR:
