operable 0.1.0

data/Gemfile

@@ -0,0 +1,2 @@
+source "http://rubygems.org"
+gemspec

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2011 Jason Coene
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,140 @@
+# Operable
+
+An easy way to perform simple operations (addition, subtraction, multiplication, division) on your models. It is tested with ActiveRecord and Mongoid and should work with any ActiveModel compliant class.
+
+[![travis](https://secure.travis-ci.org/jcoene/operable.png)](http://travis-ci.org/jcoene/operable)
+
+## A Simple Example
+
+Let's say we're collecting records of Baseball games. A `Team` model has various stats like `W`, `L`, `T`, etc.
+
+Operable, once included in your models, lets you use the `+`, `-`, `*` and `/` operators on them, just as you would an Integer. It returns in the value of the class you're already working with.
+
+We might imagine something like this:
+
+```ruby
+# Create team instances for the 2 NY baseball teams:
+yankees = Team.new :w => 5, :l => 4, :t => 1
+mets =    Team.new :w => 3, :l => 7, :t => 0
+
+# Get their combined totals
+yankees + mets # => #<Team w: 8, l: 11, t: 1>
+
+# How much better are the yankees?
+yankees - mets # => #<Team w: 2, l: -3, t: 1>
+
+# If the yankees keep this up for the rest of the season...
+yankees * 16.2 # => #<Team w: 81, l: 65, t: 16>
+```
+
+## Getting Started
+
+First, add operable to your Gemfile:
+
+```ruby
+gem 'operable'
+```
+
+Next, include the module in your model and specify which fields to operate on:
+
+```ruby
+# ActiveRecord:
+class Team < ActiveRecord::Base
+  include Operable
+  operable_on :w, :l, :t
+end
+
+# Mongoid:
+class Team
+  include Mongoid::Document
+  include Operable
+  field :w
+  field :l
+  field :t
+  operable_on :w, :l, :t
+end
+```
+
+That's it! You can call operable_on multiple times to add more fields.
+
+## Operations
+
+Four operations are provided: `+`, `-`, `*`, `/`.
+
+```ruby
+red = Color.new   :r => 128, :g => 0,   :b => 0
+green = Color.new :r => 0,   :g => 128, :b => 0
+blue = Color.new  :r => 0,   :g => 0,   :b => 128
+
+yellow = green + red # => #<Color r: 128, g: 128, b: 0>
+grey = yellow + blue # => #<Color r: 128, g: 128, b: 128>
+bright_red = red * 2 # => #<Color r: 255, g: 0,   b: 0>
+dark_grey = grey / 3 # => #<Color r: 43,  g: 43,  b: 43>
+```
+
+## Equality
+
+Compare the equality of operable objects with the `matches?` method:
+
+```ruby
+purple = Color.new :r => 128, :g => 0, :b => 128
+
+purple.matches?(red + blue)  #=> true
+purple.matches?(red + green) #=> false
+```
+
+### Operate On All (Mongoid only)
+
+Mongoid models define their fields explicitly in the model declaration. We can use this to automatically determine what to operate on:
+
+```ruby
+class Team
+  include Mongoid::Document
+  include Operable
+  field :w
+  field :l
+  field :t
+  operable_on_all # operates on w, l and t.
+  operable_on_all_except :t # operates on w and l
+end
+```
+
+### Operate On Associations (Mongoid only)
+
+We can include associations in our list of operable fields just as with normal attributes!
+
+First, include Operable on **both** documents. Then, on the **parent** document, manually specify the name of the association to *operable_on* (associations are not included by *operable_on_all* methods)
+
+```ruby
+class First
+  include Mongoid::Document
+  include Operable
+  field :a
+  field :b
+  embeds_one :second
+  operable_on_all
+  operable_on :second
+end
+
+class Second
+  include Mongoid::Document
+  include Operable
+  field :c
+  field :d
+  embedded_in :first
+  operable_on_all
+end
+
+f1 = First.new :a => 1, :b => 2, :second => Second.new(:c => 1, :d => 2)
+f2 = First.new :a => 2, :b => 3, :second => Second.new(:c => 2, :d => 3)
+f3 = f1 + f2  # => #<First a: 3, b: 5>
+f3.second     # => #<Second c: 3, d: 5>
+```
+
+## Enhancements and Pull Requests
+
+If you find the project useful but it doesn't meet all of your needs, feel free to fork it and send a pull request. I'd especially love contributions that enhance behavior with ActiveRecord. Please make sure to include specs!
+
+## License
+
+MIT license, go wild.

data/Rakefile

@@ -0,0 +1,11 @@
+# encoding: UTF-8
+
+require 'bundler'
+require 'rspec/core/rake_task'
+
+Bundler::GemHelper.install_tasks
+
+desc 'Run all specs in the spec directory'
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/lib/operable/fields.rb

@@ -0,0 +1,25 @@
+module Operable
+  module Fields
+
+    extend ActiveSupport::Concern
+
+    # Return a list of attributes (with values) to be included in operations
+    #
+    # Returns Hash of key (string) => value pairs
+    def operable_values
+      raise "Please specify one or more fields via operable_on in your model definition!" if self.class.operable_fields.nil?
+
+      keys = attributes.keys
+      keys << relations.keys if respond_to?(:associations)
+      values = attributes.select {|k, v| self.class.operable_fields.include? k }
+      if respond_to?(:associations)
+        associations.select {|k, v| self.class.operable_fields.include? k }.each do |k, v|
+          values[k.to_s] = send(k)
+        end
+      end
+
+      values
+    end
+
+  end
+end

data/lib/operable/operations.rb

@@ -0,0 +1,54 @@
+module Operable
+  module Operations
+
+    # Add or subtract one method from another
+    #
+    # method - name of method to perform, as a symbol ( :+ or :- )
+    # other - other object to operate with
+    #
+    # Returns the resulting object
+    def add_or_subtract(method, other)
+      self.class.new.tap do |o|
+        operable_values.each do |k,v|
+          o.send("#{k}=", (v || 0).send(method, (other.send(k) || 0)))
+          # o[k] = (v || 0).send(method, (other[k] || 0))
+        end
+      end
+    end
+
+    def +(other)
+      add_or_subtract(:+, other)
+    end
+
+    def -(other)
+      add_or_subtract(:-, other)
+    end
+
+    # Multiply or divide values of this object by another
+    #
+    # Returns a new object
+    def multiply_or_divide(method, by)
+      self.class.new.tap do |o|
+        operable_values.each do |k,v|
+          o.send("#{k}=", (v || 0).send(method, by))
+        end
+      end
+    end
+
+    def *(by)
+      multiply_or_divide(:*, by)
+    end
+
+    def /(by)
+      multiply_or_divide(:/, by)
+    end
+
+    # Compare equality between objects
+    #
+    # Returns true or false
+    def matches?(other)
+      operable_values == other.operable_values
+    end
+
+  end
+end

data/lib/operable/version.rb

@@ -0,0 +1,3 @@
+module Operable
+  VERSION = '0.1.0'
+end

data/lib/operable.rb

@@ -0,0 +1,37 @@
+require 'active_support'
+require 'operable/fields'
+require 'operable/operations'
+require 'operable/version'
+
+module Operable
+
+  extend ActiveSupport::Concern
+
+  include Operable::Fields
+  include Operable::Operations
+
+  included do
+    cattr_accessor :operable_fields
+  end
+
+  module ClassMethods
+
+    INOPERABLE_FIELDS = %w[_type _id created_at updated_at version]
+
+    def operable_on(*names)
+      fields = operable_fields || []
+      self.operable_fields = [fields, names].flatten.map(&:to_s).uniq.sort
+    end
+
+    def operable_on_all
+      raise "Unable to list all fields for this ORM" unless respond_to?(:fields)
+      self.operable_fields = fields.keys.reject {|k| INOPERABLE_FIELDS.include? k }
+    end
+
+    def operable_on_all_except(*names)
+      self.operable_fields = operable_on_all.reject {|k| names.map(&:to_s).include? k }
+    end
+
+  end
+
+end

metadata

@@ -0,0 +1,142 @@
+--- !ruby/object:Gem::Specification
+name: operable
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Jason Coene
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-10-08 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: &70205376469520 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70205376469520
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: &70205376468940 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+  type: :development
+  prerelease: false
+  version_requirements: *70205376468940
+- !ruby/object:Gem::Dependency
+  name: mongoid
+  requirement: &70205376468340 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: *70205376468340
+- !ruby/object:Gem::Dependency
+  name: bson_ext
+  requirement: &70205376467760 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: *70205376467760
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: &70205376467180 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: *70205376467180
+- !ruby/object:Gem::Dependency
+  name: growl
+  requirement: &70205376466680 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70205376466680
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70205376466020 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :development
+  prerelease: false
+  version_requirements: *70205376466020
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: &70205376465400 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.4.3
+  type: :development
+  prerelease: false
+  version_requirements: *70205376465400
+description: Operable is the easiest way to perform common operations on multiple
+  instances of a model.
+email:
+- jcoene@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/operable/fields.rb
+- lib/operable/operations.rb
+- lib/operable/version.rb
+- lib/operable.rb
+- MIT-LICENSE
+- Rakefile
+- Gemfile
+- README.md
+homepage: http://github.com/jcoene/operable
+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.10
+signing_key: 
+specification_version: 3
+summary: Convenient operations for your models.
+test_files: []