compound 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bde58c968de960b402bea81f6fbbf9b79432dca0
-  data.tar.gz: addbbf2bb047dab73b91fe0d1e4a3467e48bfcaf
+  metadata.gz: f4f1025df16249c199852986752859e1182992dc
+  data.tar.gz: 4cf21ac8e1adaf7c9b2d86f62437b6e73d5412e9
 SHA512:
-  metadata.gz: a5751bb4d778bca22ef25041478f7554970bbb3466fc572ffece3f489a73e02ec01f93582c688a3d12c93c0abcb933acf1422656ce5a6cfb25e5c3db5fc525b6
-  data.tar.gz: 3650a8512ade312a0dedbb3f9d8ca4a75dd2497a064b95ccae5b7083a0e6019b801802eb0a7adc3acac2c40025a96e36d9e6aa075f5fececbccc7fbeda11c8a2
+  metadata.gz: f4a198d31d92fd0e91c46b8519d2592177d524e486e6df2f5481df9303cf6f5f3539d804c62a74f1c3ce8c3e40590ffe5d2e8137e422ea66f4676935205372d8
+  data.tar.gz: 4566764d60336ee085f208c74bf5b1c5d63cbd8084ca5712902c94c69ff21c4d1c3d4d50f56b61dba77f8c3f7c4b97cf1d613d2727cadd6547593898e92b6384

data/README.md

@@ -0,0 +1,229 @@
+
+Compound provides a mechanism for mixing together modules into an object 
+while maintaining some degree of separation to help avoid namespace collisions.
+
+# Compounding
+
+An instance of a class that includes the `Compound::Host` module gains 
+the ability to host one or more `Compound::Part`s within it.
+
+``` ruby
+  require 'compound'
+  
+  class ManyFacedObject
+    include Compound::Host
+  end
+```
+
+A `Part` is constructed within the `Host` when `#compound` is called.
+The new `Part` is an object `#extend`ed by the module passed to `#compound`.
+Any number of modules can be `#compound`ed into the `Host`.
+
+``` ruby
+  module Anger;  end
+  module Sorrow; end
+  module Joy;    end
+  
+  host = ManyFacedObject.new
+  host.compound Anger
+  host.compound Sorrow
+  host.compound Joy
+```
+
+# Method Forwarding
+
+If a method is called on the `Host` which is not defined by the `Host`, but
+is defined by one of the `#compound`ed modules, the method and arguments 
+will be forwarded to the internal `Part` object associated with that module.
+If more than one module defines the method, it will be forwarded to the one
+which was most recently `#compound`ed.
+
+``` ruby
+  host.countenance #=> raises NoMethodError
+  
+  module Anger
+    def countenance
+      :grimace
+    end
+  end
+  
+  host.countenance #=> :grimace  # host can now forward to the new Anger method
+  
+  module Joy
+    def countenance
+      :grin
+    end
+  end
+  
+  host.countenance #=> :grin  # Joy shadows Anger because Joy was compounded later
+  
+  module Sorrow
+    def countenance
+      :frown
+    end
+  end
+  
+  host.countenance #=> :grin  # Joy also shadows Sorrow because Joy was compounded later
+```
+
+`Part` objects will also forward unknown methods back to the `Host`, 
+allowing methods of a `#compound`ed module to call public methods 
+of the other `#compound`ed modules or of the `Host` itself "natively" 
+(without specifying an explicit receiver).
+
+``` ruby
+  module Anger
+    def shout(msg)
+      msg.upcase + '!'
+    end
+  end
+  
+  module Joy
+    def exclaim
+      shout 'hooray'
+    end
+  end
+  
+  host.exclaim #=> 'HOORAY!'
+```
+
+# Privacy
+
+Due to this forwarding of methods, the `Host` appears to an outside object
+as if all of the `#compound`ed modules were mixed into it with `#extend`.
+However, the modules' private parts remain partitioned from one another.
+For example, private methods and instance variables are not shared among them.
+
+``` ruby
+  module Sorrow
+    private
+    def weep
+      '...'
+    end
+  end
+  
+  module Joy
+    def overcome_by_beauty
+      weep #=> raises NoMethodError
+    end
+  end
+  
+  host.overcome_by_beauty #=> call to :weep raises NoMethodError
+```
+``` ruby
+  module Joy
+    attr_accessor :value
+  end
+  
+  module Anger
+    def internalize(value)
+      @value = value
+    end
+    
+    def recall
+      @value
+    end
+  end
+  
+  host.value          #=> nil  # @value retrieved from Joy
+  host.internalize 88 #=> 88   # @value stored in Anger
+  host.recall         #=> 88   # @value retrieved from Anger
+  host.value          #=> nil  # @value retrieved from Joy
+  host.value = 999    #=> 999  # @value stored in Joy
+  host.recall         #=> 88   # @value retrieved from Anger
+```
+
+This is the chief advantage to using `#compound` instead of `#extend`.
+The modules need no longer worry about avoiding namespace collisions in
+private behaviour.  This leads to fewer mixing compatibility issues among 
+modules that may not necessarily be versioned in relation to one another.
+
+
+# Uncompounding
+
+As luck would have it, a module can be `#uncompound`ed just as simply 
+as it was `#compound`ed.
+
+``` ruby
+  host.uncompound Anger
+  host.uncompound Sorrow
+  #=> only Joy remains!
+```
+
+
+# Defining Modules for Compounding
+
+Some points to keep in mind when defining a module specifically for compounding:
+
+- Public methods are 'shared' and should be considered the 'interface' to 
+  your module; this interface should remain well-documented and versioned.
+
+- Private methods are defined only in support of the module,
+  and because they are not shared, they are free to change and rearrange
+  without worry of namespace collisions with methods of the extended objects
+  or about other object methods depending on the use of them.
+
+- Instance variables are also not shared, neither among modules nor between
+  compounded module and host.  However, when accessors are defined for them
+  the accessors are part of the public interface along with other 
+  public methods, and should be treated as such.
+
+Because the mechanism of compounding uses a module somewhat differently 
+from how it is used in the traditional inclusion/extension mechanism, 
+one might want to ensure that the module is used correctly.
+If `Compound::Guard` is `include`d in a module, it will `warn` the user 
+if that module is `include`d or `extend`ed instead of `compound`ed. 
+
+``` ruby
+  module CompoundOnly
+    include Compound::Guard
+  end
+  
+  module OtherModule
+    include CompoundOnly          #=> warns the user
+  end
+  
+  Object.new.extend CompoundOnly  #=> warns the user
+  
+  host.compound CompoundOnly      #=> intended usage, no warning
+```
+
+Inversely, one might wish to ensure that a module intended to be used
+traditionally is not used in compounding.
+If `Compound::GuardAgainst` is `include`d in a module, 
+it will `warn` the user if that module is `compound`ed. 
+
+``` ruby
+  module TraditionalModule
+    include Compound::GuardAgainst
+  end
+  
+  module OtherModule
+    include TraditionalModule          #=> intended usage, no warning
+  end
+  
+  Object.new.extend TraditionalModule  #=> intended usage, no warning
+  
+  host.compound TraditionalModule      #=> warns the user
+```
+
+
+# Initialization of Modules
+
+Sometimes, a module might want to know that it has been compounded so that it
+can initialize its internal state.  Traditional module composition will call
+the `extended` or `self.included` methods if they are defined by the module.
+However, modules intended for compounding should define a `compounded` method
+instead, to be called upon creation of the `Host`'s internal `Part` object.
+
+``` ruby
+  module Paint
+    def compounded
+      @color = :royal_blue
+    end
+    attr_accessor :color
+  end
+  
+  host.compound Paint
+  host.color          #=> :royal_blue
+```

data/lib/compound/host.rb

@@ -1,24 +1,42 @@
 
 module Compound
   
-  module Hosting
+  # Include this module in a class to gain the ability to host Parts,
+  # which each embody a module, appearing to an outside object as if
+  # the modules themselves were mixed in, while maintaining separation
+  # among the modules.  Refer to the README for more information
+  module Host
+    
+    # Internalize a new Part embodying the given module
     def compound mod
       @_compound_parts ||= []
+      uncompound mod
       @_compound_parts.unshift ::Compound::Part.new self, mod
       mod.compounded(self) if mod.respond_to? :compounded
+      return mod
+    end
+    
+    # Remove the Part associated with the given module
+    def uncompound mod
+      (@_compound_parts &&
+      (@_compound_parts.reject! { |part| part.is_a? mod } ? mod : nil))
     end
     
+    # Forward an undefined method if it is in one of the Parts
     def method_missing sym, *args, &block
       component = @_compound_parts && 
                   @_compound_parts.detect { |obj| obj.respond_to? sym }
       component ? (component.send sym, *args, &block) : super
     end
     
+    # Pretend to also respond_to methods in the Parts as well as the Host
     def respond_to? sym
       super || !!(@_compound_parts && 
                   @_compound_parts.detect { |obj| obj.respond_to? sym })
     end
     
+    # Return the Method object associated with the symbol, 
+    # even if it is in one of the Parts and not the Host
     def method sym
       return super if methods.include? sym
       component = @_compound_parts && 
@@ -26,10 +44,7 @@ module Compound
       component ? component.method(sym) :
         raise(NameError, "undefined method `#{sym}' for object `#{self}'")
     end
-  end
-  
-  class Host
-    include Hosting
+    
   end
   
 end

data/lib/compound/part.rb

@@ -6,9 +6,10 @@ module Compound
       @_compound_component_parent.send sym, *args, &block
     end
     
-    def initialize parent, component_module
+    def initialize parent, mod
       @_compound_component_parent = parent
-      extend component_module
+      extend mod
+      compounded(parent) if mod.instance_methods.include? :compounded
     end
   end
   

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: compound
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Joe McIlvain
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-12-15 00:00:00.000000000 Z
+date: 2013-12-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -90,6 +90,7 @@ files:
 - lib/compound/host.rb
 - lib/compound/part.rb
 - lib/compound.rb
+- README.md
 homepage: https://github.com/jemc/compound/
 licenses:
 - MIT License
@@ -110,9 +111,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.1.5
+rubygems_version: 2.1.11
 signing_key: 
 specification_version: 4
 summary: compound
 test_files: []
-has_rdoc: