Skip to content
This repository
Newer
Older
100644 162 lines (112 sloc) 4.949 kb
6a737a82 »
2009-03-13 Updated readme
1 =Twibot
2 Official URL: http://github.com/cjohansen/twibot/tree/master
3 Christian Johansen (http://www.cjohansen.no)
53af51b1 »
2009-03-05 Initial commit
4
6a737a82 »
2009-03-13 Updated readme
5 == DESCRIPTION
53af51b1 »
2009-03-05 Initial commit
6
9d4f0d8f »
2009-03-15 Preparing for gem release
7 Twibot (pronounced like "Abbot"), is a Ruby microframework for creating Twitter
8 bots, heavily inspired by Sinatra.
56d94212 »
2009-03-13 Readme
9
6a737a82 »
2009-03-13 Updated readme
10 == USAGE
53af51b1 »
2009-03-05 Initial commit
11
6a737a82 »
2009-03-13 Updated readme
12 === Simple example
53af51b1 »
2009-03-05 Initial commit
13
14 require 'twibot'
15
6a737a82 »
2009-03-13 Updated readme
16 # Receive messages, and tweet them publicly
53af51b1 »
2009-03-05 Initial commit
17 #
6a737a82 »
2009-03-13 Updated readme
18 message do |message, params|
19 post_tweet message
53af51b1 »
2009-03-05 Initial commit
20 end
21
6a737a82 »
2009-03-13 Updated readme
22 # Respond to @replies if they come from the right crowd
23 #
24 reply :from => [:cjno, :irbno] do |message, params|
25 post_tweet "@#{message.sender.screen_name} I agree"
26 end
27
28 # Listen in and log tweets
29 #
30 tweet do |message, params|
31 MyApp.log_tweet(message)
32 end
33
34 === Running the bot
35
36 To run the bot, simply do:
37
38 ruby bot.rb
39
40 === Configuration
41
9d4f0d8f »
2009-03-15 Preparing for gem release
42 Twibot looks for a configuration file in ./config/bot.yml. It should contain
6a737a82 »
2009-03-13 Updated readme
43 atleast:
44
84167c50 »
2009-03-13 More readme
45 login: twitter_login
46 password: twitter_password
6a737a82 »
2009-03-13 Updated readme
47
48 You can also pass configuration as command line arguments:
53af51b1 »
2009-03-05 Initial commit
49
6a737a82 »
2009-03-13 Updated readme
50 ruby bot.rb --login myaccount
51
52 ...or configure with Ruby:
53
54 configure do |conf|
55 conf.login = "my_account"
56 do
57
9d4f0d8f »
2009-03-15 Preparing for gem release
58 If you don't specify login and/or password in any of these ways, Twibot will
59 prompt you for those.
60
61 If you want to change how Twibot is configured, you can setup the bot instance
62 manually and give it only the configuration options you want:
6a737a82 »
2009-03-13 Updated readme
63
9d4f0d8f »
2009-03-15 Preparing for gem release
64 # Create bot only with default configuration
84167c50 »
2009-03-13 More readme
65 require 'twibot'
6a737a82 »
2009-03-13 Updated readme
66 bot = Twibot::Bot.new(Twibot::Config.default)
67
84167c50 »
2009-03-13 More readme
68 # Application here...
69
6a737a82 »
2009-03-13 Updated readme
70 If you want command line arguments you can do:
71
9d4f0d8f »
2009-03-15 Preparing for gem release
72 require 'twibot'
6a737a82 »
2009-03-13 Updated readme
73 bot = Twibot::Bot.new(Twibot::Config.default << Twibot::CliConfig.new)
74
75 === "Routes"
76
77 Like Sinatra, and other web app frameworks, Twibot supports "routes": patterns
78 to match incoming tweets and messages:
79
80 require 'twibot'
81
82 tweet "time :country :city" do |message,params|
83 time = MyTimeService.lookup(params[:country], params[:city])
84 client.message :post, "Time is #{time} in #{params[:city]}, #{params[:country]}"
53af51b1 »
2009-03-05 Initial commit
85 end
86
6a737a82 »
2009-03-13 Updated readme
87 You can have several "tweet" blocks (or "message" or "reply"). The first one to
88 match an incoming tweet/message will handle it.
89
a515c275 »
2009-03-13 Readme
90 === Working with the Twitter API
91
92 The DSL gives you access to your Twitter client instance through "client" (or "twitter"):
93
94 message do
95 twitter.status :post, "Hello world" # Also: client.status :post, "Hello world"
96 end
97
98 == REQUIREMENTS
53af51b1 »
2009-03-05 Initial commit
99
9d4f0d8f »
2009-03-15 Preparing for gem release
100 Twitter4r. You'll need atleast 0.3.1, which is currently only available from GitHub.
101 Versions of Twitter4r prior to 0.3.1 does not allow for the since_id parameter to be
102 appended to URLs to the REST API. Twibot needs these to only fetch fresh messages
103 and tweets.
53af51b1 »
2009-03-05 Initial commit
104
a515c275 »
2009-03-13 Readme
105 == INSTALLATION
53af51b1 »
2009-03-05 Initial commit
106
107 gem install twibot
108
9d4f0d8f »
2009-03-15 Preparing for gem release
109 == Is it Ruby 1.9?
110
111 Unfortunately no. Context, used for Twibots tests is not Ruby 1.9 compliant, which
112 makes it hard to figure out which part is causing trouble. Will be fixed soon. Fork
113 away if you want to help out!
114
115 == Polling
116
117 Twitter pulled the plug on it's xmpp service last year. This means that Twibot backed
118 bots needs to poll the Twitter service to keep up. Twitter has a request limit on 70
119 reqs/hour, so you should configure your bot not to make more than that, else it will
120 fail. You can ask for your bot account to be put on the whitelist which allows you to
121 make 20.000 reqs/hour, and shouldn't be a problem so long as your intentions are good
122 (I think).
123
124 Twibot polls like this:
125 * Poll messages if any message handlers exist
126 * Poll tweets if any tweet or reply handlers exist
127 * Sleep for +interval+ seconds
128 * Go over again
129
130 As long as Twibot finds any messages and/or tweets, the interval stays the same
131 (min_interval configuration switch). If nothing was found however, the interval to
132 sleep is increased by interval_step configuration option. This happens until it
133 reaches max_interval, where it will stay until Twibot finds anything.
134
66b076fe »
2009-03-18 Applied patch from Dan Van Derveer, which fixes wrong parameters (and…
135 == CONTRIBUTORS
136
137 * Dan Van Derveer (bug fixes)
138
a515c275 »
2009-03-13 Readme
139 == LICENSE
53af51b1 »
2009-03-05 Initial commit
140
141 (The MIT License)
142
6a737a82 »
2009-03-13 Updated readme
143 Copyright (c) 2009 Christian Johansen
53af51b1 »
2009-03-05 Initial commit
144
145 Permission is hereby granted, free of charge, to any person obtaining
146 a copy of this software and associated documentation files (the
147 'Software'), to deal in the Software without restriction, including
148 without limitation the rights to use, copy, modify, merge, publish,
149 distribute, sublicense, and/or sell copies of the Software, and to
150 permit persons to whom the Software is furnished to do so, subject to
151 the following conditions:
152
153 The above copyright notice and this permission notice shall be
154 included in all copies or substantial portions of the Software.
155
156 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
157 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
158 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
159 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
160 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
161 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
162 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.