conversational 0.3.0

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/active_record_additions.rb

@@ -0,0 +1,121 @@
+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 = ConversationDefinition.find_subclass_by_topic(topic)
+          if subclass.nil?
+            if topic && !topic.blank?
+              subclass_name = ConversationDefinition.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,188 @@
+module Conversational
+  module Conversation
+    def self.included(base)
+      base.extend ClassMethods
+      ConversationDefinition.klass = base
+      if defined?(ActiveRecord::Base) && base <= ActiveRecord::Base
+        base.send(:include, ActiveRecordAdditions)
+      else
+        base.send(:include, InstanceAttributes)
+      end
+    end
+
+    # 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 = ConversationDefinition.find_subclass_by_topic(
+        topic, options
+      )
+      self.becomes(details_subclass) if details_subclass
+    end
+
+    protected
+      # Called from a subclass to deliver the message
+      def say(message)
+        ConversationDefinition.notification.call(with, message)
+      end
+
+    module InstanceAttributes
+      attr_accessor :with, :topic
+      
+      def initialize(options = {})
+        self.with = options[:with]
+        self.topic = options[:topic]
+      end
+      
+    end
+
+    module ClassMethods
+      def unknown_topic_subclass=(klass)
+        ConversationDefinition.unknown_topic_subclass = klass
+      end
+      
+      def unknown_topic_subclass
+        ConversationDefinition.unknown_topic_subclass
+      end
+      
+      def blank_topic_subclass=(klass)
+        ConversationDefinition.blank_topic_subclass = klass
+      end
+      
+      def blank_topic_subclass
+        ConversationDefinition.blank_topic_subclass
+      end
+
+      # Register a service for sending notifications
+      #
+      # Example:
+      #
+      # <tt>
+      #   Conversation.converse do |with, message|
+      #     OutgoingTextMessage.create!(with, message).send
+      #   end
+      # </tt>
+      def converse(&blk)
+        ConversationDefinition.notification = blk
+      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)
+        ConversationDefinition.exclude(classes)
+      end
+    end
+  end
+end

data/lib/conversational/conversation_definition.rb

@@ -0,0 +1,86 @@
+module Conversational
+  class ConversationDefinition
+    cattr_accessor :unknown_topic_subclass
+    cattr_accessor :blank_topic_subclass
+    cattr_accessor :notification
+    cattr_writer   :klass
+
+    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.find_subclass_by_topic(topic, options = {})
+      subclass = nil
+      if topic.nil? || topic.blank?
+        subclass = blank_topic_subclass if blank_topic_subclass
+      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 <= @@klass &&
+          (options[:include_all] || !self.exclude?(project_class))
+            subclass = project_class
+        else
+          subclass = unknown_topic_subclass if unknown_topic_subclass
+        end
+      end
+      subclass
+    end
+
+    def self.topic_subclass_name(topic)
+      topic.classify + @@klass.to_s
+    end
+    
+    private
+      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

data/lib/conversational.rb

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

data/lib/generators/conversational/migration/USAGE

@@ -0,0 +1,5 @@
+Description:
+  Creates a migration file for when you want to use Conversation with ActiveRecord
+
+Example:
+  rails g conversation:migration

data/lib/generators/conversational/migration/migration_generator.rb

@@ -0,0 +1,23 @@
+require 'rails/generators'
+require 'rails/generators/migration'
+module Conversational
+  class MigrationGenerator < Rails::Generators::Base
+    include Rails::Generators::Migration
+
+    def self.source_root
+       @source_root ||= File.join(File.dirname(__FILE__), 'templates')
+    end
+
+    def self.next_migration_number(dirname)
+      if ActiveRecord::Base.timestamped_migrations
+        Time.now.utc.strftime("%Y%m%d%H%M%S")
+      else
+        "%.3d" % (current_migration_number(dirname) + 1)
+       end
+    end
+
+    def create_migration_file
+      migration_template 'migration.rb', 'db/migrate/create_conversations.rb'
+    end
+  end
+end

data/lib/generators/conversational/migration/templates/migration.rb

@@ -0,0 +1,14 @@
+class CreateConversations < ActiveRecord::Migration
+  def self.up
+    create_table :conversations do |t|
+      t.string :with, :null => false
+      t.string :state
+      t.string :topic
+      t.timestamps
+    end
+  end
+  
+  def self.down
+    drop_table :conversations
+  end
+end

data/lib/generators/conversational/skeleton/USAGE

@@ -0,0 +1,6 @@
+Description:
+  Creates a blank Conversation class and a directory to store your conversations
+  under app/conversations
+
+Example:
+  rails g conversation:skeleton

data/lib/generators/conversational/skeleton/skeleton_generator.rb

@@ -0,0 +1,17 @@
+require 'rails/generators'
+module Conversational
+  class SkeletonGenerator < Rails::Generators::Base
+
+    def self.source_root
+       @source_root ||= File.join(File.dirname(__FILE__), 'templates')
+    end
+
+    def create_conversations_directory
+      empty_directory "app/conversations"
+    end
+
+    def copy_conversation_file
+      copy_file "conversation.rb", "app/conversations/conversation.rb"
+    end
+  end
+end

data/lib/generators/conversational/skeleton/templates/conversation.rb

@@ -0,0 +1,3 @@
+class Conversation
+  include Conversational::Conversation
+end