whois 1.1.2 → 1.1.3

data/CHANGELOG.rdoc

@@ -1,6 +1,17 @@
 = Changelog
 
 
+== Release 1.1.3
+
+* NEW: Added simple .tk TLD parser (whois.dot.tk).
+
+* NEW: Added .sn TLD parser (whois.nic.sn).
+
+* CHANGED: Whois::Answer#== and Whois::Answer#eql? should be able to compare Whois::Answer with subclasses.
+
+* CHANGED: Deprecate Whois::Answer::Parser.properties. Use Whois::Answer::Parser::PROPERTIES instead.
+
+
 == Release 1.1.2
 
 * NEW: Whois::Answer::Contact#type property returns the type of the contact (ADMIN, TECHNICAL, ...).

data/Manifest

@@ -21,6 +21,7 @@ lib/whois/answer/parser/NOTES.txt
 lib/whois/answer/parser/ast.rb
 lib/whois/answer/parser/base.rb
 lib/whois/answer/parser/blank.rb
+lib/whois/answer/parser/example.rb
 lib/whois/answer/parser/jobswhois.verisign-grs.com.rb
 lib/whois/answer/parser/scanners/verisign.rb
 lib/whois/answer/parser/whois.adamsnames.tc.rb
@@ -44,6 +45,7 @@ lib/whois/answer/parser/whois.dns.lu.rb
 lib/whois/answer/parser/whois.domain-registry.nl.rb
 lib/whois/answer/parser/whois.domainregistry.ie.rb
 lib/whois/answer/parser/whois.domreg.lt.rb
+lib/whois/answer/parser/whois.dot.tk.rb
 lib/whois/answer/parser/whois.dotmobiregistry.net.rb
 lib/whois/answer/parser/whois.educause.edu.rb
 lib/whois/answer/parser/whois.eu.org.rb
@@ -80,6 +82,7 @@ lib/whois/answer/parser/whois.nic.mx.rb
 lib/whois/answer/parser/whois.nic.name.rb
 lib/whois/answer/parser/whois.nic.nu.rb
 lib/whois/answer/parser/whois.nic.or.kr.rb
+lib/whois/answer/parser/whois.nic.sn.rb
 lib/whois/answer/parser/whois.nic.st.rb
 lib/whois/answer/parser/whois.nic.tel.rb
 lib/whois/answer/parser/whois.nic.tl.rb
@@ -149,6 +152,7 @@ test/answer/parser/whois.dns.lu_test.rb
 test/answer/parser/whois.domain-registry.nl_test.rb
 test/answer/parser/whois.domainregistry.ie_test.rb
 test/answer/parser/whois.domreg.lt_test.rb
+test/answer/parser/whois.dot.tk_test.rb
 test/answer/parser/whois.dotmobiregistry.net_test.rb
 test/answer/parser/whois.educause.edu_test.rb
 test/answer/parser/whois.eu.org_test.rb
@@ -185,6 +189,7 @@ test/answer/parser/whois.nic.mx_test.rb
 test/answer/parser/whois.nic.name_test.rb
 test/answer/parser/whois.nic.nu_test.rb
 test/answer/parser/whois.nic.or.kr_test.rb
+test/answer/parser/whois.nic.sn_test.rb
 test/answer/parser/whois.nic.st_test.rb
 test/answer/parser/whois.nic.tel_test.rb
 test/answer/parser/whois.nic.tl_test.rb
@@ -300,6 +305,8 @@ test/testcases/responses/whois.domainregistry.ie/registered.txt
 test/testcases/responses/whois.domreg.lt/available.txt
 test/testcases/responses/whois.domreg.lt/property_nameservers_with_ip.txt
 test/testcases/responses/whois.domreg.lt/registered.txt
+test/testcases/responses/whois.dot.tk/available.txt
+test/testcases/responses/whois.dot.tk/registered.txt
 test/testcases/responses/whois.dotmobiregistry.net/available.txt
 test/testcases/responses/whois.dotmobiregistry.net/registered.txt
 test/testcases/responses/whois.educause.edu/available.txt
@@ -396,6 +403,8 @@ test/testcases/responses/whois.nic.nu/available.txt
 test/testcases/responses/whois.nic.nu/registered.txt
 test/testcases/responses/whois.nic.or.kr/available.txt
 test/testcases/responses/whois.nic.or.kr/registered.txt
+test/testcases/responses/whois.nic.sn/available.txt
+test/testcases/responses/whois.nic.sn/registered.txt
 test/testcases/responses/whois.nic.st/available.txt
 test/testcases/responses/whois.nic.st/registered.txt
 test/testcases/responses/whois.nic.tel/available.txt

data/lib/core_ext.rb

@@ -1,12 +1,17 @@
 unless :to_proc.respond_to?(:to_proc)
   class Symbol
-    # Turns the symbol into a simple proc, which is especially useful for enumerations. Examples:
+    # Turns the symbol into a simple proc, 
+    # which is especially useful for enumerations.
+    # 
+    # Examples
     #
     #   # The same as people.collect { |p| p.name }
     #   people.collect(&:name)
     #
     #   # The same as people.select { |p| p.manager? }.collect { |p| p.salary }
     #   people.select(&:manager?).collect(&:salary)
+    #
+    # Returns a Proc which incapsulates the method business logic.
     def to_proc
       Proc.new { |*args| args.shift.__send__(self, *args) }
     end

data/lib/whois/answer.rb

@@ -56,8 +56,8 @@ module Whois
     def ==(other)
       (other.equal?(self)) ||
       # This option should be deprecated
-      (other.instance_of?(String) && other == self.to_s) ||
-      (other.instance_of?(Answer) && other.to_s == self.to_s)
+      (other.is_a?(String) && other == self.to_s) ||
+      (other.is_a?(Answer) && other.to_s == self.to_s)
     end
 
     # Delegates to ==.
@@ -118,7 +118,7 @@ module Whois
     # along with corresponding values.
     def properties
       hash = {}
-      Parser.properties.each { |property| hash[property] = send(property) }
+      Parser::PROPERTIES.each { |property| hash[property] = send(property) }
       hash
     end
 
@@ -134,7 +134,7 @@ module Whois
 
       # Delegates all method calls to the internal parser.
       def method_missing(method, *args, &block)
-        if (Parser.properties + Parser::METHODS).include?(method)
+        if (Parser::PROPERTIES + Parser::METHODS).include?(method)
           self.class.class_eval foo = %{
             def #{method}(*args, &block)
               if property_supported?(:#{method})

data/lib/whois/answer/parser.rb

@@ -28,7 +28,7 @@ module Whois
         :registrant, :admin, :technical,
       ]
 
-      @@properties = [
+      PROPERTIES = [
         :disclaimer,
         :domain, :domain_id,
         :referral_whois, :referral_url,
@@ -39,13 +39,6 @@ module Whois
         :nameservers,
       ]
 
-      # Returns an array containing the name of all properties
-      # that can be registered and should be implemented by
-      # server-specific parsers.
-      def self.properties
-        @@properties
-      end
-
       attr_reader :answer
 
 
@@ -77,9 +70,9 @@ module Whois
       private
 
         def method_missing(method, *args, &block)
-          if Parser.properties.include?(method)
+          if PROPERTIES.include?(method)
             delegate_to_parsers(method, *args, &block)
-          elsif Parser::METHODS.include?(method)
+          elsif METHODS.include?(method)
             delegate_to_parsers(method, *args, &block)
           else
             super
@@ -108,22 +101,45 @@ module Whois
           end
         end
 
-        # Loops through all answer parts, for each parts tries to guess
-        # the appropriate Whois::Answer::Parser::<parser> if it exists
+        # Protected: Loops through all answer parts, for each parts tries to guess
+        # the appropriate parser object whenever available,
         # and returns the final array of server-specific parsers.
         #
         # Parsers are initialized in reverse order for performance reason.
-        # See also <tt>select_parser</tt>.
+        # See also <tt>#select_parser</tt>.
+        #
+        # Examples
         #
         #   parser.parts
         #   # => [whois.foo.com, whois.bar.com]
         #   parser.parsers
-        #   # => [parser(whois.bar.com), parser(whois.foo.com)]
+        #   # => [Whois::Answer::Parser::WhoisBarCom, Whois::Answer::Parser::WhoisFooCom]
         #
+        # Returns an Array of Class, where
+        #   each item is the parts reverse-N specific parser Class.
+        #   Each Class is expected to be a child of Whois::Answer::Parser::Base.
         def init_parsers
           answer.parts.reverse.map { |part| self.class.parser_for(part) }
         end
 
+        # Protected: Selects the first parser in <tt>#parsers</tt>
+        # where <tt>given</tt> matches <tt>status</tt>.
+        #
+        # property - The Symbol property to search for
+        # status - The Symbol status (default: :any)
+        #
+        #
+        # Examples
+        #
+        #   select_parser(:nameservers)
+        #   # => #<Whois::Answer::Parser::WhoisExampleCom>
+        #
+        #   select_parser(:nameservers, :supported)
+        #   # => nil
+        #
+        # Returns an instance of Whois::Answer::Parser::Base
+        #   with the parser which satisfies given requirement,
+        #   or nil the parser wasn't found.
         def select_parser(property, status = :any)
           parsers.each do |parser|
             return parser if parser.class.property_registered?(property, status)
@@ -132,30 +148,54 @@ module Whois
         end
 
 
-      # Returns the proper <tt>Whois::Answer::Parser::Base</tt> instance
-      # for given <tt>part</tt>.
-      # The parser class depends on the <tt>Whois::Answer::Part</tt> host.
+      # Public: Returns the proper parser instance for given <tt>part</tt>.
+      # The parser class is selected according to the
+      # value of the <tt>#host</tt> attribute for given <tt>part</tt>.
+      #
+      # part - The Whois::Answer::Parser::Part to get the parser for
+      #
+      # Examples
+      #
+      #   # Parser for a known host
+      #   Parser.parser_for("whois.example.com")
+      #   #<Whois::Answer::Parser::WhoisExampleCom>
+      #
+      #   # Parser for an unknown host
+      #   Parser.parser_for("missing.example.com")
+      #   #<Whois::Answer::Parser::Blank>
+      #
+      # Returns an instance of the specific parser for given part.
+      #   The instance is expected to be a child of Whois::Answer::Parser::Base.
       def self.parser_for(part)
         parser_klass(part.host).new(part)
       end
 
-      # Detects the proper parser class according to given <tt>host</tt>
+      # Public: Detects the proper parser class according to given <tt>host</tt>
       # and returns the class constant.
-      # If no parser exists for <tt>host</tt>, then returns a generic
-      # <tt>Whois::Answer::Parser::Blank</tt>.
       #
       # This method autoloads missing parser classes. If you want to define
       # a custom parser, simple make sure the class is loaded in the Ruby
       # environment before this method is called.
       #
-      #   Parser.parser_klass("whois.missing.com")
+      # host - A String with the host
+      #
+      # Examples
+      #
+      #   Parser.parser_klass("missing.example.com")
       #   # => Whois::Answer::Parser::Blank
       #
-      #   class Whois::Answer::Parser::WhoisMissingCom
+      #   # Define a custom parser for missing.example.com
+      #   class Whois::Answer::Parser::MissingExampleCom
       #   end
-      #   Parser.parser_klass("whois.missing.com")
-      #   # => Whois::Answer::Parser::WhoisMissingCom
       #
+      #   Parser.parser_klass("missing.example.com")
+      #   # => Whois::Answer::Parser::MissingExampleCom
+      #
+      # Returns an instance of Class representing the parser Class
+      #   corresponding to <tt>host</tt>.
+      #   If <tt>host</tt> doesn't have a specific parser implementation,
+      #   then returns the Whois::Answer::Parser::Blank Class.
+      #   The Class is expected to be a child of Whois::Answer::Parser::Base.
       def self.parser_klass(host)
         name = host_to_parser(host)
         Parser.const_defined?(name) || autoload(host)
@@ -166,26 +206,40 @@ module Whois
         Parser::Blank
       end
 
-      # Converts <tt>host</tt> to a parser class name.
-      # Note. Returns a <tt>String</tt>, not a <tt>Class</tt>.
+      # Public: Converts <tt>host</tt> to the corresponding parser class name.
+      #
+      # host - A String with the host
+      #
+      # Examples
       #
       #   Parser.host_to_parser("whois.nic.it")
       #   # => "WhoisNicIt"
       #   Parser.host_to_parser("whois.nic-info.it")
       #   # => "WhoisNicInfoIt"
       #
+      # Returns a String with the class name.
       def self.host_to_parser(host)
         host.to_s.
           gsub(/[.-]/, '_').
           gsub(/(?:^|_)(.)/)  { $1.upcase }
       end
 
-      # Requires the file at "whois/answer/parser/#{name}".
+      # Public: Requires the file at <tt>whois/answer/parser/#{name}</tt>.
+      #
+      # name - A string with the file name
+      #
+      # Returns nothing.
       def self.autoload(name)
         file = "whois/answer/parser/#{name}"
         require file
       end
 
+
+      def self.properties # :nodoc
+        Whois.deprecate("Whois::Answer::Parser.properties is deprecated. Use the Whois::Answer::Parser::PROPERTIES constant.")
+        PROPERTIES
+      end
+
     end
 
   end

data/lib/whois/answer/parser/base.rb

@@ -216,7 +216,7 @@ module Whois
         end
 
 
-        ::Whois::Answer::Parser.properties.each do |property|
+        Whois::Answer::Parser::PROPERTIES.each do |property|
           property_not_implemented(property)
         end
 

data/lib/whois/answer/parser/blank.rb

@@ -32,7 +32,7 @@ module Whois
       #
       class Blank < Base
 
-        ::Whois::Answer::Parser.properties.each do |method|
+        Whois::Answer::Parser::PROPERTIES.each do |method|
           define_method(method) do
             raise ParserNotFound, "Unable to find a parser for the server `#{part.host}'"
           end

data/lib/whois/answer/parser/example.rb

@@ -0,0 +1,191 @@
+#
+# = Ruby Whois
+#
+# An intelligent pure Ruby WHOIS client and parser.
+#
+#
+# Category::    Net
+# Package::     Whois
+# Author::      Simone Carletti <weppos@weppos.net>
+# License::     MIT License
+#
+#--
+#
+#++
+
+
+require 'whois/answer/parser/base'
+
+
+module Whois
+  class Answer
+    class Parser
+
+      #
+      # = whois.example.com parser
+      #
+      # Parser for the whois.example.com server.
+      #
+      class WhoisExampleCom < Base
+
+        # Public: Gets the registry disclaimer that comes with the answer.
+        #
+        # Returns a String with the disclaimer if available,
+        # <tt>nil</tt> otherwise.
+        property_supported :disclaimer do
+          @disclaimer ||= nil
+        end
+
+
+        # Public: Gets the domain name as stored by the registry.
+        #
+        # Returns a String with the domain name if available,
+        # <tt>nil</tt> otherwise.
+        property_supported :domain do
+          @domain ||= nil
+        end
+
+        # Public: Gets the unique domain ID as stored by the registry.
+        #
+        # Returns a String with the domain ID if available,
+        # <tt>nil</tt> otherwise.
+        property_supported :domain_id do
+          @domain_id ||= nil
+        end
+
+
+        # Public: Gets the record status or statuses.
+        #
+        # Returns a String/Array with the record status if available,
+        # <tt>nil</tt> otherwise.
+        property_supported :status do
+          @status ||= nil
+        end
+
+        # Public: Checks whether this record is available.
+        #
+        # Returns true/false depending whether this record is available.
+        property_supported :available? do
+          @available ||= nil
+        end
+
+        # Public: Checks whether this record is registered.
+        #
+        # Returns true/false depending this record is available.
+        property_supported :registered? do
+          @registered ||= nil
+        end
+
+
+        # Public: Gets the date the record was created,
+        # according to the registry answer.
+        #
+        # Returns a Time object representing the date the record was created or
+        # <tt>nil</tt> otherwise.
+        property_supported :created_on do
+          @created_on ||= nil
+        end
+
+        # Public: Gets the date the record was last updated,
+        # according to the registry answer.
+        #
+        # Returns a Time object representing the date the record was last updated or
+        # <tt>nil</tt> if not available.
+        property_supported :updated_on do
+          @updated_on ||= nil
+        end
+
+        # Public: Gets the date the record is set to expire,
+        # according to the registry answer.
+        #
+        # Returns a Time object representing the date the record is set to expire or
+        # <tt>nil</tt> if not available.
+        property_supported :expires_on do
+          @expires_on ||= nil
+        end
+
+
+        # Public: Gets the registrar object containing the registrar details
+        # extracted from the registry answer.
+        #
+        # Returns an instance of <tt>Whois::Answer::Registrar</tt> representing the registrar or
+        # <tt>nil</tt> if not available.
+        property_supported :registrar do
+          @registrar ||= nil
+        end
+
+
+        # Public: Gets the registrant contact object containing the details of the record owner
+        # extracted from the registry answer.
+        #
+        # Returns an instance of <tt>Whois::Answer::Contact</tt> representing the registrant contact or
+        # <tt>nil</tt> if not available.
+        property_supported :registrant_contact do
+          @registrant_contact ||= nil
+        end
+
+        # Public: Gets the administrative contact object containing the details of the record administrator
+        # extracted from the registry answer.
+        #
+        # Returns an instance of <tt>Whois::Answer::Contact</tt> representing the administrative contact or
+        # <tt>nil</tt> if not available.
+        property_supported :admin_contact do
+          @admin_contact ||= nil
+        end
+
+        # Public: Gets the technical contact object containing the details of the technical representative
+        # extracted from the registry answer.
+        #
+        # Returns an instance of <tt>Whois::Answer::Contact</tt> representing the technical contact or
+        # <tt>nil</tt> if not available.
+        property_supported :technical_contact do
+          @technical_contact ||= nil
+        end
+
+
+        # Public: Gets the list of name server entries for this record,
+        # extracted from the registry answer.
+        #
+        # Examples
+        #
+        #   nameserver
+        #   # => []
+        #   nameserver
+        #   # => ["ns2.google.com", "ns1.google.com", "ns3.google.com"]
+        #
+        #
+        # Returns an Array of lower case String where each String is a name server entry,
+        # an empty Array if no name server was found.
+        property_supported :nameservers do
+          @nameservers ||= []
+        end
+
+
+        # Public: Checks whether this answer is different than <tt>other</tt>.
+        #
+        # Comparing the Answer contents is not always as trivial as it seems.
+        # Whois servers sometimes inject dynamic method into the whois answer such as
+        # the timestamp the request was generated.
+        # This causes two answers to be different even if they actually should be considered equal
+        # because the registry data didn't change.
+        #
+        # This method should provide a bulletproof way to detect whether this answer
+        # changed if compared with <tt>other</tt>.
+        #
+        # Returns true/false depending whether this answer is different than <tt>other</tt>.
+        property_supported :changed? do |other|
+          !unchanged?(other)
+        end
+
+        # Public: The opposite of <tt>#changed?</tt>.
+        #
+        # Returns true/false depending whether this answer is not different than <tt>other</tt>.
+        property_supported :unchanged? do |other|
+          false
+        end
+
+      end
+
+    end
+  end
+end