bottled_decorators 0.1.4 → 0.1.5.beta.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e716ded139c4ff28b6f4029c5db454fb438227cf
-  data.tar.gz: e2a14fd0f614b0ad3bd561fbeaefc9f60386babf
+  metadata.gz: 1068d0c42b10129b8bedfb154f11da7bcdde0756
+  data.tar.gz: e60b90f42294d96277e394d77a7e6647991649db
 SHA512:
-  metadata.gz: 25196e1c60dfee280fbd1062e030b7d883332a66b089204dd2efff1c06f0944169aaeaf62a9c3d525358d391838db7e42d9d744fd59fcdccb4030249aaf36b6c
-  data.tar.gz: d999c5e670f6c11a7c7d25594368c463902fd7afd23550dcd0c08e9f8946df544c434b7b97c6729e085bcbf2340f13dc741510436eb17d4e66fc268e6af6adc8
+  metadata.gz: b3cea6e900b254ae28a34626fba8e1e938493d9105a1d5c50c6bbff950686a451e8ef8478c0e73c1dc602450ed28331c4e8b2c2a54c5955ddf7e3b96bc97c548
+  data.tar.gz: bb0e8a2148394e1aeaa679f99b5b5852e8312e11243400b25f7fa1ed6f2a18f270f547a10955da88afefcdb7937a5496603ab4cb84c4f6ebda6624f6dbab6794

data/.gitignore

@@ -7,3 +7,5 @@
 /pkg/
 /spec/reports/
 /tmp/
+
+.rvmrc

data/README.md

@@ -3,7 +3,7 @@
 ## The best thing to happen since bottled water
 
 Wait a minute, I thought that was [bottled_services?](https://github.com/John-Hayes-Reed/bottled_services), well nevermind.
-bottled_decorators are here to make your life easier, and provide decorators that are actually decorators and not just View Objects / View Helpers with the name 'decorator'. bottled_decorators encourage the use of DRY and reusable code by stopping the direct model relation, and 'my job is to prepare something for the view' mentality seen in some gems and implementations, and to bring decorators back to what they should be, a reusable and stackable extra layer of functionality.  
+bottled_decorators are here to make your life easier, and provide decorators that are actually decorators and not just View Objects / View Helpers with the name 'decorator'. bottled_decorators encourage the use of DRY and reusable code by stopping the direct model relation and 'my job is to prepare something for the view' mentality seen in some gems and implementations, and to bring decorators back to what they should be, a reusable and stackable extra layer of functionality to be used **anywhere** and not just in views.
 Creating your decorators are also as easy as pie with the botted_decorator generator. All you need to worry about is your method logic, let bottled_decorators do the rest for you!
 
 ## Installation
@@ -24,7 +24,180 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+#### Giving birth to decorators
+
+Creating new decorators is as easy as pie with the BottledDecorator Generator.
+just add the decorator name, and if you want the decorator methods, to the generator command:
+
+```
+rails g bottled_decorator LargeFoodItem
+```
+
+```
+rails g bottled_decorator PiratizedUser name greeting
+```
+
+Just like that we have two new decorators ready for use, a currently empty decorator for decorating food as large food items, and a decorator with two methods prepared for us, name and greeting, that decorates users with pirate like behaviour.
+
+#### Decorator Methods
+
+A possible implementation of the two decorators we generated above could be:
+
+```ruby
+class LargeFoodItem
+  include BottledDecorator
+
+  # A large food item has 50 cents added onto its cost
+  def cost
+    super + 50
+  end
+
+end
+```
+```ruby
+class PiratizedUser
+  include BottledDecorator
+
+  # Pirates all dream of being the captain of their own ship
+  def name
+    "Cap'n #{super}"
+  end
+
+  # And its a well studied fact that Rum is a pirates poison of choice
+  def greeting
+    "Yo ho ho and a bottle of rum!"
+  end
+
+end
+```
+
+#### A Decorator's first steps
+
+Once generated, the next things to do is decorate loads of stuff!
+
+Unlike some other implementations of decorators (many of which I dare to say are not actually decorators but just View Objects / Helpers that are hijacking the word *decorator*), BottledDecorators do not use an extension style of decorating. Instead they wrap up our objects in a lovely cosy blanket of decoration:
+
+```ruby
+pirate_user = PiratizedUser.(@user)
+
+# or
+
+@large_burger = LargeFoodItem.(burger)
+```
+
+You can also wrap a collection, to get an Array of decorated objects:
+
+```ruby
+@pirates = PiratizedUser.(@users)
+# returns an Array
+```
+
+As can be seen above, this wrapping is done using the decorator class' `::call` method, so a simple `.()` will suffice to get the job done, or any other preferred choice of envoking the call method.
+
+#### Bottled Decorators in action
+
+Once we have our decorated object, its just a case of invoking your methods:
+
+```ruby
+@user.name
+# => "John Hayes-Reed"
+@user.age
+# => 27
+
+@user = PiratizedUser.(@user)
+@user.name
+# => "Cap'n John Hayes-Reed"
+@user.greeting
+# => "Yo ho ho and a bottle of rum!"
+
+# of course we can still access the components original methods as well
+@user.age
+# => 27
+```
+
+Because BottledDecorators wrap instead of extend, we can also keep wrapping on multiple layers, adding on functionality to overridden methods indefinately, because each layer looks at its own component for its `super`, and not the original instance:
+
+```ruby
+class DrunkUser
+  include BottledDecorator
+
+  def name
+    "#{super}, the drunkard!"
+  end
+
+  def greeting
+    "#{super} (hiccup)"
+  end
+end
+```
+
+```ruby
+@user.name
+# => "John Hayes-Reed"
+
+@user = PiratizedUser.(@user)
+@user.name
+# => "Cap'n John Hayes-Reed"
+@user.greeting
+# => "Yo ho ho and a bottle of rum!"
+
+@user = DrunkUser.(@user)
+@user.name
+# => "Cap'n John Hayes-Reed, the drunkard!"
+@user.greeting
+# => "Yo ho ho and a bottle of rum! (hiccup)"
+```
+
+Because of this layering ability, we can use a single decorator to represent multiple possible states of objects:
+
+```ruby
+# a regular burger
+@burger.cost
+# => 100
+
+# a large burger
+LargeFoodItem.(@burger).cost
+# => 150
+
+# an extra large burger
+LargeFoodItem.(LargeFoodItem.(@burger)).cost
+# => 200
+
+# SUPERSIIIIIZE
+LargeFoodItem.(LargeFoodItem.(LargeFoodItem.(@burger))).cost
+# => 250
+```
+
+This can be done with multiple decorators to build up the cost of a whole variety of possibilites:
+
+```ruby
+class WithDrink
+  include BottledDecorator
+
+  def cost
+    super + 15
+  end
+
+end
+```
+
+```ruby
+# a regular burger
+@burger.cost
+# => 100
+
+# with a side order drink
+WithDrink.(@burger).cost
+# => 115
+
+# a large burger with a side order drink
+LargeFoodItem.(WithDrink.(@burger)).cost
+# => 165
+```
+
+#### Extras
+
+Currently BottledDecorators come with a few serializer methods and checker methods to add all decorated methods onto the converted object as well, currently supported are `#to_json`, `#as_json`, `#to_h`, `#respond_to?`, each of which will drill down through each component layer all the way to the root component to provide / access the whole scope available.
 
 ## Development
 
@@ -34,10 +207,11 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/bottled_decorators. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+All and any contributions to improve Bottled Decorators and make them useful for as many people as possible are gratefully welcomed. I hope all contributions can keep in line with the philosophy of Bottled Technology, which is to make simple and easy-to-use tools.
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/John-Hayes-Reed/bottled_decorators. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
-

data/bottled_decorators.gemspec

@@ -21,6 +21,6 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency "railties"
   spec.add_development_dependency "bundler", "~> 1.13"
-  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rake", "~> 12.0"
   spec.add_development_dependency "rspec", "~> 3.0"
 end

data/lib/bottled_decorators/bottled_decorator.rb

@@ -1,33 +1,81 @@
+# Public: A module to turn classes into bottled decorators, for the decorator
+# design pattern, wrapping a component with new functionality, while still
+# allowing the original functionality and access for the wrapped component.
 module BottledDecorator
-
+  # Internal: Runs when the module is included, makes the including class extend
+  # The ClassMethod module below to include a class ::call method.
+  #
+  # Returns nothing.
   def self.included(base)
     base.extend(ClassMethods)
   end
 
+  # Internal: initializes a new decorator instance. Sets the component and
+  # options attibutes and reader methods for each.
+  #
+  # Returns nothing.
   def initialize(component, **options)
     class << self
       attr_reader :component
     end
     @component = component
     options.each do |option_key, option_val|
-      self.instance_variable_set("@#{option_key}", option_val)
+      (class << self; self; end).class_eval { attr_reader option_key }
+      self.instance_variable_set(:"@#{option_key}", option_val)
     end
   end
 
+  # Internal: Sends any method requests unknown to the decorator back down to
+  # the component. This allows the wrapped instances to still use the inner
+  # components methods as if they were being called on the original component
+  # before wrapping.
+  #
+  # Examples
+  #
+  #   @user.name
+  #   # => 'John'
+  #   @decorated_user = ExampleDecorator.call @user
+  #   @decorated_user.name
+  #   # => 'John'
   def method_missing(method, *args)
     return @component.send(method, *args)
   rescue NoMethodError => e
     raise NoMethodError.new("Method #{method} was not found in the decorator, or the decorated objects", 'NoMethodError')
   end
 
+  # Public: Takes the decorated component and serializes it into a JSON format
+  # by combining its original attributes and the decorated methods from the
+  # wrapping decorator class.
+  #
+  # Returns a JSON object representation of the decorated component.
   def as_json(**args)
     to_h(**args).as_json
   end
 
+  # Public: Takes the decorated component and serializes it into a JSON format
+  # by combining its original attributes and the decorated methods from the
+  # wrapping decorator class.
+  #
+  # Returns a JSON object representation of the decorated component.
   def to_json(**args)
     to_h(**args).to_json
   end
 
+  # Public: Takes the decorated component and serializes it into a Hash format
+  # by combining its original attributes and the decorated methods from the
+  # wrapping decorator class.
+  #
+  # Examples
+  #
+  #   @user.to_h
+  #   # => { first_name: 'John', last_name: 'Hayes-Reed' }
+  #   @decorated_user = FullNameDecorator.call @user
+  #   @decorated_user.to_h
+  #   # => { first_name: 'John',
+  #          last_name: 'Hayes-Reed',
+  #          full_name: 'John Hayes-Reed' }
+  #
+  # Returns a Hash object representation of the decorated component.
   def to_h(**args)
     {}.tap do |hash|
       if @component.respond_to?(:component)
@@ -41,13 +89,69 @@ module BottledDecorator
     end
   end
 
+  # Public: checks if either the decorator class, or the decorated component
+  # Responds to a method.
+  #
+  # Examples
+  #
+  #   @user.respond_to? :name
+  #   # => true
+  #   @user.respond_to? :full_name
+  #   # => false
+  #
+  #   @decorated_user = FullNameDecorator.call @user
+  #   @decorated_user.respond_to? :name
+  #   # => true
+  #   @decorated_user.respond_to? :full_name
+  #   # => true
   def respond_to?(tester)
     response = @component.respond_to?(tester)
     return true if response
     self.class.instance_methods(false).map(&:to_s).include?("#{tester}")
   end
 
+  # Public: Uses the decorated components #to_param method as its own. This
+  # allows for the natural use of decorated objects in things like Rails url
+  # helper methods.
+  #
+  # Returns the components parameter attibute. (eg: id).
+  def to_param
+    @component.to_param
+  end
+
+  # Public: Gets the root component in the case of multiple wrapped components
+  # by first searching if the current decorators component itself holds a
+  # component.
+  #
+  # Examples
+  #
+  #   decorated_user.root_component
+  #   # => #<User:00x0...>
+  #
+  # Returns whichever is the lowest component in the stack.
+  def root_component
+    return @component.root_component if @component.respond_to? :component
+    @component
+  end
+
+  # Internal: Allows methods found in the decorator, as well as methods found
+  # in the original decorated component to be recognised by #method method.
+  #
+  # Returns a Method object if found.
+  private def respond_to_missing?(method, include_private = false)
+    @component.respond_to?(method) ||
+      self.class.instance_methods(false).map(&:to_s).include?(method.to_s) ||
+      super
+  end
+
+  # Internal: The class methods to be added to the decorator class when
+  # including this module. Adds a class ::call method.
   module ClassMethods
+    # Public: instantiates a new decorator class instance, creates an Array
+    # of instances if the first argument (the component), is an iterable
+    # group of objects.
+    #
+    # Returns a decorated object, or an Array of decorated objects.
     def call(*args)
       if args.first.respond_to?(:each)
         [].tap do |arr|
@@ -60,5 +164,4 @@ module BottledDecorator
       end
     end
   end
-
 end

data/lib/bottled_decorators/version.rb

@@ -1,3 +1,3 @@
 module BottledDecorators
-  VERSION = "0.1.4"
+  VERSION = "0.1.5.beta.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bottled_decorators
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5.beta.1
 platform: ruby
 authors:
 - John_Hayes-Reed
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-02-06 00:00:00.000000000 Z
+date: 2017-04-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -44,14 +44,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '12.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '12.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -104,12 +104,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.6.10
 signing_key: 
 specification_version: 4
 summary: The easiest way to make decorators, the way they are supposed to be.