mongoid-casino 0.0.1

data/.gitignore

@@ -0,0 +1,20 @@
+*.gem
+*.rbc
+*.un~
+.bundle
+.config
+.yardoc
+.rspec
+.rvmrc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.ruby-gemset

@@ -0,0 +1 @@
+acumen

data/.ruby-version

@@ -0,0 +1 @@
+ruby-1.9.3-p385

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in casino.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Joseph McCormick
+
+MIT License
+
+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,93 @@
+# Casino
+
+Casino is a DSL which helps you interact with and explore your `Mongoid::Document` collections, and helps you more easily use MongoDB's aggregation framework.
+
+### Casino works like this:
+
+  1. Build a class and include Casino::Collection
+    * This gives the class the following macros: `dimension`, `focus`, and `question`
+    * The class also gains the following instance methods: `answer`, `intersection`, `projection`, and `query`
+
+  2. Declare the parameters of your Casino class by defining it using the class-level macros.  You must define at least one `focus`, `dimension`, and `question`
+    * A `focus` is a class name or a list of class names where Casino can expect to find a Mongoid document API (in other words, a class which includes `Mongoid::Document`)
+    * A `dimension` defines an area of interest for the focus by name, then points to a specific `Mongoid::Document` field with a symbol or string.  This is usually something defined in the document model itself, but it can actually be anything, due to the schemaless nature of MongoDB.
+      The third argument to a dimension is a symbol which points to an `attr_accessor` or instance method on the class which provides an array of `query` method invocations.  This list represents the different facets of the dimension.
+    * Finally, a `question` is a specific action you want to use once you've produced the documents that your `dimension` and `focus` combinations have resulted in.
+      In order to tap into the current intersection being queried, Casino provides the `intersection` helper, which is a combination of all the current dimension facets currently being questioned.
+
+  3. Once defined, Casino will handle generation and querying of your generated collection from here on out.
+
+## The Casino API
+
+### Class (macro) methods
+
+#### Dimension
+  * **Arguments:**
+    * *Label:* A "pretty name" for the dimension for easy display.
+    * *Field:* This is a string or symbol which indicates the dimension's target field.
+    * *Queries:* This is a symbol which references an instance method or accessor that produces an array of `Casino::Query` objects (built with the `query` instance method).
+    * *Approach: (optional)* This is a hash which contains an `:operator` key, in case the dimension should query a field differently than the default (`where`) query plan, for example, `gt`, or `and`, etc.
+  * **Returns:** A `Casino::Dimension` object.
+  * **What it does:** The `dimension` class method creates a `Casino::Dimension` object and registers it with the `Casino::Collection` the parent class is a part of.  From that point on, the dimension will be used as a factor in building out the following:
+    * A generated collection key (`_id`).
+    * The generated collection name.
+    * The intersections for the aggregation, where Casino will ask any questions it is given.
+
+#### Focus
+  * **Arguments:**
+    * *Models:* A class which includes the `Mongoid::Document` module.
+  * **Returns:** A `Casino::Focus` object.
+  * **What it does:** Creates a `Casino::Focus` object and registers it with the `Casino::Collection` of the parent class.  From that point on, the focus object is used in the following way:
+    * The generated collection name.
+    * The targets for dimensional intersection questions.
+    * The subject material for aggregate data.
+
+#### Question
+  * **Arguments:**
+    * *Name:* The name of the question, this is what the question will be registered under.
+    * *Answer:* This is a `:method_name`.
+  * **Returns:** A `Casino::Question` object
+  * **What it does:** Creates a `Casino::Question` object for the given arguments, and registers it with the `Casino::Collection` of the parent class.
+
+    A `Casino::Question` represents the actual operation which will be performed on a focus at a given dimensional intersection.
+
+    When methods marked with the `question` macro are run, the following instance variables become available:
+
+      * `answer`: An answer to another question at the current intersection.
+      * `intersection`: The current intersection criteria.
+      * `projection`: A MongoDB aggregation framework wrapper scoped to the current intersection.
+
+### Instance methods
+
+#### Answer
+  * **Arguments:**
+    * *Method name:* A `:symbol` pointing to another question.  This method returns the results of that question.
+  * **Returns:** An answered question key/value pair: `{ question_name: question_answer }`
+
+#### Insert
+  * **Arguments:**
+    * *Documents:* Any argument passed in will be evaluated as though it were a `Mongoid::Document` of the collection's focus.
+  * **Returns:** Any results which were updated with the given documents.
+  * **What it does:** `insert` is a trickle-in mechanism, which updates any intersections which match a document.
+
+#### Intersection
+  * **Arguments:** None
+  * **Returns:** `Mongoid::Criteria` - A window into the currently active criteria being questioned.
+
+#### Projection
+  * **Arguments:** None
+  * **Returns:** A `Casino::Projection` object preloaded with the current intersection selector, which wraps around MongoDB's aggregation framework.
+
+#### Query
+  * **Arguments:**
+    * *Label:* A string or symbol that indicates a field to store the query's results in
+    * *Criterion:* A list of items to use to search within the `question` field
+  * **Returns:** A `Casino::Query` instance for use to build outputs as well as to build `Casino::Intersection` objects with.
+
+#### Results
+  * **Arguments:** None
+  * **Returns:** A list of answer hashes for every intersection.  Casino persists intersection results to a generated MongoDB collection the first time it is used, and afterward will just combine already produced results with new results (in essence, it only queries for new information and remembers the rest).
+
+#### Update
+  * **Arguments:** None
+  * **Returns:** Re-generates the entire generated collection.

data/Rakefile

@@ -0,0 +1,9 @@
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+Rake::TestTask.new do |test_task|
+  test_task.libs << "spec"
+  test_task.test_files = Dir.glob 'spec/**/*_spec.rb'
+end
+
+task default: :test

data/casino.gemspec

@@ -0,0 +1,30 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'casino/version'
+
+Gem::Specification.new do |gem|
+
+  gem.name          = "mongoid-casino"
+  gem.version       = Casino::VERSION
+  gem.authors       = ["JC McCormick"]
+  gem.email         = ["esmevane@gmail.com"]
+  gem.description   = %q{Create and maintain aggregate metadata with Mongoid}
+  gem.summary       = %q{Aggregation handler for Mongoid}
+  gem.homepage      = "http://www.github.com/esmevane/casino"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+  gem.add_dependency "mongoid", "3.0.19"
+
+  gem.add_development_dependency "database_cleaner", "~> 0.9"
+  gem.add_development_dependency "fabrication", "~> 2.6"
+  gem.add_development_dependency "json", "~> 1.7"
+  gem.add_development_dependency "minitest", "~> 4.3"
+  gem.add_development_dependency "rake", "~> 10.0"
+  gem.add_development_dependency "simplecov", "~> 0.7"
+
+end

data/lib/casino.rb

@@ -0,0 +1,13 @@
+require 'csv'
+require 'mongoid'
+
+libs = %w(collection dimension focus intersection lobby projection
+  query question store version)
+path = File.dirname(__FILE__)
+
+libs.each do |lib|
+  require "#{path}/casino/#{lib}"
+end
+
+module Casino
+end

data/lib/casino/collection.rb

@@ -0,0 +1,195 @@
+module Casino
+  module Collection
+    attr_reader :intersection, :answer
+
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+
+      def dimension(label, field, queries, approach = Hash.new)
+        register Dimension.new(label, field, queries, approach)
+      end
+
+      def question(name, answer)
+        register Question.new(name, answer)
+      end
+
+      def focus(model)
+        register Focus.new(model)
+      end
+
+      def lobby
+        @lobby ||= Lobby.new(self)
+      end
+
+      def register(object)
+        lobby.add_registry(object)
+        object
+      end
+
+    end
+
+    def dimensions
+      registry[:dimension]
+    end
+
+    def questions
+      registry[:question]
+    end
+
+    def focus
+      registry[:focus]
+    end
+
+    def store
+      @store ||= Store.new key
+    end
+
+    def key
+      Digest::SHA1.hexdigest(key_base)
+    end
+
+    def projection
+      Casino::Projection.new(focus_model).where(intersection.selector)
+    end
+
+    def answer(method_name)
+      send(method_name)
+    end
+
+    def query(label, *criteria)
+      Query.new(label, [], *criteria)
+    end
+
+    def results
+      persist_results if pending_results.any?
+      stored_results
+    end
+
+    def update
+      merge all_results
+      stored_results
+    end
+
+    def intersection
+      @intersection || focus_model.scoped
+    end
+
+    def insert(*documents)
+      matching_intersections = match_intersections documents
+      matching_results = determine_results matching_intersections
+      merge matching_results
+      stored_results.where(id: matching_results.map(&:id))
+    end
+
+    private
+
+    def queries(dimension)
+      send(dimension.queries).map { |query| query.merge(dimension) }
+    end
+
+    def intersections
+      focus.reduce(Array.new) do |list, answer_focus|
+        list + intersections_for(answer_focus)
+      end
+    end
+
+    def merge(documents)
+      store.merge *documents
+    end
+
+    def persist_results
+      merge collected_results
+    end
+
+    def collected_results
+      stored_results + pending_results
+    end
+
+    def pending_results
+      determine_results pending_intersections
+    end
+
+    def all_results
+      determine_results intersections
+    end
+
+    def answers
+      questions.reduce(Hash.new) do |hash, question|
+        hash.merge question.name => send(question.answer)
+      end
+    end
+
+    def stored_results
+      store.in(id: intersection_ids)
+    end
+
+    def intersection_ids
+      intersections.map(&:selector)
+    end
+
+    def determine_results(given_intersections)
+      given_intersections.map do |current_intersection|
+        @intersection = current_intersection.criteria
+        result = { _id: intersection.selector }.merge(answers)
+      end
+    end
+
+    def key_base
+      join       = "_and_"
+      what       = questions.map(&:name).join(join)
+      parameters = dimensions.map(&:field).join(join)
+      my_name    = self.class.name.underscore
+      targets    = focus.map(&:model).map(&:name).map(&:underscore).sort.
+        join(join)
+      "#{my_name}_asks_#{targets}_about_#{what}_by_#{parameters}"
+    end
+
+    def match_intersections(documents)
+      documents.reduce(Array.new) do |list, document|
+        list + matches_for(document)
+      end.uniq
+    end
+
+    def matches_for(document)
+      intersections.select { |intersection| intersection.match?(document) }
+    end
+
+    def pending_intersections
+      ids = stored_results.map(&:id)
+      intersections.reject do |intersection|
+        ids.include? intersection.selector
+      end
+    end
+
+    def focus_model
+      focus.map(&:model).first
+    end
+
+    def all_queries
+      dimensions.map { |dimension| queries(dimension) }
+    end
+
+    def intersections_for(answer_focus)
+      product_of_all_queries.map do |conditions|
+        label = conditions.map(&:label)
+        Intersection.new label, answer_focus.build_criteria(*conditions)
+      end
+    end
+
+    def get_product(head, *tail)
+      head.product *tail
+    end
+
+    def product_of_all_queries
+      get_product(*all_queries)
+    end
+
+    def registry
+      self.class.lobby.registry
+    end
+
+  end
+end

data/lib/casino/dimension.rb

@@ -0,0 +1,11 @@
+module Casino
+  class Dimension
+    attr_accessor :label, :field, :queries, :approach
+    def initialize(label, field, queries, approach = Hash.new)
+      self.label    = label
+      self.field    = field
+      self.queries  = queries
+      self.approach = { operator: :where }.merge(approach)
+    end
+  end
+end

data/lib/casino/focus.rb

@@ -0,0 +1,26 @@
+module Casino
+  class Focus
+    attr_accessor :model
+
+    def initialize(model)
+      self.model = model
+    end
+
+    def hash
+      model.hash
+    end
+
+    def ==(other)
+      other.is_a?(self.class) && other.model == model
+    end
+    alias :eql? :==
+
+    def build_criteria(*queries)
+      conditions = queries.map(&:conditions).flatten(1)
+      conditions.reduce(model) do |criteria, condition_pair|
+        criteria.send(condition_pair.first, condition_pair.last)
+      end
+    end
+
+  end
+end

data/lib/casino/intersection.rb

@@ -0,0 +1,30 @@
+libs = %w(equivalence base all include greater lesser recurse expression)
+path = File.dirname(__FILE__)
+
+libs.each do |lib|
+  require "#{path}/intersection/match/#{lib}"
+end
+
+module Casino
+  class Intersection
+    attr_accessor :label, :criteria
+
+    delegate :selector, to: :criteria
+
+    def initialize(label, criteria)
+      self.label = label
+      self.criteria = criteria
+    end
+
+    def match?(document)
+      selector.keys.map { |key| match_key_against(document, key) }.all?
+    end
+
+    private
+
+    def match_key_against(document, key)
+      Match::Base.new(document, key, selector).evaluate
+    end
+
+  end
+end