Allison just updated pdd21, it looks great!  Here's a first
cut at some suggested changes and wordsmithing to the text.
Feel free to adopt, ignore, or discuss any of the suggestions
below as you see fit.


: 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"]>.

Reads better if "non-nested" is removed from the first statement.

: =head2 Naming Conventions
: 
: There are many different ways to implement a namespace and Parrot's target
: languages display a wide variety of them.  By implementing an API and standard
: conventions, it should be possible to allow interoperability while still
: allowing each one to choose the best internal representation.

Rephrase the first sentence to:

   Parrot's target languages have a wide variety of namespace models.

: 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.  ...

Change "This namespace" to "An HLL root namespace" (avoid ambiguity).

: Each HLL must store implementation internals (private items) in a namespace
: named with an underscore and the lowercased name of the HLL.  For instance,
: Tcl's implementation internals should live in the C<_tcl> namespace.

I think this should read

    Each HLL must store implementation internals (private items) in an
    HLL namespace named with an underscore and the lowercased name of 
    the HLL.  For instance, Tcl's implementation internals should 
    live in the C<_tcl> HLL namespace.

: =item get_global
: 
:     $P1 = $P2.get_global($S3)
: 
: Retrieve a global variable $P1 from the namespace $P2, with the name
: $S3.

What's the meaning of "global" in this context?  Some part of me
wants this to be simply "get_symbol".  Or are we contrasting "global"
with "lexical" or "private"?  See also the get*_global and set*_global
opcodes below, which I think should be "get_symbol" and "set_symbol".

: =item get_name
: 
:     $P1 = $P2.get_name()
: 
: Gets the name of the namespace $P2 as an array of strings.  For example,
: if the current language is Perl 5 and the current Perl 5 namespace is
: "Some::Module" (that's Perl 5 syntax), then get_name() on that namespace
: returns an array of "perl5", "Some", "Module". 

Perhaps better written as:

    For example, if $P2 is the Perl 5 "Some::Module" namespace within the 
    Perl 5 HLL, then get_name() on $P2 returns an array of "perl5", 
    "Some", "Module".

: =item get_namespace
: 
:     $P1 = $P2.get_namespace($P3)
:  
: Ask the compiler $P2 to find its namespace which is named by the
: elements of the array in $P3.  Returns a namespace PMC on success and a
: null PMC on failure.  A null PMC or an empty array retrieves the HLL's
: base namespace.

Swap the order of the last two sentences, thus:

    Ask the compiler $P2 to find its namespace which is named by the
    elements of the array in $P3.  If $P3 is a null PMC or an empty
    array, retrieves the base namespace for the HLL.  Returns a namespace
    PMC on success and a null PMC on failure.

Since this is a method, it would also be nice if $P3 could be
an optional parameter to obtain the base namespace for the HLL.

: =item load_library
: 
:   $P1.load_library($P2, $P3)
:
: Ask this compiler to load a library/module named by the elements of the array
: in $P2, with optional control information in $P3.
: [...]
: The meaning of $P3 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.

Since we have slurpy named parameters in Parrot, why not simply leave $P3
off and use (optional) named parameters here to specify options?

: =item get_global
: 
:     $P1 = get_global $S2
:     $P1 = get_hll_global $S2
:     $P1 = get_root_global $S2
: 
: Retrieve the symbol named $S2 in the current namespace, HLL root
: namespace, or true root namespace.

Again, perhaps "get_symbol" might be more appropriate than
"get_global", especially since the description itself says
"Retrieve the symbol...".

Thanks,

Pm

Reply via email to