parrot/parrot.github.com — Issue #3: Bad docs: The example of the use of an 'Iterator' PMC in "Programming Parrot -- PMCs" 
Author: ayardley
Created: 2011-11-30 21:46:17+00:00
State: open

"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