iirc 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 89d3e4727f759400cf52bf6a8cb23b365d62259ef32fd977c6fcaab0d542fa53
-  data.tar.gz: fc476e509a2ca6e620d6b93bbde705113136926e574860b05bc5508c332f8e51
+  metadata.gz: 853f0b25a9eb334db23bca0fb64366ad9ed147efc9851d1ece86b5e3c2fd17af
+  data.tar.gz: ee32c34c25ac79024ab6e6a00b1460a6c894f6de101d05d2f57e28badcf338ce
 SHA512:
-  metadata.gz: c9cbf42882b4aeb2ae080266750d540d5f834a6c55be22d8b75541c7ca4b521492eacae055c21a3bdb716ca691e3db8a685c79d918c353df324ed8f42b9f168d
-  data.tar.gz: 98d82cf28be02e06e32dd8c6978eb0470ca486c6b9f898fb0642e244e2edbaa99f2c0df9aa9fc4491610968d72736cfae05aba8dfddd1fe04fcdf72681389503
+  metadata.gz: f63b32da94e064e2b614ddf01d8e965991fdc7a4603a6f27628583df1b1eccbac0b9caa93bf7b5d871a024e18cd54fd827e5f0af9da8661f05c696df2b95a262
+  data.tar.gz: 840c5505aa89eff5a7890607de7cfda3e468b3c1ae3bf9cb61266eccfe46f14b37c0a4459af59df2594b8e5cf29d142410efe90306b7f91bc02c0d9fcd3323f4

data/.yardopts

@@ -0,0 +1 @@
+--markup=markdown --private --protected

data/CHANGELOG.md

@@ -1,3 +1,21 @@
+## [0.5.0] - 2022-03-29
+
+- [Batteries] is now a module. Please change `class Foo < IIRC::Batteries`
+    to `class Foo < IIRC::IRCv3Bot; include Batteries; end`
+
+- [Event] Add #nick method (equivalent to sender.nick)
+
+- Improved README
+
+## [0.4.2] - 2022-03-29
+
+- Fix example in README
+
+## [0.4.1] - 2022-03-29
+
+- [ISupport] Add module to process RPL_ISUPPORT
+- [ISupport] Add Inquiry helpers + docs
+
 ## [0.4.0] - 2022-03-27
 
 - [Numerics] Add module with constants imported from ircdocs.horse

data/Gemfile

@@ -8,3 +8,6 @@ gemspec
 gem "rake", "~> 13.0"
 
 gem "minitest", "~> 5.0"
+
+gem "redcarpet", "= 3.5.1" # for Markdown docs (README.md)
+gem "yard"

data/README.md

@@ -1,8 +1,108 @@
 # Lean, mean IRC processing machine
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/iirc`. To experiment with that code, run `bin/console` for an interactive prompt.
+IIRC is a new IRC framework for Ruby.
 
-TODO: Delete this and the text above, and describe your gem
+IRCv3 features such as message tags, batch and labeled-response are supported.
+
+It's based on composition, with code reload, extensibility and predictability in mind,
+
+```ruby
+require 'iirc'
+
+class CoolBot < IIRC::IRCv3Bot
+  include Verbs
+  include AutoJoin
+  include RegexHooks
+  include PrintIO
+
+  def configure_coolness
+    on /^!poke/, :poke_back
+  end
+
+  def poke_back(evt)
+    act reply_target(evt), "pokes #{evt.nick} back!!!"
+  end
+
+  def autojoin_channels
+    ['##coolness']
+  end
+end
+
+CoolBot.run 'irc.libera.chat' if __FILE__ == $0
+```
+
+## Events
+
+Incoming lines are parsed as an IIRC::Event, and fired based on their verb.
+
+The Event structure and firing pattern is the same, no matter the verb.
+
+PRIVMSG fires :privmsg. NOTICE fires :notice. RPL_WELCOME (001) fires :"001".
+
+## Hooks
+
+Hooks are added using #on, and removed using #off.
+
+They are stored in a Set, so adding the same hook twice is idempotent.
+
+This supports code reloading.
+
+## Adding behaviour from classes and modules
+
+To set up behaviour from a class or module, write a configure method:
+
+```ruby
+module Greet
+  def configure_greeting
+    on :join, :do_greeting
+  end
+
+  def do_greeting evt
+    unless me === evt.nick
+      say reply_target(evt), "Hello #{evt.nick}!"
+    end
+  end
+end
+
+class MyBot < IIRC::IRCv3Bot
+  include Greet
+
+  def configure_some_feature
+    on :this, :do_that
+  end
+
+  def do_that(evt) end
+end
+```
+
+Configure methods are called automatically on a new instance, and can be run again with #configure!
+
+You might call configure! after reloading code, extending or including modules at runtime.
+
+## Hot reload
+
+For example:
+
+```ruby
+class CoolBot < IIRC::IRCv3Bot
+  include RegexHooks
+
+  def configure_reload
+    on /^=reload/, :reload!
+  end
+
+  def reload!
+    $LOADED_FEATURES
+      .filter { |file| file.start_with?(__dir__) }
+      .each   { |file| load file }
+    configure!
+  end
+end
+
+if __FILE__ == $0
+  CoolBot.run 'irc.libera.chat'
+end
+```
 
 ## Installation
 
@@ -20,10 +120,6 @@ Or install it yourself as:
 
     $ gem install iirc
 
-## Usage
-
-TODO: Write usage instructions here
-
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/examples/facts.rb

@@ -1,6 +1,7 @@
 require "iirc"
 
 IIRC {
+  include IIRC::Bot::Batteries
   include IIRC::Bot::PrintIO
 
   def facts

data/examples/wolfram.rb

@@ -1,7 +1,8 @@
 require "net/https"
 require "iirc"
 
-class Wolfram < IIRC::Batteries
+class Wolfram < IIRC::IRCv3Bot
+  include Batteries
   include PrintIO
 
   def on_privmsg(evt)
@@ -36,4 +37,4 @@ class Wolfram < IIRC::Batteries
   end
 end
 
-Wolfram.run 'irc.libera.chat', nick: 'WolframBot'+rand(100).to_s
+Wolfram.run 'irc.libera.chat', nick: 'WolframBot'+rand(100).to_s

data/lib/iirc/bot/isupport.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module IIRC
+  # Parses RPL_ISUPPORT (005) events into a Hash.
+  #
+  # These are sent by servers after registration to provide info about the network,
+  # what the server supports, and how it behaves.
+  #
+  # Provides a Hash of the raw values, extended with helper methods which process them.
+  #
+  # @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
+    # 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
+      @isupport ||= {}.extend(Inquiry)
+    end
+
+    private
+      def configure_isupport
+        on :'005', :store_isupport
+      end
+
+      def store_isupport(evt)
+        tokens = evt.args[1..-2]
+
+        for token in tokens
+          name, value = token.split('=', 2)
+          isupport[name] = value.freeze || true
+        end
+      end
+  end
+
+  # Methods for inquiry into a Hash of raw ISUPPORT key=>value pairs.
+  # These are mixed in to the Hash returned by {ISupport#isupport}.
+  #
+  # The key=>value format returned by #isupport won't change.
+  # Rather, methods which process the values can be added here.
+  module Bot::ISupport::Inquiry
+    # Whether or not the server supports a user mode which lets clients mark themselves as bots.
+    def bot_mode?
+      !!bot_mode
+    end
+
+    # User mode which can be used to mark clients as bots.
+    # @return [String] mode char (usually 'B')
+    # @return [nil] if mode is not supported
+    def bot_mode
+      self['BOT']
+    end
+
+    # A string indicating the case mapping used by the server to determine case-insensitive equality
+    # of channel names and nick names.
+    #
+    # @note IIRC does not currently perform case-insensitive comparisons. This may change in future.
+    # @return [String] the name of the casemapping. e.g. 'ascii', 'rfc1459', 'rfc3454'
+    def case_mapping
+      self['CASEMAPPING']
+    end
+
+    # Characters used as channel prefixes by this server.
+    # @see https://defs.ircdocs.horse/defs/chantypes.html
+    # @return [Array] prefixes, e.g. ['#', '&']
+    def channel_prefixes
+      (@channel_prefixes ||= self['CHANTYPES']&.chars.freeze) || ['#'].freeze
+    end
+  end
+end

data/lib/iirc/bot/members.rb

@@ -1,15 +1,11 @@
 module IIRC
   module Bot::Members
-    def self.configure_actions
-      [:listen_for_names]
-    end
-
     def members
       @members ||= {}
     end
 
     private
-      def listen_for_names
+      def configure_members_tracking
         on :'353', :receive_names
         on :'366', :receive_names_end
       end

data/lib/iirc/event.rb

@@ -17,6 +17,10 @@ module IIRC
       @args = v || []
     end
 
+    def nick
+      sender&.nick
+    end
+
     def target
       args.first
     end
@@ -25,4 +29,4 @@ module IIRC
       args.last
     end
   end
-end
+end

data/lib/iirc/version.rb

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

data/lib/iirc.rb

@@ -14,6 +14,7 @@ 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"
@@ -65,7 +66,8 @@ module IIRC
     include IRCv3::LabeledRequests
   end
 
-  class Batteries < IRCv3Bot
+  # Batteries is a recommended set of modules for writing interactive bots.
+  module Bot::Batteries
     include Bot::Channels
     include Bot::Members
     include Bot::Formatting
@@ -127,5 +129,5 @@ module IIRC
 end
 
 def IIRC(*args, **kwargs, &blk)
-  Class.new(IIRC::Batteries, &blk)
+  Class.new(IIRC::IRCv3Bot, &blk)
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: iirc
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - mooff
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-03-27 00:00:00.000000000 Z
+date: 2022-03-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ircparser
@@ -33,6 +33,7 @@ extra_rdoc_files: []
 files:
 - ".github/workflows/main.yml"
 - ".gitignore"
+- ".yardopts"
 - CHANGELOG.md
 - Gemfile
 - LICENSE
@@ -57,6 +58,7 @@ files:
 - 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