Bad docs: The example of the use of an 'Iterator' PMC in "Programming Parrot -- PMCs" #3

Closed
ayardley opened this Issue Nov 30, 2011 · 7 comments

Projects

None yet

3 participants

@ayardley
Parrot Virtual Machine member

"PMC in Programming Parrot -- PMCs" (http://docs.parrot.org/parrot/latest/html/docs/user/pir/pmcs.pod.html) discusses the use of an Iterator PMC to walk the Env PMC. Evidently, however, the syntax for this is out-of-date, yet still reflected in the doc. That is, it offers the following example:

.sub _ :main
    .local pmc env, iter
    .local string key, value
    env  = new 'Env'                    # line 3
    iter = new 'Iterator', env        # line 4
  iterloop:
    unless iter goto iterend
    key = shift iter                        # line 8
    value = env[key]
    print key
    print ":"
    print value
    print "\n"
    goto iterloop
  iterend:
.end

But it fails with the following error:

Direct creation of Iterator
current instr.: '_' pc 3 (args_2.pir:4)

The "new" (or "up-to-date") syntax for the Iterator works correctly,

.sub _ :main
.local pmc iter0, env
.local string key, value
env = new 'Env' # line 3
iter0 = iter env # line 4
iterloop:
unless iter0 goto iterend
key = shift iter0 # line 8
value = env[key]
print key
print ":"
print value
print "\n"
goto iterloop
iterend:
.end

I don't know why the syntax changed; and I don't know when it changed (but, fwiw, I prefer the old). Regardless, this example and the others in the doc which use the Iterator PMC must be updated.

Alvis

@bacek
Parrot Virtual Machine member

This behaviour was changed about 2 years ago.

@bacek
Parrot Virtual Machine member

And, "old way of creating of Iterators" is ugly on many, many levels.

@ayardley
Parrot Virtual Machine member

bacek,

I'm not trying to be contentious here, but what's wrong with,

 iter = new 'Iterator', env

It seems rather clear to me: Give me a, give me an Iterator on the Env PMC.

Does it violate some principle of OO design or some-such?

Seeking enlightenment (in general, but on this issue in particular :)

@bacek
Parrot Virtual Machine member

In Parrot world, "new 'Iterator', env" creates instance of Iterator object. Which should have knowledge of all possible ways of iterating over all possible aggregates. It's more then ugly. It's unmaintainable. In any OO designs "Iterator" is concept/interface/anything but implementation. Switching to "$P0 = iter env" (which is technically $P0 = env.get_iter()) provide clean way of creating aggregate-specific Iterator. Such as HashIterator, ArrayIterator, etc.

@ayardley
Parrot Virtual Machine member

Ahh, ok. Thank you.

@Util
Parrot Virtual Machine member

Fixed by 7d99edd Update docs to fix GH issue 3 on parrot.github.com - outdated examples of iterator use.

@Util Util closed this Dec 1, 2011
@bacek
Parrot Virtual Machine member
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment