Document :join event

[bazz1tv]

This PR adds an event :joining so cinch API can receive an event when a user joins a channel.

It was easy to add to the pre-existing on_join private method in irc.rb

I named it :joining to relate to :leaving event. If you want, I can change the name at your request (eg :join :joined)

Here's an example plugin that can use the new event:

require 'cinch'

module Cinch
  module Plugins
    class Misc
      include Cinch::Plugin

      listen_to :joining

      def listen(m)
        return if m.user == @bot

        m.reply "Hello #{m.user} :)"
      end
    end
  end
end

[petertseng]

Is there any difference between this and the :join event?

require 'cinch'

class Join
  include Cinch::Plugin

  listen_to :join, method: :joined

  def joined(m)
    m.reply("#{m.user} joined") if m.user != m.bot
  end
end

bot = Cinch::Bot.new do
  configure do |c|
    c.nick = 'JoinBot'
    c.server = 'irc.freenode.org'
    c.port = 6697
    c.ssl.use = true
    c.channels = ['#joinbottest']
    c.verbose = true
    c.plugins.plugins = [
      Join,
    ]
  end
end

bot.start

Seems to display a message when a user joins, for me.

http://www.rubydoc.info/gems/cinch/file/docs/events.md

[bazz1tv]

Oh, I need to investigate the :join event you are talking about. It is not documented! I'll try it out and report back.

[bazz1tv]

It's true.. There is already a :join event as you say, but how is it generated? I could not find a reference.

In this case, I will squash my commit to only a documentation update 😉

[bazz1tv]

OK, I've rebased my commits to only a documentation update.

[petertseng]

There is already a :join event as you say, but how is it generated?

https://github.com/cinchrb/cinch/blob/master/lib/cinch/irc.rb#L269

[dominikh]

From the documentation:

Events mapping directly to IRC commands. For example :topic, which will be triggered when someone changes the topic, or :kick, when someone gets kicked.

and

We will not further describe all possible events of the first two categories

where the first category is the events mapping directly to IRC commands.

I'd rather not document every single IRC command.

[bazz1tv]

The only problem I have is that, it does not allow someone to find an answer by a keyword search. ie searching "join" will not help someone looking for the answer. I consider that bad documentation. Perhaps including a list of IRC commands eg "join, kick, topic, ..." just so it allows a keyword search to yield a solution.