whois 1.6.6 → 2.0.0

data/lib/whois/record/part.rb

@@ -0,0 +1,30 @@
+#--
+# Ruby Whois
+#
+# An intelligent pure Ruby WHOIS client and parser.
+#
+# Copyright (c) 2009-2011 Simone Carletti <weppos@weppos.net>
+#++
+
+
+require 'whois/record/super_struct'
+
+
+module Whois
+  class Record
+
+    # A single {Whois::Record} fragment. For instance,
+    # in case of *thin server*, a {Whois::Record} can be composed by
+    # one or more parts corresponding to all responses
+    # returned by the WHOIS servers.
+    #
+    # A part is composed by a +body+ and a +host+.
+    #
+    # @attr [String] body The body containing the WHOIS output.
+    # @attr [String] host The host which returned the body.
+    #
+    class Part < SuperStruct.new(:body, :host)
+    end
+
+  end
+end

data/lib/whois/record/registrar.rb

@@ -0,0 +1,34 @@
+#--
+# Ruby Whois
+#
+# An intelligent pure Ruby WHOIS client and parser.
+#
+# Copyright (c) 2009-2011 Simone Carletti <weppos@weppos.net>
+#++
+
+
+require 'whois/record/super_struct'
+
+
+module Whois
+  class Record
+
+    # Holds the details of the Registrar extracted from the WHOIS response.
+    #
+    # A registrar is composed by the several attributes,
+    # accessible through corresponding getter / setter methods.
+    #
+    # Please note that a response is not required to provide
+    # all the attributes. When an attribute is not available,
+    # the corresponding value is set to nil.
+    #
+    # @attr [String] id
+    # @attr [String] name
+    # @attr [String] organization
+    # @attr [String] url
+    #
+    class Registrar < SuperStruct.new(:id, :name, :organization, :url)
+    end
+
+  end
+end

data/lib/whois/record/super_struct.rb

@@ -0,0 +1,60 @@
+#--
+# Ruby Whois
+#
+# An intelligent pure Ruby WHOIS client and parser.
+#
+# Copyright (c) 2009-2011 Simone Carletti <weppos@weppos.net>
+#++
+
+
+require 'ostruct'
+
+
+# SuperStruct is an enhanced version of the Ruby Standard library {Struct}.
+#
+# Compared with the original version, it provides the following additional features:
+# * ability to initialize an instance from Hash
+# * ability to pass a block on creation
+#
+class SuperStruct < Struct
+
+  # Overwrites the standard {Struct} initializer
+  # to add the ability to create an instance from a {Hash} of parameters.
+  #
+  # @overload initialize({ Symbol => Object })
+  #   Initializes the object with a key/value hash.
+  #   @param [{ Symbol => Object }] values
+  #   @return [SuperStruct]
+  # @overload initialize([ value1, value1, ... ])
+  #   Initializes the object with given values.
+  #   @param [Array] values
+  #   @return [SuperStruct]
+  # @overload initialize(value1, value1, ...)
+  #   Initializes the object with given values.
+  #   @return [SuperStruct]
+  #
+  # @yield  self
+  #
+  # @example
+  #   attributes = { :foo => 1, :bar => "baz" }
+  #   Struct.new(attributes)
+  #   # => #<Struct foo=1, bar="baz">
+  #
+  def initialize(*args)
+    if args.first.is_a? Hash
+      initialize_with_hash(args.first)
+    else
+      super
+    end
+    yield(self) if block_given?
+  end
+
+  private
+
+    def initialize_with_hash(attributes = {})
+      attributes.each do |key, value|
+        self[key] = value
+      end
+    end
+
+end

data/lib/whois/server.rb

@@ -1,16 +1,9 @@
-#
-# = Ruby Whois
+#--
+# Ruby Whois
 #
 # An intelligent pure Ruby WHOIS client and parser.
 #
-#
-# Category::    Net
-# Package::     Whois
-# Author::      Simone Carletti <weppos@weppos.net>
-# License::     MIT License
-#
-#--
-#
+# Copyright (c) 2009-2011 Simone Carletti <weppos@weppos.net>
 #++
 
 
@@ -19,8 +12,16 @@ require 'ipaddr'
 
 module Whois
 
+  # The {Whois::Server} class has two important roles:
+  #
+  # 1. it acts as a database for the WHOIS server definitions
+  # 2. it is responsible for selecting the right adapter used to handle the query to the WHOIS server(s).
+  #
   class Server
 
+    # The {Whois::Server::Adapters} module is a namespace for all
+    # WHOIS server adapters. Each adapter is a subclass of {Whois::Server::Adapters::Base},
+    # customized to handle WHOIS queries for a type or a group of servers.
     module Adapters
       autoload :Base,             "whois/server/adapters/base"
       autoload :Arpa,             "whois/server/adapters/arpa"
@@ -35,11 +36,17 @@ module Whois
     end
 
 
+    # The WHOIS server definitions.
+    #
+    # @return [{ Symbol => Array }] The definition Hash.
+    # @private
     @@definitions = {}
 
-    # Searches the /definitions folder for definition files and loads them.
+    # Searches the +/definitions+ folder for definition files and loads them.
     # This method is automatically invoked when this file is parsed
     # by the Ruby interpreter (scroll down to the bottom of this file).
+    #
+    # @return [void]
     def self.load_definitions
       Dir[File.dirname(__FILE__) + '/definitions/*.rb'].each { |file| load(file) }
     end
@@ -47,24 +54,23 @@ module Whois
     # Lookup and returns the definition list for given <tt>type</tt>,
     # or all definitions if <tt>type</tt> is <tt>nil</tt>.
     #
-    # ==== Parameters
-    #
-    # type::  The type of WHOIS server to lookup.
+    # @param  [Symbol] type The type of WHOIS server to lookup.
     #         Known values are :tld, :ipv4, :ipv6.
     #
-    # ==== Returns
+    # @return [{ Symbol => Array }]
+    #         The definition Hash if +type+ is +nil+.
+    # @return [Array<Hash>]
+    #         The definitions for given +type+ if +type+ is not +nil+ and +type+ exists.
+    # @return [nil]
+    #         The definitions for given +type+ if +type+ is not +nil+ and +type+ doesn't exist.
     #
-    # Hash::  If the method is called without specifying a <tt>type</tt>.
-    # Array:: If the method is called specifying a <tt>type</tt>,
-    #         and the <tt>type</tt> exists.
-    # nil::   If the method is called specifying a <tt>type</tt>,
-    #         and the <tt>type</tt> doesn't exist.
-    #
-    # ==== Examples
+    # @example Return the definition database.
     #
     #   Whois::Server.definitions
     #   # => { :tld => [...], :ipv4 => [], ... }
     #
+    # @example Return the definitions for given key.
+    #
     #   Whois::Server.definitions(:tld)
     #   # => [...]
     #
@@ -81,26 +87,22 @@ module Whois
 
     # Defines a new server for <tt>:type</tt> queries.
     #
-    # ==== Parameters
-    #
-    # type::        The type of WHOIS server to define.
-    #               Known values are :tld, :ipv4, :ipv6.
-    # allocation::  The allocation, range or hostname
-    #               this server is responsible for.
-    # host::        The server hostname.
-    #               Use nil if unknown or not available.
-    # options::     Hash of options (default: {}).
-    #               The <tt>:adapter</tt> option has a special meaning
-    #               and determines the adapter Class to use.
-    #               Defaults to </tt>Whois::Server::Adapters::Standard</tt>
-    #               unless specified. All the other options are passed
-    #               directly to the adapter which can decide how to use them.
-    #
-    # ==== Returns
+    # @param  [Symbol] type
+    #         The type of WHOIS server to define.
+    #         Known values are :tld, :ipv4, :ipv6.
+    # @param  [String] allocation
+    #         The allocation, range or hostname, this server is responsible for.
+    # @param  [String, nil] host
+    #         The server hostname. Use nil if unknown or not available.
+    # @param  [Hash] options Optional definition properties.
+    # @option options [Class] :adapter (Whois::Server::Adapters::Standard)
+    #         This option has a special meaning and determines the adapter Class to use.
+    #         Defaults to {Whois::Server::Adapters::Standard} unless specified.
+    #         All the other options are passed directly to the adapter which can decide how to use them.
     #
-    # Nothing.
+    # @return [void]
     #
-    # ==== Examples
+    # @example
     #
     #   # Define a server for the .it extension
     #   Whois::Server.define :tld, ".it", "whois.nic.it"
@@ -128,7 +130,7 @@ module Whois
     # Creates a new server adapter from given arguments
     # and returns the server instance.
     #
-    # By default, returns a new Whois::Servers::Adapter::Standard instance.
+    # By default, returns a new {Whois::Server::Adapters::Standard} instance.
     # You can customize the behavior passing a custom adapter class
     # as <tt>:adapter</tt> option.
     #
@@ -140,38 +142,33 @@ module Whois
     #   # => #<Whois::Servers::Adapter::Custom>
     #
     # Please note that any adapter is responsible for a limited set
-    # of queries, which should be included in the range
-    # of the <tt>allocation</tt> parameter.
-    # Use <tt>Whois::Server#guess</tt> if you are not sure which adapter
+    # of queries, which should be included in the range of the <tt>allocation</tt> parameter.
+    # Use {Whois::Server.guess} if you are not sure which adapter
     # is the right one for a specific string.
     #
-    # ==== Parameters
-    #
-    # type::        The type of WHOIS server to define.
-    #               Known values are :tld, :ipv4, :ipv6.
-    # allocation::  The allocation, range or hostname
-    #               this server is responsible for.
-    # host::        The server hostname.
-    #               Use nil if unknown or not available.
-    # options::     Hash of options (default: {}).
-    #               The <tt>:adapter</tt> option has a special meaning
-    #               and determines the adapter Class to use.
-    #               Defaults to </tt>Whois::Server::Adapters::Standard</tt>
-    #               unless specified. All the other options are passed
-    #               directly to the adapter which can decide how to use them.
-    #
-    # ==== Returns
-    #
-    # Whois::Server::Adapters::Standard::
-    #   An adapter that can be used to perform queries.
+    # @param  [Symbol] type
+    #         The type of WHOIS server to define.
+    #         Known values are :tld, :ipv4, :ipv6.
+    # @param  [String] allocation
+    #         The allocation, range or hostname, this server is responsible for.
+    # @param  [String, nil] host
+    #         The server hostname. Use nil if unknown or not available.
+    # @param  [Hash] options Optional definition properties.
+    # @option options [Class] :adapter (Whois::Server::Adapters::Standard)
+    #         This option has a special meaning and determines the adapter Class to use.
+    #         Defaults to {Whois::Server::Adapters::Standard} unless specified.
+    #         All the other options are passed directly to the adapter which can decide how to use them.
+    #
+    # @return [Whois::Server::Adapters::Standard]
+    #         An adapter that can be used to perform queries.
     #
     def self.factory(type, allocation, host, options = {})
       options = options.dup
       (options.delete(:adapter) || Adapters::Standard).new(type, allocation, host, options)
     end
-    
-    
-    # Parses <tt>qstring</tt> and tries to guess the right server.
+
+
+    # Parses <tt>string</tt> and tries to guess the right server.
     #
     # It successfully detects the following query types:
     # * ipv6
@@ -182,49 +179,47 @@ module Whois
     #
     # Note that not all query types actually have a corresponding adapter.
     # For instance, the following request will result in a
-    # <tt>Whois::ServerNotSupported</tt> exception.
+    # {Whois::ServerNotSupported} exception.
     #
     #   Whois::Server.guess "mail@example.com"
     #
-    # ==== Returns
     #
-    # Whois::Server::Adapters::Base::
-    #   The adapter that can be used to perform
-    #   WHOIS queries for <tt>qstring</tt>.
+    # @param  [String] string
+    # @return [Whois::Server::Adapters::Base]
+    #         The adapter that can be used to perform
+    #         WHOIS queries for <tt>string</tt>.
     #
-    # ==== Raises
+    # @raise  [Whois::ServerNotFound]
+    #         When unable to find an appropriate WHOIS adapter
+    #         for <tt>string</tt>. Most of the cases, the <tt>string</tt>
+    #         haven't been recognised as one of the supported query types.
+    # @raise  [Whois::ServerNotSupported]
+    #         When the <tt>string</tt> type is detected,
+    #         but the object type doesn't have any supported WHOIS adapter associated.
     #
-    # Whois::ServerNotFound::
-    #   When unable to find an appropriate WHOIS adapter
-    #   for <tt>qstring</tt>. Most of the cases, the <tt>qstring</tt>
-    #   haven't been recognised as one of the supported query types.
-    # Whois::ServerNotSupported::
-    #   When the <tt>qstring</tt> type is detected,
-    #   but the object type doesn't have any supported WHOIS adapter associated.
-    #
-    def self.guess(qstring)
+    def self.guess(string)
       # Top Level Domain match
-      if matches_tld?(qstring)
+      if matches_tld?(string)
         return factory(:tld, ".", "whois.iana.org")
       end
-      
+
       # IP address (secure match)
-      if matches_ip?(qstring)
-        return find_for_ip(qstring)
+      if matches_ip?(string)
+        return find_for_ip(string)
       end
 
       # Email Address (secure match)
-      if matches_email?(qstring)
-        return find_for_email(qstring)
+      if matches_email?(string)
+        return find_for_email(string)
       end
 
       # Domain Name match
-      if server = find_for_domain(qstring)
+      if server = find_for_domain(string)
         return server
       end
 
       # Gave Over
-      raise ServerNotFound, "Unable to find a whois server for `#{qstring}'"
+      raise ServerNotFound, "Unable to find a WHOIS server for `#{string}'"
     end
 
 
@@ -243,24 +238,24 @@ module Whois
       end
 
 
-      def self.find_for_ip(qstring)
-        ip = IPAddr.new(qstring)
+      def self.find_for_ip(string)
+        ip = IPAddr.new(string)
         type = ip.ipv4? ? :ipv4 : :ipv6
         definitions(type).each do |definition|
           if IPAddr.new(definition.first).include?(ip)
             return factory(type, *definition)
           end
         end
-        raise AllocationUnknown, "IP Allocation for `#{qstring}' unknown. Server definitions might be outdated."
+        raise AllocationUnknown, "IP Allocation for `#{string}' unknown. Server definitions might be outdated."
       end
 
-      def self.find_for_email(qstring)
+      def self.find_for_email(string)
         raise ServerNotSupported, "No WHOIS server is known for email objects"
       end
 
-      def self.find_for_domain(qstring)
+      def self.find_for_domain(string)
         definitions(:tld).each do |definition|
-          return factory(:tld, *definition) if /#{Regexp.escape(definition.first)}$/ =~ qstring
+          return factory(:tld, *definition) if /#{Regexp.escape(definition.first)}$/ =~ string
         end
         nil
       end

data/lib/whois/server/adapters/afilias.rb

@@ -1,16 +1,9 @@
-#
-# = Ruby Whois
+#--
+# Ruby Whois
 #
 # An intelligent pure Ruby WHOIS client and parser.
 #
-#
-# Category::    Net
-# Package::     Whois
-# Author::      Simone Carletti <weppos@weppos.net>
-# License::     MIT License
-#
-#--
-#
+# Copyright (c) 2009-2011 Simone Carletti <weppos@weppos.net>
 #++
 
 
@@ -18,18 +11,36 @@ module Whois
   class Server
     module Adapters
 
+      #
+      # = Afilias Adapter
+      #
+      # Provides ability to query Afilias WHOIS interfaces.
+      #
+      # The following WHOIS servers are currently known
+      # to require the Afilias adapter:
+      #
+      # - whois.afilias-grs.info
+      #
       class Afilias < Base
 
-        def request(qstring)
-          response = ask_the_socket(qstring, "whois.afilias-grs.info", DEFAULT_WHOIS_PORT)
-          append_to_buffer response, "whois.afilias-grs.info"
+        # Executes a WHOIS query to the Afilias WHOIS interface,
+        # resolving any intermediate referral,
+        # and appends the response to the client buffer.
+        #
+        # @param  [String] string
+        # @return [void]
+        #
+        def request(string)
+          response = query_the_socket(string, host, DEFAULT_WHOIS_PORT)
+          buffer_append response, host
 
           if endpoint = extract_referral(response)
-            response = ask_the_socket(qstring, endpoint, DEFAULT_WHOIS_PORT)
-            append_to_buffer response, endpoint
+            response = query_the_socket(string, endpoint, DEFAULT_WHOIS_PORT)
+            buffer_append response, endpoint
           end
         end
 
+
         private
 
           def extract_referral(response)