finishing_moves 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7edf17bb22f39f2a5ef98ff9a636605c0dfc0772
-  data.tar.gz: 9f60832e76dfa4d8738844398bfef705dc76a059
+  metadata.gz: 42ea93a2ee588f125b572cf38ae4c1498d143bdb
+  data.tar.gz: 6a5f4e469d4342896ee4c01af854477f58d95537
 SHA512:
-  metadata.gz: 89e13ebcf8b735570055a2d1a3270989b9424f2c47947c1f1c59af6451c1c2fa6ebc6b2ac92d93160bc1154738db2891110e269143deaae90173eee0498a1cdb
-  data.tar.gz: 16e94f9abb4f914aaff7b37cacc9734ae07269a52d2eae05848648ab9e67e4833cc97a662cb24c629f541fcfd6b783db40f5eddb906f77772d05e53481ce442a
+  metadata.gz: e3743c09cf0ad5bbcbb40c9ab99434988150648f0b624fde2c2dfbdff11e694081f4a571d731aba7f5b555e4fb17f39f90580ffe0aaf15b7bd63b8349cbcda07
+  data.tar.gz: b3f8d3f73fcf940be756c60132f042cc38530a59febb382610d3a918a859a2f97e1dcac2bb8c0de5b1a353cc8a506f6d67872aea78d345108a18a849b11ecd81

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    finishing_moves (0.1.1)
+    finishing_moves (0.1.2)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -195,7 +195,6 @@ else
 end
 
 # with nil_chain, we get a nice one liner
-
 var = nil_chain(:default_value) { my_hash[:foo] }
 
 # What if the default value is coming from somewhere else?
@@ -208,9 +207,7 @@ var = nil_chain(Geomancer.reset_ley_lines) { summon_fel_beast[:step_3].scry }
 #    Geomancer.reset_ley_lines if it's not
 ```
 
-##### Aliases
-
-`nil_chain` is aliased to `chain` for more brevity, and `method_chain` for alternative clarity.
+`nil_chain` is aliased to `method_chain` for alternative clarity.
 
 #### `Object#bool_chain`
 
@@ -327,7 +324,7 @@ class_exists? DefinitelyFakeClass
 # => NameError: uninitialized constant DefinitelyFakeClass
 
 class_exists? :DefinitelyFakeClass
-# => false (at least it better be; if you actually use this name, I will find you...)
+# => false (at least it better be; if you *actually* use this name, I will find you...)
 ```
 
 #### `Object#not_nil?`
@@ -343,6 +340,80 @@ nil.not_nil?
 
 Much better. Now pass me another PBR and my fedora.
 
+#### `Object#cascade`
+
+This method is designed to facilitate a set of consecutive, mutating actions which may be interrupted at multiple arbitrary points. In pseudo-code, the logic we're trying to write looks like this:
+
+1. Begin stepwise process.
+2. Set `[values]` to a default starting state.
+3. If `[first requirement]` is not met, bail out.
+4. Perform steps that require `[first requirement]`, possibly mutating `[values]`.
+5. If [next requirement] is not met, bail out.
+6. Perform steps that require `[first requirement]`, possibly mutating `[values]` again.
+7. (Repeat for as many steps as necessary.)
+8. End stepwise process.
+9. Perform follow-up action(s) based on resulting `[values]`.
+
+A common real-world scenario would be a login approval process. Here's a contrived Rails-y sample:
+
+```ruby
+cascade do
+  logged_in = false
+  # not doing anything if they didn't provide creds
+  break if params['username'].nil? || params['password'].nil?
+  # ok, got creds, do they exist?
+  user = User.find_by username: params['username']
+  # does the user exist?
+  break if user.nil?
+  # does the password match?
+  break if user.validate_password(params['password'])
+  # maybe the user account is banned?
+  break if user.banned?
+  # everything looks good, let's do it
+  login user
+  logged_in = true
+end
+
+if logged_in
+  # additional follow-up steps for authenticated users
+else
+  # display error message, log the failed attempt, whatever
+end
+```
+
+We're using the [`loop`](http://www.ruby-doc.org/core-2.1.5/Kernel.html#method-i-loop) construct under the hood, which is what allows us to use the `break` statement as outlined in the example.
+
+###### *"Why not just shove the logic into a method and use `return` instead of `break`?"*
+
+You should absolutely use methods if it makes sense. The example above is probably best handled by its own method, given it's complexity and the likelihood that you'll want to run tests on it.
+
+`cascade` is ideal for small sets of logic, where you're *already* inside a method and further breakout is just silly.
+
+To illustrate, here's an actual sample from a real project:
+
+```ruby
+class ReportsController
+
+  before_action :define_search_params, only: :run_report
+
+  def define_search_params
+    # Set the report type
+    # defaults to medical, skip if building a dismissals report
+    cascade do
+      @part = :medical
+      break if @report == :dismissals
+      @part = params[:part].to_sym if params[:part].to_sym.in? APP.enum.part.to_hash
+    end
+
+    # ...
+  end
+
+end
+```
+
+It's overkill to break that bit of logic out into another method. We could have alternatively used nested `if` statements, but the vertically aligned codes reads better, in my opinion.
+
+
 ### Extensions to `Hash`
 
 #### `Hash#delete!`
@@ -445,7 +516,7 @@ For consistency, we added matching methods to `Float` and `BigDecimal` that simp
 # => ArgumentError: Cannot get length: "12356469.987" is not an integer
 
 1265437718438866624512.123.class.name
-# => "Float" (it's really BigDecimal, trust us)
+# => "Float" (it's really BigDecimal, trust me)
 1265437718438866624512.123.length
 # => ArgumentError: Cannot get length: "1.2654377184388666e+21" is not an integer
 ```

data/lib/finishing_moves/version.rb

@@ -1,3 +1,3 @@
 module FinishingMoves
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 end

data/spec/object_spec.rb

@@ -16,15 +16,18 @@ describe Object do
     a = A.new b
     expect(a.b.c.hello).to eq "Hello, world!"
     b.c = nil
-    expect(method_chain{a.b.c.hello}).to eq nil
+    expect(nil_chain{a.b.c.hello}).to eq nil
     a = nil
-    expect(method_chain{a.b.c.hello}).to eq nil
+    expect(nil_chain{a.b.c.hello}).to eq nil
 
-    expect( chain(true) { bogus_variable } ).to equal true
-    expect( chain(false) { bogus_variable } ).to equal false
-    expect( chain('gotcha!') { bogus_variable } ).to eq 'gotcha!'
-    expect( chain('gotcha!') { params[:bogus_key] } ).to eq 'gotcha!'
-    expect( chain('gotcha!') { params[:foo] } ).to eq 'bar'
+    expect( nil_chain(true) { bogus_variable } ).to equal true
+    expect( nil_chain(false) { bogus_variable } ).to equal false
+    expect( nil_chain('gotcha!') { bogus_variable } ).to eq 'gotcha!'
+    expect( nil_chain('gotcha!') { params[:bogus_key] } ).to eq 'gotcha!'
+    expect( nil_chain('gotcha!') { params[:foo] } ).to eq 'bar'
+
+    # alias
+    expect(method_chain{bogus_variable}).to eq nil
   end
 
   it "#bool_chain" do
@@ -68,9 +71,17 @@ describe Object do
     expect(user.same_as(:FACELESS_ONE)).to eq false
   end
 
+  it "#cascade" do
+    expect(test_cascade).to be_nil
+    expect(test_cascade('step1')).to eq 1
+    expect(test_cascade('step2')).to eq 2
+    expect(test_cascade('step3')).to eq 3
+    expect(test_cascade('foobar')).to eq 4
+  end
+
 end
 
-# test classes
+# some small test fixtures
 
 class A
   attr_accessor :b
@@ -103,3 +114,18 @@ class User
     handle.to_s
   end
 end
+
+def test_cascade(trigger = nil)
+  ultimate_value = nil
+  cascade do
+    break if trigger.nil?
+    ultimate_value = 1
+    break if trigger == 'step1'
+    ultimate_value = 2
+    break if trigger == 'step2'
+    ultimate_value = 3
+    break if trigger == 'step3'
+    ultimate_value = 4
+  end
+  return ultimate_value
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: finishing_moves
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Frank Koehl
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-12-23 00:00:00.000000000 Z
+date: 2015-01-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb-readline