Author: particle
Date: Wed Apr 12 10:48:10 2006
New Revision: 12190
Modified:
trunk/docs/pdds/pdd21_namespaces.pod
Log:
[PDD21] modify doc to match current code behavior
~ define HLL Root Namespace
~ modify HLL User-Created Namespace definition
~ namespaces passed to "{find,store}_global" ops are relative to HLL root
namespace
Modified: trunk/docs/pdds/pdd21_namespaces.pod
==============================================================================
--- trunk/docs/pdds/pdd21_namespaces.pod (original)
+++ trunk/docs/pdds/pdd21_namespaces.pod Wed Apr 12 10:48:10 2006
@@ -67,6 +67,18 @@
=over 4
+=item HLL Root Namespaces
+
+Each HLL must store public items in a namespace named with the lowercased
+name of the HLL. This is the HLL root namespace. For instance, Tcl's user-
+created namespaces should live in the C<tcl> namespace. This eliminates any
+accidental collisions between languages.
+
+This namespace must be stored at the first level in parrot's namespace
+hierarchy. These top-level namespaces should also be specified in a standard
+unicode encoding. The reasons for these restrictions is to allow compilers
+to remain completely ignorant of each other.
+
=item HLL Implementation Namespaces
Each HLL must store implementation internals (private items) in a namespace
@@ -75,18 +87,10 @@
=item HLL User-Created Namespaces
-Each HLL must store all user-created namespaces under a namespace named with
-the lowercased name of the HLL. For example, Perl 5's CGI module must be
-named "perl5::CGI". This eliminates any accidental collisions between
-languages.
-
-These top-level namespaces should also be specified in a standard unicode
-encoding. The reasons for these restrictions is to allow compilers to remain
-completely ignorant of each other.
-
-HLLs should use hierarchical namespaces to the extent practical. A single
-flat namespace can be made to work, of course, but it complicates symbol
-exportation.
+Each HLL must store all user-created namespaces under the HLL root namespace.
+It is suggested that HLLs use hierarchical namespaces to the extent
+practical. A single flat namespace can be made to work, but it complicates
+symbol exportation.
=back
@@ -261,8 +265,8 @@
=item $P0 = find_global $S0
-Find the variable $S0 in the current namespace, or in $P1, relative to the
-HLL namespace.
+Find $P0 as the variable $S0 in the current namespace. or in $P1, relative
+to the HLL root namespace.
=item $P0 = get_namespace $P1
@@ -283,7 +287,7 @@
=item store_global $S0, $P0
Store $P0 as the variable $S0 in the current namespace, or in $P1, relative
-to the HLL namespace.
+to the HLL root namespace.
=back
