conversational 0.3.0

data/.gitignore

@@ -0,0 +1,8 @@
+.bundle
+db/*.sqlite3
+log/*.log
+tmp/**/*
+config/database.yml
+*~
+config/initializers/ebay_config*
+rerun.txt

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2010 David Wilkie
+
+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.markdown

@@ -0,0 +1,239 @@
+# Conversational
+
+Conversational makes it easier to accept incoming text messages (SMS) and respond to them in your application. You could also use Conversational to respond to incoming email or IM.
+
+Conversational allows you to have have *stateful* or *stateless* interactions with your users.
+
+## Stateless Conversations
+
+This is the most common way of dealing with incoming messages in SMS apps. Stateless conversations don't know anything about a previous request and therefore require you to text in an explicit command. Let's look at an example:
+
+Say you have an application which allows you to interact with Facebook over SMS. You want be able to write on on your friends wall and change your status by sending an SMS to your app. You also want to receive SMS alerts when a friend writes on your wall or you have a new friend request.
+
+Let's tackle the incoming messages first.
+
+### Incoming Text Messages
+
+Say your commands are:
+
+*  us is ready for a beer
+*  wow johnny wanna go 4 a beer?
+
+Where "us" is update status and "wow" is write on wall
+
+Assuming you have set up a controller in your application to accept the incoming text messages when they are posted from your SMS gateway you could use Conversational as follows:
+
+    class Conversation
+      include Conversational::Conversation
+      converse do |with, message|
+        OutgoingTextMessage.send(with, message)
+      end
+    end
+
+    class UsConversation < Conversation
+      def move_along(message)
+        # code to update status
+        say "Successfully updated your status"
+      end
+    end
+
+    class WowConversation < Conversation
+      def move_along(message)
+        # Code to write on wall
+        say "Successfully wrote on wall"
+      end
+    end
+
+    class IncomingTextMessageController
+      def create
+        message = params[:message]
+        topic = params[:message].split(" ").first
+        number = params[:number]
+        Conversation.new(:with => number, :topic => topic).details.move_along(message)
+      end
+    end
+
+There's quite a bit going on here so let's have a bit more of a look.
+
+In the controller a new Conversation is created with the number of the incoming message and the topic as the first word of the text message. In our case the topic will be either "us" or "wow". Calling `details` on an instance of Conversation will try and return an instance of a class in your project that subclasses your main Conversation class and has the same name as the topic. In our case our main Conversation class *is* called Conversation so a topic of "us" will map to `UsConversation`. Similarly "wow" maps to `WowConversation`. So say we text in "us is ready for a beer" an instance of `UsConversation` is returned and move_along is then called on the instance.
+
+Inside our subclassed conversations there is a method available to us called `say`. Say simple executes the converse block you set up inside your main Conversation class.In our case this will call `OutgoingTextMessage.send` passing in the number and the message. Obviously this example doesn't contain any error checking. If we text in something starting with other than "us" or "wow" we'll get an error because `details` will return nil and `move_along` will be called on `nil`
+
+### Outgoing Text Messages
+
+To handle your Facebook alerts you can simply make use of Conversation's `say` method: You might do something like this:
+
+    class FacebookAlert < Conversation
+      def wrote_on_wall(facebook_notification)
+        # Code to get the wall details
+        say "Someone wrote on your wall..."
+      end
+
+      def friend_request(facebook_notification)
+        # Code to get the name of the person who befriended you
+        say "You have a new friend request from ..."
+      end
+    end
+
+Then when you get a facebook alert simply do either:
+    
+    FacebookAlert.new(:with => "your number").wrote_on_wall(facebook_notification)
+    FacebookAlert.new(:with => "your number").friend_request(facebook_notification)
+
+## Stateful Conversations
+
+Conversational also allows you to have *stateful* conversations. A stateful conversation knows about prevous interactions and therefore allows you to respond differently. Note this is currently only supported in Rails.
+
+Let's build on the prevous example using stateful conversations.
+
+Our application so far is *stateless*. Currently if we get a friend request we have no way of accepting or rejecting it. If we were to continue building a stateless application we would simple add a couple of new commands such as:
+
+* "afr &lt;friend&gt;"
+* "rfr &lt;friend&gt;"
+where "afr" is accept friend request and "rfr" is reject friend request.
+
+But instead of doing that let's allow us to respond to a friend request notification with yes or no.
+
+So we'll change our existing friend request alert to: "You have a new friend request from Johnnie Cash. Do you want to accept? Text yes or no."
+
+With the current stateless implementation if they text "yes" then `details` will look to see if `YesConversation` is defined in our project, won't be able to find and return `nil` So here's how to make our application stateful.
+
+    class Conversation < ActiveRecord::Base
+      include Conversational::Conversation
+      converse do |with, message|
+        OutgoingTextMessage.send(with, message)
+      end
+      protected
+        def finish
+          state = "finished"
+          self.save!
+        end
+    end
+
+    class IncomingTextMessageController
+      def create
+        message = params[:message]
+        topic = params[:message].split(" ").first
+        number = params[:number]
+        Conversation.find_or_create_with(number, topic).move_along(message)
+      end
+    end
+
+    class FacebookAlertConversation < Conversation
+      def move_along(message)
+        if message == "yes"
+          # code to accept friend request
+          say "You successfully accepted the friend request"
+        elsif message == "no"
+          # say "You successfully rejected the friend request"
+        else
+          say "Invalid response. Reply with yes or no"
+        end
+        finish
+      end
+
+      def friend_request(facebook_notification)
+        # Code to get the name of the person who befriended you
+        say "You have a new friend request from ...Do you want to accept? Text yes or no."
+      end
+    end
+
+The first change you'll notice is that our Conversation base class now extends from ActiveRecord::Base. This does a couple of things. But first we will need a migration file (which can be generated with `rails g conversational:migration`). Once we have that we can simply migrate our database `rake db:migrate`. Extending from ActiveRecord::Base adds a couple of methods for us which i'll describe in some more detail later. For our example we only care about one of them.
+
+Jumping over to our controller you can see that now we are calling `Conversation.find_or_create_with` This method was added when we extended Conversation from ActiveRecord::Base. The method tries to return the last *recent*, *open* conversation with this number. By *open* we mean that it's state is *not* finished and by *recent* we mean that it was updated within the last 24 hours. More on how you can override this later. If it finds one it will return an instance of this conversation subclass. If it doesn't it will create a new conversation with the topic specified and return it as an instance of its subclass (just like `details`).
+
+Now take a look at our `FacebookAlert` class. The first thing is that we renamed it to `FacebookAlertConversation`. This is important so that it is now recognised as a type of conversation.
+
+There is also a new method `move_along` which looks at the message to see if the user replied with "yes" or "no" and responds appropriately. Notice it also calls `finish`. 
+
+If we jump back and take a look at our main Conversation class we see that `finish` marks the conversation state as finished so it will be found by `find_or_create_with` It is important that you remember to call `finish` on all conversations where you don't expect a response.
+
+So how does this all tie together?
+
+The application receives an alert from Facebook with a new friend request and calls:
+
+    FacebookAlert.create!(
+      :with => "your number", :topic => "facebook_alert"
+    ).friend_request(facebook_notification)
+
+This sends the following message to you: "You have a new friend request from...Do you want to accept? Text yes or no."
+
+Notice that it calls `create!` and *not* `new` as we want to save this conversation. Also notice that topic is set to "facebook_alert" which is the name of the class minus "Conversation". This is important so `find_or_create_with` can find the conversation. Also notice that `friend_request` does *not* call finish. This conversation isn't over yet!
+
+Now sometime later you reply with "yes". The controller calls
+`Conversation.find_or_create_with` which finds your open conversation and returns the an instance as a `FacebookAlertConversation`
+
+The controller then calls `move_along` on this conversation which looks at your message, sees that you replied with "yes" and replies with "You successfully accepted the friend request". It also calls `finish` which marks the conversation as finished, so that next time you text something in it won't find any open conversations.
+
+There are still a few more things we need to do in order to make this application work properly. Right now if we text in something other than "us", "wow" or "yes" we will get an exception. Let's fix it in the following section
+
+## Configuration
+
+In our example application we are responding to requests based on the first word of their text message. But what if they text in something unknown to us or they text in something blank?
+
+You can configure Conversation to deal with this situation as follows:
+
+    class Conversation
+      unknown_topic_subclass = UnknownTopicNotification
+      blank_topic_subclass = BlankTopicNotification
+    end
+
+    class UnknownTopicNotification < Conversation
+      def move_along
+        say "Sorry. Unknown Command"
+      end
+    end
+
+    class BlankTopicNotification < Conversation
+      def move_along
+        say "Hey. What do you want?"
+      end
+    end
+
+Now when the user texts in with "hey jonnie", `details` will try and find a conversation defined as `HeyConversation`, won't be able to find it and will return an instance of `UnknownTopicConversation`
+
+`move_along` then causes a message to be sent saying "Sorry. Unknown Command."
+
+The same thing happens for a blank conversation.
+
+There is one more subtle issue with our application. What if a user texts in "facebook_alert"? The reply will be: "Invalid response. Reply with yes or no" when it should be "Sorry. Unknown Command". This is because if `find_or_create_with` cannot find an existing conversation it will try and create one with the topic "facebook_alert" if `FacebookAlertConversation` is defined in our application (which it is). To solve this prolem we can use `exclude`
+
+    class Conversation
+      exclude FacebookAlertConversation
+    end
+
+## Overriding Defaults
+
+When you extend your base conversation class from ActiveRecord::Base in addition to `find_or_create_with` you will also get the following class methods:
+
+`converser("someone")` returns all conversations with "someone"
+
+`in_progress` returns all conversations that are not "finished".
+
+`recent(time)` returns all conversations in the last *time* or within the last 24 if *time* is not suppied
+
+`with("someone")` a convienience method for `converse("someone").in_progress.recent`
+
+
+## Installation
+
+Add the following to your Gemfile: `gem "conversational"`
+
+## Setup
+
+`rails g conversational:skeleton`
+Generates a base conversation class under app/conversations
+
+`rails g conversational:migration`
+Generates a migration file if you want to use Conversational with Rails
+
+## More Examples
+
+Here's an [example](http://github.com/dwilkie/drinking) *stateful* conversation app  about drinking
+
+## Notes
+
+Conversational is compatible with Rails 3
+To use with Rails 2.3.x you must install Conversation version 0.1.0 which is an old and obsolete version.
+
+Copyright (c) 2010 David Wilkie, released under the MIT license

data/Rakefile

@@ -0,0 +1,38 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the conversational plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'spec'
+  t.libs << 'features'
+  t.pattern = 'spec/**/*_spec.rb'
+  t.verbose = true
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "conversational"
+    gemspec.summary = "Have conversations with your users over SMS"
+    gemspec.email = "dwilkie@gmail.com"
+    gemspec.homepage = "http://github.com/dwilkie/conversational"
+    gemspec.authors = ["David Wilkie"]
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: gem install jeweler"
+end
+
+desc 'Generate documentation for the conversational plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Conversational'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+

data/VERSION

@@ -0,0 +1 @@
+0.3.0

data/conversational.gemspec

@@ -0,0 +1,78 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{conversational}
+  s.version = "0.3.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["David Wilkie"]
+  s.date = %q{2010-06-01}
+  s.email = %q{dwilkie@gmail.com}
+  s.extra_rdoc_files = [
+    "README.markdown"
+  ]
+  s.files = [
+    ".gitignore",
+     "MIT-LICENSE",
+     "README.markdown",
+     "Rakefile",
+     "VERSION",
+     "conversational.gemspec",
+     "features/configure_blank_topic.feature",
+     "features/configure_exclusion_conversations.feature",
+     "features/configure_unknown_topic.feature",
+     "features/find_existing_conversation.feature",
+     "features/find_or_create_with.feature",
+     "features/retrieve_conversation_details.feature",
+     "features/step_definitions/conversation_steps.rb",
+     "features/step_definitions/pickle_steps.rb",
+     "features/support/conversation.rb",
+     "features/support/email_spec.rb",
+     "features/support/env.rb",
+     "features/support/mail.rb",
+     "features/support/paths.rb",
+     "features/support/pickle.rb",
+     "features/support/sample_conversation.rb",
+     "lib/conversational.rb",
+     "lib/conversational/active_record_additions.rb",
+     "lib/conversational/conversation.rb",
+     "lib/conversational/conversation_definition.rb",
+     "lib/generators/conversational/migration/USAGE",
+     "lib/generators/conversational/migration/migration_generator.rb",
+     "lib/generators/conversational/migration/templates/migration.rb",
+     "lib/generators/conversational/skeleton/USAGE",
+     "lib/generators/conversational/skeleton/skeleton_generator.rb",
+     "lib/generators/conversational/skeleton/templates/conversation.rb",
+     "spec/active_record_additions_spec.rb",
+     "spec/conversation_definition_spec.rb",
+     "spec/conversation_spec.rb",
+     "spec/spec_helper.rb",
+     "spec/support/conversation.rb"
+  ]
+  s.homepage = %q{http://github.com/dwilkie/conversational}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.6}
+  s.summary = %q{Have conversations with your users over SMS}
+  s.test_files = [
+    "spec/conversation_spec.rb",
+     "spec/active_record_additions_spec.rb",
+     "spec/conversation_definition_spec.rb",
+     "spec/spec_helper.rb",
+     "spec/support/conversation.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end
+

data/features/configure_blank_topic.feature

@@ -0,0 +1,9 @@
+Feature: Specify a blank conversation topic template
+  In order to converse when the topic is blank
+  As a Conversation user
+  I want to be able to specify a conversation template to use when the topic is blank
+  
+  Scenario: Specify a blank conversation topic
+    Given I configured Conversation with the following: Conversation.blank_topic_subclass = SampleConversation
+    When I start up a conversation with an blank topic
+    Then the conversation details should be a SampleConversation

data/features/configure_exclusion_conversations.feature

@@ -0,0 +1,20 @@
+Feature: Configure exclusion conversations
+  In order to allow conversations to exist in a project that should not be found
+           when using Conversation.details or Conversation.find_or_create_with
+  As a Conversation user
+  I want to be able to configure which conversations should be excluded
+  
+  Scenario Outline: Configure exclusion conversations
+    Given I configured Conversation with the following: <configuration>
+    And a conversation exists with topic: "sample", with: "someone@example.com"
+    Then the conversation details should be nil
+
+    Examples:
+      | configuration                                                              |
+      | Conversation.exclude [SampleConversation]                                  |
+      | Conversation.exclude SampleConversation                                    |
+      | Conversation.exclude "sample_conversation"                                 |
+      | Conversation.exclude "SampleConversation"                                  |
+      | Conversation.exclude :sample_conversation                                  |
+      | Conversation.exclude /sample/i                                             |
+      | Conversation.exclude [/sample/, "sample_conversation", SampleConversation] |

data/features/configure_unknown_topic.feature

@@ -0,0 +1,9 @@
+Feature: Specify an unknown conversation topic template
+  In order to converse when the topic is unknown
+  As a Conversation user
+  I want to be able to specify a conversation template to use when the topic is unknown
+
+  Scenario: Specify an unknown conversation topic
+    Given I configured Conversation with the following: Conversation.unknown_topic_subclass = SampleConversation
+    When I start up a conversation with an unknown topic
+    Then the conversation details should be a SampleConversation

data/features/find_existing_conversation.feature

@@ -0,0 +1,21 @@
+Feature: Find existing conversations
+  In order to find an active conversation with a user
+  As a Conversation user
+  I want to be able to find the conversation easily
+
+  Background:
+    Given a conversation exists with topic: "sample", with: "someone@example.com"
+
+  Scenario: Find an open conversation updated within the last 24 hours
+    Given 23 hours have elapsed since the conversation was last updated
+    Then I should be able to find a conversation with: "someone@example.com"
+
+  Scenario: Find an open conversation updated more than that 24 hours
+    Given 24 hours have elapsed since the conversation was last updated
+    Then I should not be able to find a conversation with: "someone@example.com"
+
+  Scenario: Find a finished conversation
+    Given 1 hour has elapsed since the conversation was last updated
+    And the conversation is finished
+    Then I should not be able to find a conversation with: "someone@example.com"
+

data/features/find_or_create_with.feature

@@ -0,0 +1,33 @@
+Feature: Find existing conversation or create a new one
+  In order to easily create a new conversation if an existing one cannot be found
+  As a Conversation user
+  I want to be able to call find_or_create_with supplying who with and the topic
+
+  Scenario: No conversations exist
+    Given no conversations exist with: "someone"
+    When I call find_or_create_with("someone", "sample")
+    Then a conversation should exist with topic: "sample", with: "someone"
+
+  Scenario: A recent conversation exists
+    Given a conversation exists with topic: "sample", with: "someone"
+    When I call find_or_create_with("someone", "sample")
+    Then 1 conversations should exist
+
+  Scenario: An old conversation exists
+    Given a conversation exists with topic: "sample", with: "someone"
+    And 24 hours have elapsed since the conversation was last updated
+    When I call find_or_create_with("someone", "sample")
+    Then 2 conversations should exist
+
+  Scenario: An finished conversation exists
+    Given a conversation exists with topic: "sample", with: "someone"
+    And the conversation is finished
+    When I call find_or_create_with("someone", "sample")
+    Then 2 conversations should exist
+  
+  Scenario: No conversation exists and the subclass has been excluded
+    Given a conversation exists with topic: "sample", with: "someone"
+    And I configured Conversation with the following: Conversation.exclude [SampleConversation]
+    When I call find_or_create_with("someone", "sample")
+    Then 1 conversations should exist
+

data/features/retrieve_conversation_details.feature

@@ -0,0 +1,13 @@
+Feature: Get the conversation specifics
+  In order to get the specific conversation based on the topic and then move it along
+  As a Conversation user
+  I want to be able to get the specific conversation from the general one based off the topic
+
+  Scenario: Get the details from a conversation instance
+    Given a conversation exists with topic: "sample", with: "someone@example.com"
+    Then the conversation details should be a SampleConversation
+
+  Scenario: Get the details from a conversation instance
+    Given a conversation exists with topic: "sample", with: "someone@example.com"
+    And I configured Conversation with the following: Conversation.exclude [SampleConversation]
+    Then conversation.details(:include_all => true) should be a SampleConversation

data/features/step_definitions/conversation_steps.rb

@@ -0,0 +1,60 @@
+Given /^(an|\d+) hours? (?:has|have) elapsed since #{capture_model} was last updated$/ do |time, conversation|
+  conversation = model!(conversation)
+  time = parse_email_count(time)
+  Conversation.record_timestamps = false
+  conversation.updated_at = time.hours.ago
+  conversation.save!
+  Conversation.record_timestamps = true
+end
+
+Given /^#{capture_model} is (.+)$/ do |conversation, state|
+  conversation = model!(conversation)
+  conversation.state = state
+  conversation.save!
+end
+
+Given /^no conversations exist with: "([^\"]*)"/ do |with|
+  find_models("conversation", "with: \"#{with}\"").each do |instance|
+    instance.destroy
+  end
+end
+
+Given /^I configured Conversation with the following: (.+)$/ do |configuration|
+  instance_eval(configuration)
+end
+
+When /^I start a new conversation(?: with #{capture_fields})?$/ do |fields|
+  
+end
+
+When /^I call find_or_create_with\("([^\"]*)", "([^\"]*)"\)$/ do |with, topic|
+  Conversation.find_or_create_with(with, topic)
+end
+
+When /^I start up a conversation with an? (blank|unknown) topic$/ do |template_type|
+  topic = ""
+  topic = "unknown" if template_type == "unknown"
+  Given "a conversation exists with topic: \"#{topic}\", with: \"someone\""
+end
+
+Then /^the conversation details should be a (\w+)$/ do |template_name|
+  model!("conversation").details.class.should == template_name.constantize
+end
+
+Then /^I should (not )?be able to find a conversation with: "([^\"]*)"$/ do |negative, with|
+  conversation = Conversation.with(with).last
+  unless negative
+    conversation.should == model!("conversation")
+  else
+   conversation.should be_nil
+  end
+end
+
+Then /^#{capture_model} details should (?:be|have) (?:an? )?#{capture_predicate}$/ do |name, predicate|
+  model!(name).details.should send("be_#{predicate.gsub(' ', '_')}")
+end
+
+Then /^conversation\.details\(:include_all => true\) should be a SampleConversation$/ do
+  model!("conversation").details(:include_all => true).class.should == SampleConversation
+end
+

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'