galvinhsiu-active_cart 0.0.19

data/galvinhsiu-active_cart.gemspec

@@ -0,0 +1,21 @@
+Gem::Specification.new do |s|
+  s.name = 'galvinhsiu-active_cart'
+  s.summary = "Shopping Cart framework gem. Supports 'storage engines' and order total plugins, forked to use state_machine from active_cart."
+  s.description = <<-EOS
+    You can use active_cart as the basis of a shopping cart system. It's not a shopping cart application - it's a shopping cart framework.
+  EOS
+  s.email = 'myles@madpilot.com.au, galvinhsiu@gmail.com'
+  s.homepage = "http://gemcutter.org/gems/galvinhsiu-active_cart"
+  s.authors = ["Myles Eftos", "Galvin Hsiu"]
+  s.version = '0.0.19'
+
+  s.require_paths = ['lib']
+
+  s.add_dependency 'state_machine'
+  s.add_development_dependency 'shoulda'
+  s.add_development_dependency 'mocha'
+  s.add_development_dependency 'machinist'
+  s.add_development_dependency 'faker'
+
+  s.files = Dir['lib/**/*', 'galvinhsiu-active_cart.gemspec']
+end

data/lib/active_cart/cart.rb

@@ -0,0 +1,189 @@
+module ActiveCart
+  # The Cart class is the core class in ActiveCart. It is a singleton (so you can only have one cart per application), that gets setup initially by passing in
+  # a storage engine instance. Storage engines abstract away the storage of the cart, and is left as an exercise to the user. See the Storage engine docs
+  # for details.
+  #
+  # The Cart class also takes order_total objects, which will calculate order totals. it may include thinkgs like shipping, or gift vouchers etc. See the Order Total
+  # docs for details.
+  #
+  # The Cart object delegates a number of Array methods:
+  # :[], :<<, :[]=, :at, :clear, :collect, :map, :delete, :delete_at, :each, :each_index, :empty?, :eql?, :first, :include?, :index, :inject, :last, :length, :pop, :push, :shift, :size, :unshift
+  #
+  # The CartEngine object uses a state machine to track the state of the cart. The default states are: shopping, checkout, verifying_payment, completed, failed. It exposed the following transitions:
+  # continue_shopping, checkout, check_payment, payment_successful, payment_failed
+  #
+  #   @cart.checkout! # transitions from shopping or verifying_payment to checkout
+  #   @cart.check_payment! # transistions from checkout to verifying_payment
+  #   @cart.payment_successful! # transitions from verifying_payment to completed
+  #   @cart.payment_failed! # transitions from verifying_payment to failed
+  #   @cart.continue_shopping! # transitions from checkout or verifying_payment to shopping
+  #
+  class Cart
+    attr_accessor :storage_engine, :order_total_calculators, :customer
+    include Enumerable
+    
+    # You need to supply a storage engine. An optional block can be given which allows you to add order total items.
+    #
+    # A typical initialization block might look like this
+    #
+    #   @cart = Cart.new(MyAwesomeStorageEngine.new) do |o|
+    #     o << ShippingOrderTotal.new
+    #     o << GstOrderTotal.new
+    #   end
+    #
+    def initialize(storage_engine, &block)
+      @storage_engine = storage_engine
+      @order_total_calculators = OrderTotalCollection.new(self)
+
+      if block_given?
+        yield order_total_calculators
+      end
+    end
+
+    extend Forwardable
+    # Storage Engine Array delegators
+    # TODO: Consolidate - not all of these make sense, and some need overriding so they take the callbacks into account
+    # 
+    # Candidates for removal:
+    #   delete_at
+    #   delete_if
+    #   []=
+    #   replace
+    #   insert
+    #   shift
+    #   unshift
+    #   pop
+    #
+    # Aliases
+    #   delete => remove_from_cart(obj, 1)
+    #   << => add_to_cart(obj, 1)
+    #   push => add_to_cart(obj, 1)
+    #
+    # Overrides
+    #   clear => .each { |obj| self.remove_from_cart(obj) }
+    #
+    def_delegators :@storage_engine, :[], :<<, :[]=, :at, :clear, :collect, :map, :delete, :delete_at, :each, :each_index, :empty?, :eql?, :first, :include?, :index, :inject, :last, :length, :pop, :push, :shift, :size, :unshift
+    
+    # Returns a unique id for the invoice. It's upto the storage engine to generate and track these numbers
+    #
+    def invoice_id
+      @storage_engine.invoice_id
+    end
+
+    # Returns the sub-total of all the items in the cart. Usually returns a float.
+    #
+    #   @cart.sub_total # => 100.00
+    #
+    def quantity
+      @storage_engine.quantity
+    end
+
+    # Returns the subtotal of cart, which is effectively the total of all the items multiplied by their quantites. Does NOT include order_totals
+    def sub_total
+      @storage_engine.sub_total
+    end
+
+    # Adds an item to the cart. If the item already exists in the cart (identified by the id of the item), then the quantity will be increased but the supplied quantity (default: 1)
+    #
+    #   @cart.add_to_cart(item, 5)
+    #   @cart.quantity # => 5
+    #
+    #   @cart.add_to_cart(item, 2)
+    #   @cart.quantity # => 7
+    #   @cart[0].size # => 7
+    #   @cart[1] # => nil
+    #
+    #   @cart.add_to_cart(item_2, 4)
+    #   @cart.quantity => 100
+    #   @cart[0].size # => 7
+    #   @cart[1].size # => 4
+    #
+    # Callbacks:
+    #
+    # Calls the storage engines before_add_to_cart(item, quantity) and after_add_to_cart(item, quantity) methods (if they exist). If before_add_to_cart returns false, the add will be halted.
+    # Calls the items before_add_to_item(quantity) and after_add_to_cart(quantity) methods (if they exist). If before_add_to_cart returns false, the add will be halted.
+    #
+    def add_to_cart(item, quantity = 1, options = {})
+      with_callbacks(:add_to_cart, item, quantity, options) do
+        @storage_engine.add_to_cart(item, quantity, options)
+      end
+    end
+
+    # Sets the quantity of an item to the supplied value
+    #
+    #   @cart.add_to_cart(item, 5)
+    #   @cart[0].quantity # => 5
+    #   @cart.update_cart(item, 15)
+    #   @cart[0].quantity # => 15
+    #   @cart.update_cart(item, 2)
+    #   @cart[0].quantity # => 2
+    #
+    def update_cart(item, quantity = 1, options = {})
+      if @storage_engine.include?(item)
+        index = @storage_engine.index(item)
+        diff = quantity - @storage_engine.at(index).quantity
+        
+        if diff < 0
+          return remove_from_cart(item, -1 * diff, options)
+        else
+          return add_to_cart(item, diff, options)
+        end
+      else
+        return add_to_cart(item, quantity, options)
+      end
+    end
+
+    # Removes an item from the cart (identified by the id of the item). If the supplied quantity is greater than equal to the number in the cart, the item will be removed, otherwise the quantity will simply be decremented by the supplied amount
+    #
+    #   @cart.add_to_cart(item, 5)
+    #   @cart[0].quantity # => 5
+    #   @cart.remove_from_cart(item, 3)
+    #   @cart[0].quantity # => 2
+    #   @cart.remove_from_cart(item, 2)
+    #   @cart[0] # => nil
+    #
+    # Callbacks:
+    #
+    # Calls the storage engines before_remove_from_cart(item, quantity) and after_remove_from_cart(item, quantity) methods (if they exist). If before_remove_from_cart returns false, the remove will be halted.
+    # Calls the items before_remove_from_item(quantity) and after_remove_from_cart(quantity) methods (if they exist). If before_remove_from_cart returns false, the remove will be halted.
+    #
+    def remove_from_cart(item, quantity = 1, options = {})
+      with_callbacks(:remove_from_cart, item, quantity, options) do
+        @storage_engine.remove_from_cart(item, quantity, options)
+      end
+    end
+    
+    # Returns the total of the cart. This includes all the order_total calculations
+    #
+    def total
+      sub_total + order_total_calculators.total
+    end
+
+    # Returns the current state of the cart storage engine
+    #
+    def state
+      storage_engine.state
+    end
+
+    # :nodoc
+    def method_missing(symbol, *args)
+      # This allows developers to add extra aasm event transaction, and still allow them to called from the cart
+      if @storage_engine.state_paths.events.include?(symbol.to_s[0..-2].to_sym)
+        @storage_engine.send(symbol)
+      else
+        super
+      end
+    end
+
+  private
+    def with_callbacks(type, item, quantity, options, &blk)
+      return false unless item.send("before_#{type}".to_sym, quantity, options) if item.respond_to?("before_#{type}".to_sym)
+      return false unless @storage_engine.send("before_#{type}".to_sym, item, quantity, options) if @storage_engine.respond_to?("before_#{type}".to_sym)
+      
+      yield
+      
+      @storage_engine.send("after_#{type}".to_sym, item, quantity, options) if @storage_engine.respond_to?("after_#{type}".to_sym)
+      item.send("after_#{type}".to_sym, quantity, options) if item.respond_to?("after_#{type}".to_sym)
+    end
+  end
+end

data/lib/active_cart/cart_storage.rb

@@ -0,0 +1,121 @@
+# Mixin this module into the class you want to use as your storage class. Remember to override the invoice_id method
+#
+module ActiveCart
+  # The CartStorage object uses a state machine to track the state of the cart. The default states are: shopping, checkout, verifying_payment, completed, failed. It exposed the following transitions:
+  # continue_shopping, checkout, check_payment, payment_successful, payment_failed
+  #
+  #   @cart.checkout! # transitions from shopping, verifying_payment or failed to checkout
+  #   @cart.check_payment! # transistions from checkout to verifying_payment
+  #   @cart.payment_successful! # transitions from verifying_payment to completed
+  #   @cart.payment_failed! # transitions from verifying_payment to failed
+  #   @cart.continue_shopping # transitions from checkout, verifying_payment or failed to shopping
+  #   
+  #   It will fire before_ and after callbacks with the same name as the transitions
+  #
+  module CartStorage
+    def self.included(base) #:nodoc:
+
+      base.state_machine :state, :initial => :shopping do
+
+        event :continue_shopping do
+          transition [ :checkout, :verifying_payment, :failed ] => :shopping
+        end
+
+        event :checkout do
+          transition [ :shopping, :verifying_payment, :failed ] => :checkout
+        end
+
+        event :check_payment do
+          transition :checkout => :verifying_payment
+        end
+
+        event :payment_successful do
+          transition :verifying_payment => :completed
+        end
+
+        event :payment_failed do
+          transition :verifying_payment => :failed
+        end
+
+        state :shopping
+        state :checkout
+        state :verifying_payment
+        state :completed
+        state :failed
+      end
+    end
+
+    # Returns the unique invoice_id for this cart instance. This MUST be overriden by the concrete class this module is mixed into, otherwise you
+    # will get a NotImplementedError
+    #
+    def invoice_id
+      raise NotImplementedError
+    end
+
+    # Returns the sub-total of all the items in the cart. Usually returns a float.
+    #
+    #   @cart.sub_total # => 100.00
+    #
+    def sub_total
+      inject(0) { |t, item| t + (item.quantity * item.price.to_f)  }
+    end
+
+    # Returns the number of items in the cart. It takes into account the individual quantities of each item, eg if there are 3 items in the cart, each with a quantity of 2, this will return 6
+    #
+    def quantity
+      inject(0) { |t, item| t + item.quantity }
+    end
+
+    # Adds an item to the cart. If the item already exists in the cart (identified by the id of the item), then the quantity will be increased but the supplied quantity (default: 1)
+    #
+    #   @cart.add_to_cart(item, 5)
+    #   @cart.quantity # => 5
+    #
+    #   @cart.add_to_cart(item, 2)
+    #   @cart.quantity # => 7
+    #   @cart[0].quantity # => 7
+    #   @cart[1] # => nil
+    #
+    #   @cart.add_to_cart(item_2, 4)
+    #   @cart.quantity => 100
+    #   @cart[0].quantity # => 7
+    #   @cart[1].quantity # => 4
+    #
+    def add_to_cart(item, quantity = 1, options = {})
+      if self.include?(item)
+        index = self.index(item)
+        self.at(index).quantity += quantity
+      else
+        item.quantity += quantity
+        self << item
+      end
+    end
+
+    # Removes an item from the cart (identified by the id of the item). If the supplied quantity is greater than equal to the number in the cart, the item will be removed, otherwise the quantity will simply be decremented by the supplied amount
+    #
+    #   @cart.add_to_cart(item, 5)
+    #   @cart[0].quantity # => 5
+    #   @cart.remove_from_cart(item, 3)
+    #   @cart[0].quantity # => 2
+    #   @cart.remove_from_cart(item, 2)
+    #   @cart[0] # => nil
+    #   
+    #   @cart.add_to_cart(item, 3)
+    #   @cart[0].quantity # => 3
+    #   @cart_remove_from_cart(item, :all)
+    #   @cart[[0].quantity # => 0
+    def remove_from_cart(item, quantity = 1, option = {})
+      if self.include?(item)
+        index = self.index(item)
+        
+        quantity = self.at(index).quantity if quantity == :all
+
+        if (existing = self.at(index)).quantity - quantity > 0
+          existing.quantity = existing.quantity - quantity
+        else
+          self.delete_at(index)
+        end
+      end
+    end
+  end
+end

data/lib/active_cart/item.rb

@@ -0,0 +1,36 @@
+# Mixin this module into the class you want to act as an item 
+#
+module ActiveCart
+  # 
+  module Item
+    # A unique id for the item. The Mixee needs to implement this or a NotImplementedError will be thrown
+    #
+    def id
+      raise NotImplementedError
+    end
+
+    # A display name for the item. The Mixee needs to implement this or a NotImplementedError will be thrown
+    #
+    def name
+      raise NotImplementedError
+    end
+
+    # Returns the quantity of this item in the context of a cart
+    #
+    def quantity
+      @quantity || 0
+    end
+
+    # Set the quantity of this item in the context of a cart
+    #
+    def quantity=(quantity)
+      @quantity = quantity
+    end
+
+    # Returns the price of this item
+    #
+    def price
+      raise NotImplementedError
+    end
+  end
+end

data/lib/active_cart/items/memory_item.rb

@@ -0,0 +1,18 @@
+module ActiveCart
+  module Items
+    class MemoryItem
+      attr_accessor :id, :name, :price
+      include ActiveCart::Item
+
+      def ==(item)
+        self.id == item.id
+      end
+      
+      def initialize(id, name, price)
+        @id = id
+        @name = name
+        @price = price
+      end
+    end
+  end
+end

data/lib/active_cart/order_total.rb

@@ -0,0 +1,48 @@
+# Mixin this module into any classes that act as an order_total.
+#
+# You need to overwrite the price, name and description methods
+#
+module ActiveCart
+  module OrderTotal
+    
+    # Returns a boolean depending if the order total is active in this particular cart
+    #
+    #   @order_total.active? # => true
+    #
+    def active?
+      @active || false
+    end
+
+    # Make a particular order_total active
+    #
+    #   @order_total.active = true
+    #   @order_total.active? # => true
+    #
+    #   @order_total.active = false
+    #   @order_total.active? # => falese
+    #
+    def active=(active)
+      @active = active
+    end
+
+    # Returns the adjustment caused by this order_total object. Takes a cart object as a parameter, allowing the object to interrogate the items in the cart. 
+    #
+    # This must be overriden in the mixee class, otherwise it will throw a NotImplementedError
+    #
+    #   @order.price(@cart) => 2
+    #
+    def price(cart)
+      raise NotImplementedError
+    end
+
+    # Returns the friendly name of the order total. Can be used for display (Such as on an invoices etc)
+    #
+    # This must be overriden in the mixee class, otherwise it will throw a NotImplementedError
+    #
+    #   @order.name # => 'My awesome order total class'
+    #
+    def name
+      raise NotImplementedError
+    end
+  end
+end

data/lib/active_cart/order_total_collection.rb

@@ -0,0 +1,75 @@
+module ActiveCart
+  class OrderTotalCollection < Array
+    # Returns a new OrderTotalCollection
+    #
+    # You must pass in an cart object. 
+    #
+    # collection = OrderTotalCollection.new(@cart)
+    #
+    # You can also pass in an array of order_total objects
+    #
+    #   cart = ActiveCart::Cart.instance
+    #   collection = OrderTotalCollection.new(cart, order_total_1, order_total_2)  # => [ order_total_1, order_total_2 ]
+    #
+    def initialize(cart, *seed)
+      @cart = cart
+      seed.each do |s|
+        self.push(s)
+      end
+    end
+
+    # Concatenation.Returns a new OrderTotalCollection built by concatenating the two OrderTotalCollections together to produce a third OrderTotalCollection. (The supplied collection can be a regular array)
+    #
+    #   [ order_total_1, order_total_2, order_total_3 ] + [ order_total_4, order_total_5 ] #=> [ order_total_1, order_total_2, order_total_3, order_total_4, order_total_5 ]
+    #
+    def +(order_total_collection)
+      tmp = OrderTotalCollection.new(@cart)
+      self.each { |s| tmp << s }
+      order_total_collection.each { |s| tmp << s }
+      tmp
+    end
+
+    # Inserts the items before the item that is currently at the supplied index
+    #
+    #   items = [ order_total_1, order_total_2 ]
+    #   items.insert_before(1, order_total_2) #=> [ order_total_1, order_total_3, order_total_2 ]
+    #
+    def insert_before(index, *items)
+      items.reverse.each do |item|
+        self.insert(index, item)
+      end
+      self
+    end
+
+    # Inserts the items after the item that is currently at the supplied index
+    #
+    #   items = [ order_total_1, order_total_2 ]
+    #   items.insert_after(0, order_total_2) #=> [ order_total_1, order_total_3, order_total_2 ]
+    #
+    def insert_after(index, *items)
+      items.each_with_index do |item, i|
+        self.insert(index + i + 1, item)
+      end
+      self
+    end
+
+    # Allows you to reorder the order totals. Moves the item at index <em>from</em> to index <em>to</em>
+    #
+    #   items = [ order_total_1, order_total_2 ]
+    #   items.move(0, 1) #=> [ order_total_2, order_total_1 ]
+    #
+    def move(from, to)
+      index = self.delete_at(from)
+      self.insert(to, index)
+    end
+
+    # Calculates the total price applied by all the order_total objects.
+    #
+    #   order_total_collection = OrderTotalCollection.new(nil, order_total_1, order_total_2)
+    #   order_total_collection.total # => 10
+    #
+    def total
+      self.inject(0) { |t, calculator| t + (calculator.active? ? calculator.price(@cart) : 0) }
+    end
+  end
+end

data/lib/active_cart/storage_engines/memory.rb

@@ -0,0 +1,14 @@
+module ActiveCart
+  module StorageEngines
+    # This storage engine is probably only useful as a reference implementation (It would work in a desktop app I guess). Items only exist in memory, so
+    # as soon as the thread dies, so does the cart.
+    #
+    class Memory < Array
+      include ActiveCart::CartStorage
+      
+      def invoice_id
+        @@last_id = @@last_id ? @@last_id + 1 : 1
+      end
+    end
+  end
+end

data/lib/active_cart.rb

@@ -0,0 +1,20 @@
+$:.unshift(File.join(File.dirname(__FILE__), 'active_cart'))
+
+require 'rubygems'
+require 'singleton'
+require 'forwardable'
+require 'state_machine'
+require 'item'
+require 'cart_storage'
+require 'order_total'
+require 'order_total_collection'
+require 'cart'
+
+require 'exceptions/out_of_stock'
+
+require 'storage_engines/memory'
+require 'items/memory_item'
+
+module ActiveCart
+  VERSION = File.exist?('VERSION') ? File.read('VERSION') : ""
+end

data/lib/exceptions/out_of_stock.rb

@@ -0,0 +1,4 @@
+module ActiveCart
+  class OutOfStock < StandardError
+  end
+end

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification
+name: galvinhsiu-active_cart
+version: !ruby/object:Gem::Version
+  version: 0.0.19
+  prerelease: 
+platform: ruby
+authors:
+- Myles Eftos
+- Galvin Hsiu
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-12-07 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: state_machine
+  requirement: &86400220 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *86400220
+- !ruby/object:Gem::Dependency
+  name: shoulda
+  requirement: &86400000 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *86400000
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: &86399790 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *86399790
+- !ruby/object:Gem::Dependency
+  name: machinist
+  requirement: &86399580 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *86399580
+- !ruby/object:Gem::Dependency
+  name: faker
+  requirement: &86399370 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *86399370
+description: ! '    You can use active_cart as the basis of a shopping cart system.
+  It''s not a shopping cart application - it''s a shopping cart framework.
+
+'
+email: myles@madpilot.com.au, galvinhsiu@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/active_cart.rb
+- lib/exceptions/out_of_stock.rb
+- lib/active_cart/cart.rb
+- lib/active_cart/order_total_collection.rb
+- lib/active_cart/cart_storage.rb
+- lib/active_cart/items/memory_item.rb
+- lib/active_cart/order_total.rb
+- lib/active_cart/storage_engines/memory.rb
+- lib/active_cart/item.rb
+- galvinhsiu-active_cart.gemspec
+homepage: http://gemcutter.org/gems/galvinhsiu-active_cart
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.12
+signing_key: 
+specification_version: 3
+summary: Shopping Cart framework gem. Supports 'storage engines' and order total plugins,
+  forked to use state_machine from active_cart.
+test_files: []
+has_rdoc: