five-star 0.1.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f0ec61a85ec090995b6030203a9b8808e85ff27e
-  data.tar.gz: a21d6768ecb083c34b4b103d78100f2095d726dc
+  metadata.gz: d5343fe7238068fb78cb53e3fc86339774633348
+  data.tar.gz: 167c1f8ec30362080420cffde1c5b3025d98dde4
 SHA512:
-  metadata.gz: ca8a6fdb9c2f2fd00d25ea31ca507fafa6cd69c0c9eb3bbe7d3509f368b67a35329012be76909f56a71defb91be16a3d35358eed729e8623a7d586466f810aa2
-  data.tar.gz: b1734c47ace30591629843cc41dfda108c2671e13cf2c15831972659db6b55025a5c5f74b869e76dfd815f4438a539e250bf1cf7bc9d202799836d054d4595f1
+  metadata.gz: 6250ef18663aa9959dd415678b633cb2cac036c59c6d18048532b01deedebbcb4e7d68619f7d7b3768e95e2b85791e2f71fd69e819adcbffd50b5d76c3b4e1e1
+  data.tar.gz: 045e580ca96472802d7d4b1fee0059db2211a7a5a041cff4bbd630b37a07896a759a3eaf7bbbdc9c45fc5ad90ce600e3468c7076c22475bd12932a556cd2e7f3

data/.travis.yml

@@ -1,4 +1,5 @@
 language: ruby
+sudo: false
 rvm:
   - 2.0
   - 2.1

data/README.md

@@ -8,7 +8,7 @@
 
 :star: **FiveStar** :star: is a library to build a rating system - it allows you to rate *something* in your domain by various classification or criteria you define. This library gives you the structure to rate your object with as many of these different classifications as you like with the overall rating calculated from the weighted average.
 
-This uses *Plain Old Ruby Objects* so can be used in any project.
+This gem uses *Plain Old Ruby Objects* so it can be used in any project.
 
 
 ## Example
@@ -70,7 +70,7 @@ class SwearingRater < FiveStar.base_rater
 end
 
 film = Film.new
-film.rating # => 6
+film.rating # => 6.0
 film.rating_descriptions # => ["The film Alien was rated 8 for gore", ...]
 
 ```
@@ -123,7 +123,7 @@ class Film
 end
 
 film = Film.new
-film.rating # => 6
+film.rating # => 6.0
 film.rating_descriptions # => ["The film Alien was rated 8 for gore", ...]
 ```
 
@@ -165,7 +165,7 @@ end
 
 The calculation used will be a weighted average based on each rating and the weighting defined in that class. If weighting is not required then all will be use the default value (of 1.0) and therefore be weighted the same, this being just a normal mean average calculation.
 
-The default rating scale used is 0 - 10 as floating point numbers although this can be overriden and customised.
+The default rating scale used is 0 - 10 as floating point numbers although this can be customised.
 
 
 ## Development
@@ -176,7 +176,7 @@ 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]/five-star. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at https://github.com/rob-murray/five-star. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](contributor-covenant.org) code of conduct.
 
 
 ## License

data/lib/five-star.rb

@@ -1,18 +1,19 @@
 require "five-star/version"
 require "five-star/base_rater"
+require "five-star/configuration"
 require "five-star/rateable"
+require "five-star/errors"
 require "five-star/rating_calculator"
 
 # Base module for library interface
 module FiveStar
   class << self
     # Include this in your class that can be rated - this is your domain model
-    #   object that has various attributes that you need rated.
+    # object that has various attributes that you need rated.
     # Being +rateable+ is defined as an object that has attributes on which a
-    #   rating can be calculated based on varying attributes of that model.
+    # rating can be calculated based on varying attributes of that model.
     #
     # This adds the public class and instance methods from the Rateable module.
-    # See FiveStar::Rateable
     #
     # @example
     #   class Film
@@ -22,6 +23,8 @@ module FiveStar
     #     # ...
     #   end
     #
+    # @see FiveStar::Rateable
+    #
     # @return [Class]
     #
     # @api public
@@ -30,15 +33,14 @@ module FiveStar
     end
 
     # The base class of a class that gives a rating and weighting to something
-    #   that is rateable. See FiveStar.rateable.
+    # that is rateable. See FiveStar.rateable.
     #
     # This implements the interface necessary to calculate a rating for the
-    #   rateable instance. At a minium this must be +build+, +rating+,
-    #   +description+ and +weighting+.
+    # rateable instance. At a minimum this must be +build+, +rating+,
+    # +description+ and +weighting+.
     #
     # The method +build+ *will* be called on each class with the argument of
-    #   the instance being rated.
-    # See FiveStar::BaseRater
+    # the instance being rated.
     #
     # @example
     #   class GoreRater < FiveStar.base_rater
@@ -53,6 +55,8 @@ module FiveStar
     #     end
     #   end
     #
+    # @see FiveStar::BaseRater
+    #
     # @return [Class]
     #
     # @api public

data/lib/five-star/base_rater.rb

@@ -1,26 +1,24 @@
 module FiveStar
   # Base implementation of a class to give a rating, weighting and description
-  #   to a +rateable+ instance.
+  # to a +rateable+ instance.
   #
-  # Default implementation is defined below, users should override methods
-  #   with their own implementation.
+  # You are *expected* to subclass this class and override the default
+  # implementation with your own implementation.
   class BaseRater
-    # Called to build a new instance of the rater with the given object
-    #   being rated.
+    # Called to build a new instance of the rater with the given object being rated.
     #
     # @param [Object] rateable
     #   the instance of the Object being rated
     #
-    # @return [Object] the instance created ready to rate
+    # @return [Object] the instance of Rating class created ready to be used
     #
     # @api public
     def self.build(rateable)
       new(rateable)
     end
 
-    # Set the weighting for this rating classifcation class. This can be any
-    #   valid floating point number at present, the weighting system is up to
-    #   the user to ensure correct.
+    # Set the weighting for this rating classifcation class. This should
+    # a valid floating point within the scale configured.
     #
     # @example
     #   class GoreRater < FiveStar.base_rater
@@ -41,11 +39,11 @@ module FiveStar
     # Return the weighting value for this rating classifcation class.
     #
     # @return [Float]
-    #   the weighting value
+    #   the weighting value. Defaults to 1.0
     #
     # @api public
     def self.weighting
-      @weighting ||= 1.0
+      @weighting ||= Configuration::DEFAULT_WEIGHTING
     end
 
     # Create a new instance of rater
@@ -58,9 +56,9 @@ module FiveStar
       @rateable = rateable
     end
 
-    # Return the rating description for the rater given to the `rateable`
-    #   object.
-    # Override to customise this message.
+    # Return the rating description for the rater given to the +rateable+
+    # object.
+    # Override this method to customise the message.
     #
     # @example
     #   class GoreRater < FiveStar.base_rater
@@ -80,11 +78,11 @@ module FiveStar
       "#{self.class} rated #{rateable_name} at #{rating} with weighting of #{weighting}"
     end
 
-    # Return the rating for the rater given to the `rateable` object.
-    # Override this method to perform your own calculation for the rating based
-    #   on your own criteria. If this is an expensive operation then the result
-    #   should be cached as this method *can* be called more than once, for
-    #   example by the +description+ method.
+    # Return the rating for the rater given to the +rateable+ object.
+    # You are *expected* to override this method to perform your own calculation
+    # for the rating based on your own criteria. If this is an expensive
+    # operation then the result should be cached as this method *can* be
+    # called more than once, for example by the +description+ method.
     #
     # @example
     #   class GoreRater < FiveStar.base_rater
@@ -104,12 +102,15 @@ module FiveStar
     #
     #   rater.rating # => 6
     #
-    # @return [Float] the rating value
-    #   defaults to 0 unless overridden
+    # @raise [FiveStar::RatingError] raises error if any raters return either
+    #   +rating+ or +weighting+ that is outside of configuration bounds.
+    #
+    # @return [Float] the rating value calculated.
+    #   Defaults to minimum rating value unless overridden
     #
     # @api public
     def rating
-      0
+      configuration.min_rating
     end
 
     # Return the weighting value for this rating classifcation class.
@@ -127,27 +128,29 @@ module FiveStar
     attr_reader :rateable
 
     # Return the maximum weighting value for this rating classifcation class.
+    # By default this comes from the instance of FiveStar::Configuration used.
     #
     # Override if required - this should be the same for each rater class.
     #
     # @return [Fixnum]
-    #   the maximum rating value.
+    #   the maximum rating value from configuration.
     #
     # @api protected
     def max_rating
-      10
+      configuration.max_rating
     end
 
     # Return the minimum weighting value for this rating classifcation class.
+    # By default this comes from the instance of FiveStar::Configuration used.
     #
     # Override if required - this should be the same for each rater class.
     #
     # @return [Fixnum]
-    #   the minimum rating value.
+    #   the minimum rating value from configuration.
     #
     # @api protected
     def min_rating
-      0
+      configuration.min_rating
     end
 
     # Return the name of the given rateable instance.
@@ -157,7 +160,17 @@ module FiveStar
     #
     # @api protected
     def rateable_name
-      rateable.name
+      rateable.rateable_name
+    end
+
+    # The current configuration instance for the given +rateable+ object.
+    #
+    # @return [FiveStar::Configuration]
+    #   the instance of configuration described by the +rateable+ class.
+    #
+    # @api protected
+    def configuration
+      rateable.configuration
     end
   end
 end

data/lib/five-star/configuration.rb

@@ -0,0 +1,14 @@
+module FiveStar
+  # Default configuration of rating values and weighting.
+  #
+  # @api private
+  class Configuration
+    DEFAULT_WEIGHTING = 1.0.freeze
+
+    def min_rating; 0.0; end
+    def max_rating; 10.0; end
+
+    def min_weighting; 0.0; end
+    def max_weighting; 1.0; end
+  end
+end

data/lib/five-star/errors.rb

@@ -0,0 +1,5 @@
+module FiveStar
+  # Exception raised when error calculating occurs.
+  #
+  RatingError = Class.new(StandardError)
+end

data/lib/five-star/rateable.rb

@@ -1,10 +1,10 @@
 module FiveStar
-  # A module to be included to enhance an object with the interface below
+  # A module to be included to enhance an object with the interface below.
   module Rateable
     # Extends base class or a module with Rateable methods
     #
-    # @param [Object] object
-    #   the object to mix in this +Rateable+ module
+    # @param base [Object]
+    #   the object to mix in this *Rateable* module
     #
     # @return [undefined]
     #
@@ -15,7 +15,7 @@ module FiveStar
 
     module ClassMethods
       # Set which rating classes will be used to rate the object
-      #  using this module.
+      # using this module.
       # Each class must implement the rater methods, see FiveStar::BaseRater
       #
       # @example
@@ -26,20 +26,20 @@ module FiveStar
       #      # ...
       #    end
       #
-      # @param [Class] *klasses
+      # @param klasses [Class]
       #   constants referencing classes to rate object included with
       #
       # @return [undefined]
       #
-      # @see FiveStar.rateable
+      # @see FiveStar::BaseRater
       #
       # @api public
       def rate_with(*klasses)
         @rating_klasses = Array(klasses)
       end
 
-      # Define which rating classes will be used to rate the object
-      #  using this module.
+      # Return which rating classes will be used to rate the object
+      # using this module.
       #
       # @return [Array] list of classes to rate with
       #
@@ -49,26 +49,40 @@ module FiveStar
       def rating_klasses
         @rating_klasses ||= []
       end
+
+      # Reference to Configuration used for this +rateable+ instance.
+      #
+      # @return [FiveStar::Configuration] Configuration instance in use
+      #
+      # @see FiveStar::Configuration
+      #
+      # @api private
+      def configuration
+        @configuration ||= Configuration.new
+      end
     end
 
-    # Return the rating given to the `rateable` object by calculating based on
-    #   set raters and their configuration.
+    # Return the rating given to the +rateable+ object by calculating based on
+    # set raters and their configuration.
     #
     # @example
     #    film = Film.new
-    #    film.rating # => 6
+    #    film.rating # => 6.0
     #
     # @return [Float] rating calculated by set raters for the object
     #
+    # @raise [FiveStar::RatingError] raises error if any raters return either
+    #   +rating+ or +weighting+ that is outside of configuration bounds.
+    #
     # @api public
     def rating
-      rating_calculator.rate(raters)
+      rating_calculator.rate(self.class.configuration, raters)
     end
 
-    # Return the rating description for each rater given to the `rateable`
-    #   object.
+    # Return the rating description for each rater given to the +rateable+
+    # object.
     # These are returned in the order in which the rating classes were
-    #   defined in `rate_with`.
+    # defined in +rate_with+.
     #
     # @example
     #    film = Film.new
@@ -81,18 +95,26 @@ module FiveStar
       raters.map { |rater| rater.description }
     end
 
-    # The name of the object that is rateable. This may be used by raters
-    #   when generating descriptions.
-    # This can be overridden to provide a better response, otherwise is the class
-    #   name.
+    # The name of the object that is rateable. This may be used by raters when
+    # generating descriptions.
+    # This can be overridden to provide a better response, otherwise is the class name.
     #
     # @return [String] name of the class
     #
     # @api public
-    def name
+    def rateable_name
       self.class.name
     end
 
+    # Reference to Configuration used for this +rateable+ instance. Delegates to class.
+    #
+    # @return [FiveStar::Configuration] Configuration instance in use
+    #
+    # @api private
+    def configuration
+      self.class.configuration
+    end
+
     protected
 
     # The instance that included this module

data/lib/five-star/rating_calculator.rb

@@ -1,37 +1,83 @@
 module FiveStar
   # Calculate overall rating for the rateable object from each rater.
-  #   Each instance must implement `rating` and `weighting`.
+  # Each instance must implement +rating+ and +weighting+.
+  # The configuration instance provides min and max rating and weighting values.
+  #
   # @api private
   class RatingCalculator
-    def self.rate(raters)
-      new(raters).calculate_rating
+    # @see calculate_rating
+    def self.rate(configuration, raters)
+      new(configuration, raters).calculate_rating
     end
 
-    def initialize(raters)
+    def initialize(configuration, raters)
+      @configuration = configuration
       @raters = raters
     end
 
     # Calculate the overall weighting from each rating class
     #
     # @return [Float] the calculated rating
+    #    The min rating will be returned if there are no raters.
+    #
+    # @raise [FiveStar::RatingError] raises error if any raters return either
+    #   +rating+ or +weighting+ that is outside of configuration bounds.
     #
     # @api private
     def calculate_rating
-      return 0 unless raters.any?
+      return min_rating unless raters.any?
 
-      sum_total / weights_total.to_f
+      sum_total / weights_total
     end
 
     private
 
-    attr_reader :raters
+    attr_reader :raters, :configuration
 
     def sum_total
-      raters.map { |rater| rater.rating * rater.weighting }.inject(&:+)
+      raters.map { |rater|
+        validate_rating!(rater.rating, rater) * validate_weighting!(rater.weighting, rater)
+      }.reduce(&:+)
     end
 
     def weights_total
-      raters.map(&:weighting).inject(&:+)
+      raters.map(&:weighting).reduce(&:+)
+    end
+
+    def validate_rating!(rating, rater)
+      rating = rating.to_f
+
+      if rating < min_rating || rating > max_rating
+        raise RatingError, "Rating #{rating} is invalid from #{rater.class}"
+      else
+        rating
+      end
+    end
+
+    def validate_weighting!(weighting, rater)
+      weighting = weighting.to_f
+
+      if weighting < min_weighting || weighting > max_weighting
+        raise RatingError, "Weighting #{weighting} is invalid from #{rater.class}"
+      else
+        weighting
+      end
+    end
+
+    def min_rating
+      configuration.min_rating
+    end
+
+    def max_rating
+      configuration.max_rating
+    end
+
+    def min_weighting
+      configuration.min_weighting
+    end
+
+    def max_weighting
+      configuration.max_weighting
     end
   end
 end

data/lib/five-star/version.rb

@@ -1,3 +1,3 @@
 module FiveStar
-  VERSION = "0.1.1"
+  VERSION = "1.0.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: five-star
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Rob Murray
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-12-06 00:00:00.000000000 Z
+date: 2016-01-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -129,6 +129,8 @@ files:
 - five-star.gemspec
 - lib/five-star.rb
 - lib/five-star/base_rater.rb
+- lib/five-star/configuration.rb
+- lib/five-star/errors.rb
 - lib/five-star/rateable.rb
 - lib/five-star/rating_calculator.rb
 - lib/five-star/version.rb