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

[ayardley]

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

This behaviour was changed about 2 years ago.

[bacek]

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

[ayardley]

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]

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]

Ahh, ok. Thank you.

[Util]

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

[bacek]

See also http://trac.parrot.org/parrot/ticket/1254