chatterbot 2.0.3 → 2.0.4

data/docs/advanced.md

@@ -0,0 +1,67 @@
+---
+layout: page
+title: "Advanced Features"
+category: doc
+---
+
+Direct Client Access
+--------------------
+
+If you want to do something not provided directly by Chatterbot, you
+have access to an instance of Twitter::Client provided by the
+**client** method. In theory, you can do something like this in your
+bot to unfollow users who DM you:
+
+    client.direct_messages_received(:since_id => since_id).each do |m|
+        client.unfollow(m.user.name)
+    end
+
+Storing Config in the Database
+------------------------------
+Sometimes it is preferable to store the authorization credentials for
+your bot in a database.
+
+Chatterbot can manage configurations that are stored in the database,
+but to do this you will need to specify how to connect to the
+database. You can do this by specifying the connection string
+either in one of the global config files by setting
+
+```
+:db_uri:mysql://username:password@host/database
+```
+
+Or you can specify the connection on the command-line by using the
+--db="db_uri" 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
+
+    mysql://username:password@host/database
+
+see http://sequel.rubyforge.org/rdoc/files/doc/opening_databases_rdoc.html
+for details.
+
+
+Logging Tweets to the Database
+------------------------------
+
+Chatterbot can log tweet activity to a database if desired. This can
+be handy for archival purposes, or for tracking what's going on with
+your bot.
+
+If you've configured your bot for database access, you can store a
+tweet to the database by calling the `log` method like this:
+
+```
+search "chatterbot" do |tweet|
+    log tweet
+end
+```
+
+See `Chatterbot::Logging` for details on this.
+
+
+Streaming
+---------
+
+Chatterbot has basic support for Twitter's Streaming API. You can read
+more about it [here](streaming.html)

data/docs/basics.md

@@ -0,0 +1,12 @@
+---
+layout: page
+title: "Basics"
+category: tut
+published: false
+---
+
+A bit about concepts, what you might do, ethics, etc.
+
+
+basic features
+

data/docs/bin/jekyll-page

@@ -0,0 +1,109 @@
+#!/usr/bin/env ruby
+
+require 'date'
+require 'optparse'
+
+options = {
+    # Expects to be in the bin/ sub-directory by default
+    :path => File.dirname(File.dirname(__FILE__))
+}
+
+parser = OptionParser.new do |opt|
+    opt.banner = 'usage: jekyll-page TITLE CATEGORY [FILENAME] [OPTIONS]'
+    opt.separator ''
+    opt.separator 'Options'
+    opt.on('-e', '--edit', 'Edit the page') do |edit|
+        options[:edit] = true
+    end
+    opt.on('-l', '--link', 'Relink pages') do |link|
+        options[:link] = true
+    end
+    opt.on('-p PATH', '--path PATH', String, 'Path to project root') do |path|
+        options[:path] = path
+    end
+    opt.separator ''
+end
+
+parser.parse!
+
+title = ARGV[0]
+category = ARGV[1]
+filename = ARGV[2]
+
+# Resolve any relative links
+BASE_DIR = File.expand_path(options[:path])
+POSTS_DIR = "#{BASE_DIR}/_posts"
+PAGES_DIR = "#{BASE_DIR}/_pages"
+
+# Ensure the _posts directory exists (we are in the correct directory)
+if not Dir.exists?(POSTS_DIR)
+    puts "#{POSTS_DIR} directory does not exists"
+    exit
+end
+
+# Create _pages directory if it doesn't exist
+if not Dir.exists?(PAGES_DIR)
+    Dir.mkdir(PAGES_DIR)
+end
+
+if options[:link]
+    Dir.foreach(POSTS_DIR) do |name|
+        next if name[0] == '.'
+        nodate = name[/\d{4}-\d{2}-\d{2}-(?<rest>.*)/, 'rest']
+        if File.symlink?("#{PAGES_DIR}/#{nodate}")
+            File.delete("#{PAGES_DIR}/#{nodate}")
+        end
+        abspath = File.absolute_path("#{POSTS_DIR}/#{name}")
+        File.symlink(abspath, "#{PAGES_DIR}/#{nodate}")
+    end
+end
+
+if not title or not category
+    # This flag can be used by itself, exit silently if no arguments
+    # are defined
+    if not options[:link]
+        puts parser
+    end
+    exit
+end
+
+if not filename
+    filename = title.downcase.gsub(/[^a-z0-9\s]/, '').gsub(/\s+/, '-')
+end
+
+today=Date.today().strftime('%F')
+now=DateTime.now().strftime('%F %T')
+
+filepath = "#{POSTS_DIR}/#{today}-#{filename}.md"
+symlink = "#{PAGES_DIR}/#{filename}.md"
+
+if File.exists?(filepath)
+    puts "File #{filepath} already exists"
+    exit
+end
+
+content = <<END
+---
+layout: page
+title: \"#{title}\"
+category: #{category}
+date: #{now}
+---
+
+
+END
+
+File.open(filepath, 'w') do |file|
+    file.puts content
+end
+
+File.symlink(File.absolute_path(filepath), symlink)
+
+if options[:edit]
+    if not ENV['EDITOR']
+        puts 'No $EDITOR variable set'
+        exit
+    end
+    puts ENV['EDITOR']
+    exec("#{ENV['EDITOR']} #{filename}")
+end

data/docs/configuration.md

@@ -0,0 +1,32 @@
+---
+layout: page
+title: "Configuration"
+category: doc
+---
+
+You will need to store some information for your bot. This includes
+the OAuth credentials, timestamps, etc.  Chatterbot offers a whole
+bunch of different methods of storing the config for your bot:
+
+1. Your credentials can be stored as variables in the script itself.
+   If you generate a bot via `chatterbot-register`, the file will have
+   these variables specified. However, if your bot source code is
+   going to be public, you should NOT do this. Anyone who has your
+   credentials can do nasty things with your Twitter account. Also, if
+   your bot is using replies or searches, chatterbot will need to
+   track some state information, and that data will be written to a
+   YAML file.
+2. 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.
+   `chatterbot-register` will also create this file. If you are using
+   git or another source code control system, you should **NOT** store
+   this file! It will be updated every time your bots run.
+3. In a global config file at `/etc/chatterbot.yml` -- values stored here
+   will apply to any bots you run.
+4. In another global config file specified in the environment variable
+   `'chatterbot_config'`.
+5. In a `global.yml` 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.
+6. In a database.  You can read more about this on the [Advanced
+   Features](advanced.html) page

data/docs/contributing.md

@@ -0,0 +1,14 @@
+---
+layout: page
+title: "Contributing"
+category: dev
+---
+
+Bug fixes, features, etc are eagerly welcomed. Since this code is
+being used to run current Twitter bots, any changes need to maintain
+compatibility. 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.
+
+
+

data/docs/css/main.css

@@ -0,0 +1,58 @@
+body {
+    font-weight: 400;
+    text-shadow: 0 1px 1px rgba(255, 255, 255, 0.7);
+}
+
+pre, code {
+    border: none;
+    border-radius: 0;
+    background-color: #f9f9f9;
+    font-size: 0.85em;
+}
+
+pre {
+    font-size: 1em;
+}
+
+code {
+    color: inherit;
+}
+
+#header {
+    border-bottom: 1px solid #eee;
+    margin-bottom: 20px;
+}
+
+#header a:hover {
+    text-decoration: none;
+}
+
+#footer {
+    margin: 20px 0;
+    font-size: 0.85em;
+    color: #999;
+    text-align: center;
+}
+
+#content > .page-header:first-child {
+    margin-top: 0;
+}
+
+#content > .page-header:first-child h2 {
+    margin-top: 0;
+}
+
+
+#navigation {
+    font-size: 0.9em;
+}
+
+#navigation li a {
+    padding-left: 10px;
+    padding-right: 10px;
+}
+
+#navigation .nav-header {
+    padding-left: 0;
+    padding-right: 0;
+}

data/docs/css/syntax.css

@@ -0,0 +1,61 @@
+.highlight .hll { background-color: #ffffcc }
+.highlight  { background: #ffffff; }
+.highlight .c { color: #888888 } /* Comment */
+.highlight .err { color: #a61717; background-color: #e3d2d2 } /* Error */
+.highlight .k { color: #008800; font-weight: bold } /* Keyword */
+.highlight .cm { color: #888888 } /* Comment.Multiline */
+.highlight .cp { color: #cc0000; font-weight: bold } /* Comment.Preproc */
+.highlight .c1 { color: #888888 } /* Comment.Single */
+.highlight .cs { color: #cc0000; font-weight: bold; background-color: #fff0f0 } /* Comment.Special */
+.highlight .gd { color: #000000; background-color: #ffdddd } /* Generic.Deleted */
+.highlight .ge { font-style: italic } /* Generic.Emph */
+.highlight .gr { color: #aa0000 } /* Generic.Error */
+.highlight .gh { color: #333333 } /* Generic.Heading */
+.highlight .gi { color: #000000; background-color: #ddffdd } /* Generic.Inserted */
+.highlight .go { color: #888888 } /* Generic.Output */
+.highlight .gp { color: #555555 } /* Generic.Prompt */
+.highlight .gs { font-weight: bold } /* Generic.Strong */
+.highlight .gu { color: #666666 } /* Generic.Subheading */
+.highlight .gt { color: #aa0000 } /* Generic.Traceback */
+.highlight .kc { color: #008800; font-weight: bold } /* Keyword.Constant */
+.highlight .kd { color: #008800; font-weight: bold } /* Keyword.Declaration */
+.highlight .kn { color: #008800; font-weight: bold } /* Keyword.Namespace */
+.highlight .kp { color: #008800 } /* Keyword.Pseudo */
+.highlight .kr { color: #008800; font-weight: bold } /* Keyword.Reserved */
+.highlight .kt { color: #888888; font-weight: bold } /* Keyword.Type */
+.highlight .m { color: #0000DD; font-weight: bold } /* Literal.Number */
+.highlight .s { color: #dd2200; background-color: #fff0f0 } /* Literal.String */
+.highlight .na { color: #336699 } /* Name.Attribute */
+.highlight .nb { color: #003388 } /* Name.Builtin */
+.highlight .nc { color: #bb0066; font-weight: bold } /* Name.Class */
+.highlight .no { color: #003366; font-weight: bold } /* Name.Constant */
+.highlight .nd { color: #555555 } /* Name.Decorator */
+.highlight .ne { color: #bb0066; font-weight: bold } /* Name.Exception */
+.highlight .nf { color: #0066bb; font-weight: bold } /* Name.Function */
+.highlight .nl { color: #336699; font-style: italic } /* Name.Label */
+.highlight .nn { color: #bb0066; font-weight: bold } /* Name.Namespace */
+.highlight .py { color: #336699; font-weight: bold } /* Name.Property */
+.highlight .nt { color: #bb0066; font-weight: bold } /* Name.Tag */
+.highlight .nv { color: #336699 } /* Name.Variable */
+.highlight .ow { color: #008800 } /* Operator.Word */
+.highlight .w { color: #bbbbbb } /* Text.Whitespace */
+.highlight .mf { color: #0000DD; font-weight: bold } /* Literal.Number.Float */
+.highlight .mh { color: #0000DD; font-weight: bold } /* Literal.Number.Hex */
+.highlight .mi { color: #0000DD; font-weight: bold } /* Literal.Number.Integer */
+.highlight .mo { color: #0000DD; font-weight: bold } /* Literal.Number.Oct */
+.highlight .sb { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Backtick */
+.highlight .sc { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Char */
+.highlight .sd { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Doc */
+.highlight .s2 { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Double */
+.highlight .se { color: #0044dd; background-color: #fff0f0 } /* Literal.String.Escape */
+.highlight .sh { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Heredoc */
+.highlight .si { color: #3333bb; background-color: #fff0f0 } /* Literal.String.Interpol */
+.highlight .sx { color: #22bb22; background-color: #f0fff0 } /* Literal.String.Other */
+.highlight .sr { color: #008800; background-color: #fff0ff } /* Literal.String.Regex */
+.highlight .s1 { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Single */
+.highlight .ss { color: #aa6600; background-color: #fff0f0 } /* Literal.String.Symbol */
+.highlight .bp { color: #003388 } /* Name.Builtin.Pseudo */
+.highlight .vc { color: #336699 } /* Name.Variable.Class */
+.highlight .vg { color: #dd7700 } /* Name.Variable.Global */
+.highlight .vi { color: #3333bb } /* Name.Variable.Instance */
+.highlight .il { color: #0000DD; font-weight: bold } /* Literal.Number.Integer.Long */

data/docs/deploying.md

@@ -0,0 +1,53 @@
+---
+layout: page
+title: "Running your Bot"
+category: doc
+---
+
+There's a couple ways of running your bot:
+
+Manually
+--------
+
+Run it on the command-line whenever you like. Whee!
+
+
+Cron
+----
+Run it via cron.  Here's an example of running a bot every two minutes
+
+    */2 * * * * . ~/.bash_profile; cd /path/to/bot/;  ./bot.rb
+
+Looping
+-------
+Run it as a background process.  Just put the guts of your bot in a loop like this:
+
+```rb
+loop do
+  search "twitter" do |tweet|
+    # here you could do something with a tweet
+    # if you want to retweet
+    retweet(tweet[:id])
+  end
+
+  replies do |tweet|
+    # do stuff
+  end
+
+  # explicitly update our config
+  update_config
+
+  sleep 60
+end
+```
+
+**NOTE:** You need to call `update_config` to update the last tweet your script
+has processed -- if you don't have this call, you will get duplicate
+tweets.
+
+Streaming
+---------
+
+Chatterbot has rough support for the Streaming API. If your bot can
+use it, it's a great option, because you get your data immediately.
+You can read more about setting up a bot to use [streaming](streaming.html).

data/docs/examples.md

@@ -0,0 +1,168 @@
+---
+layout: page
+title: "Examples"
+category: tut
+---
+
+Here's a couple examples of working bots.
+
+@echoes_bot
+-----------
+
+This is a working bot. It responds to any mentions with the incoming
+text:
+
+<blockquote class="twitter-tweet" lang="en"><p><a href="https://twitter.com/muffinista">@muffinista</a> hello there!</p>&mdash; Echo Echo (@echoes_bot) <a href="https://twitter.com/echoes_bot/status/515166110950256640">September 25, 2014</a></blockquote>
+<script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script>
+
+Here's the code. This is right out of the git repo for chatterbot:
+
+```
+## This is a very simple working example of a bot you can build with
+## chatterbot. It looks for mentions of '@echoes_bot' (the twitter
+## handle the bot uses), and sends replies with the name switched to
+## the handle of the sending user
+
+#
+# require the dsl lib to include all the methods you see below.
+#
+require 'rubygems'
+require 'chatterbot/dsl'
+
+puts "Loading echoes_bot.rb"
+
+##
+## If I wanted to exclude some terms from triggering this bot, I would list them here.
+## For now, we'll block URLs to keep this from being a source of spam
+##
+exclude "http://"
+
+blacklist "mean_user, private_user"
+
+puts "checking for replies to me"
+replies do |tweet|
+  # replace the incoming username with #USER#, which will be replaced
+  # with the handle of the user who tweeted us by the
+  # replace_variables helper
+  src = tweet.text.gsub(/@echoes_bot/, "#USER#")  
+
+  # send it back!
+  reply src, tweet
+end
+```
+
+
+@SpaceJamCheck
+--------------
+
+This is another working bot. It checks the website for the movie Space
+Jam to see if it is still online (it does this by using the spacejam
+gem), and tweets the results of that check.
+
+
+```
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'bundler/setup'
+
+require 'chatterbot/dsl'
+require 'spacejam'
+
+#
+# this is the script for the twitter bot SpaceJamCheck
+# generated on 2013-11-04 16:24:46 -0500
+#
+
+consumer_key 'key'
+consumer_secret 'secret'
+
+secret 'secret'
+token 'token'
+
+
+check_url = "http://www2.warnerbros.com/spacejam/movie/jam.htm"
+check_string = "<title>Space Jam</title>"
+
+uptime_messages = [
+                   "Hooray! Space Jam is still online!",
+                   "It's #{Time.now.year} and the Space Jam website is still online",
+                   "In case you were worried, Space Jam is still online",
+                   "Looks like the Space Jam website is still there",
+                   "Yes",
+                   "Yep",
+                   "Still Kickin",
+                   "The Space Jam website is still online",
+                   "Still Online"
+                  ]
+
+downtime_messages = [
+                     "Hmm, looks like Space Jam isn't online. Hopefully it's a fluke ;("
+                    ]
+
+
+x = Spacejam::HTTPCheck.new(url:check_url, body:check_string)
+
+# pick a random tweet according to the website status
+result = if x.online?
+  uptime_messages
+else
+  downtime_messages
+end.sample
+
+# add a timestamp. this helps to prevent duplicate tweet issues
+result << " (#{Time.now.utc})"
+
+# tweet it out!
+tweet result
+```
+
+
+Streaming Bot
+--------------
+
+
+```
+#!/usr/bin/env ruby
+
+## This is a very simple working example of a bot using the streaming
+## API. It's basically a copy of echoes_bot.rb, just using streaming.
+
+#
+# require the dsl lib to include all the methods you see below.
+#
+require 'rubygems'
+require 'chatterbot/dsl'
+
+consumer_secret 'foo'
+secret 'bar'
+token 'biz'
+consumer_key 'bam'
+
+
+puts "Loading echoes_bot.rb using the streaming API"
+
+exclude "http://", "https://"
+
+blacklist "mean_user, private_user"
+
+streaming do
+  favorited do |user, tweet|
+    reply "@#{user.screen_name} thanks for the fave!", tweet
+  end
+
+  followed do |user|
+    tweet "@#{user.screen_name} just followed me!"
+    follow user
+  end
+
+  replies do |tweet|
+    favorite tweet
+
+    puts "It's a tweet!"
+    src = tweet.text.gsub(/@echoes_bot/, "#USER#")  
+    reply src, tweet
+  end
+end
+
+```