grinch 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 42bdf33a559d3d5eb8554340981ca88fc329085886c870db0af86eb651d21ccb
+  data.tar.gz: 7b793e554505585038fb85cc83a3d0a0b42381898bf0935af4d44ba2c4369ff0
+SHA512:
+  metadata.gz: d82d81004649adea9f10e9996f24e4fca7411718d2877125e5ff66f49533a1f9b3867926072913198e336cab28829b8238712cf8b9d6df874aae6f0a3610c10b
+  data.tar.gz: ee26329f1ae9592b2f68beb3c463f86fef9fd76af4d3982ed68008dc5efff364e4f701c4960d6676325fcf35ee3b1edd44fb4a32ec37320c2966be7d3932d672

data/.yardopts

@@ -0,0 +1 @@
+--hide-void-return -m kramdown --verbose --no-private --asset docs/images:images --readme docs/readme.md --plugin kramdown - docs/**/*.md

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2010 Lee Jarvis, Dominik Honnef
+Copyright (c) 2011 Dominik Honnef
+Copyright (c) 2019 William Woodruff
+
+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.md

@@ -0,0 +1,180 @@
+Grinch - The IRC Bot Building Framework
+=====================================
+
+**WARNING!**
+
+Grinch is a *lightly* maintained fork of [Cinch](https://github.com/cinchrb/cinch/), which
+is no longer maintained. It has three primary development goals:
+
+1. To remain (mostly) API compatible with Cinch
+2. To fix security and usability bugs
+3. To function with currently maintained versions of Ruby
+
+
+Description
+-----------
+
+Grinch is an IRC Bot Building Framework for quickly creating IRC bots in
+Ruby with minimal effort. It provides a simple interface based on plugins and
+rules. It's as easy as creating a plugin, defining a rule, and watching your
+profits flourish.
+
+Grinch will do all of the hard work for you, so you can spend time creating cool
+plugins and extensions to wow your internet peers.
+
+For general support, join #cinch channel on Freenode server (irc://irc.freenode.org/cinch) – but
+please don't bring any bots.
+
+Installation
+------------
+
+### RubyGems
+
+You can install the latest Grinch gem using RubyGems
+
+```
+gem install cinch
+```
+
+### GitHub
+
+Alternatively you can check out the latest code directly from Github
+
+```
+git clone https://github.com/woodruffw/grinch
+```
+
+Example
+-------
+
+Your typical Hello, World application in Cinch would go something like this:
+
+```ruby
+require 'cinch'
+
+bot = Cinch::Bot.new do
+  configure do |c|
+    c.server = "irc.freenode.org"
+    c.channels = ["#cinch-bots"]
+  end
+
+  on :message, "hello" do |m|
+    m.reply "Hello, #{m.user.nick}"
+  end
+end
+
+bot.start
+```
+
+More examples can be found in the `examples` directory.
+
+Features
+--------
+
+### Documentation
+
+Grinch provides a documented API, which is online for your viewing pleasure
+[here](http://rubydoc.info/gems/cinch/frames).
+
+### Object Oriented
+
+Many IRC bots (and there are, **so** many) are great, but we see so little of
+them take advantage of the awesome Object Oriented Interface which most Ruby
+programmers will have become accustomed to and grown to love.
+
+Well, Grinch uses this functionality to its advantage. Rather than having to
+pass around a reference to a channel or a user, to another method, which then
+passes it to another method (by which time you're confused about what's
+going on) -- Grinch provides an OOP interface for even the simpliest of tasks,
+making your code simple and easy to comprehend.
+
+### Threaded
+
+Unlike a lot of popular IRC frameworks, Grinch is threaded. But wait, don't let
+that scare you. It's totally easy to grasp.
+
+Each of Grinch's plugins and handlers are executed in their own personal thread.
+This means the main thread can stay focused on what it does best, providing
+non-blocking reading and writing to an IRC server. This will prevent your bot
+from locking up when one of your plugins starts doing some intense operations.
+Damn that's handy.
+
+### Plugins
+
+That's right folks, Grinch provides a modular based plugin system. This is a
+feature many people have bugged us about for a long time. It's finally here,
+and it's as awesome as you had hoped!
+
+This system allows you to create feature packed plugins without interfering with
+any of the Grinch internals. Everything in your plugin is self contained, meaning
+you can share your favorite plugins among your friends and release a ton of
+your own plugins for others to use
+
+Want to see the same Hello, World application in plugin form? Sure you do!
+
+```ruby
+require 'cinch'
+
+class Hello
+  include Cinch::Plugin
+
+  match "hello"
+
+  def execute(m)
+    m.reply "Hello, #{m.user.nick}"
+  end
+end
+
+bot = Cinch::Bot.new do
+  configure do |c|
+    c.server = "irc.freenode.org"
+    c.channels = ["#cinch-bots"]
+    c.plugins.plugins = [Hello]
+  end
+end
+
+bot.start
+```
+
+Note: Plugins take a default prefix of `/^!/` which means the actual match is `!hello`.
+
+More information can be found in the {Cinch::Plugin} documentation.
+
+### Numeric Replies
+
+Do you know what IRC code 401 represents? How about 376? or perhaps 502?
+Sure you don't (and if you do, you're as geeky as us!). Grinch doesn't expect you
+to store the entire IRC RFC code set in your head, and rightfully so!
+
+That's exactly why Grinch has a ton of constants representing these numbers
+so you don't have to remember them. We're so nice.
+
+### Pretty Output
+
+Ever get fed up of watching those boring, frankly unreadable lines
+flicker down your terminal screen whilst your bot is online? Help is
+at hand! By default, Grinch will colorize all text it sends to a
+terminal, meaning you get some pretty damn awesome readable coloured
+text. Grinch also provides a way for your plugins to log custom
+messages:
+
+```ruby
+on :message, /hello/ do |m|
+  debug "Someone said hello"
+end
+```
+
+Contribute
+----------
+
+Love Grinch? Love Ruby? Love helping? Of course you do! If you feel like Grinch
+is missing that awesome jaw-dropping feature and you want to be the one to
+make this magic happen, you can!
+
+Please note that although we very much appreciate all of your efforts, Grinch
+will not accept patches in aid of Ruby 1.8 compatibility. We have no intention
+of supporting Ruby versions below 1.9.1.
+
+Fork the project, implement your awesome feature in its own branch, and send
+a pull request to one of the Grinch collaborators. We'll be more than happy
+to check it out.

data/docs/bot_options.md

@@ -0,0 +1,454 @@
+# @title Bot options
+# @markup kramdown
+
+# Options
+
+## channels
+Type
+: Array<String>
+
+Default value
+: `[]`
+
+Description
+: Channels in this list will be joined upon connecting.
+
+
+### Notes
+- To automatically join password-protected channels, just append the
+  password to the channel's name, separated by a space, e.g.
+  `"#mychannel mypassword"`.
+
+## dcc
+
+### dcc.own_ip
+Type
+: String
+
+Default value
+: `nil`
+
+Description
+: The external IP which should be used for outgoing DCC SENDs. For
+more information see {Cinch::DCC::Outgoing::Send}.
+
+## delay_joins
+Type
+: Number, Symbol
+
+Default value
+: `0`
+
+Description
+: Delay joining channels N seconds after connecting, or until the event S fires.
+
+### Notes
+- This is especially useful in combination with the /cinch-identify/ plugin, which will trigger the `:identified` event.
+
+## encoding
+Type
+: String, Encoding
+
+Default value
+: `:irc`
+
+Description
+: This determines which encoding text received from IRC will have.
+
+
+### Notes
+- {file:docs/encodings.md More information on how Cinch handles encoding issues}
+
+## local_host
+Type
+: String
+
+Default value
+: `nil`
+
+Description
+: Which IP/host to bind to when connecting. This is useful for using
+  so called "vhosts".
+
+## max_messages
+Type
+: Fixnum
+
+Default value
+: `nil`
+
+Description
+: When an overlong message gets split, only `max_messages` parts will
+  be sent to the recipient.
+
+
+### Notes
+- Set this option to `nil` to disable any limit.
+
+## max_reconnect_delay
+Type
+: Fixnum
+
+Default value
+: `300`
+
+Descriptipn
+: With every unsuccessful reconnection attempt, Cinch increases the
+  delay between new attempts. This setting is the maximum number of
+  seconds to wait between two attempts.
+
+## messages_per_second
+Type
+: Float
+
+Default value
+: Network dependent
+
+Description
+: How many incoming messages the server processes per second. This is
+  used for throttling.
+
+
+### Notes
+- If your bot gets kicked for excess flood, try lowering the value of
+  `messages_per_second`.
+- See also: {file:docs/bot_options.md#serverqueuesize `server_queue_size`}
+
+## message_split_end
+Type
+: String
+
+Default value
+: `" ..."`
+
+Description
+: When a message is too long to be sent as a whole, it will be split
+  and the value of this option will be appended to all but the last
+  parts of the message.
+
+
+## message_split_start
+Type
+: String
+
+Default value
+: `"... "`
+
+Description
+: When a message is too long to be sent as a whole, it will be split
+  and the value of this option will be prepended to all but the first
+  parts of the message.
+
+## modes
+Type
+: Array<String>
+
+Default value
+: []
+
+Description
+: An array of modes the bot should set on itself after connecting.
+
+## nick
+Type
+: String
+
+Default value
+: `"cinch"`
+
+Description
+: The nickname the bot will use.
+
+
+### Notes
+- If the nickname is in use, Cinch will append underscores until it
+  finds a free nick.
+- You really should set this option instead of using the default.
+
+## nicks
+Type
+: Array<String>
+
+Default value
+: `nil`
+
+Description
+: This option overrules {file:docs/bot_options.md#nick `nick`} and allows Cinch
+  to try multiple nicks before adding underscores.
+
+
+## password
+Type
+: String
+
+Default value
+: `nil`
+
+Description
+: A server password for access to private servers.
+
+
+### Notes
+- Some networks allow you to use the server password for
+  authenticating with services (e.g. NickServ).
+
+
+## ping_interval
+Type
+: Number
+
+Default value
+: `120`
+
+Description
+: The server will be pinged every X seconds, to keep the connection
+  alive.
+
+
+### Notes
+- The ping interval should be smaller than
+  {file:docs/bot_options.md#timeoutsread `timeouts.read`} to prevent Cinch from
+  falsely declaring a connection dead.
+
+
+## plugins
+
+### plugins.plugins
+Type
+: Array<Class>
+
+Default value
+: `[]`
+
+Description
+: A list of plugins to register.
+
+
+#### Notes
+- An example: `[Plugin1, Plugin2, Plugin3]` -- Note that we are adding
+  the plugin **classes** to the list.
+
+### plugins.prefix
+Type
+: String, Regexp, Lambda
+
+Default value
+: `/^!/`
+
+Description
+: A prefix that will be prepended to all plugin commands.
+
+
+### plugins.suffix
+Type
+: String, Regexp, Lambda
+
+Default value
+: `nil`
+
+Description
+: A suffix that will be appended to all plugin commands.
+
+
+
+### plugins.options
+Type
+: Hash
+
+Default value
+: `Hash.new {|h,k| h[k] = {}}`
+
+Description
+: Options specific to plugins.
+
+
+#### Notes
+- Information on plugins and options for those will be made available
+  in a separate document soon.
+
+
+## port
+Type
+: Fixnum
+
+Default value
+: `6667`
+
+Description
+: The port the IRC server is listening on
+
+
+## realname
+Type
+: String
+
+Default value
+: `"cinch"`
+
+Description
+: The real name Cinch will connect with.
+
+## reconnect
+Type
+: Boolean
+
+Default value
+: `true`
+
+Description
+: Should Cinch attempt to reconnect after a connection loss?
+
+## sasl
+
+### sasl.username
+Type
+: String
+
+Default value
+: `nil`
+
+Description
+: The username to use for SASL authentication.
+
+### sasl.password
+Type
+: String
+
+Default value
+: `nil`
+
+Description
+: The password to use for SASL authentication.
+
+### sasl.mechanisms
+Type
+: Array<Cinch::SASL::Mechanism>
+
+Default value
+: `[Cinch::SASL::DH_Blowfish, Cinch::SASL::Plain]`
+
+Description
+: The SASL mechanisms to use. All mechanisms in the array will be
+attempted, until one was successful
+
+## server
+Type
+: String
+
+Default value
+: `"localhost"`
+
+Description
+: The IRC server to connect to
+
+
+## server_queue_size
+Type
+: Fixnum
+
+Default value
+: Network dependent
+
+Description
+: The number of incoming messages the server will queue, before
+  killing the bot for excess flood.
+
+
+### Notes
+- If your bot gets kicked for excess flood, try lowering the value of
+  `server_queue_size`.
+- See also: {file:docs/bot_options.md#messagespersecond `messages_per_second`}
+
+## ssl
+
+### ssl.use
+Type
+: Boolean
+
+Default value
+: `false`
+
+Description
+: Sets if SSL should be used
+
+### ssl.verify
+Type
+: Boolean
+
+Default value
+: `false`
+
+Description
+: Sets if the SSL certificate should be verified
+
+
+### ssl.ca_path
+Type
+: String
+
+Default value
+: `"/etc/ssl/certs"`
+
+Description
+: The path to a directory with certificates. This has to be set
+  properly for {file:docs/bot_options.md#sslverify `ssl.verify`} to work.
+
+
+### ssl.client_cert
+Type
+: String
+
+Default value
+: `nil`
+
+Description
+: The path to a client certificate, which some networks can use for
+  authentication (see {http://www.oftc.net/oftc/NickServ/CertFP})
+
+
+#### Notes
+- You will want to set the correct port when using SSL
+
+## user
+Type
+: String
+
+Default value
+: `"cinch"`
+
+Description
+: The user name to use when connecting to the IRC server.
+
+## timeouts
+
+### timeouts.read
+Type
+: Number
+
+Default value
+: `240`
+
+Description
+: If no data has been received for this amount of seconds, the
+  connection will be considered dead.
+
+
+### timeouts.connect
+Type
+: Number
+
+Default value
+: `10`
+
+Description
+: Give up connecting after this amount of seconds.
+
+## default_logger_level
+Type
+: Symbol
+
+Default value
+: `:debug`
+
+Description
+: Modify the log level of the default logger, for instance, the bot will log very little if you set this value to `:fatal`.