atheme-ruby 0.0.3 → 0.0.4

data/README.md

@@ -50,12 +50,12 @@ If an option is missing, the default ones as stated above are used.
 
 ### Login
 
-The initial session uses an anonymous login which can be re-choosen by  logging out.
+The initial session uses an anonymous login which can be re-choosen by logging out.
 
 To login with an account registered with NickServ use the following:
 
     @session.login(username, password, ip="127.0.0.1") #=> you'll get a cookie on success
-    @session.logged_in? #=> true or false
+    @session.logged_in?                                #=> true or false
 
 The cookie is a random generated string from Atheme for your current login session and will be valid for one(1) hour or until the server is shut down or restarted.
 
@@ -76,7 +76,7 @@ You can call any commands you want to perform like you do on IRC; Each param goe
 
     @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
+    @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:
@@ -90,19 +90,41 @@ 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.vhost!("omg.that.is.awesome")
       n.reset_password!
     end
 
 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.
 
+### Error-Handling
+
+Errors can occur if you do not have the permissions to run a command you would like, specifies the wrong arguments or forget one.
+There are many possibilities that something went wrong, especially if you have a long command-chain.
+
+You can test if your command or your command-chain run successfully by asking #success? or #error? on it.
+
+    cmd = @session.chanserv.info("#opers").fdrop!
+    cmd.success? #=> true on success, false otherwise
+
+If the API returned an error, you can inspect it:
+
+    cmd.error           #=> Holds the Exception ($!)
+    cmd.skipped_methods #=> Array of [method, args, block] which have been skipped due to the exception
+
+You can read more about the fault codes here: [Atheme XMLRPC - Fault codes](https://github.com/atheme/atheme/blob/master/doc/XMLRPC#L106)
+
+
+### Known limitations/bugs
+
+* [Attributes of entities do not update until refetch/reinitialize of the whole object](https://github.com/Flauschbaellchen/atheme-ruby/issues/1)
+
+
 TODO
 ----
 * Tests!
 * Docs!
 * Add more parsers/subcommands to all kinds of services (pull requests welcome)
-* Brainstorming: Catch API-Errors and handle them gracefully. Provide a #success? method to decide if the command was successfully executed or not. Need to handle chains like the ones above.
 
 Contributing to atheme-ruby
 ---------------------------

data/lib/atheme/entities/channel.rb

@@ -5,6 +5,85 @@ module Atheme
       @session.chanserv.info(@token)
     end
 
+    # Returns the channel's name
+    def name
+      match(/^Information\son\s([&#+][^:]+):$/)
+    end
+
+    # Returns the founder as an Atheme::User object
+    def founder
+      Atheme::User.new(@session, match(/Founder\s+:\s+(\w+)/))
+    end
+
+    # Returns the successor as an Atheme::User object
+    # Returns nil if noone has been set
+    def successor
+      match(/Successor\s+:\s+\(none\)/) ? nil : Atheme::User.new(@session, match(/Successor\s+:\s+(\w+)/))
+    end
+
+    # Date object which is set to the time when the channel was registered
+    def registered
+      Date.parse(match(/Registered\s+:\s+(\w+ [0-9]{2} [0-9(:?)]+ [0-9]{4})/))
+    end
+
+    # Date object which is set to the time when the channel was last used
+    def last_used
+      Date.parse(match(/Last\sused\s+:\s+(\w+ [0-9]{2} [0-9(:?)]+ [0-9]{4})/)) rescue nil
+    end
+
+    # String of the mode locked on the channel, e.g. "+Ctn-ksi"
+    def mlock
+      match(/Mode\slock\s+:\s+([-+A-Za-z0-9]*)/)
+    end
+    alias_method :mode_lock, :mlock
+
+    # Sets the given mlock/mode lock on the channel, e.g. +mntF-kljf or +ntlL 40 #foo2
+    def mlock!(modes)
+      @session.chanserv.set(self.name, :mlock, modes)
+    end
+    alias_method :mode_lock!, :mlock!
+
+    # Entry message of the channel, if set - otherwise nil.
+    def entrymsg
+      match(/Entrymsg\s+:\s+(.+)/)
+    end
+
+    # Sets the entrymsg for the channel.
+    # Call without arguments to clear it.
+    def entrymsg!(msg=nil)
+      msg.kind_of?(String) ? @session.chanserv.set(self.name, :entrymsg, msg) : @session.chanserv.set(self.name, :entrymsg)
+    end
+
+    # Returns the hannel's URL if one has been set, otherwise nil.
+    def url
+      match(/URL\s+:\s+(.+)/)
+    end
+
+    # Sets the URL for the channel.
+    # Call without arguments to clear it.
+    def url!(url=nil)
+      url.kind_of?(String) ? @session.chanserv.set(self.name, :url, url) : @session.chanserv.set(self.name, :url)
+    end
+
+    # Array of channel flags
+    def flags
+      match(/Flags\s+:\s+(.+)$/).split rescue []
+    end
+
+    # Prefix character used on the channel, e.g. "!"
+    def prefix
+      match(/Prefix\s+:\s+([^\s])/)
+    end
+
+    # Allows you to customize the channel fantasy trigger
+    # for your channel. This is particularly useful if you have
+    # channel bots that conflict with ChanServ's default fantasy
+    # prefix. Providing no prefix argument (or DEFAULT) resets
+    # the channel fantasy prefix to the network default prefix
+    def prefix!(prefix="DEFAULT")
+      @session.chanserv.set(self.name, :prefix, prefix)
+    end
+
     # Forcefully removes the channel, including
     # all data associated with it (like access lists etc)
     # and cannot be restored.
@@ -13,7 +92,7 @@ module Atheme
       @session.chanserv.fdrop(self.name)
     end
 
-    # close! prevents a channel from being used. Anyone
+    # close prevents a channel from being used. Anyone
     # who enters is immediately kickbanned. The channel
     # cannot be dropped and foundership cannot be
     # transferred.
@@ -21,7 +100,7 @@ module Atheme
     # On executing this method, it will immediately kick all
     # users from the channel.
     # 
-    # Use unclose!/open! to reopen a channel. While closed,
+    # Use unclose/open to reopen a channel. While closed,
     # channels will still expire.
     # 
     # Only opers may use this.
@@ -35,7 +114,7 @@ module Atheme
     def open!
       @session.chanserv.close(self.name, :off)
     end
-    alias_method :unclose!, :open!
+    alias_method :unclose, :open
 
     # Gives someone channel admin/protection (+a) permissions
     # If the nick is omitted the action is performed
@@ -103,7 +182,7 @@ module Atheme
       change_permissions(:devoice, nick)
     end
 
-    # mark! allows operators to attach a note to a channel.
+    # 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)
@@ -131,12 +210,12 @@ module Atheme
     end
 
     # Allows you to ban a user or hostmask from a channel.
-    def ban!(nick_or_host)
+    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)
+    def unban(nick_or_host)
       @session.chanserv.unban(self.name, nick_or_host)
     end
 
@@ -145,7 +224,7 @@ module Atheme
     # 
     # Your nick will be added to the kick reason.
     # The reason is optional./cs 
-    def kick!(reason=nil)
+    def kick(reason=nil)
       reason.kind_of?(String) ? @session.chanserv.kick(self.name, nick) : @session.chanserv.kick(self.name, nick, reason)
     end
 
@@ -160,7 +239,7 @@ module Atheme
     end
 
     private
-    def change_permissions(perm, nick=nil)
+    def change_permissions(perm, nick)
       case
         when nick.kind_of?(String)
           @session.chanserv.send(perm, self.name, nick)
@@ -169,8 +248,8 @@ module Atheme
         when nick.kind_of?(Array)
           nick.each do |n|
             change_permissions(perm, self.name, n)
-          end
-      end
+        end
+    end
     end
 
   end

data/lib/atheme/entities/user.rb

@@ -5,6 +5,77 @@ module Atheme
       @session.nickserv.info(@token)
     end
 
+    # Returns the nickname (not account name) of the user
+    def name
+      match(/^Information\son\s([^\s]+)/)
+    end
+
+    # Returns the account name of the user as an Atheme::User object
+    def account
+      Atheme::User.new(@session, match(/\(account\s([^\(]+)\):/))
+    end
+
+    # Date object which is set to the time when the nick was registered
+    def registered
+      Date.parse(match(/Registered\s+:\s+(\w+ [0-9]{2} [0-9(:?)]+ [0-9]{4})/))
+    end
+
+    # Unique entity ID. Available only if the user is currently connected
+    def entity_id
+      match(/Entity\sID\s+:\s+([A-F0-9]+)$/)
+    end
+
+    # Returns the vhost of the nick if set
+    def vhost
+      match(/vHost\s+:\s+([^\s]+)$/)
+    end
+
+    # Real address of the user's connection
+    def real_address
+      match(/Real\saddr\s+:\s+([^\s]+)$/)
+    end
+
+    # Date object of the time when the nick was last seen
+    def last_seen
+      Date.parse(match(/Last\sseen\s+:\s+(\w+ [0-9]{2} [0-9(:?)]+ [0-9]{4})/))
+    end
+
+    # Date object of the time when the user was last seen
+    def user_seen
+      Date.parse(match(/User\sseen\s+:\s+(\w+ [0-9]{2} [0-9(:?)]+ [0-9]{4})/)) rescue nil
+    end
+
+    # Returns an array of linked nicknames to this nick/account
+    def nicks
+      match(/Nicks\s+:\s+([^\s]+(?:\s[^\s]+)*)$/).split rescue []
+    end
+
+    # Returns the user's email
+    def email
+      match(/Email\s+:\s+([^\s]+)/)
+    end
+
+    # Returns the user's language
+    def language
+      match(/Language\s+:\s+([\w]+)$/)
+    end
+
+    # Returns the user's flags as an array, e.g. HideMail
+    def flags
+      match(/Flags\s+:\s+(.+)$/).split rescue []
+    end
+
+    # Returns true if the user enabled nick protection, false otherwise
+    def protected
+      match(/has\s(enabled)\snick\sprotection/) ? true : false
+    end
+    alias_method :protected?, :protected
+
+    # Returns the user's groups as an array,
+    def groups
+      match(/Groups\s+:\s+(.+)$/).split rescue []
+    end
+
     # Forcefully removes the account, including
     # all nicknames, channel access and memos attached to it.
     # Only opers may use this.
@@ -12,7 +83,7 @@ module Atheme
       @session.nickserv.fdrop(self.name)
     end
 
-    # freeze! allows operators to "freeze" an abusive user's
+    # 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.
@@ -25,7 +96,7 @@ module Atheme
       @session.nickserv.freeze(self.name, :off)
     end
 
-    # mark! allows operators to attach a note to an account.
+    # 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.
@@ -38,12 +109,13 @@ module Atheme
       @session.nickserv.mark(self.name, :off)
     end
 
-    # vhost! allows operators to set a virtual host (also
+    # 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)
+    # If no vhost is given, the current one will be deleted.
+    def vhost!(vhost=nil)
+      vhost.nil? ? remove_vhost! : @session.nickserv.vhost(self.name, :on, vhost)
     end
 
     # Removes a previously added vhost from the account

data/lib/atheme/entity.rb

@@ -42,8 +42,13 @@ module Atheme
     def fetchable?
       true
     end
-
     private :do_fetch!, :fetchable?
+
+    private
+    def match(expression)
+      raw_output[expression, 1]
+    end
+
   end
 
   class Entity < EntityBase

data/lib/atheme/error.rb

@@ -0,0 +1,23 @@
+module Atheme
+  class Error
+    attr_reader :error, :skipped_methods
+
+    def initialize(error=nil)
+      @error = error || $!
+      @skipped_methods = []
+    end
+
+    def success?
+      false
+    end
+
+    def error?
+      true
+    end
+
+    def method_missing(meth, *args, &block)
+      @skipped_methods << [meth, args, block]
+      self
+    end
+  end
+end

data/lib/atheme/service.rb

@@ -39,8 +39,7 @@ module Atheme
       end
 
       def match(expression)
-        ematch = expression.match(raw_output)
-        ematch && ematch[1]
+        raw_output[expression, 1]
       end
     end
 
@@ -76,8 +75,11 @@ module Atheme
     end
 
     def method_missing(method, *args, &block)
-      raw_output = @session.service_call(service_name, method, *args)
-
+      begin
+        raw_output = @session.service_call(service_name, method, *args)
+      rescue
+        return Atheme::Error.new
+      end
       response = {raw_output: raw_output}
       parser = @@parsers.has_key?(service_name) && @@parsers[service_name][method]
 

data/lib/atheme/services/chanserv.rb

@@ -3,44 +3,6 @@ module Atheme
 
     parse :info do
       responds_with Atheme::Channel
-
-      command :name do
-        match(/^Information\son\s([&#+][^:]+):$/)
-      end
-
-      command :founder, as: Atheme::User do
-        match(/Founder\s+:\s+(\w+)/)
-      end
-
-      command :successor, as: Atheme::User do
-        match(/Successor\s+:\s+\(none\)/) ? nil : match(/Successor\s+:\s+(\w+)/)
-      end
-
-      command :registered do
-        Date.parse(match(/Registered\s+:\s+(\w+ [0-9]{2} [0-9(:?)]+ [0-9]{4})/))
-      end
-
-      command :last_used do
-        time = match(/Last\sused\s+:\s+(\w+ [0-9]{2} [0-9(:?)]+ [0-9]{4})/)
-        time && Date.parse(time)
-      end
-
-      command :mode_lock do
-        match(/Mode\slock\s+:\s+([-+A-Za-z0-9]*)/)
-      end
-
-      command :entry_msg do
-        match(/Entrymsg\s+:\s+(.+)/)
-      end
-
-      command :flags do
-        flags = match(/Flags\s+:\s+(\w+(?:\s\w+)*)$/)
-        flags && flags.split || []
-      end
-
-      command :prefix do
-        match(/Prefix\s+:\s+([^\s])/)
-      end
     end
 
     parse :list do

data/lib/atheme/services/nickserv.rb

@@ -3,66 +3,7 @@ module Atheme
 
     parse :info do
       responds_with Atheme::User
-
-      command :name do
-        match(/^Information\son\s([^\s]+)/)
-      end
-
-      command :account, as: Atheme::User do
-        match(/\(account\s([^\(]+)\):/)
-      end
-
-      command :registered do
-        Date.parse(match(/Registered\s+:\s+(\w+ [0-9]{2} [0-9(:?)]+ [0-9]{4})/))
-      end
-
-      command :entity_id do
-        match(/Entity\sID\s+:\s+([A-F0-9]+)$/)
-      end
-
-      command :vhost do
-        match(/vHost\s+:\s+([^\s]+)$/)
-      end
-
-      command :real_address do
-        match(/Real\saddr\s+:\s+([^\s]+)$/)
-      end
-
-      command :last_seen do
-        Date.parse(match(/Last\sseen\s+:\s+(\w+ [0-9]{2} [0-9(:?)]+ [0-9]{4})/))
-      end
-
-      command :user_seen do
-        time = match(/User\sseen\s+:\s+(\w+ [0-9]{2} [0-9(:?)]+ [0-9]{4})/)
-        time && Date.parse(time)
-      end
-
-      command :nicks do
-        nicks = match(/Nicks\s+:\s+([^\s]+(?:\s[^\s]+)*)$/)
-        nicks && nicks.split || []
-      end
-
-      command :email do
-        match(/Email\s+:\s+([^\s]+)/)
-      end
-
-      command :language do
-        match(/Language\s+:\s+([\w]+)$/)
-      end
-
-      command :flags do
-        flags = match(/Flags\s+:\s+(\w+(?:\s\w+)*)$/)
-        flags && flags.split || []
-      end
-
-      command :protected do
-        match(/has\s(enabled)\snick\sprotection/) ? true : false
-      end
-
-      command :groups do
-        flags = match(/Groups\s+:\s+(.+)$/)
-        flags && flags.split || []
-      end
     end
+    
   end
 end

data/lib/atheme/version.rb

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

data/lib/atheme.rb

@@ -3,6 +3,7 @@ end
 
 require "xmlrpc/client"
 
+require "atheme/error"
 require "atheme/helpers"
 require "atheme/version"
 require "atheme/session"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: atheme-ruby
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-08-29 00:00:00.000000000 Z
+date: 2013-08-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -60,6 +60,7 @@ files:
 - lib/atheme/entities/channel.rb
 - lib/atheme/entities/user.rb
 - lib/atheme/entity.rb
+- lib/atheme/error.rb
 - lib/atheme/helpers.rb
 - lib/atheme/service.rb
 - lib/atheme/services/chanserv.rb