== Summary methodchain - ruby helpers for method chaining: chain, tap, then, else, and, or

Easy ways to navigate around nil without creating local variables.

Initial blog post describing previous ideas: http://blog.thoughtfolder.com/2008-03-16-navigating-nil-method-chaining-in-ruby.html

== Author and License Copyright (c) 2008 Greg Weber, http://gregweber.info Licensed under the MIT license

== Examples === ##then and ##else ==== old way person = nil name = person ? person.name : nil

==== new way name = person.then {|p| p.name}

or

name = person.then {name}

not a huge savings. But sometimes the person variable is actually a function call, and then we must save it in a variable first.

==== old way def find(*args) # do some expensive database queries end

person = find(:first) @phone = person && person.phone # => nil

==== new way @phone = find(:first).then {phone} # => nil

We have reduced a line of code and removed a local variable. ##else is the opposite of #then, and the two methods can be used together

'a'.then{'b'} #=> 'b' nil.then{'b'}.else{'c'} #=> 'c'

==== message sending The normal conditional for ##then and ##else is self

if self # inside MethodChain#then # evaluate block end

##then and ##else allow message sending as the conditional. See more examples of message sending with the MethodChain#chain examples below

"not empty".then(:empty?) {"N/A"} # => "not empty" "".then(:empty?) {"N/A"} # => "N/A"

=== ##and, ##or ==== old way Return a default value or the original value depending on whether multiple conditions are met Person = Struct.new(:phone ) blank = Person.new('') # or {:phone => nil} blank.phone && (not blank.phone.empty?) ? blank.phone : "N/A" # => "N/A" p = Person.new('123') p.phone && (not p.phone.empty?) ? p.phone : "N/A" # => "123"

==== new way blank.phone.and {not empty?} || "N/A" # => "N/A" p.phone.and {not empty?} || "N/A" # => "123"

=== ##tap if you don't already know about this method, look it up on the net. The tap included here allows message sending.

==== old way arr = [1] arr.compact! # => nil arr.first # => 1

==== normal ##tap (still valid) [1].tap {|arr| arr.compact!}.first # => 1

==== new ##tap [1].tap(:compact!).first # => 1

==== normal ##tap (still valid) [1].tap {|arr| arr.compact!}.tap {|arr| arr * 2}.first # => 1

==== new ##tap [1].tap( :compact!, [:*, 2] ).first # => 1

You can also pass Procs as arguments [1].tap( :compact!, lambda{|arr| arr * 2} ).first # => 1

=== ##chain chain is like tap, but instead of always returning self, it will return the result of the method call. [1].chain(:first) == [1].first

But there is an important difference- chain guards against certain results (by default it guards against nil and false)

==== old way customer = nil customer && customer.order && customer.order.id

==== new way customer.chain(:order, :id)

note that this is equivalent to

customer.then {order}.then {id}

=== ##chain - Custom guards, multiple arguments, and Procs ==== old way - guarding against zero value = 0

result = if value == 0 then value else tmp = value.abs

if tmp == 0 then tmp else
  tmp * 20
end

end result # => 0

==== new way value.chain(:abs, [:*, 20]) {|s| s == 0 } # => 0

Procs can be used, so this is equivalent to value.chain(:abs, lambda {|n| n * 20 }) {|s| s == 0 } # => 0

== Usage require 'rubygems'

=== import all MethodChain methods into Object

require 'methodchain'

=== selectively import MethodChain methods

require 'methodchain/not-included'

You can then include methodchain into selected classes, or you can use the module-import gem to include only certain methods

gem install module-import

require 'module-import' class Object import MethodChain, :chain # I only want Object#chain end

import will still load all the private methods from the module:

• yield_or_eval
• send_as_function
• send_as_functions

== Implementation There are no proxy objects and no use of method_missing- these are simply function calls, so it should be fast.

private methods:

• yield_or_eval: allows the two different block forms {|p| p.name} and {name}, where the first form yields self and the second form is called using instance_eval.

• send_as_function: allows symbols and arrays to be sent as messages, and calls yield_or_eval on Proc arguments

• send_as_functions:

  def send_arguments_as_functions *args args.each {|arg| send_as_function arg} self end

== Install gem install methodchain

== Source === browser http://github.com/gregwebs/methodchain/tree/master === repository git clone git://github.com/gregwebs/methodchain.git

== Homepage http://gregweber.info/projects/methodchain.html

== RDoc documentation included with gem