decorum 0.3.0 → 0.4.0

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+# 0.4.0 / 2014-12-26
+
+* [FEATURE] specify default decorators in a class with .decorators
+* [FEATURE] #is_decorated?
+
 # 0.3.0 / 2014-2-3
 
 * [FEATURE] directly callable decorators

data/README.md

@@ -24,10 +24,16 @@ end
 
 bp = BirthdayParty.new
 bp.respond_to?(:shoot_confetti) # ==> false
+bp.is_decorated? # ==> false
 bp.decorate(Confetti)
+bp.is_decorated? # ==> true
 bp.shoot_confetti # ==> "boom, yay"
 ```
 
+## New in 0.4.0
+- Decorators and their attributes may now be specified in class definitions, and loaded with `#load_decorators_from_class`
+- `#is_decorated?`
+
 ## New in 0.3.0
 - Methods may be called directly on decorators
 - Decorator namespaces
@@ -196,7 +202,7 @@ original definition is found.)
 A sizeable amount of the world's total Ruby functionality is implemented
 by overriding `#method_missing`, so decorators shouldn't get in the way.
 Because Decorum intercepts messages in the objects eigenclass, it also
-respects existing overrides. If the decorator chain doesn't claim the
+respects existing class-level overrides. If the decorator chain doesn't claim the
 message, `super` is called and lookup proceeds normally.
 
 #### Unloadable decorators
@@ -205,10 +211,10 @@ Decorators can be unloaded, if necessary:
 
 ```ruby
 @bob.decorate(IsTheMole)
-@bob.revoke_security_clearances 
 
-class IsTheMole < Decorum::Decorators
-  # callback
+# meanwhile:
+class IsTheMole < Decorum::Decorator
+  # hook method
   def post_decorate
     object.revoke_security_clearances
   end
@@ -219,6 +225,8 @@ class IsTheMole < Decorum::Decorators
   end
 end
 ```
+This example also shows the use of the `#post_decorate` hook.
+
 
 ### Implementation
 
@@ -243,7 +251,7 @@ by including Decorum::Decorations, or for a single object, by extending it.
 Decorum::Decorations at whatever point(s) of the class hierarchy you
 feel appropriate.
 
-### Helpers
+### Using Decorators
 The decorated object is accessible as either `#root` or `#object`. A helper method:
 
 ```ruby
@@ -299,6 +307,31 @@ object; this shared state can be used for a number of purposes. Finally,
 `default_attributes` lets you set class-level defaults; these will be
 preempted by options passed to the constructor.
 
+#### Specifying decorators in classes
+
+Decoration may be performed by the instance method `#decorate` above,
+or you can include default decorators and arguments in your class
+definition:
+
+```ruby
+class Coffee
+  include Decorum::Decorations
+  # two bovine dairy no sugar by default, please:
+  decorators Milk, { animal: "cow" }, Milk, { animal: "cow" }
+  ...
+end
+
+c = Coffee.new
+c.load_decorators_from_class
+c.add_milk
+c.milk_level # ==> 2
+```
+
+Note that this usage does _not_ automatically include decorators on new
+objects. That would require invasive procedures on your object initialization.
+Instead, Decorum provides `#load_decorators_from_class`, which you can call 
+in your initializations, or later.
+
 As a side note, you can disable another decorators methods thus:
 
 ```ruby
@@ -334,7 +367,7 @@ other things:
 
 And so on. 
 
-### `#decorated_tail`
+### #decorated_tail
 
 How exactly did the first MilkDecorator pass `#add_milk`
 down the chain instead of returning? In general, the decision

data/lib/decorum/decorations.rb

@@ -1,5 +1,36 @@
 module Decorum
   module Decorations
+    def self.included(modyool)
+      # class method to declare default decorators
+      def modyool.decorators(*args)
+        # set first-listed priority
+        if args[0] == :reverse
+          return @_decorum_stack_reverse = true
+        end
+
+        @_decorum_stack ||= []
+
+       if !args.empty? 
+          args.each do |arg|
+            if (arg.is_a?(Class) && arg.ancestors.include?(Decorum::Decorator)) || arg.is_a?(Hash)
+              next if arg.is_a?(Hash)
+              klass     = arg
+              next_arg  = args[args.index(arg) + 1]
+              options   = next_arg.is_a?(Hash) ? next_arg : {}
+              @_decorum_stack << [klass, options]
+            else
+              raise ArgumentError, "invalid argument to #{self.to_s}.decorate_with: #{arg.to_s}"
+            end
+          end
+        else
+          @_decorum_stack_reverse ? @_decorum_stack.reverse : @_decorum_stack
+        end
+      end 
+    end
+  
+    # public instance methods
+
+
     def decorate(klass, options={})
       if namespace_method = options.delete(:namespace)
         decorator = nil
@@ -11,7 +42,7 @@ module Decorum
           end
           namespace.decorate(klass, options) { |d| decorator = d }
         else
-          namespace = Decorum::DecoratorNamespace.new(self)
+          namespace   = Decorum::DecoratorNamespace.new(self)
           namespace.decorate(klass, options) { |d| decorator = d }
           instance_variable_set(:"@_decorum_#{namespace_method}", namespace)
           m = Module.new do
@@ -20,6 +51,7 @@ module Decorum
             end
           end
           extend m
+          _decorator_namespaces << namespace_method
         end
         yield CallableDecorator.new(decorator) if block_given?
       else
@@ -35,13 +67,22 @@ module Decorum
       remove_from_decorator_chain(target)
       self
     end
-
     
+    def is_decorated?
+      ![ decorators, _decorator_namespaces.map { |ns| send(ns).decorators } ].flatten.empty?
+    end
+   
     # returns callable decorators---use this
     def decorators
       _decorators.map { |d| CallableDecorator.new(d) }
     end
 
+    # leaving it to you to, say, call this from #initialize
+    def load_decorators_from_class
+      self.class.decorators.each { |decorator_class, options| decorate(decorator_class, options) }
+      self
+    end
+
     # returns raw decorators---don't use this unless
     # you know what you're doing
     def _decorators
@@ -75,6 +116,10 @@ module Decorum
         @_decorated_state
       end
     end
+
+    def _decorator_namespaces
+      @_decorator_namespaces ||= []
+    end
  
     module Decorum::Decorations::Intercept
       def method_missing(message, *args, &block)
@@ -90,11 +135,11 @@ module Decorum
       end
     end
 
-    protected
+    private
 
     def add_to_decorator_chain(klass, options)
       unless klass.ancestors.include?(Decorum::Decorator)
-        raise RuntimeError, "decorator chain needs a Decorator"
+        raise TypeError, "decorator chain needs a Decorator"
       end
 
       if options[:decorator_handle]

data/lib/decorum/version.rb

@@ -1,3 +1,3 @@
 module Decorum
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/spec/support/decorations/class_specified_decorator_one.rb

@@ -0,0 +1,21 @@
+module Decorum
+  module Spec
+    module Decorations
+      class ClassSpecifiedDecoratorOne < Decorum::Decorator
+        attr_accessor :passed_option
+        
+        def one
+          "one"
+        end
+      end
+
+      class ClassSpecifiedDecoratorTwo < ClassSpecifiedDecoratorOne
+        attr_accessor :passed_option
+        
+        def two 
+          "two"
+        end
+      end
+    end
+  end
+end

data/spec/unit/decorations_spec.rb

@@ -6,6 +6,55 @@ describe Decorum::Decorations do
   let(:deco_class_2) { Decorum::Spec::Decorations::SecondDecorator }
   let(:deco_class_3) { Decorum::Spec::Decorations::ThirdDecorator }
 
+  context 'loading decorators from class defaults' do
+    let(:klass) do 
+      Class.new do
+        include Decorum::Decorations
+        decorators Decorum::Spec::Decorations::ClassSpecifiedDecoratorOne, { passed_option: "one" },
+          Decorum::Spec::Decorations::ClassSpecifiedDecoratorTwo, { passed_option: "two" }
+      end
+    end
+
+    describe '.decorators' do
+      it 'stores decorators in own state correctly' do
+        expect(klass.decorators.map { |d| d[0].ancestors.include?(Decorum::Decorator) }.inject(:&)).to be_true
+      end
+
+      # the instance method #load_decorators_from_class will insert them in the order given:
+      
+      it 'normally gives first priority to last listed' do
+        expect(klass.decorators.map { |d| d[1] } == [{ passed_option: "one" }, { passed_option: "two" }]).to be_true
+      end
+
+      it 'reverses order for first-specfied priority' do
+        klass.decorators :reverse
+        expect(klass.decorators.map { |d| d[1] } == [{ passed_option: "two" }, { passed_option: "one" }]).to be_true
+      end
+
+      it 'rejects malformed options' do
+        expect { klass.decorators(Decorum::Spec::Decorations::FirstDecorator, "invalid decorator argument") }.to raise_error
+      end
+
+      # this probably belongs with other instance methods below, but we've got the 
+      # support objects built for it here...
+      describe '#decorators' do 
+        let(:obj) { klass.new.load_decorators_from_class }
+        it 'returns self' do
+          # sort of
+          expect(obj.is_a?(klass)).to be_true
+        end
+
+        it 'loads all decorators given by .decorators' do
+          expect(obj.one == "one" && obj.two == "two").to be_true
+        end
+
+        it 'loads decorators in the order given by .decorators' do
+          expect(obj.passed_option == "two").to be_true
+        end
+      end
+    end
+  end
+
   context 'as-yet-undecorated' do 
     # assert some basic assumptions
     it 'is decoratable' do
@@ -20,6 +69,12 @@ describe Decorum::Decorations do
       expect(decorated.undecorated_method).to be_true
     end
 
+    describe '#is_decorated?' do
+      it 'is false' do
+        expect(decorated.is_decorated?).to be_false
+      end
+    end
+
     describe '#decorated_state' do
       it 'returns a hash' do
         blank_state = decorated.decorated_state
@@ -41,7 +96,7 @@ describe Decorum::Decorations do
         expect(decorated.undecorate(:symbol_arg)).to be_equal(decorated)
       end
 
-      it 'returns self on spurious Decorator' do
+      it 'returns self on spurious decorator' do
         expect(decorated.undecorate(deco_class_1)).to be_equal(decorated)
       end
     end
@@ -71,6 +126,17 @@ describe Decorum::Decorations do
           decorated.decorate(deco_class_1, decorator_options)
         end
 
+        describe '#is_decorated?' do
+          it 'returns true' do
+            expect(decorated.is_decorated?).to be_true
+          end
+          
+          it 'returns false after unloading' do
+            decorated.undecorate(decorated.decorators.first)
+            expect(decorated.is_decorated?).to be_false
+          end
+        end
+            
         it 'installs intercept' do
           expect(decorated.is_a?(Decorum::Decorations::Intercept)).to be_true
         end
@@ -127,7 +193,7 @@ describe Decorum::Decorations do
 
       context 'failure' do
         it 'rejects classes that are not Decorators' do
-          expect { decorated.decorate(Class,{}) }.to raise_error(RuntimeError)
+          expect { decorated.decorate(Class,{}) }.to raise_error(TypeError)
         end
 
         it 'rejects non unique decorator handles' do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: decorum
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-02-04 00:00:00.000000000 Z
+date: 2014-12-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -95,6 +95,7 @@ files:
 - spec/integration/immediate_methods_spec.rb
 - spec/spec_helper.rb
 - spec/support/decorated_state/shared_state_stub.rb
+- spec/support/decorations/class_specified_decorator_one.rb
 - spec/support/decorations/decorated_object_stub.rb
 - spec/support/decorations/first_decorator.rb
 - spec/support/decorations/second_decorator.rb
@@ -144,6 +145,7 @@ test_files:
 - spec/integration/immediate_methods_spec.rb
 - spec/spec_helper.rb
 - spec/support/decorated_state/shared_state_stub.rb
+- spec/support/decorations/class_specified_decorator_one.rb
 - spec/support/decorations/decorated_object_stub.rb
 - spec/support/decorations/first_decorator.rb
 - spec/support/decorations/second_decorator.rb