Use Enumators

[nyarly]

The API is confusing enough regarding traversing an entity tree (docs might help) but it's really a let down that the iterations aren't actually using the Ruby Enumerable module and Enumerator class.

[louismullie]

Yes, it would be better design to use Enumerable; it's on my todo list. If you have time, then send me a pull request on birch.

Regarding the API, can you provide more specific/constructive information on why you find it confusing?

entity.each do |child|
  child.each do |subchild|
    # etc...
   end
end

coll.each_document do |doc|
   doc.each_sentence do |sent|
     sent.each_word do |word|
       # ...
     end
   end
end

I'm not sure how I could've design a clearer API here...

[nyarly]

This probably should go in a new issues but:

The documentation as I was able to find talked a lot about assembling entity trees (and it might be a nice convenience to have a Builder object that includes the DSL so that you could build a tree without having to inject methods into the object), but doesn't even include visualizations of the entities - IMO it would be really nice to see #visualize(:tree) right after building a tree.

Your example above is good (although it's not completely clear how it works - an example tree + comments about exactly what's yielded would help too.)

So: if I ran across Treat code, it'd be perfectly lucid what was going on. But generating the code from whole cloth is a hurdle.

[louismullie]

+1 for a Builder object - #37

[louismullie]

https://github.com/louismullie/birch/commit/9d563a22f23a915f0f2c484b57300791f6b6630d