ircinch 2.4.0

data/docs/encodings.md

@@ -0,0 +1,69 @@
+# @title Encodings
+# @markup kramdown
+
+# Encodings
+
+The IRC protocol doesn't define a specific encoding that should be
+used, nor does it provide any information on which encodings _are_
+being used.
+
+At the same time, lots of different encodings have become popular on
+IRC. This presents a big problem, because, if you're using a different
+encoding than someone else on IRC, you'll receive their text as
+garbage.
+
+Cinch tries to work around this issue in two ways, while also keeping
+the usual Ruby behaviour.
+
+## The `encoding` option
+By setting {file:docs/bot_options.md#encoding the `encoding` option}, you
+set your expectations on what encoding other users will use. Allowed
+values are instances of Encoding, names of valid encodings (as
+strings) and the special `:irc` encoding, which will be explained
+further down.
+
+
+## Encoding.default_internal
+If set, Cinch will automatically convert incoming messages to the
+encoding defined by `Encoding.default_internal`, unless the special
+encoding `:irc` is being used as the {file:docs/bot_options.md#encoding
+`encoding option`}
+
+## The `:irc` encoding
+As mentioned earlier, people couldn't decide on a single encoding to
+use. As such, specifying a single encoding would most likely lead to
+problems, especially if the bot is in more than one channel.
+
+Luckily, even though people cannot decide on a single encoding,
+western countries usually either use CP1252 (Windows Latin-1) or
+UTF-8. Since text encoded in CP1252 fails validation as UTF-8, it is
+easy to tell the two apart. Additionally it is possible to losslessly
+re-encode CP1252 in UTF-8 and as such, a small subset of UTF-8 is also
+representable in CP1252.
+
+If incoming text is valid UTF-8, it will be interpreted as such. If it
+fails validation, a CP1252 → UTF-8 conversion is performed. This
+ensures that you will always deal with UTF-8 in your code, even if
+other people use CP1252. Note, however, that we ignore
+`Encoding.default_internal` in this case and always present you with
+UTF-8.
+
+If text you send contains only characters that fit inside the
+CP1252 code page, the entire line will be sent that way.
+
+If the text doesn't fit inside the CP1252 code page, (for example if
+you type Eastern European characters, or Russian) it will be sent as
+UTF-8. Only UTF-8 capable clients will be able to see these characters
+correctly.
+
+## Invalid bytes and unsupported translations
+If Cinch receives text in an encoding other than the one assumed, it
+can happen that the message contains bytes that are not valid in the
+assumed encoding. Instead of dropping the complete message, Cinch will
+replace offending bytes with question marks.
+
+Also, if you expect messages in e.g. UTF-8 but re-encode them in
+CP1252 (by setting `Encoding.default_internal` to CP1252), it can
+happen that some characters cannot be represented in CP1252. In such a
+case, Cinch will too replace the offending characters with question
+marks.

data/docs/events.md

@@ -0,0 +1,273 @@
+# @title Events
+# @markup kramdown
+
+Cinch provides three kinds of events:
+
+1. Events mapping directly to IRC commands
+
+   For example `:topic`, which will be triggered when someone changes
+   the topic, or `:kick`, when someone gets kicked.
+
+2. Events mapping directly to IRC numeric codes
+
+   For example `:"401"` for `ERR_NOSUCHNICK`, which is triggered when
+   trying to operate on an unknown nickname, or `:"318"` for
+   `RPL_ENDOFWHOIS`, which is triggered after whois information have
+   been received.
+
+3. Events mapping to more abstract ideas
+
+   For example `:leaving` whenever a user parts, quits or gets
+   kicked/killed or `:message`, which is actually a synonym for
+   `:privmsg`, the underlying IRC command.
+
+# Events of the first two kinds
+
+All events of the first two kinds behave exactly the same: When they
+get triggered, the handler will be passed a single object, a reference
+to the {Cinch::Message Message object}.
+
+Example:
+
+    on :topic do |m|
+      # m is the message object
+    end
+
+We will not further describe all possible events of the first two
+categories.
+
+# Events of the third kind
+
+Events of the third kind can each have different signatures, as they
+get passed objects directly relating to their kind, for example the
+leaving user in case of `:leaving`. This document will describe all
+events of that kind, their signature and example usage.
+
+**Note: Because *all* handlers receive a {Cinch::Message Message}
+  object as the first argument, we will only mention and describe
+  additional arguments.**
+
+## `:action`
+
+The `:action` event is triggered when a user sends a CTCP ACTION to a
+channel or the bot. CTCP ACTION is commonly refered to simply as
+"actions" or "/me's", because that is the command used in most IRC
+clients.
+
+Example:
+
+    on :action, "kicks the bot" do |m|
+      m.reply "Ouch! Stop kicking me :(", true
+    end
+
+
+## `:away`
+
+The `:away` event is triggered when a user goes away. This feature
+only works on networks implementing the "away-notify" extension.
+
+Example:
+
+    on :away do |m|
+      debug("User %s just went away: %s" % [m.user, m.message])
+    end
+
+See also {file:docs/events.md#unaway the `:unaway` event}.
+
+
+## `:ban`
+
+The `:ban` event is triggered when a user gets banned in a channel.
+
+One additional argument, a {Cinch::Ban Ban object}, gets passed to
+the handler.
+
+Example:
+
+    on :ban do |m, ban|
+      debug("%s just banned %s" % [ban.by, ban.mask])
+    end
+
+See also {file:docs/events.md#unban the `:unban` event}.
+
+
+## `:catchall`
+
+`:catchall` is a special event that gets triggered for every incoming
+IRC message/command, no matter what the type is.
+
+
+## `:channel`
+
+The `:channel` event is triggered for channel messages (the usual
+form of communication on IRC).
+
+See also {file:docs/events.md#private the `:private` event}.
+
+
+## `:connect`
+
+The `:connect` event is triggered after the bot successfully
+connected to the IRC server.
+
+One common use case for this event is setting up variables,
+synchronising information etc.
+
+
+## `:ctcp`
+
+The `:ctcp` event is triggered when receiving CTCP-related messages,
+for example the VERSION request.
+
+
+## `:dcc_send`
+
+`:dcc_send` gets triggered when a user tries to send a file to the
+bot, using the DCC SEND protocol.
+
+One additional argument, a {Cinch::DCC::Incoming::Send DCC::Send
+object}, gets passed to the handler.
+
+For example usage and a general explanation of DCC in Cinch check
+{Cinch::DCC::Incoming::Send}.
+
+
+## `:dehalfop`, `:deop`, `:deowner`, `:devoice`
+
+These events get triggered for the respective channel operations of
+taking halfop, op, owner and voice from a user.
+
+One additional argument, the user whose rights are being modifed, gets
+passed to the handler.
+
+
+## `:error`
+
+`:error` gets triggered for all numeric replies that signify errors
+(`ERR_*`).
+
+
+## `:halfop`
+
+This event gets triggered when a user in a channel gets half-opped.
+
+One additional argument, the user being half-opped, gets passed to the
+handler.
+
+
+## `:leaving`
+
+`:leaving` is an event that is triggered whenever any of the following
+are triggered as well: `:part`, `:quit`, `:kick`, `:kill`.
+
+The event can thus be used for noticing when a user leaves a channel
+or the network, no matter the reason.
+
+One additional argument, the leaving user, gets passed to the handler.
+
+Be careful not to confuse the additional argument with
+{Cinch::Message#user}. For example in the case of a kick,
+{Cinch::Message#user} will describe the user kicking someone, not the
+one who is being kicked.
+
+Example:
+
+    on :leaving do |m, user|
+      if m.channel?
+        debug("%s just left %s." % [user, m.channel])
+      else
+        debug("%s just left the network." % user)
+      end
+    end
+
+
+
+## `:mode_change`
+
+This event gets triggered whenever modes in a channel or on the bot
+directly change. Unlike events like `:op`, this event is more
+low-level, as the argument the handler gets passed is an array
+describing every change.
+
+
+## `:offline`
+
+This event is triggered when a
+{file:docs/common_tasks.md#checking-if-a-user-is-online monitored user}
+goes offline.
+
+One additional argument, the user going offline, gets passed to the
+handler.
+
+
+## `:online`
+
+This event is triggered when a
+{file:docs/common_tasks.md#checking-if-a-user-is-online monitored user}
+comes online.
+
+One additional argument, the user coming online, gets passed to the
+handler.
+
+
+## `:op`
+
+This event gets triggered when a user in a channel gets opped.
+
+One additional argument, the user being opped, gets passed to the
+handler.
+
+
+## `:owner`
+
+
+This event gets triggered when a user in a channel receives
+owner-status.
+
+One additional argument, the user receiving owner-status, gets passed
+to the handler.
+
+
+## `:message`
+
+The `:message` event is triggered for messages directed at either a
+channel or directly at the bot. It's synonymous with `:privmsg`.
+
+
+## `:private`
+
+The `:private` event is triggered for messages directly towarded at
+the bot (think /query in traditional IRC clients).
+
+See also {file:docs/events.md#channel the `:channel` event}.
+
+
+## `:unaway`
+
+The `:unaway` event is triggered when a user no longer is away. This
+feature only works on networks implementing the "away-notify"
+extension.
+
+Example:
+
+    on :unaway do |m|
+      debug("User %s no longer is away." % m.user)
+    end
+
+See also {file:docs/events.md#away the `:away` event}.
+
+
+## `:unban`
+
+The `:unban` event is triggered when a user gets unbanned in a
+channel.
+
+One additional argument, a {Cinch::Ban Ban object}, gets passed to the
+handler.
+
+
+## `:voice`
+This event gets triggered when a user in a channel gets voiced.
+
+One additional argument, the user being voiced, gets passed to the
+handler.

data/docs/getting_started.md

@@ -0,0 +1,184 @@
+# @title Getting Started
+# @markup kramdown
+
+# Getting Started
+
+This short guide will show you how to easily and quickly write your
+own IRC bot with Cinch.
+
+# What Cinch really is
+
+First and foremost, it is important to understand that Cinch is more
+of an API for IRC access than a full-blown bot framework like Autumn
+or Rbot.
+
+There will be no enforced directory structures, no magical places from
+which plugins will be loaded and no obscure, "fancy" names. Plugins
+will be plugins and not "leaves".
+
+This, however, does not mean that Cinch requires you to be familiar
+with the internals of the IRC protocol. Quite the opposite: A very
+high-level abstraction is provided, allowing things such as
+
+    Channel("#cinch").users.each do |user, modes|
+      user.send "I am watching you!"
+    end
+
+to work.
+
+
+Furthermore, the API has been designed in a way that it sticks true to
+the way Ruby looks and behaves. Plugins are normal classes that mix-in
+a module, functions of the bot are implemented as normal methods and
+so on.
+
+# Hello, World
+
+The following will describe one of the most basic IRC bots you can
+write in Cinch: One that joins a specific channel and responds to
+"hello" by saying "Hello, World".
+
+
+    require "cinch"
+
+    bot = Cinch::Bot.new do
+      configure do |c|
+        c.server   = "irc.freenode.net"
+        c.channels = ["#cinch-bots"]
+      end
+
+      on :message, "hello" do |m|
+        m.reply "Hello, World"
+      end
+    end
+
+    bot.start
+
+
+Note that this is the entire file and all you need for the basic bot
+to work. Save the above example to a file and run it with Ruby.
+
+## In Detail
+
+So, what are we actually doing in that short piece of code? First, we
+create a new bot in line 3 and conigure it in lines 4–6 –
+{Cinch::Bot#configure configure} simply yields the configuration
+object, which allows you to configure various things. In this example,
+we only set which server to connect to and which channel to join.
+Another often-used option is the nickname of the bot
+({file:docs/bot_options.md#nick c.nick}). For an overview of all
+available options, see {file:docs/bot_options.md the list of options}.
+
+Following, we define a basic message handler. In its simplest form,
+{Cinch::Bot#on on} expects two arguments: The kind of message to react
+to and the pattern to match. In this case, the kind is
+{file:docs/events.md#message :message}, which means that the bot will
+respond to both messages in channels as well as messages sent directly
+to the bot. For a list of all kinds, called events, see
+{file:docs/events.md the list of events}.
+
+For the pattern we use a basic string, which means that the message
+has to be exactly that string. It mustn't have anything before or
+after the word "hello". Another way of using {Cinch::Bot#on on} is by using
+regular expressions:
+
+    on :message, /^\d{4}$/ do |m|
+      # ...
+    end
+
+will match all messages that consist of exactly four digits and
+nothing else.
+
+Whenever a message matches the handler we just defined, the block we
+provided will be called, with the message object, and optionally
+capture groups of the regular expression, passed to it.
+
+The message object allows insight into the nature of the message, i.e.
+who sent it, when was it sent etc, and also provides the
+{Cinch::Message#reply reply} method, an easy way of responding to a
+message. If the message was sent to a channel, {Cinch::Message#reply
+reply} will respond to the channel, otherwise directly to the user.
+
+We then use exactly that {Cinch::Message#reply reply} method to send back "Hello, World"
+whenever someone says "hello".
+
+That's it!
+
+# on-handlers vs. plugins
+
+Using `on` might be nice and handy for writing simple bots, but if you
+want to write a more complex bot, providing lots of different features
+to its users, then using plugins might be a better solution.
+
+But what are plugins, exactly? Technically, plugins are implemented as
+Ruby classes that mix-in a {Cinch::Plugin specific module} to get
+access to various methods.
+
+To have an example to work with, we'll convert our "Hello, World" bot
+to using the plugin API:
+
+    require "cinch"
+
+    class HelloWorld
+      include Cinch::Plugin
+
+      match "hello"
+      def execute(m)
+        m.reply "Hello, World"
+      end
+    end
+
+    bot = Cinch::Bot.new do
+      configure do |c|
+        c.server = "irc.freenode.net"
+        c.channels = ["#cinch-bots"]
+        c.plugins.plugins = [HelloWorld]
+      end
+    end
+
+    bot.start
+
+The first thing to notice is that we wrote a new class called
+`HelloWorld`, and that we use {Cinch::Plugin::ClassMethods#match
+match} instead of `on` to define our handler. Furthermore, we didn't
+specify a message type nor did we provide any blocks.
+
+But let's back up and proceed in smaller steps to see how plugins are built.
+
+First thing after defining a new class is to include {Cinch::Plugin} –
+This module will provide methods like
+{Cinch::Plugin::ClassMethods#match match} and also allows Cinch to
+control the class in specific ways required for plugins to work.
+
+Then we use aforementioned `match`, instead of `on`, to specify what
+messages we want to react to. We didn't have to specify the message
+type because plugins default to {file:docs/events.md#message :message}.
+
+We then define a method called `execute`, which is pretty much the
+same as blocks are to on-handlers. And from here on, everything is the
+same.
+
+The only thing left to do is to tell Cinch to use our plugin, by
+adding it to {file:docs/bot_options.md#pluginsplugins c.plugins.plugins}.
+
+One important thing remains to note: Plugins have a
+{file:docs/bot_options.md#pluginsprefix prefix}, a string (or pattern)
+that gets appended to all patterns you define, and by default this
+prefix is `/^!/`. This means that in order to invoke our HelloWorld
+plugin, a user has to say "!hello" instead of "hello". This prefix can
+be configured on a per-plugin or global basis, but that's not in the
+scope of this document.
+
+# Final Words
+
+This short guide only explains the basics of using Cinch, so that you
+can get started as quickly as possible. For more advanced topics, you
+will want to read the specific documents:
+
+- {file:docs/plugins.md Plugins}
+- {file:docs/bot_options.md A list of all available bot options}
+- {file:docs/events.md A list of all available events}
+- {file:docs/encodings.md Dealing with encodings}
+- {file:docs/logging.md Logging in Cinch}
+- {file:docs/common_tasks.md A cookbook for common tasks}
+- {file:docs/common_mistakes.md A list of common mistakes and how to avoid them}

data/docs/logging.md

@@ -0,0 +1,90 @@
+# @title Logging
+# @markup kramdown
+
+# Using the logger
+
+Plugins can use the logging facility for logging their own messages,
+either by using the logging related helper methods (#debug, #info, and
+so on) or by directly interfacing with {Cinch::LoggerList}, which is
+available via `@bot.loggers`.
+
+Example:
+
+    class MyPlugin
+      include Cinch::Plugin
+
+      match "foo"
+      def execute(m)
+        debug "Starting handler..."
+        info  "Some more important information"
+        debug "Done."
+      end
+    end
+
+# Logger levels
+
+Cinch uses a priority-based logging system, using the types `:debug`,
+`:log`, `:info`, `:warn`, `:error` and `:fatal`, each of them
+displaying less information than the previous.
+
+By default, the logging level to display is set to `:debug`, which
+will include all possible kinds of log events, including the rather
+verbose debug output caused by plugins.
+
+`:log` will hide debug output but still contain the raw IRC log and
+from there on, the levels are rather self-explanatory.
+
+## Changing the level
+
+The level can be changed for single loggers or all loggers at once, by either using {Cinch::Logger#level=} or {Cinch::LoggerList#level=} respectively.
+
+Example:
+
+    bot = Cinch::Bot.new { }
+    bot.loggers << Cinch::Logger::FormattedLogger.new(File.open("/tmp/log.log", "a"))
+    bot.loggers.level = :debug
+    bot.loggers.first.level  = :info
+
+This will set all loggers to the `:debug` level (which actually is the
+default already) and the first logger (which is the default STDOUT
+logger) to `:info`.
+
+# Log filtering
+
+Sometimes it is undesirable to log a message unchanged. For example
+when identifying to the network, passwords might be sent in plain
+text. To prevent such information from appearing in logs, {Cinch::LogFilter log filters}
+can be employed.
+
+Log filters take a log message as input and return a new message. This
+allows removing/masking out passwords or other undesired information.
+Additionally, messages can be dropped entirely by returning nil.
+
+It is possible to use more than one filter, in which case they will be
+called in order, each acting on the previous filter's output.
+
+Filters can be installed by adding them to {Cinch::LoggerList#filters}.
+
+An example (and very simple) password filter might look like this:
+
+    class PasswordFilter
+      def initialize(bot)
+        @bot = bot
+      end
+
+      def filter(message, event)
+        message.gsub(@bot.config.password, "*" * @bot.config.password.size)
+      end
+    end
+
+This filter will replace the password in all log messages (except for
+exceptions). It could further discriminate by looking at `event` and
+only modify outgoing IRC messages. It could also use the
+{Cinch::Message} class to parse the message and only operate on the
+actual message component, not channel names and similar. How fancy
+your filtering needs to be depends on you.
+
+# Writing your own logger
+
+This section will follow soon. For now just look at the code of
+already implemented loggers.