chatterbot 0.2.0

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/.gitignore

@@ -0,0 +1,52 @@
+Gemfile.lock
+
+# rcov generated
+coverage
+
+# rdoc generated
+rdoc
+
+# yard generated
+doc
+.yardoc
+
+# bundler
+.bundle
+
+# jeweler generated
+pkg
+
+# Have editor/IDE/OS specific files you need to ignore? Consider using a global gitignore: 
+#
+# * Create a file at ~/.gitignore
+# * Include files you want ignored
+# * Run: git config --global core.excludesfile ~/.gitignore
+#
+# After doing this, these files will be ignored in all your git projects,
+# saving you from having to 'pollute' every project you touch with them
+#
+# Not sure what to needs to be ignored for particular editors/OSes? Here's some ideas to get you started. (Remember, remove the leading # of the line)
+#
+# For MacOS:
+#
+#.DS_Store
+
+# For TextMate
+#*.tmproj
+#tmtags
+
+# For emacs:
+#*~
+#\#*
+#.\#*
+
+# For vim:
+#*.swp
+
+# For redcar:
+#.redcar
+
+# For rubinius:
+#*.rbc
+
+examples/*.yml

data/Gemfile

@@ -0,0 +1,25 @@
+source :rubygems
+gemspec
+
+#gem "twitter_oauth"
+#gem "sequel"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "shoulda", ">= 0"
+  gem "rspec"
+
+  gem "bundler", "~> 1.0.0"
+  gem "rcov"
+  gem "watchr"
+end
+
+#
+# couple extra gems for testing db connectivity
+#
+group :test do
+  gem "sequel"
+  gem "mysql"
+  gem "sqlite3"
+end

data/LICENSE.txt

@@ -0,0 +1,17 @@
+DO WHAT THE FUCK YOU WANT TO -- BUT DON'T BE AN ASSHOLE PUBLIC LICENSE
+
+   Version 1, May 2011
+
+Copyright (C) 2011 Colin Mitchell <colin@muffinlabs.com>
+Derived from WTFPL, Copyright (C) 2004 Sam Hocevar <sam@hocevar.net>
+
+ Everyone is permitted to copy and distribute verbatim or modified
+ copies of this license document, and changing it is allowed as long
+ as the name is changed.
+
+ DO WHAT THE FUCK YOU WANT TO -- BUT DON'T BE AN ASSHOLE PUBLIC LICENSE
+ TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. You just DO WHAT THE FUCK YOU WANT TO.
+  1. Don't be an asshole. Really.
+

data/README.rdoc

@@ -0,0 +1,184 @@
+= Chatterbot
+
+Chatterbot is a Ruby library for making bots on Twitter.  It is basic
+enough that you can put it into use quickly, but can be used to make
+pretty involved bots. It handles searches, replies and tweets, and has
+a simple blacklist system to help keep you from spamming people who
+don't want to hear from your bot.
+
+== A quick list of features:
+
+* Works via Twitter's OAuth system.
+* Handles search queries and replies to your bot
+* Use a simple DSL, or extend a Bot class if you need it
+* Simple blacklistling system to limit your annoyance of users
+* Optionally log tweets to the database for metrics and tracking purposes
+
+== Using Chatterbot
+
+=== Make a Twitter account
+
+First thing you'll need to do is create an account for your bot on
+Twitter.  That's the easy part.
+
+=== Write your bot
+
+Chatterbot has a very simple DSL inspired by Sinatra and Twibot, an
+earlier Twitter bot framework.  Here's an example, based on @dr_rumack
+on Twitter (http://twitter.com/#!/Dr_Rumack):
+
+  require 'chatterbot/dsl'
+  search("'surely you must be joking'") do |tweet|
+    reply "@#{tweet_user(tweet)} I am serious, and don't call me Shirley!", tweet
+  end
+
+Or, you can create a bot object yourself, extend it if needed, and use
+it like so:
+
+  bot = Chatterbot::Bot.new
+  bot.search("'surely you must be joking'") do |tweet|
+   bot.reply "@#{tweet_user(tweet)} I am serious, and don't call me Shirley!", tweet
+  end
+
+That's it!
+
+=== Authorize your bot
+
+If you only want to use Chatterbot to search for tweets, it will work
+out of the box without any authorization.  However, if you want to
+reply to tweets, or check for replies to your bot, you will have to
+jump through a few authorization hoops with Twitter. The very
+first time you want to setup a bot, you will need to register an
+application with Twitter.  Twitter requires all API communication to be via an
+app which is registered on Twitter. I would set one up and make it
+part of Chatterbot, but unfortunately Twitter doesn't allow developers
+to publicly post the OAuth consumer key/secret that you would need to
+use.  If you're planning to run more than one bot, you only need to do
+this step once -- you can use the same app setup for other bots too.
+
+Chatterbot will walk you through what is needed to get this setup.  If
+you run your bot without having an app setup, it will prompt you with
+the instructions. Here's the instructions if you want to do it yourself:
+
+1. Setup your own app on Twitter at this URL https://twitter.com/apps/new
+2. Choose 'Client' as the app type
+3. Choose 'Read & Write' access unless you don't need to send tweets.
+4. Take the consumer key/consumer secret values, and either run your
+   bot, and enter them in when prompted, or store them in a config
+   file for your bot. (See below for details on this).  It should look
+   like this:
+
+  --- 
+  :consumer_secret: CONSUMER SECRET GOES HERE
+  :consumer_key: CONSUMER KEY GOES HERE
+
+Chatterbot will point you at the URL in Step #1, then ask for the
+same values as in Step #4.
+
+Once this is done, you will need to setup authorization for the actual
+bot with Twitter. At the first run, you'll get a message asking you to go
+to a Twitter URL, where you can authorize the bot to post messages for
+your account or not.  If you accept, you'll get a PIN number back.
+You need to copy this and paste it back into the prompt for the
+bot. Hit return, and you should be all set.
+
+This is obviously a bunch of effort, but once you're done, you're
+ready to go!
+
+=== Configuration
+
+Chatterbot offers a couple different methods of storing the config for
+your bot:
+
+1. In a YAML file with the same name as the bot, so if you have
+   botname.rb or a Botname class, store your config in botname.yaml
+2. In a global config file at <tt>/etc/chatterbot.yml</tt> -- values stored here
+   will apply to any bots you run.
+3. In another global config file specified in the environment variable
+   <tt>'chatterbot_config'</tt>.
+4. In a <tt>global.yml</tt> file in the same directory as your bot.  This
+   gives you the ability to have a global configuration file, but keep
+   it with your bots if desired.
+5. In a database.  You can store your configuration in a DB, and then
+   specify the connection string either in one of the global config
+   files, or on the command-line by using the <tt>--db="db_uri"</tt>
+   configuration option.  Any calls to the database are handled by the
+   Sequel gem, and MySQL and Sqlite should work.  The DB URI should
+   be in the form of <tt>mysql://username:password@host/database</tt> -- see
+   http://sequel.rubyforge.org/rdoc/files/doc/opening_databases_rdoc.html
+   for details.
+
+=== Running Your Bot
+
+There's a couple ways of running your bot:
+
+Run it on the command-line whenever you like. Whee!
+
+Run it via cron.  Here's an example of running a bot every two minutes
+
+  */2 * * * * . ~/.bash_profile; cd /path/to/bot/;  ./bot.rb
+
+Run it as a background process.  Just put the guts of your bot in a loop like this:
+  loop do
+    replies do |tweet|
+      # do stuff
+    end
+
+    sleep 60
+  end
+
+=== Database logging
+
+Chatterbot can log tweet activity to the database if desired.  This
+can be handy for tracking what's going on with your bot.  See
+<tt>Chatterbot::Logging</tt> for details on this.
+
+
+=== Blacklists
+
+Not everyone wants to hear from your bot.  To keep annoyances to a
+minimum, Chatterbot has a global blacklist option, as well as
+bot-specific blacklists if desired.  The global blacklist is stored in
+the database, and you can add entries to it by using the
+<tt>chatterbot-blacklist</tt> script included with the gem.
+
+You can also specify users to skip as part of the DSL:
+
+  require 'chatterbot'
+  blacklist "mean_user, private_user"
+
+There's also an 'exclude' method which can be used to add
+words/phrases you might want to ignore -- for example, if you wanted
+to ignore tweets with links, you could do something like this:
+
+  exclude "http://"
+
+== TODO
+
+* A skeleton bot generator
+* web-based frontend for tracking bot activity
+* opt-out system that adds people to blacklist if they reply to a bot
+  in the right way
+
+== Contributing to Chatterbot
+
+Since this code is based off of actual Twitter bots, it's mostly
+working the way I want it to, and I might prefer to keep it that way.
+But please, if there are bugs or things you would like to improve,
+fork the project and hack away.  I'll pull anything back that makes
+sense if requested.
+
+
+== Copyright/License
+
+Copyright (c) 2011 Colin Mitchell. Chatterbot is distributed under a
+modified WTFPL licence -- it's the 'Do what the fuck you want to --
+but don't be an asshole' public license.  Please see LICENSE.txt for
+further details. Basically, do whatever you want with this code, but
+don't be an asshole about it.  If you spam users inappropriately,
+expect your karma to suffer.
+
+
+http://muffinlabs.com
+
+

data/Rakefile

@@ -0,0 +1,26 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require "chatterbot/version"
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov_opts = %w{--exclude .bundler,.rvm}
+  spec.rcov = true
+end
+
+task :default => :spec
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  rdoc.main = "README.rdoc"
+  rdoc.rdoc_files.include("README.rdoc", "lib/**/*.rb")
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "'chatterbot #{Chatterbot::VERSION}'"
+end

data/bin/chatterbot-blacklist

@@ -0,0 +1,63 @@
+#!/usr/bin/env ruby
+$LOAD_PATH.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+
+require 'chatterbot'
+require 'optparse'
+
+include Chatterbot::Helpers
+include Chatterbot::Blacklist
+include Chatterbot::Config
+include Chatterbot::DB
+include Chatterbot::Logging
+
+@display_blacklist = false
+
+#
+# pull in any arguments and set them as env variables
+#
+opts = OptionParser.new
+opts.banner = "Usage: #{File.basename($0)} [options]"
+
+opts.separator ""
+opts.separator "Specific options:" 
+
+opts.on('-d', '--db [ARG]', "Specify a DB connection URI")    { |d| ENV["chatterbot_db"] = d }
+opts.on('-c', '--config [ARG]', "Specify a config file to use")    { |c| ENV["chatterbot_config"] = c }
+opts.on('-p', '--print', "Print out the current blacklist")    { @display_blacklist = true }
+opts.on_tail("-h", "--help", "Show this message") do
+  puts opts
+  exit
+end      
+
+extra = opts.parse!(ARGV)
+
+if ! has_db?
+  puts "You need to specify a db connection!"
+  exit
+end
+
+
+if @display_blacklist
+  db[:blacklist].each do |u|
+    puts u.inspect
+  end
+  
+elsif extra.empty?
+  #
+  # iterate through STDIN and add anything to the blacklist.  nothing too shiny here.
+  #
+  $stdin.each_line do |l|
+    add_to_blacklist(l.chomp)
+  end 
+else
+  #
+  # add any users specified on the command-line
+  #
+  extra.each do |l|
+    add_to_blacklist(l.chomp)
+  end  
+  
+end
+
+
+

data/chatterbot.gemspec

@@ -0,0 +1,53 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "chatterbot/version"
+
+Gem::Specification.new do |s|
+  s.name = %q{chatterbot}
+  s.version     = Chatterbot::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors = ["Colin Mitchell"]
+  s.email = %q{colin@muffinlabs.com}
+  s.homepage = %q{http://github.com/muffinista/chatterbot}
+  s.summary = %q{A framework for writing Twitter bots}
+  s.description = %q{A framework for writing bots that run on Twitter. Comes with a simple DSL for easy coding.}
+
+  s.rubyforge_project = "chatterbot"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+  s.licenses = ["WTFDBAL"]
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<twitter_oauth>, [">= 0"])
+      s.add_development_dependency(%q<shoulda>, [">= 0"])
+      s.add_development_dependency(%q<rspec>, [">= 0"])
+      s.add_development_dependency(%q<rdoc>, [">= 0"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_development_dependency(%q<rcov>, [">= 0"])
+      s.add_development_dependency(%q<watchr>, [">= 0"])
+    else
+      s.add_dependency(%q<twitter_oauth>, [">= 0"])
+      s.add_dependency(%q<shoulda>, [">= 0"])
+      s.add_dependency(%q<rspec>, [">= 0"])
+      s.add_dependency(%q<rdoc>, [">= 0"])
+      s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_dependency(%q<rcov>, [">= 0"])
+      s.add_dependency(%q<watchr>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<twitter_oauth>, [">= 0"])
+    s.add_dependency(%q<shoulda>, [">= 0"])
+    s.add_dependency(%q<rspec>, [">= 0"])
+	s.add_dependency(%q<rdoc>, [">= 0"])
+    s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+    s.add_dependency(%q<rcov>, [">= 0"])
+    s.add_dependency(%q<watchr>, [">= 0"])
+  end
+end
+

data/examples/class_bot.rb

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+
+require 'chatterbot'
+
+
+x = Chatterbot::Bot.new
+x.search("foo") do |tweet|
+  puts tweet.inspect
+end