Iterate error: block did not return an instance of Either

[Shpigford]

I'm using the following to iterate over segments:

a.flatmap do |isa|
  isa.iterate(:GS) do |gs|
    gs.iterate(:ST) do |st|
      st.tap do |m|
         el(m.find(:L11, nil, '2I'), 1){|e| puts "Tracking Number: #{e}" }
      end
    end
  end
end

That works well, except after it's successfully iterated through all of the ST's, it throws this error:

TypeError: block did not return an instance of Either
   from /bundler/gems/stupidedi-499b645a6675/lib/stupidedi/either.rb:107:in `flatmap'
   from (irb):107
   from /gems/railties-3.2.13/lib/rails/commands/console.rb:47:in `start'
   from /gems/railties-3.2.13/lib/rails/commands/console.rb:8:in `start'
   from /gems/railties-3.2.13/lib/rails/commands.rb:41:in `<top (required)>'
   from script/rails:6:in `require'
   from script/rails:6:in `<main>'

[kputnam]

Yeah, a is an Either so the top-level a.flatmap { ... } block must return another Either value. The intended use of #flatmap is to convert one Either to another. In this case you should use a.tap { ... } instead, since you don't need the return value of the top-level expression.

The API for Either is documented in Navigation.md, but it's kind of buried and should be made its own document. Here's a quick reference:

• e.map{ ... }: transform the value, eg Either.success(-3).map(&:abs) => Either.success(3)
• e.tap { ... }: yields the wrapped value (or does nothing on Either.failure) and returns the original e
• e.flatmap { ... }: transform the value to another Either, unwrapping one layer. For example

Either.success(-3).map{|x| Either.success(x.abs)} #=> Either.success(Either.success(3))
Either.success(-3).flatmap{|x| Either.success(x.abs) } #=> Either.success(3)

The first probably has one more level of nesting than you'd want, but the second removes the extra layer. You can think of Either in terms of an Array that contains either zero or one elements. Then #flatmap is like [].concat(*a.map{ ... }) where the block returns a zero or one-element array, and #tap is like each, etc.

[Shpigford]

Gotcha. Makes sense.

Thanks!