deject 0.2.2 → 0.2.3

data/.travis.yml

@@ -0,0 +1,5 @@
+nguage: ruby
+rvm:
+  - 1.9.3
+  - rbx-19mode
+script: "bundle exec rspec"

data/Rakefile

@@ -1 +1,6 @@
 require "bundler/gem_tasks"
+
+task :default do
+  sh 'bundle exec rspec'
+  sh 'bundle exec mountain_berry_fields Readme.md.mountain_berry_fields'
+end

data/Readme.md

@@ -8,7 +8,7 @@ Install
 
 On most systems:
 
-    $ gem install deject # coming soon
+    $ gem install deject
 
 On some systems:
 
@@ -19,6 +19,7 @@ If you have to use sudo and you don't know why, it's because you need to set you
 Examples
 ========
 
+
 Add Deject to your class.
 
 ```ruby
@@ -75,7 +76,7 @@ Game.new.with_player { MockPlayer.new }.player # => #<MockPlayer:0x007fb2a10155f
 ```
 
 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`
+If you are worried about clobbering a previously registered value, invoke as `.register(:player2, safe: true)`
 this is turned off by default because I found that code reloading was horking everything up.
 
 ```ruby
@@ -303,7 +304,8 @@ Deject does not litter your classes or instances with unexpected methods or vari
 Special Thanks
 ==============
 
-To the [8th Light](http://8thlight.com/)ers who have provided feedback, questions, and criticisms.
+* To [Enova](http://www.enovafinancial.com/) for helping me find the best use cases and most relevant missing features.
+* To the [8th Light](http://8thlight.com/)ers who have provided feedback, questions, and criticisms.
 
 
 Todo

data/Readme.md.mountain_berry_fields

@@ -0,0 +1,366 @@
+About
+=====
+
+Simple dependency injection
+
+Install
+=======
+
+On most systems:
+
+    $ gem install deject
+
+On some systems:
+
+    $ sudo gem install deject
+
+If you have to use sudo and you don't know why, it's because you need to set your GEM_HOME environment variable.
+
+Examples
+========
+
+<% setup do %>
+$LOAD_PATH.unshift File.expand_path '../lib', __FILE__
+require 'deject'
+<% end %>
+
+Add Deject to your class.
+
+```ruby
+<% test 'adding Deject to your class', with: :magic_comments do %>
+class Game
+  Deject self
+end
+<% end %>
+```
+
+Declare a dependency with a default.
+
+```ruby
+<% test 'declaring a dependency with a default', with: :magic_comments do %>
+ComputerPlayer = Class.new
+
+class Game
+  Deject self
+  dependency(:player) { ComputerPlayer.new }
+end
+
+Game.new.player # => #<ComputerPlayer:0x007fb504945f28>
+<% end %>
+```
+
+Override the dependency for the class.
+
+```ruby
+<% test 'override the dependency for the class', with: :magic_comments do %>
+ComputerPlayer = Class.new
+HumanPlayer    = Class.new
+
+class Game
+  Deject self
+  dependency(:player) { ComputerPlayer.new }
+end
+
+Game.override(:player) { HumanPlayer.new } # in some initialization file
+
+Game.new.player # => #<HumanPlayer:0x007fde2d8ac880>
+<% end %>
+```
+
+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
+<% test 'override the dependency for the instance', with: :magic_comments do %>
+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>
+<% end %>
+```
+
+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 as `.register(:player2, safe: true)`
+this is turned off by default because I found that code reloading was horking everything up.
+
+```ruby
+<% test 'declaring defaults', with: :magic_comments do %>
+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) { HumanPlayer.new }
+  dependency :player2
+end
+
+Game.new.player1 # => #<HumanPlayer:0x007fed8212d7d0>
+Game.new.player2 # => #<ComputerPlayer:0x007fed8212d348>
+<% end %>
+```
+
+Dependencies without a default block can passed to the Deject function.
+
+```ruby
+<% test 'shorter syntax for when using default', with: :magic_comments do %>
+ComputerPlayer = Class.new
+
+class Game
+  Deject self, :player
+end
+
+Game.new.with_player(ComputerPlayer.new).player # => #<ComputerPlayer:0x007fac2393a248>
+<% end %>
+```
+
+Anywhere a block is used, the instance is passed to it.
+
+```ruby
+<% test 'instances are passed to blocks', with: :magic_comments do %>
+ChattyPlayer = Struct.new :message
+
+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"
+<% end %>
+```
+
+Results are memoized.
+
+```ruby
+<% test 'results are memoized', with: :magic_comments do %>
+NamedPlayer = Struct.new :name
+
+class Game < Struct.new(:name)
+  Deject self
+
+  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"
+<% end %>
+```
+
+
+Reasons
+=======
+
+
+Why write this?
+---------------
+
+Hard dependencies kick ass. They make your code clear and easy to understand.
+But, of course, they're hard, you can't change them (or can't reasonably change them).
+So when you go to test, it sucks. When you want to reuse, it sucks. How to get around this?
+Inject your dependencies.
+
+And while it's not the worst thing in the world to do custom dependency injection in Ruby,
+it still gets obnoxious.
+
+
+Example: passing dependency when initializing
+
+```ruby
+<% test "example 1", with: :magic_comments do %>
+class SomeClass
+  attr_accessor :some_dependency
+
+  # cannot set this unless also setting arg2
+  def initialize(arg1, arg2=default, some_dependency=default)
+  end
+
+  # cannot set arg2 without being forced to set dependency
+  def initialize(arg1, some_dependency=default, arg2=default)
+  end
+
+  # forced to deal with the dependency *every place* you use this class
+  def initialize(some_dependency, arg1, arg2=default)
+  end
+
+  # okay, this isn't too bad unless:
+  #   1) You want to change the default
+  #   2) You only have one other optional arg
+  #      as you must degrade the interface for this new requirement
+  #   3) Your options aren't simple,
+  #     (e.g. will be passed to some other class as I was dealing with when I decided to write this),
+  #     then you will have to namespace your options and theirs
+  def initializing(arg1, options={})
+    arg2 = options.fetch(:arg2) { default }
+    self.some_dependency = options.fetch(:some_dependency) { default }
+  end
+end
+<% end %>
+```
+
+
+Example: try to set it in a method that you change later
+
+```ruby
+<% test "example 2", with: :magic_comments do %>
+class SomeClass
+  class << self
+    attr_writer :some_dependency
+    def some_dependency(instance)
+      @some_dependency ||= default
+    end
+  end
+
+  attr_writer :some_dependency
+  def some_dependency
+    @some_dependency ||= self.class.some_dependency self
+  end
+end
+
+# blech, that's:
+#   1) complicated -- as in difficult to easily look at and understand
+#      especially if you were to have more than one dependency
+#   2) probably needs explicit tests given that there's quite a bit of
+#      indirection and behaviour going on in here
+#   3) the class level override can't take into account anything unique
+#      about the instance (ie it must be an object, so must work for all instances)
+#   4) instances must be overridden like this: instance = SomeClass.new
+#                                              instance.some_dependency = override
+#                                              instance.whatever
+#      whereas Deject would be like this: SomeClass.new.with_some_dependency(override).whatever
+<% end %>
+```
+
+
+Example: redefine the method
+
+```ruby
+<% test 'redefining the method', with: :magic_comments do %>
+class SomeClass
+  def some_dependency
+    @some_dependency ||= default
+  end
+end
+
+# then later in some other file, totally unbeknownst to anyone reading the above code
+class SomeClass
+  def some_dependency
+    @some_dependency ||= new_default
+  end
+end
+
+# Want to piss off your colleagues? Imagine how long it will take them to figure out
+# why this code doesn't behave as they expect. What's more, guess what happens when
+# someone refactors that main class... your redefinition of some_dependency just becomes
+# a definition. It doesn't fail, it has no idea about the method it's overriding,
+# or the changes that happened to it.
+<% end %>
+```
+
+Compare the above examples to Deject
+
+```ruby
+<% test 'compare to deject', with: :magic_comments do %>
+class SomeClass
+  Deject self
+  dependency(:some_dependency) { |instance| default }
+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.
+<% end %>
+```
+
+
+
+About the Code
+--------------
+
+There have been maybe four or five implementations of Deject throughout it's life (though I think only two were ever committed to the repo).
+I ultimately chose the current implementation because it was the easiest to add features to.
+That said, it is not canonical Ruby style code, and will take an open mind to work with.
+
+I intentially chose to avoid using a module because this is pervasive and widely abused in Ruby, for more, see my [blog post](http://blog.8thlight.com/josh-cheek/2012/02/03/modules-called-they-want-their-integrity-back.html).
+I thought a long time about how to add the functionality, thinking about `Deject.execute` or some other verb that the Deject noun could perform.
+But I couldn't think of a good one. But wait, do I _really_ need a verb? I went and re-read [Execution in the Kingdom of Nouns](http://steve-yegge.blogspot.com/2006/03/execution-in-kingdom-of-nouns.html)
+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. 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
+make a point that relying on ivars is a bad practice: You cannot change implementations (without changing all the code using the ivar)
+ if you use the ivar instead of the getter (e.g. switch from `attr_accessor` to a struct, or in an `ActiveRecord::Base` subclass, moving a variable
+from an `attr_accessor` into the database). Furthermore, directly accessing ivars requires you to know when they were
+initialized, which you should not have to deal with, and this also impedes you from extracting the variable into a
+method you inherit from a module (the module can't lazily initialize it, because their methods are completely bypassed).
+And it even impedes refactoring. If you previously initialized `@full_name` in the `#initialize` method, you could not then decide to
+refactor `def fullname() @fullname end` into `def fullname() "#@firstname #@lastname" end` because users of
+fullname aren't using the method, they're accessing the variable directly. In general, I think it is best to
+encapsulate from everyone, including other methods in the same object. In Deject you don't have a choice,
+you use the methods because there are no variables. If you'd like to read an argument against my position on this,
+Rick Denatale summarizes Kent Beck's opinion on [ruby-talk](http://www.ruby-forum.com/topic/211544#919648).
+
+Deject does not litter your classes or instances with unexpected methods or variables.
+
+
+Special Thanks
+==============
+
+* To [Enova](http://www.enovafinancial.com/) for helping me find the best use cases and most relevant missing features.
+* To the [8th Light](http://8thlight.com/)ers who have provided feedback, questions, and criticisms.
+
+
+Todo
+====
+
+Maybe raise an error if you call `with_whatever` and pass no args.
+Maybe add a setter rather than only provide the overrider.
+
+License
+=======
+
+Copyright (c) 2012 Joshua Cheek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/deject.gemspec

@@ -13,8 +13,6 @@ Gem::Specification.new do |s|
 
   s.rubyforge_project = "deject"
 
-  s.required_ruby_version = "~> 1.9.2"
-
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
@@ -23,4 +21,7 @@ Gem::Specification.new do |s|
   # specify any dependencies here; for example:
   s.add_development_dependency "rspec"
   s.add_development_dependency "pry"
+  s.add_development_dependency "rake"
+  s.add_development_dependency 'mountain_berry_fields'
+  s.add_development_dependency 'mountain_berry_fields-magic_comments'
 end

data/lib/deject/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: deject
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-01 00:00:00.000000000 Z
+date: 2012-07-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70127720072140 !ruby/object:Gem::Requirement
+  requirement: &70118802190260 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70127720072140
+  version_requirements: *70118802190260
 - !ruby/object:Gem::Dependency
   name: pry
-  requirement: &70127720071620 !ruby/object:Gem::Requirement
+  requirement: &70118802189840 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,7 +32,40 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70127720071620
+  version_requirements: *70118802189840
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &70118802189420 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70118802189420
+- !ruby/object:Gem::Dependency
+  name: mountain_berry_fields
+  requirement: &70118802189000 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70118802189000
+- !ruby/object:Gem::Dependency
+  name: mountain_berry_fields-magic_comments
+  requirement: &70118802188580 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70118802188580
 description: Provides a super simple API for dependency injection
 email:
 - josh.cheek@gmail.com
@@ -41,9 +74,11 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .travis.yml
 - Gemfile
 - Rakefile
 - Readme.md
+- Readme.md.mountain_berry_fields
 - deject.gemspec
 - lib/deject.rb
 - lib/deject/version.rb
@@ -62,9 +97,9 @@ require_paths:
 required_ruby_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
-  - - ~>
+  - - ! '>='
     - !ruby/object:Gem::Version
-      version: 1.9.2
+      version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -73,7 +108,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: deject
-rubygems_version: 1.8.11
+rubygems_version: 1.8.17
 signing_key: 
 specification_version: 3
 summary: Simple dependency injection
@@ -84,4 +119,3 @@ test_files:
 - spec/global_registration_spec.rb
 - spec/instance_methods_spec.rb
 - spec/spec_helper.rb
-has_rdoc: