#Iterate could check that segment shouldn't repeat

[kputnam]

There's a small issue that I think enough people have encountered (probably not realizing it), that it would be helpful to beginners if it was fixed: foo.iterate(:XYZ) doesn't actually check that XYZ is a repeating segment.

If XYZ is not repeating (according to the grammar), then in cases where it finds XYZ the first time, it will throw an exception at the end of the given block when it tries to do another find -- "XYZ cannot be reached from this state". That's a confusing error because it appears that did find XYZ!

In the other case is that it didn't find XYZ, it doesn't throw an exception that you shouldn't have used iterate... it's kind of a bug waiting to happen when you eventually have a file that did have an XYZ.

I think we could change the definition of iterate by adding a test at the start, before calling find. This seems like a small change that would be good for a contributor to work on, and I think there's some code already (somewhere?) that checks if a segment is repeatable and throws an error if it's not... try searching for repeatable?. It might be in the Guide Builder code.