Call Chains & Tap

## What a bang method returns In Ruby a method ending in `!` is the **"dangerous" twin** of a method without it; for the String and Array methods discussed here, the danger is that it modifies the receiver in place. The part that breaks chains is the **return value**. The core documentation writes it in the call signature: - `String#strip!`: self or nil - `String#squeeze!`: self or nil - `String#gsub!(pattern, replacement)`: self or nil - `Array#uniq!`, `Array#compact!`, `Array#flatten!`: self or nil "Self or nil" means: **the receiver if anything changed, `nil` if nothing did.** The `nil` is a signal, useful in a condition such as `puts "trimmed" if title.strip!`, but it is poison in a chain. ## Why the failure depends on the data ```ruby title = " Red Mug ".dup title.strip!.squeeze!(" ") # works: strip! changed it and returned title title = "Red Mug".dup title.strip!.squeeze!(" ") # NoMethodError: undefined method 'squeeze!' for nil ``` 1. For a padded title, `strip!` removes whitespace and returns the String, so `squeeze!` runs. 2. For an already-trimmed title, `strip!` has nothing to do and returns `nil`. 3. The next link calls `squeeze!` on `nil`, which has no such method. This is why the bug is **intermittent**: it depends on whether each record happened to need the first step. Test fixtures copied from messy input pass; clean production data crashes, or the other way round. ## Two correct rewrites | Style | Code | Result | |---|---|---| | Non-mutating chain | `title = title.strip.squeeze(" ")` | new String assigned; the old one untouched | | Separate statements | `title.strip!` then `title.squeeze!(" ")` | same object edited; return values ignored | - The **chain** is the default: every non-bang link returns a String, so nothing can turn into `nil`. - **Statements** fit when the String must be edited in place, for example because other code holds a reference to it, or to avoid intermediate allocations in a measured hot path. Each call's return value is simply not used. - Using `tap` to keep a chain shape, `title.tap { |t| t.strip! }.tap { |t| t.squeeze!(" ") }`, also works, because `tap` returns its receiver whatever the block returns; it is rarely clearer than two statements. ## Not every bang returns nil The "self or nil" contract is per method, not a rule about the `!` suffix: | Method | Returns | |---|---| | `String#strip!`, `squeeze!`, `gsub!`, `downcase!`, `capitalize!` | `self` or `nil` | | `Array#uniq!`, `compact!`, `flatten!`, `select!`, `reject!` | `self` or `nil` | | `Array#sort!`, `map!`, `reverse!` | always `self` | | `Hash#merge!` | always `self` | So `titles.sort!.first` is safe, while `titles.uniq!.first` fails whenever there were no duplicates. The only reliable guide is the documented return value of the specific method. ## Common wrong fixes - Adding `rescue nil` to the chain hides the failure and skips the remaining steps. - Replacing the chain with `(title.strip! || title).squeeze!(" ")` works but repeats the trap for the next link, and the next reader has to reason about each `||`. - Assuming the non-bang form might also return `nil`; `strip` and `squeeze` always return a String. ## Spotting it in review A reviewer can catch this pattern without running anything: 1. Look for a bang method **followed by a dot**: `strip!.`, `uniq!.`, `gsub!(...).`. Any such link is suspect. 2. Look up the method's documented return. If it says "self or nil", the chain fails whenever the method has nothing to do. 3. Ask what input makes it a no-op: an already trimmed title, an Array without duplicates, a String the pattern does not match. That input is the missing test case. The same reasoning explains why `if title.gsub!(/\s+/, " ")` is a legitimate condition while `title.gsub!(/\s+/, " ").strip` is a latent crash: the `nil` is information when you test it and a trap when you chain on it.