deject 0.2.1 → 0.2.2

data/Readme.md

@@ -16,85 +16,135 @@ On some systems:
 
 If you have to use sudo and you don't know why, it's because you need to set your GEM_HOME environment variable.
 
-Example
-=======
+Examples
+========
+
+Add Deject to your class.
 
 ```ruby
-require 'deject'
+class Game
+  Deject self
+end
+```
 
-class HumanPlayer
-  def type
-    'human player'
-  end
+Declare a dependency with a default.
+
+```ruby
+ComputerPlayer = Class.new
+
+class Game
+  Deject self
+  dependency(:player) { ComputerPlayer.new }
 end
 
-class ComputerPlayer
-  def type
-    'computer player'
-  end
+Game.new.player # => #<ComputerPlayer:0x007fb504945f28>
+```
+
+Override the dependency for the class.
+
+```ruby
+ComputerPlayer = Class.new
+HumanPlayer    = Class.new
+
+class Game
+  Deject self
+  dependency(:player) { ComputerPlayer.new }
 end
 
-class MockPlayer
-  def type
-    'mock player'
-  end
+Game.override(:player) { HumanPlayer.new } # in some initialization file
+
+Game.new.player # => #<HumanPlayer:0x007fde2d8ac880>
+```
+
+Override the dependency for an instance by using `#with_<dependency>`. You can
+pass a specific object, or a block for lazy initialization. This method returns
+the instance.
+
+```ruby
+ComputerPlayer = Class.new
+HumanPlayer    = Class.new
+MockPlayer     = Class.new
+
+class Game
+  Deject self
+  dependency(:player) { ComputerPlayer.new }
 end
 
+Game.new.with_player(HumanPlayer.new).player   # => #<HumanPlayer:0x007fb2a1015e40>
+Game.new.with_player { MockPlayer.new }.player # => #<MockPlayer:0x007fb2a10155f8>
+```
+
+Set a global default value to be used when a value isn't explicitly provided.
+If you are worried about clobbering a previously registered value, invoke with `:player2, safe: true`
+this is turned off by default because I found that code reloading was horking everything up.
+
+```ruby
+ComputerPlayer = Class.new
+HumanPlayer    = Class.new
+
+# these would go in some initialization file
+Deject.register(:player1) { ComputerPlayer.new }
+Deject.register(:player2) { ComputerPlayer.new }
+
 class Game
   Deject self
-  dependency(:player1) { ComputerPlayer.new }
+  dependency(:player1) { HumanPlayer.new }
   dependency :player2
-
-  def name
-    'poker'
-  end
 end
 
-# register a global value (put this into an initializer or dependency injection file)
-# if you are worried about clobbering a previously set value, invoke with `:player2, safe: true`
-# this is turned off by default because I found that code reloading was horking everything up
-Deject.register(:player2) { HumanPlayer.new }
+Game.new.player1 # => #<HumanPlayer:0x007fed8212d7d0>
+Game.new.player2 # => #<ComputerPlayer:0x007fed8212d348>
+```
 
-# declared with a block, so will default to block value
-Game.new.player1.type # => "computer player"
+Dependencies without a default block can passed to the Deject function.
 
-# declared without a block, so will default to the global definition for player1
-Game.new.player2.type # => "human player"
+```ruby
+ComputerPlayer = Class.new
 
-# we can override for this entire class
-Game.override(:player2) { MockPlayer.new }
-Game.new.player2.type # => "mock player"
+class Game
+  Deject self, :player
+end
 
-# we can override for some specific instance using either a block or a value
-# instance level overriding is done using method with_<dependnecy_name>, which returns the instance
-Game.new.with_player2 { HumanPlayer.new }.player2.type # => "human player"
-Game.new.with_player2(ComputerPlayer.new).player2.type # => "computer player"
+Game.new.with_player(ComputerPlayer.new).player # => #<ComputerPlayer:0x007fac2393a248>
+```
 
-# anywhere a block is used, the instance will be passed into it
-generic_player = Struct.new :type
+Anywhere a block is used, the instance is passed to it.
 
-game = Game.new.with_player1 { |game| generic_player.new "#{game.name} player1" }
-game.player1.type # => "poker player1"
+```ruby
+ChattyPlayer = Struct.new :message
 
-Game.override(:player2) { |game| generic_player.new "#{game.name} player2" }
-game.player2.type # => "poker player2"
-```
+class Game < Struct.new(:name)
+  Deject self
+  dependency(:player) { |game| ChattyPlayer.new "You're good at #{game.name}" }
+end
+
+player = Game.new('Monopoly').player
+player.message # => "You're good at Monopoly"
 
+player = Game.new('Monopoly').with_player { |game| ChattyPlayer.new "You're terrible at #{game.name}" }.player
+player.message # => "You're terrible at Monopoly"
+```
 
-Note that dependencies using the defaults can be declared when dejecting the class:
+Results are memoized.
 
 ```ruby
-class Game
-  # this
+NamedPlayer = Struct.new :name
+
+class Game < Struct.new(:name)
   Deject self
-  dependency :player1
-  dependency :player2
 
-  # is the same as this
-  Deject self, :player1, :player2
+  i = 0
+  dependency(:player) { NamedPlayer.new "Player#{i+=1}" }
 end
+
+game = Game.new
+game.player.name # => "Player1"
+game.player.name # => "Player1"
+
+Game.new.player.name # => "Player2"
 ```
 
+
 Reasons
 =======
 
@@ -198,7 +248,7 @@ end
 # or the changes that happened to it.
 ```
 
-Compare to Deject
+Compare the above examples to Deject
 
 ```ruby
 class SomeClass
@@ -207,6 +257,7 @@ class SomeClass
 end
 
 # straightforward (no one will be surprised when this changes),
+# declarative so easy to understand
 # convenient to override for all instances or any specific instance.
 ```
 
@@ -225,11 +276,12 @@ But I couldn't think of a good one. But wait, do I _really_ need a verb? I went
 and decided I was okay with having a method named after the class that applies it, hence `Deject SomeClass`. Not a usual practice
 but not unheard of, and I don't think it makes sense to force an OO like interface where it doesn't fit well.
 
-We use `with_<dependency>` instead of `dependency=` because taking blocks is grotesque with assignment methods. Further, I have a general
+We use `with_<dependency>` instead of `dependency=` because taking blocks is grotesque with assignment methods. I have a general
 disdain for assignment methods as they encourage a mindset that doesn't appreciate the advantages of OO.
 _"When you have a 'setter' on an object, you have turned an object back into a data structure" -- Alan Kay_.
 Furthermore, I nearly always want to be able to override the result inline, which you can't easily do with assignment methods
 as the interpreter guarantees they return the RHS (best solution would be to `tap` the object).
+The `with_<name>` pattern is a common pattern in [IO](http://iolanguage.com/).
 
 In general, all variables are stored as locals in closures rather than instance variables on the object. This is
 partially due to the implementation (alternative implementations used ivars), and partially because I wanted to

data/lib/deject/version.rb

@@ -1,3 +1,3 @@
 module Deject
-  VERSION = '0.2.1'
+  VERSION = '0.2.2'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: deject
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-04-29 00:00:00.000000000 Z
+date: 2012-05-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70118660588240 !ruby/object:Gem::Requirement
+  requirement: &70127720072140 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70118660588240
+  version_requirements: *70127720072140
 - !ruby/object:Gem::Dependency
   name: pry
-  requirement: &70118660586140 !ruby/object:Gem::Requirement
+  requirement: &70127720071620 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,7 +32,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70118660586140
+  version_requirements: *70127720071620
 description: Provides a super simple API for dependency injection
 email:
 - josh.cheek@gmail.com