atheme-ruby 0.0.2 → 0.0.3

data/README.md

@@ -1,5 +1,12 @@
 [![Gem Version](https://badge.fury.io/rb/atheme-ruby.png)](http://badge.fury.io/rb/atheme-ruby) [![Dependency Status](https://gemnasium.com/Flauschbaellchen/atheme-ruby.png)](https://gemnasium.com/Flauschbaellchen/atheme-ruby)
 
+This gem is a work-in-process. If you expire some bugs or search for features, try the master-branch first.
+I try to maintain the interface as stable as I can, but until I release version 0.1.0 or 1.0.0 it'll probably change sometimes.
+
+This README reflects the state of the master-branch.
+Please consider that some features might not have been officially released yet.
+Take a look at the commit history and the release date of the latest gem.
+
 # atheme-ruby
 The gem was inspired by [jameswritescode/atheme-ruby](https://github.com/jameswritescode/atheme-ruby/).
 However, his gem use module-methods and thus does not allow concurrent connections within the same script.
@@ -65,21 +72,30 @@ You may logout after you finished your work:
 ### Service-Calls
 
 This gem supports all service-bots of atheme, like chanserv, nickserv etc.
-You can call any commands you want to perform like you do on IRC; subcommands goes into the first argument of the method:
+You can call any commands you want to perform like you do on IRC; Each param goes into a different argument of the method:
 
-    @session.chanserv.info('#opers')       # /msg chanserv info #opers
-    @session.chanserv.list                 # /msg chanserv list
-    @session.nickserv.help('set password') # /msg nickserv help password
+    @session.chanserv.info('#opers')                     # /msg chanserv info #opers
+    @session.chanserv.list                               # /msg chanserv list
+    @session.nickserv.mark("Nick", "ON", "marking Nick") # Marks Nick with a note
 
 I think you're getting the point...
 However, you can perform additional questions on these return values:
 
-    @session.chanserv.info('#opers').founder      #=> #<Atheme::User ...>
-    @session.chanserv.info('#opers').founder.name #=> "Nick_Of_Founder"
-    @session.chanserv.info('#opers').registered   #=> #<Date: 2013-05-13 ((2456426j,0s,0n),+0s,2299161j)>
+    @session.chanserv.info('#opers').founder             #=> #<Atheme::User ...>
+    @session.chanserv.info('#opers').founder.name        #=> "Nick_Of_Founder"
+    @session.chanserv.info('#opers').registered          #=> #<Date: 2013-05-13 ((2456426j,0s,0n),+0s,2299161j)>
+    @session.nickserv.info("Nick").mark!("marking Nick") #=> Marks an user
+
+Or a bit simplier if you want to run multiple ones on one User/Channel/...
+
+    @session.nickserv.info("Nick") do |n|
+      n.mark!("marking...")
+      n.set_vhost!("omg.that.is.awesome")
+      n.reset_password!
+    end
 
-Take a look into _lib/atheme/services/*_ to find available subcommands.
-The commands return a Atheme::Entity or a subclass like Atheme::User or Atheme::Channel. You can call #raw_output on these to get the raw service reply of the command you called.
+Take a look into _lib/atheme/services/*_ and _lib/atheme/entities/*_ to find available subcommands.
+The commands which call the API return a Atheme::Entity or a subclass like Atheme::User or Atheme::Channel etc. You can call #raw_output on these to get the raw service reply of the command you called.
 
 TODO
 ----

data/lib/atheme/entities/channel.rb

@@ -1,7 +1,177 @@
 module Atheme
   class Channel < Entity
-    def fetch!
+
+    def fetch! #:nodoc:
       @session.chanserv.info(@token)
     end
+
+    # Forcefully removes the channel, including
+    # all data associated with it (like access lists etc)
+    # and cannot be restored.
+    # Only opers may use this.
+    def fdrop!
+      @session.chanserv.fdrop(self.name)
+    end
+
+    # close! prevents a channel from being used. Anyone
+    # who enters is immediately kickbanned. The channel
+    # cannot be dropped and foundership cannot be
+    # transferred.
+    # 
+    # On executing this method, it will immediately kick all
+    # users from the channel.
+    # 
+    # Use unclose!/open! to reopen a channel. While closed,
+    # channels will still expire.
+    # 
+    # Only opers may use this.
+    def close!(reason)
+      @session.chanserv.close(self.name, :on, reason)
+    end
+
+    # Opens a previously closed channel.
+    # 
+    # Only opers may use this.
+    def open!
+      @session.chanserv.close(self.name, :off)
+    end
+    alias_method :unclose!, :open!
+
+    # Gives someone channel admin/protection (+a) permissions
+    # If the nick is omitted the action is performed
+    # on the person requesting the command.
+    # Nick can be a single user or an array of users (as strings or Atheme::Users).
+    def protect(nick)
+      change_permissions(:protect, nick)
+    end
+    alias_method :admin, :protect
+
+    # Takes channel operator (-a) permissions from someone.
+    # If the nick is omitted the action is performed
+    # on the person requesting the command.
+    # Nick can be a single user or an array of users (as strings or Atheme::Users).
+    def deprotect(nick)
+      change_permissions(:deprotect, nick)
+    end
+    alias_method :deadmin, :deprotect
+
+    # Gives someone channel operator (+o) permissions
+    # If the nick is omitted the action is performed
+    # on the person requesting the command.
+    # Nick can be a single user or an array of users (as strings or Atheme::Users).
+    def op(nick)
+      change_permissions(:op, nick)
+    end
+
+    # Takes channel operator (-o) permissions from someone.
+    # If the nick is omitted the action is performed
+    # on the person requesting the command.
+    # Nick can be a single user or an array of users (as strings or Atheme::Users).
+    def deop(nick)
+      change_permissions(:deop, nick)
+    end
+
+    # Gives someone channel halfop (+h).
+    # If the nick is omitted the action is performed
+    # on the person requesting the command.
+    # Nick can be a single user or an array of users (as strings or Atheme::Users).
+    def halfop(nick)
+      change_permissions(:halfop, nick)
+    end
+
+    # Takes channel halpop (-h) from someone.
+    # If the nick is omitted the action is performed
+    # on the person requesting the command.
+    # Nick can be a single user or an array of users (as strings or Atheme::Users).
+    def dehalfop(nick)
+      change_permissions(:dehalfop, nick)
+    end
+
+    # Gives someone channel voice (+v).
+    # If the nick is omitted the action is performed
+    # on the person requesting the command.
+    # Nick can be a single user or an array of users (as strings or Atheme::Users).
+    def voice(nick)
+      change_permissions(:voice, nick)
+    end
+
+    # Takes channel voice (-v) from someone.
+    # If the nick is omitted the action is performed
+    # on the person requesting the command.
+    # Nick can be a single user or an array of users (as strings or Atheme::Users).
+    def devoice(nick)
+      change_permissions(:devoice, nick)
+    end
+
+    # mark! allows operators to attach a note to a channel.
+    # For example, an operator could mark the channel to be a botnet channel.
+    def mark!(reason)
+      @session.chanserv.mark(self.name, :on, reason)
+    end
+
+    # Unmark a previously marked channel.
+    def unmark!
+      @session.chanserv.mark(self.name, :off)
+    end
+
+    # Allows you to regain control of your
+    # channel in the event of a takeover.
+    #  
+    # More precisely, everyone will be deopped,
+    # limit and key will be cleared, all bans
+    # matching you are removed, a ban exception
+    # matching you is added (in case of bans Atheme
+    # can't see), the channel is set invite-only
+    # and moderated and you are invited.
+    #  
+    # If you are on channel, you will be opped and
+    # no ban exception will be added.
+    def recover!
+      @session.chanserv.recover(self.name)
+    end
+
+    # Allows you to ban a user or hostmask from a channel.
+    def ban!(nick_or_host)
+      @session.chanserv.ban(self.name, nick_or_host)
+    end
+
+    # Allows you to unban a user or hostmask from a channel.
+    def unban!(nick_or_host)
+      @session.chanserv.unban(self.name, nick_or_host)
+    end
+
+    # The KICK command allows for the removal of a user from
+    # a channel. The user can immediately rejoin.
+    # 
+    # Your nick will be added to the kick reason.
+    # The reason is optional./cs 
+    def kick!(reason=nil)
+      reason.kind_of?(String) ? @session.chanserv.kick(self.name, nick) : @session.chanserv.kick(self.name, nick, reason)
+    end
+
+    # Sets a topic on the channel.
+    def topic!(topic)
+      @session.chanserv.topic(self.name, topic)
+    end
+
+    # Prepends something to the topic on the channel.
+    def prepend_topic!(topic)
+      @session.chanserv.topicprepend(self.name, topic)
+    end
+
+    private
+    def change_permissions(perm, nick=nil)
+      case
+        when nick.kind_of?(String)
+          @session.chanserv.send(perm, self.name, nick)
+        when nick.kind_of?(Atheme::User)
+          @session.chanserv.send(perm, self.name, nick.name)
+        when nick.kind_of?(Array)
+          nick.each do |n|
+            change_permissions(perm, self.name, n)
+          end
+      end
+    end
+
   end
 end

data/lib/atheme/entities/user.rb

@@ -1,7 +1,60 @@
 module Atheme
   class User < EntityBase
-    def fetch!
+
+    def fetch! #:nodoc:
       @session.nickserv.info(@token)
     end
+
+    # Forcefully removes the account, including
+    # all nicknames, channel access and memos attached to it.
+    # Only opers may use this.
+    def fdrop!
+      @session.nickserv.fdrop(self.name)
+    end
+
+    # freeze! allows operators to "freeze" an abusive user's
+    # account. This logs out all sessions logged in to the
+    # account and prevents further logins. Thus, users
+    # cannot obtain the access associated with the account.
+    def freeze!(reason)
+      @session.nickserv.freeze(self.name, :on, reason)
+    end
+
+    # Unfreeze an previously frozen account.
+    def unfreeze!
+      @session.nickserv.freeze(self.name, :off)
+    end
+
+    # mark! allows operators to attach a note to an account.
+    # For example, an operator could mark the account of
+    # a spammer so that others know the user has previously
+    # been warned.
+    def mark!(reason)
+      @session.nickserv.mark(self.name, :on, reason)
+    end
+
+    # Unmark a previously marked account.
+    def unmark!
+      @session.nickserv.mark(self.name, :off)
+    end
+
+    # vhost! allows operators to set a virtual host (also
+    # known as a spoof or cloak) on an account. This vhost
+    # will be set on the user immediately and each time
+    # they identify
+    def set_vhost!(vhost)
+      @session.nickserv.vhost(self.name, :on, vhost)
+    end
+
+    # Removes a previously added vhost from the account
+    def remove_vhost!
+      @session.nickserv.vhost(self.name, :off)
+    end
+
+    # Sets a random password for this account.
+    # Only opers may use this.
+    def reset_password!
+      @session.nickserv.resetpass(self.name)
+    end
   end
 end

data/lib/atheme/entity.rb

@@ -14,6 +14,8 @@ module Atheme
         @updated = false
         @token = hash_or_token
       end
+
+      yield self if block_given?
     end
 
     def method_missing(meth, *args, &block)

data/lib/atheme/service.rb

@@ -81,12 +81,12 @@ module Atheme
       response = {raw_output: raw_output}
       parser = @@parsers.has_key?(service_name) && @@parsers[service_name][method]
 
-      return Atheme::Entity.new(@session, response) unless parser
+      return Atheme::Entity.new(@session, response, &block) unless parser
       
       parser.commands.each do |command|
         response[command.name] = command.call(@session, raw_output)
       end
-      parser.responder.new(@session, response) if parser.responder
+      parser.responder.new(@session, response, &block) if parser.responder
     end
 
     private

data/lib/atheme/services/chanserv.rb

@@ -21,7 +21,8 @@ module Atheme
       end
 
       command :last_used do
-        Date.parse(match(/Last\sused\s+:\s+(\w+ [0-9]{2} [0-9(:?)]+ [0-9]{4})/))
+        time = match(/Last\sused\s+:\s+(\w+ [0-9]{2} [0-9(:?)]+ [0-9]{4})/)
+        time && Date.parse(time)
       end
 
       command :mode_lock do

data/lib/atheme/version.rb

@@ -1,3 +1,3 @@
 module Atheme
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: atheme-ruby
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-08-28 00:00:00.000000000 Z
+date: 2013-08-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler