cicloid-conversational 0.3.2.pre

data/features/step_definitions/pickle_steps.rb

@@ -0,0 +1,87 @@
+# this file generated by script/generate pickle
+
+# create a model
+Given(/^#{capture_model} exists?(?: with #{capture_fields})?$/) do |name, fields|
+  create_model(name, fields)
+end
+
+# create n models
+Given(/^(\d+) #{capture_plural_factory} exist(?: with #{capture_fields})?$/) do |count, plural_factory, fields|
+  count.to_i.times { create_model(plural_factory.singularize, fields) }
+end
+
+# create models from a table
+Given(/^the following #{capture_plural_factory} exists?:?$/) do |plural_factory, table|
+  create_models_from_table(plural_factory, table)
+end
+
+# find a model
+Then(/^#{capture_model} should exist(?: with #{capture_fields})?$/) do |name, fields|
+  find_model!(name, fields)
+end
+
+# not find a model
+Then(/^#{capture_model} should not exist(?: with #{capture_fields})?$/) do |name, fields|
+  find_model(name, fields).should be_nil
+end
+
+# find models with a table
+Then(/^the following #{capture_plural_factory} should exists?:?$/) do |plural_factory, table|
+  find_models_from_table(plural_factory, table).should_not be_any(&:nil?)
+end
+
+# find exactly n models
+Then(/^(\d+) #{capture_plural_factory} should exist(?: with #{capture_fields})?$/) do |count, plural_factory, fields|
+  find_models(plural_factory.singularize, fields).size.should == count.to_i
+end
+
+# assert equality of models
+Then(/^#{capture_model} should be #{capture_model}$/) do |a, b|
+  model!(a).should == model!(b)
+end
+
+# assert model is in another model's has_many assoc
+Then(/^#{capture_model} should be (?:in|one of|amongst) #{capture_model}(?:'s)? (\w+)$/) do |target, owner, association|
+  model!(owner).send(association).should include(model!(target))
+end
+
+# assert model is not in another model's has_many assoc
+Then(/^#{capture_model} should not be (?:in|one of|amongst) #{capture_model}(?:'s)? (\w+)$/) do |target, owner, association|
+  model!(owner).send(association).should_not include(model!(target))
+end
+
+# assert model is another model's has_one/belongs_to assoc
+Then(/^#{capture_model} should be #{capture_model}(?:'s)? (\w+)$/) do |target, owner, association|
+  model!(owner).send(association).should == model!(target)
+end
+
+# assert model is not another model's has_one/belongs_to assoc
+Then(/^#{capture_model} should not be #{capture_model}(?:'s)? (\w+)$/) do |target, owner, association|
+  model!(owner).send(association).should_not == model!(target)
+end
+
+# assert model.predicate? 
+Then(/^#{capture_model} should (?:be|have) (?:an? )?#{capture_predicate}$/) do |name, predicate|
+  model!(name).should send("be_#{predicate.gsub(' ', '_')}")
+end
+
+# assert not model.predicate?
+Then(/^#{capture_model} should not (?:be|have) (?:an? )?#{capture_predicate}$/) do |name, predicate|
+  model!(name).should_not send("be_#{predicate.gsub(' ', '_')}")
+end
+
+# model.attribute.should eql(value)
+# model.attribute.should_not eql(value)
+Then(/^#{capture_model}'s (\w+) (should(?: not)?) be #{capture_value}$/) do |name, attribute, expectation, expected|
+  actual_value  = model(name).send(attribute)
+  expectation   = expectation.gsub(' ', '_')
+  
+  case expected
+  when 'nil', 'true', 'false'
+    actual_value.send(expectation, send("be_#{expected}"))
+  when /^-?[0-9_]+$/
+    actual_value.send(expectation, eql(expected.to_i))
+  else
+    actual_value.to_s.send(expectation, eql(expected))
+  end
+end

data/features/support/conversation.rb

@@ -0,0 +1,2 @@
+require File.dirname(__FILE__) + '/../../spec/support/conversation'
+

data/features/support/email_spec.rb

@@ -0,0 +1 @@
+require 'email_spec/cucumber'

data/features/support/env.rb

@@ -0,0 +1,58 @@
+# IMPORTANT: This file is generated by cucumber-rails - edit at your own peril.
+# It is recommended to regenerate this file in the future when you upgrade to a 
+# newer version of cucumber-rails. Consider adding your own code to a new file 
+# instead of editing this one. Cucumber will automatically load all features/**/*.rb
+# files.
+
+ENV["RAILS_ENV"] ||= "test"
+require File.expand_path(File.dirname(__FILE__) + '/../../config/environment')
+
+require 'cucumber/formatter/unicode' # Remove this line if you don't want Cucumber Unicode support
+require 'cucumber/rails/rspec'
+require 'cucumber/rails/world'
+require 'cucumber/rails/active_record'
+require 'cucumber/web/tableish'
+
+require 'capybara/rails'
+require 'capybara/cucumber'
+require 'capybara/session'
+require 'cucumber/rails/capybara_javascript_emulation' # Lets you click links with onclick javascript handlers without using @culerity or @javascript
+# Capybara defaults to XPath selectors rather than Webrat's default of CSS3. In
+# order to ease the transition to Capybara we set the default here. If you'd
+# prefer to use XPath just remove this line and adjust any selectors in your
+# steps to use the XPath syntax.
+Capybara.default_selector = :css
+
+# If you set this to false, any error raised from within your app will bubble 
+# up to your step definition and out to cucumber unless you catch it somewhere
+# on the way. You can make Rails rescue errors and render error pages on a
+# per-scenario basis by tagging a scenario or feature with the @allow-rescue tag.
+#
+# If you set this to true, Rails will rescue all errors and render error
+# pages, more or less in the same way your application would behave in the
+# default production environment. It's not recommended to do this for all
+# of your scenarios, as this makes it hard to discover errors in your application.
+ActionController::Base.allow_rescue = false
+
+# If you set this to true, each scenario will run in a database transaction.
+# You can still turn off transactions on a per-scenario basis, simply tagging 
+# a feature or scenario with the @no-txn tag. If you are using Capybara,
+# tagging with @culerity or @javascript will also turn transactions off.
+#
+# If you set this to false, transactions will be off for all scenarios,
+# regardless of whether you use @no-txn or not.
+#
+# Beware that turning transactions off will leave data in your database 
+# after each scenario, which can lead to hard-to-debug failures in 
+# subsequent scenarios. If you do this, we recommend you create a Before
+# block that will explicitly put your database in a known state.
+Cucumber::Rails::World.use_transactional_fixtures = true
+# How to clean your database when transactions are turned off. See
+# http://github.com/bmabey/database_cleaner for more info.
+if defined?(ActiveRecord::Base)
+  begin
+    require 'database_cleaner'
+    DatabaseCleaner.strategy = :truncation
+  rescue LoadError => ignore_if_database_cleaner_not_present
+  end
+end

data/features/support/mail.rb

@@ -0,0 +1,6 @@
+require 'mail'
+Mail.defaults do
+  delivery_method :test
+end
+
+

data/features/support/paths.rb

@@ -0,0 +1,33 @@
+module NavigationHelpers
+  # Maps a name to a path. Used by the
+  #
+  #   When /^I go to (.+)$/ do |page_name|
+  #
+  # step definition in web_steps.rb
+  #
+  def path_to(page_name)
+    case page_name
+
+    when /the home\s?page/
+      '/'
+
+    # Add more mappings here.
+    # Here is an example that pulls values out of the Regexp:
+    #
+    #   when /^(.*)'s profile page$/i
+    #     user_profile_path(User.find_by_login($1))
+
+    else
+      begin
+        page_name =~ /the (.*) page/
+        path_components = $1.split(/\s+/)
+        self.send(path_components.push('path').join('_').to_sym)
+      rescue Object => e
+        raise "Can't find mapping from \"#{page_name}\" to a path.\n" +
+          "Now, go and add a mapping in #{__FILE__}"
+      end
+    end
+  end
+end
+
+World(NavigationHelpers)

data/features/support/pickle.rb

@@ -0,0 +1,24 @@
+# this file generated by script/generate pickle [paths] [email]
+#
+# Make sure that you are loading your factory of choice in your cucumber environment
+#
+# For machinist add: features/support/machinist.rb
+#
+#    require 'machinist/active_record' # or your chosen adaptor
+#    require File.dirname(__FILE__) + '/../../spec/blueprints' # or wherever your blueprints are
+#    Before { Sham.reset } # to reset Sham's seed between scenarios so each run has same random sequences
+#
+# For FactoryGirl add: features/support/factory_girl.rb
+#
+#    require 'factory_girl'
+#    require File.dirname(__FILE__) + '/../../spec/factories' # or wherever your factories are
+#
+# You may also need to add gem dependencies on your factory of choice in <tt>config/environments/cucumber.rb</tt>
+
+require 'pickle/world'
+# Example of configuring pickle:
+#
+# Pickle.configure do |config|
+#   config.adapters = [:machinist]
+#   config.map 'I', 'myself', 'me', 'my', :to => 'user: "me"'
+# end

data/features/support/sample_conversation.rb

@@ -0,0 +1,3 @@
+class SampleConversation < Conversation
+end
+

data/lib/conversational.rb

@@ -0,0 +1,3 @@
+require 'conversational/conversation'
+require 'conversational/active_record_additions'
+

data/lib/conversational/active_record_additions.rb

@@ -0,0 +1,122 @@
+module Conversational
+  module ActiveRecordAdditions
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      attr_accessor :finishing_keywords
+
+      def converser(with)
+        scoped.where("'with' = ?", with)
+      end
+
+      def in_progress
+        scoped.where("state != ? OR state IS NULL", "finished")
+      end
+
+      def recent(time = nil)
+        time ||= 24.hours.ago
+        scoped.where("updated_at > ?", time)
+      end
+
+      def with(with)
+        scoped.converser(with).in_progress.recent
+      end
+
+      # Finds an existing conversation with using the defaults or
+      # creates a new conversation and returns the specific conversation based
+      # on the conversation topic.
+      # Example:
+      #
+      # <tt>
+      #   Class Conversation < ActiveRecord::Base
+      #     include Conversational::Conversation
+      #   end
+      #
+      #   Class HelloConversation < Conversation
+      #   end
+      #
+      #   Class GoodbyeConversation < Conversation
+      #   end
+      #
+      #   Conversation.create!("someone", "hello")
+      #   existing_conversation = Conversation.find_or_create_with(
+      #     "someone",
+      #     "goodbye"
+      #   ) => #<HelloConversation topic: "hello", with: "someone">
+      #
+      #   Conversation.exclude HelloConversation
+      #
+      #   existing_conversation = Conversation.find_or_create_with(
+      #     "someone",
+      #     "goodbye"
+      #   ) => #<HelloConversation topic: "hello", with: "someone">
+      #
+      #   existing_conversation.destroy
+      #
+      #   non_existing_conversation = Conversation.find_or_create_with(
+      #     "someone",
+      #     "goodbye"
+      #   ) => #<GoodbyeConversation topic: "goodbye", with: "someone">
+      #
+      #   non_existing_conversation.destroy
+      #
+      #   Conversation.exclude GoodbyeConversation
+      #
+      #   non_existing_conversation = Conversation.find_or_create_with(
+      #     "someone",
+      #     "goodbye"
+      #   ) => BOOM! (Raises Error)
+      #
+      #   unknown_conversation = Conversation.find_or_create_with(
+      #     "someone",
+      #     "cheese"
+      #   ) => BOOM! (Raises Error)
+      #
+      #   Conversation.unknown_topic_subclass = HelloConversation
+      #
+      #   unknown_conversation = Conversation.find_or_create_with(
+      #     "someone",
+      #     "cheese"
+      #   ) => #<HelloConversation topic: "hello", with: "someone">
+      #
+      #   unknown_conversation.destroy
+      #
+      #   blank_conversation = Conversation.find_or_create_with(
+      #     "someone"
+      #   ) => BOOM! (Raises Error)
+      #
+      #   Conversation.blank_topic_subclass = GoodbyeConversation
+      #
+      #   blank_conversation = Conversation.find_or_create_with(
+      #     "someone"
+      #   ) => #<GoodbyeConversation topic: "goodbye", with: "someone">
+      #
+      # </tt>
+      def find_or_create_with(with, topic)
+        if default_find = self.with(with).last
+          default_find.details(:include_all => true)
+        else
+          subclass = Conversational::Conversation.find_subclass_by_topic(topic)
+          if subclass.nil?
+            if topic && !topic.blank?
+              subclass_name = Conversational::Conversation.topic_subclass_name(topic)
+              raise(
+                 ArgumentError,
+                "You have either not defined #{subclass_name} it does not subclass #{self.to_s}, or it has been excluded. You can either define #{subclass_name} as a subclass of #{self.to_s} or define an unknown_topic_subclass for #{self.to_s}"
+              )
+            else
+              raise(
+                 ArgumentError,
+                "You have not defined a blank_topic_subclass for #{self.to_s} so conversations without a topic are not allowed."
+              )
+            end
+          end
+          subclass.create!(:with => with, :topic => topic)
+        end
+      end
+    end
+  end
+end
+

data/lib/conversational/conversation.rb

@@ -0,0 +1,285 @@
+module Conversational
+  module Conversation
+
+    mattr_accessor :unknown_topic_subclass,
+                   :blank_topic_subclass,
+                   :parent,
+                   :class_suffix
+
+    def self.included(base)
+      self.parent = base
+      base.send(:include, InstanceMethods)
+      base.extend ClassMethods
+      if defined?(ActiveRecord::Base) && base <= ActiveRecord::Base
+        base.send(:include, ActiveRecordAdditions)
+      else
+        base.send(:include, InstanceAttributes)
+      end
+    end
+
+    module InstanceAttributes
+      attr_accessor :with, :topic
+
+      def initialize(options = {})
+        self.with = options[:with]
+        self.topic = options[:topic]
+      end
+    end
+
+    module InstanceMethods
+      # Returns the specific sublass of conversation based from the topic
+      # Example:
+      #
+      # <tt>
+      #   Class Conversation
+      #     include Conversational::Conversation
+      #   end
+      #
+      #   Class HelloConversation < Conversation
+      #   end
+      #
+      #   Class GoodbyeConversation < Conversation
+      #   end
+      #
+      #   hello = Conversation.new("someone", "hello")
+      #   hello.details => #<HelloConversation topic: "hello", with: "someone">
+      #
+      #   unknown = Conversation.new("someone", "cheese")
+      #   unknown.details => nil
+      #
+      #   Conversation.unknown_topic_subclass = HelloConversation
+      #
+      #   unknown = Conversation.new("someone", "cheese")
+      #   unknown.details => #<HelloConversation topic: "cheese", with: "someone">
+      #
+      #   blank = Conversation.new("someone")
+      #   blank.details => nil
+      #
+      #   Conversation.blank_topic_subclass = GoodbyeConversation
+      #
+      #   blank = Conversation.new("someone")
+      #   blank.details => #<GoodbyeConversation topic: nil, with: "someone">
+      #
+      #   Conversation.exclude HelloConversation
+      #
+      #   hello = Conversation.new("someone", "hello")
+      #   hello.details => nil
+      #
+      #   hello.details(:include_all => true) => #<HelloConversation topic: "hello", with: "someone">
+      #
+      # </tt>
+      def details(options = {})
+        details_subclass = Conversational::Conversation.find_subclass_by_topic(
+          topic, options
+        )
+        if details_subclass
+          self.respond_to?(:becomes) ?
+            becomes(details_subclass) :
+            Conversational::Conversation.becomes(
+              details_subclass, self
+            )
+        end
+      end
+
+      def topic_defined?
+        details_subclass = Conversational::Conversation.topic_defined?(topic)
+      end
+    end
+
+    module ClassMethods
+      def unknown_topic_subclass(value)
+        Conversational::Conversation.unknown_topic_subclass = value
+      end
+
+      def blank_topic_subclass(value)
+        Conversational::Conversation.blank_topic_subclass = value
+      end
+
+      def class_suffix(value)
+        Conversational::Conversation.class_suffix = value
+      end
+
+      # Register classes which will not be treated as conversations
+      # when you use #details or Conversation.find_or_create_with
+      #
+      # Example:
+      #
+      # Consider the following situation where you define AbstractConversation
+      # that MonkeyConversations inherits from. You want to work with MonkeyConversation
+      # but you never want to work with AbstractConversation directly.
+      #
+      # <tt>
+      #   class AbstractConversation < Conversation
+      #   end
+      #
+      #   class MonkeyConversation < AbstractConversation
+      #   end
+      #
+      #   class UnknownTopicConversation < AbstractConversation
+      #   end
+      #
+      #   class IncomingTextMessage < ActiveRecord::Base
+      #   end
+      #
+      #   class IncomingTextMessagesController < ApplicationController
+      #     def create
+      #       IncomingTextMessage.create(params[:message_text], params[:number])
+      #     end
+      #   end
+      # </tt>
+      #
+      # Now what happens when a user sends in a message like "monkey"
+      # <tt>
+      #   message = IncomingTextMessage.last
+      #   topic = message.text.split(" ").first
+      #   => "monkey"
+      #   number = message.number
+      #   => "123456789"
+      #   conversation = Conversation.new(:with => number, :topic => topic).details
+      #   => #<MonkeyConversation topic: "monkey", with: "123456789">
+      # </tt>
+
+      # No problem here you will work with MonkeyConversation directly. But what if
+      # the user sends in a message like "abstract"?
+      # <tt>
+      #   message = IncomingTextMessage.last
+      #   topic = message.text.split(" ").first
+      #   => "abstract"
+      #   number = message.number
+      #   => "123456789"
+      #   conversation = Conversation.new(:with => number, :topic => topic).details
+      #   => #<AbstractConversation topic: "abstract", with: "123456789">
+      # </tt>
+      # Now you're are about to work with AbstractConversation directly
+      # which is not what you want. Let's fix it
+      # <tt>
+      #   # config/initializers/conversation.rb
+      #   Conversation.exclude AbstractConversation
+      #   Conversation.unknown_topic_subclass = UnkownTopicConversation
+      # </tt>
+      #
+      # <tt>
+      #   message = IncomingTextMessage.last
+      #   topic = message.text.split(" ").first
+      #   => "abstract"
+      #   number = message.number
+      #   => "123456789"
+      #   conversation = Conversation.new(:with => number, :topic => topic).details
+      #   => #<UnknownTopicConversation topic: "abstract", with: "123456789">
+      # </tt>
+      #
+      # <tt>Conversation.exclude</tt> accepts the following
+      # * Class: <tt>Conversation.exclude AbstractConversation</tt>
+      # * Array: <tt>Conversation.exclude [AbstractConversation, OtherConversation]</tt>
+      # * Symbol: <tt>Conversation.exclude :abstract_conversation</tt>
+      # * String: <tt>Conversation.exclude "abstract_conversation"</tt>
+      # * Regexp: <tt>Conversation.exclude /abstract/i</tt>
+
+      def exclude(classes)
+        Conversational::Conversation.exclude(classes)
+      end
+    end
+
+    def self.topic_defined?(topic)
+      self.find_subclass_by_topic(
+        topic,
+        :exclude_blank_unknown => true
+      )
+    end
+
+    def self.find_subclass_by_topic(topic, options = {})
+      subclass = nil
+      if topic.nil? || topic.blank?
+        unless options[:exclude_blank_unknown]
+          subclass = blank_topic_subclass.constantize if blank_topic_subclass
+        end
+      else
+        project_class_name = self.topic_subclass_name(topic)
+        begin
+          project_class = project_class_name.constantize
+        rescue
+          project_class = nil
+        end
+        # the subclass has been defined
+        # check that it is a subclass klass
+        if project_class && project_class <= parent &&
+          (options[:include_all] || !self.exclude?(project_class))
+            subclass = project_class
+        else
+          unless options[:exclude_blank_unknown]
+            subclass = unknown_topic_subclass.constantize if unknown_topic_subclass
+          end
+        end
+      end
+      subclass
+    end
+
+    def self.exclude(classes)
+      if classes
+        if classes.is_a?(Array)
+          classes.each do |class_name|
+            check_exclude_options!(class_name)
+          end
+        else
+          check_exclude_options!(classes)
+        end
+      end
+      @@excluded_classes = classes
+    end
+
+    def self.topic_subclass_name(topic)
+      topic.classify + (class_suffix || parent).to_s
+    end
+
+    private
+
+    def self.becomes(klass, from)
+      klass_instance = klass.new
+      from.instance_variables.each do |instance_variable|
+        klass_instance.instance_variable_set(
+          instance_variable,
+          from.instance_variable_get(instance_variable)
+        )
+      end
+      klass_instance
+    end
+
+    def self.exclude?(subclass)
+      if defined?(@@excluded_classes)
+        if @@excluded_classes.is_a?(Array)
+          @@excluded_classes.each do |excluded_class|
+            break if exclude_class?(subclass)
+          end
+        else
+          exclude_class?(subclass)
+        end
+      end
+    end
+
+    def self.exclude_class?(subclass)
+      if @@excluded_classes.is_a?(Class)
+        @@excluded_classes == subclass
+      elsif @@excluded_classes.is_a?(Regexp)
+        subclass.to_s =~ @@excluded_classes
+      else
+        excluded_class = @@excluded_classes.to_s
+        begin
+          excluded_class.classify.constantize == subclass
+        rescue
+          false
+        end
+      end
+    end
+
+    def self.check_exclude_options!(classes)
+      raise(
+        ArgumentError,
+        "You must specify an Array, Symbol, Regex, String or Class or nil. You specified a #{classes.class}"
+      ) unless classes.is_a?(Symbol) ||
+          classes.is_a?(Regexp) ||
+          classes.is_a?(String) ||
+          classes.is_a?(Class)
+    end
+  end
+end
+