short_circu_it 0.6.3 → 0.6.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca07490139f5e57b69e2d9403982ce9e144e813b8160ac2fd28b1abe0c886344
-  data.tar.gz: ac9f15e7d6ab5ea72faa8af8f083152db6d2945cc0da42604696bc5a953a6d8b
+  metadata.gz: 8e7f261ac6aaee08daa2c0e9f9aff3e81d6a82dd19f71b8be5f5d6ff590b02cf
+  data.tar.gz: 0b0a0069e63dc99f7e471bdb6c53370a3fc1103b3212e0bdf58d0ff2a07ddcd8
 SHA512:
-  metadata.gz: 504275f24bbaf3ad12c6e17bd958c777324366aa0ceea3b845d00873d6720ad5f8dbb6ee638fd33bf9ee8dd15827ab0cd8b87e7d9f2f1b7faa8bab3bf1d4cf29
-  data.tar.gz: 29d0f3fabdf8b3b7ee67f6bd43154a97fca1609888b671d2ac56572c24e54427c8d6d82ab7ff88fcb38ecc30e258bb3fec5ea0b4793a50bcc9f3c067bdc96e48
+  metadata.gz: da812e637b60671e65164524f41103f2a96b850bede88267d870a6c28eef0c27067b6817af5773832100efcde5cc5548c394fb5589ae1773cc5a37bac78c0491
+  data.tar.gz: 88347985f0e8a7441f18fc675dfbbfd2846b26e964b2fe8ced22eb90f7b8152eecd4a4542783be9a6c6a13b01deae916a23926de037ba870543d57fc6880f0f3

data/README.md

@@ -1,9 +1,20 @@
-# ShortCircuIt
+# [ShortCircuIt](https://www.youtube.com/watch?v=XtP88AGsslo)
 
 [![Build Status](https://semaphoreci.com/api/v1/freshly/spicerack/branches/master/badge.svg)](https://semaphoreci.com/freshly/spicerack)
 [![Maintainability](https://api.codeclimate.com/v1/badges/7e089c2617c530a85b17/maintainability)](https://codeclimate.com/github/Freshly/spicerack/maintainability)
 [![Test Coverage](https://api.codeclimate.com/v1/badges/7e089c2617c530a85b17/test_coverage)](https://codeclimate.com/github/Freshly/spicerack/test_coverage)
 
+* [Installation](#installation)
+* [What's memoization?](#whats-memoization)
+* [Usage](#usage)
+   * [Static methods](#static-methods)
+   * [Arguments](#arguments)
+   * [Instance State](#instance-state)
+   * [Observables](#observables)
+* [Development](#development)
+* [Contributing](#contributing)
+* [License](#license)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -20,9 +31,114 @@ Or install it yourself as:
 
     $ gem install short_circu_it
 
+## What's memoization?
+
+ShortCircuIt provides method memoization with awareness for arguments, instance state, weather, Oxford commas, or anything else you can think to throw at it.
+
+Imagine you have this method in your code, for some reason:
+
+```ruby
+def nth_digit_of_pi(n)
+  # MATH
+end
+```
+
+Now imagine you need to show the 1000th digit of pi in three places on a single webpage. Do you calculate it three times, or do you assign it to a variable once and use that variable three times? The latter is memoization; the former is... also an option.
+
 ## Usage
 
-TODO: Write usage instructions here
+### Static methods
+
+In the simplest case, `ShortCircuIt` is no harder to forget than the method name itself:
+
+```ruby
+class TheClassiest
+  include ShortCircuIt
+  
+  def how_methodical
+    puts "Pity on my sysop!"
+    this_must_be_expensive
+  end
+  memoize :how_methodical
+end
+
+the_classiest = TheClassiest.new
+3.times.map { the_classiest.how_methodical }
+# Pity on my sysop!
+#=> [
+#   "One Billion Dollars",
+#   "One Billion Dollars",
+#   "One Billion Dollars"
+# ]
+```
+
+Even though the method gets called 3 times, the code only gets executed once.
+
+### Arguments
+
+But what if your method takes arguments? We gotcha covered - memoization is specific to the arguments passed to the method, so a call with the same arguments will return the memoized value, while a call with different arguments will execute the method again.
+
+```ruby
+the_classiest.how_methodical(1)
+# Pity on my sysop!
+#=> "One Billion Dollars"
+
+the_classiest.how_methodical(1)
+#=> "One Billion Dollars"
+
+the_classiest.how_methodical(2)
+# Pity on my sysop!
+#=> "Two Billion Dollars"
+```
+
+### Instance State
+
+Sometimes instances are stateful and mutable. By default, ShortCircuIt will watch an object's state via its `hash` value, so the memoization is broken when its attributes change:
+
+```ruby
+the_classiest.how_methodical(1)
+# Pity on my sysop!
+#=> "One Billion Dollars"
+
+the_classiest.how_methodical(1)
+#=> "One Billion Dollars"
+
+the_classiest.orders_of_magnitude = 8
+the_classiest.how_methodical(1)
+# Pity on my sysop!
+#=> "One Hundred Million Dollars"
+```
+
+### Observables
+
+Maybe I have a method I'd like memoize on a complex object with many unrelated attributes:
+
+```ruby
+class TheAntist
+  attr_accessor :root_beer_floats_are_delicious, :physics, :weight_of_the_universe
+  
+  def how_much_ants_can_carry
+    # SCIENCE
+  end
+  memoize :how_much_ants_can_carry, observes: :physics
+  # Can also be
+  memoize :how_much_ants_can_carry, observes: [:physics, :weight_of_the_universe]
+end
+
+antist = TheAntist.new
+antist.how_much_ants_can_carry
+# => .5 oz
+
+# When we change an unobserved value, the memoiozation persists:
+antist.root_beer_floats_are_delicious = true
+antist.how_much_ants_can_carry
+# => .5 oz
+
+# But if we change the observed value, the memoization is broken:
+antist.physics = :parallel_universe
+antist.how_much_ants_can_carry
+# => 100 lbs
+```
 
 ## Development
 

data/lib/short_circu_it/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ShortCircuIt
-  VERSION = "0.6.3"
+  VERSION = "0.6.4"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: short_circu_it
 version: !ruby/object:Gem::Version
-  version: 0.6.3
+  version: 0.6.4
 platform: ruby
 authors:
 - Allen Rettberg
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-03-29 00:00:00.000000000 Z
+date: 2019-04-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.6.3
+        version: 0.6.4
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.6.3
+        version: 0.6.4
 description: Memoize methods safely with parameter and dependency observation
 email:
 - allen.rettberg@freshly.com