Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 174 lines (122 sloc) 5.391 kB
e2a0d22 updated readme
Lee Jarvis authored
1 Cinch - The IRC Bot Building Framework
25bd372 started basic readme implementation
Lee Jarvis authored
2 =====================================
067d38f initial
Lee Jarvis authored
3
25bd372 started basic readme implementation
Lee Jarvis authored
4 Description
5 -----------
067d38f initial
Lee Jarvis authored
6
76d3bfd @dominikh replaced all references to #cinch as a test channel with #cinch-bots
dominikh authored
7 Cinch is an IRC Bot Building Framework for quickly creating IRC bots in
8 Ruby with minimal effort. It provides a simple interface based on plugins and
9 rules. It's as easy as creating a plugin, defining a rule, and watching your
25bd372 started basic readme implementation
Lee Jarvis authored
10 profits flourish.
067d38f initial
Lee Jarvis authored
11
76d3bfd @dominikh replaced all references to #cinch as a test channel with #cinch-bots
dominikh authored
12 Cinch will do all of the hard work for you, so you can spend time creating cool
25bd372 started basic readme implementation
Lee Jarvis authored
13 plugins and extensions to wow your internet peers.
96bfa12 README changes
Lee Jarvis authored
14
76d3bfd @dominikh replaced all references to #cinch as a test channel with #cinch-bots
dominikh authored
15 If you'd like to test your own Cinch experiments you can do so in the
16 \#cinch-bots IRC channel on
17 [irc.freenode.org](irc://irc.freenode.org/cinch-bots). For general
18 support, join [#cinch](irc://irc.freenode.org/cinch).
5a15245 updated documentation
Lee Jarvis authored
19
25bd372 started basic readme implementation
Lee Jarvis authored
20 Installation
21 ------------
5a15245 updated documentation
Lee Jarvis authored
22
25bd372 started basic readme implementation
Lee Jarvis authored
23 ### RubyGems
067d38f initial
Lee Jarvis authored
24
25bd372 started basic readme implementation
Lee Jarvis authored
25 You can install the latest Cinch gem using RubyGems
067d38f initial
Lee Jarvis authored
26
25bd372 started basic readme implementation
Lee Jarvis authored
27 gem install cinch
067d38f initial
Lee Jarvis authored
28
25bd372 started basic readme implementation
Lee Jarvis authored
29 ### GitHub
067d38f initial
Lee Jarvis authored
30
76d3bfd @dominikh replaced all references to #cinch as a test channel with #cinch-bots
dominikh authored
31 Alternatively you can check out the latest code directly from Github
5480488 updates
Lee Jarvis authored
32
a05502d updated references to new repository
Lee Jarvis authored
33 git clone http://github.com/cinchrb/cinch.git
067d38f initial
Lee Jarvis authored
34
25bd372 started basic readme implementation
Lee Jarvis authored
35 Example
36 -------
919ebdd readme syntax fix
Lee Jarvis authored
37
bb68f0a initial readme rewrite
Lee Jarvis authored
38 Your typical Hello, World application in Cinch would go something like this:
39
40 require 'cinch'
41
42 bot = Cinch::Bot.new do
43 configure do |c|
44 c.server = "irc.freenode.org"
45 c.channels = ["#cinch-bots"]
46 end
47
48 on :message, "hello" do |m|
49 m.reply "Hello, #{m.user.nick}"
50 end
51 end
52
53 bot.start
54
55 More examples can be found in the `examples` directory.
56
25bd372 started basic readme implementation
Lee Jarvis authored
57 Features
58 --------
8b8a7ec updated readme
Lee Jarvis authored
59
8ddc237 @dominikh fix levels of some headers in README
dominikh authored
60 ### Documentation
bb68f0a initial readme rewrite
Lee Jarvis authored
61
09fd8fb readme lines should be <= 80 chars
Lee Jarvis authored
62 Cinch provides a documented API, which is online for your viewing pleasure
d183888 @dominikh point to the gem documentation, not the one generated from git
dominikh authored
63 [here](http://rubydoc.info/gems/cinch/frames).
bb68f0a initial readme rewrite
Lee Jarvis authored
64
8ddc237 @dominikh fix levels of some headers in README
dominikh authored
65 ### Object Oriented
bb68f0a initial readme rewrite
Lee Jarvis authored
66
e2a0d22 updated readme
Lee Jarvis authored
67 Many IRC bots (and there are, **so** many) are great, but we see so little of
09fd8fb readme lines should be <= 80 chars
Lee Jarvis authored
68 them take advantage of the awesome Object Oriented Interface which most Ruby
69 programmers will have become accustomed to and grown to love.
bb68f0a initial readme rewrite
Lee Jarvis authored
70
09fd8fb readme lines should be <= 80 chars
Lee Jarvis authored
71 Well, Cinch uses this functionality to its advantage. Rather than having to
72 pass around a reference to a channel or a user, to another method, which then
73 passes it to another method (by which time you're confused about what's
74 going on) -- Cinch provides an OOP interface for even the simpliest of tasks,
75 making your code simple and easy to comprehend.
bb68f0a initial readme rewrite
Lee Jarvis authored
76
8ddc237 @dominikh fix levels of some headers in README
dominikh authored
77 ### Threaded
8b8a7ec updated readme
Lee Jarvis authored
78
09fd8fb readme lines should be <= 80 chars
Lee Jarvis authored
79 Unlike a lot of popular IRC frameworks, Cinch is threaded. But wait, don't let
80 that scare you. It's totally easy to grasp.
e1b578b huzzah plugins
Lee Jarvis authored
81
09fd8fb readme lines should be <= 80 chars
Lee Jarvis authored
82 Each of Cinch's plugins and handlers are executed in their own personal thread.
83 This means the main thread can stay focused on what it does best, providing
84 non-blocking reading and writing to an IRC server. This will prevent your bot
85 from locking up when one of your plugins starts doing some intense operations.
86 Damn that's handy.
e1b578b huzzah plugins
Lee Jarvis authored
87
8ddc237 @dominikh fix levels of some headers in README
dominikh authored
88 ### Plugins
bb68f0a initial readme rewrite
Lee Jarvis authored
89
09fd8fb readme lines should be <= 80 chars
Lee Jarvis authored
90 That's right folks, Cinch provides a modular based plugin system. This is a
91 feature many people have bugged us about for a long time. It's finally here,
92 and it's as awesome as you had hoped!
e1b578b huzzah plugins
Lee Jarvis authored
93
94 This system allows you to create feature packed plugins without interfering with
95 any of the Cinch internals. Everything in your plugin is self contained, meaning
f168613 where for art thou threads
Lee Jarvis authored
96 you can share your favorite plugins among your friends and release a ton of
e1b578b huzzah plugins
Lee Jarvis authored
97 your own plugins for others to use
98
99 Want to see the same Hello, World application in plugin form? Sure you do!
100
101 require 'cinch'
102
103 class Hello
104 include Cinch::Plugin
105
106 match "hello"
107
108 def execute(m)
109 m.reply "Hello, #{m.user.nick}"
110 end
111 end
112
113 bot = Cinch::Bot.new do
114 configure do |c|
115 c.server = "irc.freenode.org"
116 c.channels = ["#cinch-bots"]
117 c.plugins.plugins = [Hello]
118 end
119 end
120
121 bot.start
122
123 More information can be found in the {Cinch::Plugin} documentation.
124
8ddc237 @dominikh fix levels of some headers in README
dominikh authored
125 ### Numeric Replies
e1b578b huzzah plugins
Lee Jarvis authored
126
127 Do you know what IRC code 401 represents? How about 376? or perhaps 502?
128 Sure you don't (and if you do, you're as geeky as us!). Cinch doesn't expect you
129 to store the entire IRC RFC code set in your head, and rightfully so!
130
131 That's exactly why Cinch has a ton of constants representing these numbers
132 so you don't have to remember them. We're so nice.
133
8ddc237 @dominikh fix levels of some headers in README
dominikh authored
134 ### Pretty Output
bb68f0a initial readme rewrite
Lee Jarvis authored
135
d8dc080 @dominikh update README to reflect changes to logging
dominikh authored
136 Ever get fed up of watching those boring, frankly unreadable lines
137 flicker down your terminal screen whilst your bot is online? Help is
138 at hand! By default, Cinch will colorize all text it sends to a
139 terminal, meaning you get some pretty damn awesome readable coloured
140 text. Cinch also provides a way for your plugins to log custom
141 messages:
142
143 on :message, /hello/ do |m|
bfa7f53 @dominikh update code example in readme
dominikh authored
144 debug "Someone said hello"
d8dc080 @dominikh update README to reflect changes to logging
dominikh authored
145 end
bb68f0a initial readme rewrite
Lee Jarvis authored
146
25bd372 started basic readme implementation
Lee Jarvis authored
147 Authors
148 -------
067d38f initial
Lee Jarvis authored
149
c32b7b3 @dominikh update website link of Dominik Honnef
dominikh authored
150 * [Dominik Honnef](http://dominik.honnef.co)
78e148a version 0.1
Lee Jarvis authored
151
25bd372 started basic readme implementation
Lee Jarvis authored
152 Contribute
153 ----------
5d1580f no specs, no cookies!
Lee Jarvis authored
154
155 Love Cinch? Love Ruby? Love helping? Of course you do! If you feel like Cinch
156 is missing that awesome jaw-dropping feature and you want to be the one to
59916e9 @dominikh fix trailing whitespace in README
dominikh authored
157 make this magic happen, you can!
5d1580f no specs, no cookies!
Lee Jarvis authored
158
ed2403e document lack of intention towards 1.8 compatilibility
Lee Jarvis authored
159 Please note that although we very much appreciate all of your efforts, Cinch
160 will not accept patches in aid of Ruby 1.8 compatibility. We have no intention
161 of supporting Ruby versions below 1.9.1.
162
b6f5cca fixed 'retarded' typos
Lee Jarvis authored
163 Fork the project, implement your awesome feature in its own branch, and send
5d1580f no specs, no cookies!
Lee Jarvis authored
164 a pull request to one of the Cinch collaborators. We'll be more than happy
165 to check it out.
166
f9effce @dominikh mention contributors in README
dominikh authored
167 ### Contributors
0439ae4 @dominikh don't invite spam bots to email contributors
dominikh authored
168 - darix &lt;darix [at] nordisch.org&gt; (wrote the message splitting algorithm)
bd819a3 @dominikh added robgleeson to the list of contributors
dominikh authored
169 - robgleeson (thanks for testing, contributing a lot of ideas,
170 discussing design decisions etc)
2aaca6c @dominikh update list of contributors
dominikh authored
171 - Emil Loer (http://github.com/thedjinn) for improving the handling of
172 unexpected disconnects and reconnects.
691498d @dominikh update contributors list in readme
dominikh authored
173 - Check the list of authors for smaller contributions
Something went wrong with that request. Please try again.