[svn:parrot-pdd] r13740 - in trunk: . docs/pdds

[all...@cvs.perl.org]

Author: allison
Date: Tue Aug 1 13:00:29 2006
New Revision: 13740

Modified:
trunk/docs/pdds/pdd21_namespaces.pod

Changes in other areas also in this revision:
Modified:
trunk/ (props changed)

Log:
Namespace opcodes now accept arrays to select multidimensional
namespaces again. The namespace object methods for setting/retrieving
namespaces and globals are eliminated as redundant.

Modified: trunk/docs/pdds/pdd21_namespaces.pod
==============================================================================
--- trunk/docs/pdds/pdd21_namespaces.pod (original)
+++ trunk/docs/pdds/pdd21_namespaces.pod Tue Aug 1 13:00:29 2006
@@ -18,10 +18,8 @@

=item - Namespaces should be hierarchical

-=item - The get_namespace opcode takes a multidimensional hash key
-
-=item - The get_namespace method on a namespace object takes an array of
-name strings
+=item - The get_namespace opcode takes a multidimensional hash key or an
+array of name strings

=item - Namespaces follow the semantics of the HLL in which they're defined

@@ -125,58 +123,13 @@
interface>, which allows direct naming in the native style of the namespace's
HLL.

-One part of this interface consists of standard Parrot hash interface,
-with all its keys, values, lookups, deletions, etc. Just treat the
-namespace like a hash. (It probably is one, really, deep down.)
-
-The other part of this interface is a series of methods on the namespace
-object. These parallel the namespace opcodes but instead of taking a
-constant hash key argument to select a multi-level namespace, they
-take an array PMC.
-
-=over 4
-
-=item get_namespace
-
- $P1 = $P2.get_namespace($S3)
-
-Retrieve the namespace $P1 from within the namespace $P2 by a simple
-string name $S3.
-
- $P1 = $P2.get_namespace($P3)
-
-Retrieve the namespace $P1 from within the namespace $P2 by an array of
-names $P3 for a multi-level namespace.
-
-=item set_namespace
-
- $P1.set_namespace($P2, $P3)
-
-Add the namespace $P3 under a name denoted by an array of names $P2
-for a multi-level namespace relative to the namespace $P1.
-
-=item get_global
-
- $P1 = $P2.get_global($S3)
-
-Retrieve a symbol $P1 from the namespace $P2, with the name $S3.
+This interface consists of standard Parrot hash interface, with all its
+keys, values, lookups, deletions, etc. Just treat the namespace like a
+hash. (It probably is one, really, deep down.)

- $P1 = $P2.get_global($P3, $S4)
+The untyped interface also has one method:

-Retrieve a symbol $P1, with the name $S4, from a namespace selected by an
-array $P3 relative to the namespace $P2.
-
-=item set_global
-
- $P1.set_global($S2, $P3)
-
-Store a symbol $P3, in the namespace $P1 with the name $S2.
-
- $P1.set_global($P2, $S3, $P4)
-
-Store a symbol $P4, with the name $S3, in a namespace selected by an
-array $P2 relative to the namespace $P1. If the given namespace does
-not exist it is created.
+=over 4

=item get_name

@@ -370,13 +323,11 @@

=head2 Namespace Opcodes

-Note that all namespace opcodes operate from the local HLL root
-namespace. The namespace opcodes all have 3 variants: one that operates
-from the currently selected namespace (i.e. the namespace of the
-currently executing subroutine), one that operates from the HLL root
-namespace (identified by "hll" in the opcode name), and one that
-operates from the true root namespace (identified by "root" in the
-name).
+The namespace opcodes all have 3 variants: one that operates from the
+currently selected namespace (i.e. the namespace of the currently
+executing subroutine), one that operates from the HLL root namespace
+(identified by "hll" in the opcode name), and one that operates from the
+true root namespace (identified by "root" in the name).

=over 4

@@ -389,6 +340,13 @@
Add the namespace PMC $P1 under the name denoted by a multidimensional
hash key.

+ set_namespace $P1, $P2
+ set_hll_namespace $P1, $P2
+ set_root_namespace $P1, $P2
+
+Add the namespace PMC $P2 under the name denoted by an array of name
+strings $P1.
+
=item del_namespace

{{ NOTE: this opcode has been removed from the spec. The del_namespace
@@ -410,18 +368,41 @@
Retrieve the namespace denoted by a multidimensional hash key and
store it in C<$P1>.

-The opcodes for namespace lookups only accept hash keys. Thus, to get
-the "Foo::Bar" namespace from the top-level of the HLL, if the name was
-known at compile time, you could use this opcode:
+ $P1 = get_namespace $P2
+ $P1 = get_hll_namespace $P2
+ $P1 = get_root_namespace $P2
+
+Retrieve the namespace denoted by the array of names $P2 and store it in
+C<$P1>.
+
+Thus, to get the "Foo::Bar" namespace from the top-level of the HLL if
+the name was known at compile time, you could retrieve the namespace
+with a key:

$P0 = get_hll_namespace ["Foo"; "Bar"]

-If the name was not known at compile time, you would use a method call
-on the namespace object instead:
+If the name was not known at compile time, you would retrieve the
+namespace with an array instead:

- $P0 = get_hll_namespace
$P1 = split "::", "Foo::Bar"
- $P2 = $P0.get_namespace($P1)
+ $P0 = get_hll_namespace $P1
+
+=item make_namespace
+
+ $P1 = make_namespace [key]
+ $P1 = make_hll_namespace [key]
+ $P1 = make_root_namespace [key]
+
+Create and retrieve the namespace denoted by a multidimensional hash key
+and store it in C<$P1>. If the namespace already exists, only retrieve
+it.
+
+ $P1 = make_namespace $P2
+ $P1 = make_hll_namespace $P2
+ $P1 = make_root_namespace $P2
+
+Create and retrieve the namespace denoted by the array of names $P2 and
+store it in C<$P1>. If the namespace already exists, only retrieve it.

=item get_global

@@ -439,6 +420,13 @@
Retrieve the symbol named $S2 by a multidimensional hash key relative
to the current namespace, HLL root namespace, or true root namespace.

+ $P1 = get_global $P2, $S3
+ $P1 = get_hll_global $P2, $S3
+ $P1 = get_root_global $P2, $S3
+
+Retrieve the symbol named $S3 by the array of names $P2 relative to the
+current namespace, HLL root namespace, or true root namespace.
+
=item set_global

set_global $S1, $P2
@@ -456,6 +444,14 @@
relative to the current namespace, HLL root namespace, or true root
namespace. If the given namespace does not exist it is created.

+ set_global $P1, $S2, $P3
+ set_hll_global $P1, $S2, $P3
+ set_root_global $P1, $S2, $P3
+
+Store $P3 as the symbol named $S2 by the array of names $P1, relative to
+the current namespace, HLL root namespace, or true root namespace. If
+the given namespace does not exist it is created.
+
=back

=head2 HLL Namespace Mapping
@@ -516,13 +512,12 @@
$S0 = "$" . $S0
$P3 = new .PerlInt
$P3 = 5
- $P4 = get_namespace
- $P4.set_global($P2, $S0, $P3)
+ set_global $P2, $S0, $P3
.end

-In this case, C<get_namespace> should see that it was called from
-"main", which is in a Perl5 namespace, so the C<set_global> method will
-create the "Foo" namespace as a Perl5 namespace.
+In this case, C<set_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

[Matt Diephouse]

all...@cvs.perl.org <all...@cvs.perl.org> wrote:
> Author: allison
> Date: Tue Aug 1 13:00:29 2006
> New Revision: 13740
>
> Modified:
> trunk/docs/pdds/pdd21_namespaces.pod
>
> Changes in other areas also in this revision:
> Modified:
> trunk/ (props changed)
>
> Log:
> Namespace opcodes now accept arrays to select multidimensional
> namespaces again. The namespace object methods for setting/retrieving
> namespaces and globals are eliminated as redundant.

How does this handle the case where namespaces have a sigil or some
other sort of name mangling? Aren't the get/set namespace methods an
essential part of the typed interface?

--
Matt Diephouse
http://matt.diephouse.com

[Allison Randal]

Matt Diephouse wrote:
>> Namespace opcodes now accept arrays to select multidimensional
>> namespaces again. The namespace object methods for setting/retrieving
>> namespaces and globals are eliminated as redundant.
>
> How does this handle the case where namespaces have a sigil or some
> other sort of name mangling? Aren't the get/set namespace methods an
> essential part of the typed interface?

The get/set_namespace methods were part of the untyped interface (so any
name mangling had to be handled manually). The typed interface uses
find_namespace and add_namespace.

Allison