iirc 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23bf3a78d1201f86c54b9d6409bb98d24b1dbeeb38bfa0d9173db4945ffab46b
-  data.tar.gz: b18ad6cde53fc59365e1dfc935d2c1d16e6e962d3168b5b7a64feb5ca30a786b
+  metadata.gz: 619cec1c65f965243d45c96b29f02c38d7f6fb576c180587ec468fb8292cfece
+  data.tar.gz: d3b9ca07dcdb07132b36c35a776f6ea287edf88d51f11bc7c4135eac67ed54e6
 SHA512:
-  metadata.gz: 9be4d722d3d609865e8a829197ea20a80ad14789e3809e746025414e61cc94df29b301969b6d1814a9fb4c63947243a65989d723fca2ef44c343df1f48e87574
-  data.tar.gz: 4767a7575a0ff58c2df94872322d8cc1440a2d18ff03ef1fc33b9350b1754246d9484b1ec3f7a125659f45effd76ae814056fb75b98b1d286038258763e8a47e
+  metadata.gz: e80238e5d75e018b049e2cb1ee545bced58d4745a32243d5480a433774a5dbb29247da204bde26927135411c14102b0dab92dbba460772a1d450d7c8394b283a
+  data.tar.gz: 7d7a764ee1b744ca006fc6c4fd949d73b7a14ee2765501c11ffb3dd05db13dc8a72272a4cb0bdb00f29da47375494e17ca359cee6fefdd2d22f0f1f7d44cf627

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.6.0] - 2022-03-30
+
+- Move modules from IIRC::Bot to IIRC namespace
+
+- Document AcceptInvites
+- Document Ambient
+- Document AutoJoin
+- Document Channels
+- Document Members
+- Document PrintIO
+- Document Reading
+
 ## [0.5.1] - 2022-03-29
 
 - [Batteries] Include ISupport

data/README.md

@@ -10,10 +10,10 @@ It's based on composition, with code reload, extensibility and predictability in
 require 'iirc'
 
 class CoolBot < IIRC::IRCv3Bot
-  include Verbs
-  include AutoJoin
-  include RegexHooks
-  include PrintIO
+  include IIRC::Verbs
+  include IIRC::AutoJoin
+  include IIRC::RegexHooks
+  include IIRC::PrintIO
 
   def configure_coolness
     on /^!poke/, :poke_back
@@ -35,8 +35,8 @@ CoolBot.run 'irc.libera.chat' if __FILE__ == $0
 require 'iirc'
 
 class SillyBot < IIRC::IRCv3Bot
-  include AcceptInvites
-  include Batteries # Verbs, Ambient, RegexHooks used here
+  include IIRC::AcceptInvites
+  include IIRC::Batteries # Verbs, Ambient, RegexHooks used here
 
   def configure_silliness
     on /^!uptime/, :say_uptime
@@ -110,7 +110,7 @@ For example:
 
 ```ruby
 class CoolBot < IIRC::IRCv3Bot
-  include RegexHooks
+  include IIRC::RegexHooks
 
   def configure_reload
     on /^=reload/, :reload!

data/examples/facts.rb

@@ -1,8 +1,8 @@
 require "iirc"
 
 IIRC {
-  include IIRC::Bot::Batteries
-  include IIRC::Bot::PrintIO
+  include IIRC::Batteries
+  include IIRC::PrintIO
 
   def facts
     @facts ||= {}

data/examples/greeter.rb

@@ -1,12 +1,12 @@
 require "iirc"
 
 class Greeter < IIRC::Bot
-  include AutoJoin
-  include Verbs
-  include PrintIO
+  include IIRC::AutoJoin
+  include IIRC::Verbs
+  include IIRC::PrintIO
 
   def on_join(evt)
-    say evt.target, "Hello #{evt.sender.nick}!" unless me === evt.sender
+    say evt.target, "Hello #{evt.nick}!" unless me === evt.sender
   end
 
   def autojoin_channels
@@ -14,4 +14,4 @@ class Greeter < IIRC::Bot
   end
 end
 
-Greeter.run 'irc.libera.chat', nick: 'GreeterBot' if __FILE__ == $0
+Greeter.run 'irc.libera.chat', nick: 'GreeterBot' if __FILE__ == $0

data/examples/wolfram.rb

@@ -2,8 +2,8 @@ require "net/https"
 require "iirc"
 
 class Wolfram < IIRC::IRCv3Bot
-  include Batteries
-  include PrintIO
+  include IIRC::Batteries
+  include IIRC::PrintIO
 
   def on_privmsg(evt)
     case evt.message

data/lib/iirc/{bot → modules}/accept_invites.rb

@@ -1,8 +1,11 @@
 module IIRC
-  module Bot::AcceptInvites
-    # Override this to decide whether we should accept a given invite.
+  # Accept INVITEs to join a channel.
+  # By default, all invites are accepted.  
+  # To choose which ones to accept, define {#accept_invite?} on your object / class.
+  module AcceptInvites
+    # Decides whether to accept a given INVITE.
     # By default, all invites are accepted.
-    # @param [Event]
+    # @param evt [Event] the invite
     # @return [true] if we should join the channel
     def accept_invite?(evt)
       true

data/lib/iirc/{bot → modules}/ambient.rb

@@ -1,7 +1,28 @@
 require_relative "reply_target"
 
 module IIRC
-  module Bot::Ambient
+  # Ambient lets you access the current event without having to pass it around.
+  # 
+  # A thread-local variable is set by {Events} when an event comes in.  
+  #
+  # Overloads of {#say}, {#act}, {#mode}, {#join} etc. make their
+  #   first argument optional.
+  #
+  # This module pulls in both {Events} and {Verbs}.
+  #
+  # @example say (with Ambient)
+  #   def on_privmsg
+  #     say "Hello!"
+  #   end
+  # @example say (without)
+  #   def on_privmsg(evt)
+  #     say reply_target(evt), "Hello!"
+  #   end
+  # @example mode (with Ambient)
+  #   def on_join(evt)
+  #     mode "+v #{evt.nick}"
+  #   end
+  module Ambient
     module Events
       private
         def configure_ambient_events

data/lib/iirc/modules/autojoin.rb

@@ -0,0 +1,25 @@
+module IIRC
+  # Automatically joins channels on RPL_WELCOME (001).  
+  # 
+  # Override {#autojoin_channels} to choose which channels to join.
+  # {#autojoin!} may be called at any time to resend.
+  module AutoJoin
+    private def configure_autojoin
+      on :'001', :autojoin!
+    end
+
+    # Send JOIN for each {#autojoin_channel}
+    # @return [Array<String>] channels joined
+    def autojoin!
+      for channel in autojoin_channels
+        self << "JOIN #{channel}"
+      end
+    end
+
+    # The channels to join. By default, returns an empty array.
+    # @return [Array<String>] channel names
+    def autojoin_channels
+      []
+    end
+  end
+end

data/lib/iirc/{bot → modules}/channels.rb

@@ -1,15 +1,19 @@
 module IIRC
-  module Bot::Channels
+  # Keeps track of the channels we are currently in.
+  # The list can be retrieved with {#channels}.
+  # Based on JOIN, PART and KICK messages received for our nick.
+  module Channels
+    # @return [Set<String>] 
     def channels
       @channels ||= Set.new
     end
 
     private
       def configure_channel_tracking
-        hook :track_self_channels
+        hook :track_own_channels
       end
 
-      def track_self_channels(evt)
+      def track_own_channels(evt)
         case evt.verb
         when :'001'
           channels.clear

data/lib/iirc/{bot → modules}/configure.rb

@@ -1,5 +1,5 @@
 module IIRC
-  module Bot::Configure
+  module Configure
     def self.included(m)
       require 'set'
       m.extend ClassMethods

data/lib/iirc/{bot → modules}/formatting.rb

@@ -1,5 +1,5 @@
 module IIRC
-  module Bot::Formatting
+  module Formatting
     module_function
       def bold(s) "\x02#{s}\x02" end
       def italic(s) "\x1d#{s}\x1d" end

data/lib/iirc/{bot → modules}/hooks.rb

@@ -1,5 +1,5 @@
 module IIRC
-  module Bot::Hooks
+  module Hooks
     def hooks
       @hooks ||= Hash.new { |h,v| h[v] = Set.new }
     end

data/lib/iirc/{bot → modules}/ircv3/batches.rb

@@ -1,5 +1,5 @@
 module IIRC
-  module Bot::IRCv3
+  module IRCv3
     class Batch < Event
       def events
         @events ||= []

data/lib/iirc/{bot → modules}/ircv3/caps.rb

@@ -1,5 +1,5 @@
 module IIRC
-  module Bot::IRCv3
+  module IRCv3
     module Caps
       def caps
         raise NotImplementedError.new

data/lib/iirc/{bot → modules}/ircv3/labeled_requests.rb

@@ -1,5 +1,5 @@
 module IIRC
-  module Bot::IRCv3
+  module IRCv3
     module LabeledRequests
       def labeled_request(line)
         SecureRandom.alphanumeric(8).tap { |id|

data/lib/iirc/{bot → modules}/ircv3/parsing.rb

@@ -1,5 +1,5 @@
 module IIRC
-  module Bot::IRCv3
+  module IRCv3
     module Parsing
       autoload :IRCParser, 'ircparser'
 

data/lib/iirc/{bot → modules}/isupport.rb

@@ -11,7 +11,7 @@ module IIRC
   # @see https://defs.ircdocs.horse/defs/isupport.html List of tokens and their values (defs.ircdocs.horse)
   # @see https://datatracker.ietf.org/doc/html/draft-hardy-irc-isupport-00
   # @see https://datatracker.ietf.org/doc/html/draft-brocklesby-irc-isupport-00
-  module Bot::ISupport
+  module ISupport
     # Hash of tokens sent by the server after registration indicating feature support and limits.
     # @return [Hash#extend(Inquiry)] the raw isupport key=>value pairs. keys with no value are assigned +true+.
     def isupport
@@ -38,7 +38,7 @@ module IIRC
   #
   # The key=>value format returned by #isupport won't change.
   # Rather, methods which process the values can be added here.
-  module Bot::ISupport::Inquiry
+  module ISupport::Inquiry
     # Whether or not the server supports a user mode which lets clients mark themselves as bots.
     def bot_mode?
       !!bot_mode

data/lib/iirc/modules/members.rb

@@ -0,0 +1,39 @@
+module IIRC
+  # Processes lists of channel participants sent by the server into {#members}.  
+  # Namely, it processes NAMES replies, such as the ones sent automatically when we
+  # join a channel.
+  # @note IIRC doesn't send NAMES by itself, but will process any replies received, such
+  #   as to JOIN, or any requests you have made yourself.
+  # @see IIRC::Verbs#names send a NAMES request
+  module Members
+    # Nicknames present in channels, by channel.
+    # Updated from NAMES replies.
+    # @return [Hash<String,[String]>]
+    def members
+      @members ||= {}
+    end
+
+    private
+      # @note In a future release, this may also track using JOIN/KICK/PART, etc.
+      def configure_members_tracking
+        on :'353', :receive_names
+        on :'366', :receive_names_end
+      end
+
+      def receive_names evt
+        names = evt.args[3]
+        channel = evt.args[2]
+        members_receiving[channel].concat names.tr('&+@%~', '').split(' ')
+      end
+
+      def receive_names_end evt
+        channel = evt.args[1]
+        members[channel] = members_receiving.delete(channel)
+      end
+
+      # @return [Hash]
+      def members_receiving
+        @members_receiving ||= Hash.new { |h,k| h[k] = [] }
+      end
+  end
+end

data/lib/iirc/{bot → modules}/oper_up.rb

@@ -1,5 +1,5 @@
 module IIRC
-  module Bot::OperUp
+  module OperUp
     def oper_up!
       self << "OPER #{ENV['IRC_OPER']}" if ENV['IRC_OPER']
     end

data/lib/iirc/{bot → modules}/parsing.rb

@@ -1,5 +1,5 @@
 module IIRC
-  module Bot::Parsing
+  module Parsing
     def parse(line)
       Event.new.tap { |evt|
         words = line.chomp.split " "

data/lib/iirc/{bot → modules}/pong.rb

@@ -1,5 +1,5 @@
 module IIRC
-  module Bot::Pong
+  module Pong
     def on_ping evt
       self << "PONG :#{evt.args[0]}"
     end

data/lib/iirc/modules/print_io.rb

@@ -0,0 +1,17 @@
+module IIRC
+  # Wraps {Reading#lines} and {Bot#<<} to print lines received and sent to stdout.
+  # Useful for debugging.
+  module PrintIO
+    # Prints `>> #{line}` to stdout, then yields, for each line from super.
+    def lines
+      super { |line| puts ">> #{line}"; yield line }
+    end
+
+    # Prints `<< #{line}` to stdout, then calls super
+    # @return [self]
+    def <<(line)
+      puts "<< #{line}"
+      super
+    end
+  end
+end

data/lib/iirc/modules/reading.rb

@@ -0,0 +1,12 @@
+module IIRC
+  module Reading
+    # Read lines from {#socket} in a blocking loop until EOF or an error is raised.
+    # @return nil
+    # @yield [String] line encoded as UTF-8.
+    def lines
+      loop {
+        yield socket.readline.force_encoding('utf-8').encode
+      }
+    end
+  end
+end

data/lib/iirc/{bot → modules}/redis.rb

@@ -1,5 +1,5 @@
 module IIRC
-  module Bot::Redis
+  module Redis
     def self.included(*)
       require 'redis'
     end

data/lib/iirc/{bot → modules}/regex_hooks.rb

@@ -1,5 +1,5 @@
 module IIRC
-  module Bot::RegexHooks
+  module RegexHooks
     def regex_hooks
       hooks.filter { |k,v| Regexp === k }.freeze
     end

data/lib/iirc/{bot → modules}/reply_target.rb

@@ -1,5 +1,5 @@
 module IIRC
-  module Bot::ReplyTarget
+  module ReplyTarget
     # The +reply_target+ of an event is the sender's nickname when _we_ are the
     # +target+. Otherwise, it returns the regular +target+.
     #

data/lib/iirc/{bot → modules}/track_own_nick.rb

@@ -1,5 +1,5 @@
 module IIRC
-  module Bot::TrackOwnNick
+  module TrackOwnNick
     private
 
       def configure_own_nick_tracking

data/lib/iirc/{bot → modules}/verbs.rb

@@ -1,5 +1,5 @@
 module IIRC
-  module Bot::Verbs
+  module Verbs
     def join(channel) self << "JOIN #{channel}" end
     def part(channel, reason=nil) self << "PART #{channel}#{" :#{reason}" if reason}" end
     def names(channel) self << "NAMES #{channel}" end

data/lib/iirc/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module IIRC
-  VERSION = "0.5.1"
+  VERSION = "0.6.0"
 end

data/lib/iirc.rb

@@ -4,33 +4,33 @@ require_relative "iirc/event"
 require_relative "iirc/sender"
 require_relative "iirc/user"
 
+require_relative "iirc/bot"
 require_relative "iirc/numerics"
 
-require_relative "iirc/bot"
-require_relative "iirc/bot/accept_invites"
-require_relative "iirc/bot/ambient"
-require_relative "iirc/bot/autojoin"
-require_relative "iirc/bot/channels"
-require_relative "iirc/bot/configure"
-require_relative "iirc/bot/formatting"
-require_relative "iirc/bot/hooks"
-require_relative "iirc/bot/isupport"
-require_relative "iirc/bot/members"
-require_relative "iirc/bot/oper_up"
-require_relative "iirc/bot/parsing"
-require_relative "iirc/bot/pong"
-require_relative "iirc/bot/print_io"
-require_relative "iirc/bot/reading"
-require_relative "iirc/bot/redis"
-require_relative "iirc/bot/regex_hooks"
-require_relative "iirc/bot/reply_target"
-require_relative "iirc/bot/track_own_nick"
-require_relative "iirc/bot/verbs"
-
-require_relative "iirc/bot/ircv3/caps"
-require_relative "iirc/bot/ircv3/parsing"
-require_relative "iirc/bot/ircv3/batches"
-require_relative "iirc/bot/ircv3/labeled_requests"
+require_relative "iirc/modules/accept_invites"
+require_relative "iirc/modules/ambient"
+require_relative "iirc/modules/autojoin"
+require_relative "iirc/modules/channels"
+require_relative "iirc/modules/configure"
+require_relative "iirc/modules/formatting"
+require_relative "iirc/modules/hooks"
+require_relative "iirc/modules/isupport"
+require_relative "iirc/modules/members"
+require_relative "iirc/modules/oper_up"
+require_relative "iirc/modules/parsing"
+require_relative "iirc/modules/pong"
+require_relative "iirc/modules/print_io"
+require_relative "iirc/modules/reading"
+require_relative "iirc/modules/redis"
+require_relative "iirc/modules/regex_hooks"
+require_relative "iirc/modules/reply_target"
+require_relative "iirc/modules/track_own_nick"
+require_relative "iirc/modules/verbs"
+
+require_relative "iirc/modules/ircv3/caps"
+require_relative "iirc/modules/ircv3/parsing"
+require_relative "iirc/modules/ircv3/batches"
+require_relative "iirc/modules/ircv3/labeled_requests"
 
 module IIRC
   class Error < StandardError; end
@@ -67,15 +67,15 @@ module IIRC
   end
 
   # Batteries is a recommended set of modules for writing interactive bots.
-  module Bot::Batteries
-    include Bot::Channels
-    include Bot::Members
-    include Bot::Formatting
-    include Bot::AutoJoin
-    include Bot::Verbs
-    include Bot::Ambient
-    include Bot::RegexHooks
-    include Bot::ISupport
+  module Batteries
+    include Channels
+    include Members
+    include Formatting
+    include AutoJoin
+    include Verbs
+    include Ambient
+    include RegexHooks
+    include ISupport
   end
 
   module SSL

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: iirc
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - mooff
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-03-29 00:00:00.000000000 Z
+date: 2022-03-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ircparser
@@ -47,30 +47,30 @@ files:
 - iirc.gemspec
 - lib/iirc.rb
 - lib/iirc/bot.rb
-- lib/iirc/bot/accept_invites.rb
-- lib/iirc/bot/ambient.rb
-- lib/iirc/bot/autojoin.rb
-- lib/iirc/bot/channels.rb
-- lib/iirc/bot/configure.rb
-- lib/iirc/bot/formatting.rb
-- lib/iirc/bot/hooks.rb
-- lib/iirc/bot/ircv3/batches.rb
-- lib/iirc/bot/ircv3/caps.rb
-- lib/iirc/bot/ircv3/labeled_requests.rb
-- lib/iirc/bot/ircv3/parsing.rb
-- lib/iirc/bot/isupport.rb
-- lib/iirc/bot/members.rb
-- lib/iirc/bot/oper_up.rb
-- lib/iirc/bot/parsing.rb
-- lib/iirc/bot/pong.rb
-- lib/iirc/bot/print_io.rb
-- lib/iirc/bot/reading.rb
-- lib/iirc/bot/redis.rb
-- lib/iirc/bot/regex_hooks.rb
-- lib/iirc/bot/reply_target.rb
-- lib/iirc/bot/track_own_nick.rb
-- lib/iirc/bot/verbs.rb
 - lib/iirc/event.rb
+- lib/iirc/modules/accept_invites.rb
+- lib/iirc/modules/ambient.rb
+- lib/iirc/modules/autojoin.rb
+- lib/iirc/modules/channels.rb
+- lib/iirc/modules/configure.rb
+- lib/iirc/modules/formatting.rb
+- lib/iirc/modules/hooks.rb
+- lib/iirc/modules/ircv3/batches.rb
+- lib/iirc/modules/ircv3/caps.rb
+- lib/iirc/modules/ircv3/labeled_requests.rb
+- lib/iirc/modules/ircv3/parsing.rb
+- lib/iirc/modules/isupport.rb
+- lib/iirc/modules/members.rb
+- lib/iirc/modules/oper_up.rb
+- lib/iirc/modules/parsing.rb
+- lib/iirc/modules/pong.rb
+- lib/iirc/modules/print_io.rb
+- lib/iirc/modules/reading.rb
+- lib/iirc/modules/redis.rb
+- lib/iirc/modules/regex_hooks.rb
+- lib/iirc/modules/reply_target.rb
+- lib/iirc/modules/track_own_nick.rb
+- lib/iirc/modules/verbs.rb
 - lib/iirc/numerics.rb
 - lib/iirc/sender.rb
 - lib/iirc/user.rb

data/lib/iirc/bot/autojoin.rb

@@ -1,18 +0,0 @@
-module IIRC
-  module Bot::AutoJoin
-    private def configure_autojoin_hook
-      on :'001', :autojoin!
-    end
-
-    def autojoin!
-      for channel in autojoin_channels
-        self << "JOIN #{channel}"
-      end
-    end
-
-    # override this to read from e.g. redis, config
-    def autojoin_channels
-      []
-    end
-  end
-end

data/lib/iirc/bot/members.rb

@@ -1,28 +0,0 @@
-module IIRC
-  module Bot::Members
-    def members
-      @members ||= {}
-    end
-
-    private
-      def configure_members_tracking
-        on :'353', :receive_names
-        on :'366', :receive_names_end
-      end
-
-      def receive_names evt
-        names = evt.args[3]
-        channel = evt.args[2]
-        members_receiving[channel].concat names.tr('&+@%~', '').split(' ')
-      end
-
-      def receive_names_end evt
-        channel = evt.args[1]
-        members[channel] = members_receiving.delete(channel)
-      end
-
-      def members_receiving
-        @members_receiving ||= Hash.new { |h,k| h[k] = [] }
-      end
-  end
-end

data/lib/iirc/bot/print_io.rb

@@ -1,12 +0,0 @@
-module IIRC
-  module Bot::PrintIO
-    def lines
-      super { |line| puts ">> #{line}"; yield line }
-    end
-
-    def <<(line)
-      puts "<< #{line}"
-      super
-    end
-  end
-end

data/lib/iirc/bot/reading.rb

@@ -1,9 +0,0 @@
-module IIRC
-  module Bot::Reading
-    def lines
-      loop {
-        yield socket.readline.force_encoding('utf-8').encode
-      }
-    end
-  end
-end