whois 0.5.3 → 0.8.0

data/CHANGELOG.rdoc

@@ -1,6 +1,61 @@
 = Changelog
 
 
+== Release 0.8.0
+
+* FIXED: Server definition with :format doesn't use the Formatted adapter (closes #305)
+
+* ADDED: whois.denic.de (.de TLD) parser [Aaron Mueller]
+
+* ADDED: introduced support for multipart answers and Parser proxy class. This is useful in case of thin servers such as .com or .net because the parser needs to know all different responses in order to load all single scanners.
+
+* ADDED: whois.crsnic.net (.com, .net, ... TLDs) parser.
+
+* CHANGED: extracted all scanners into separated classes in order to make easier extract shared features.
+
+* CHANGED: renamed Whois::Response to Whois::Answer. This change is required to avoid confusion between query-answer and server request-response. A Whois::Answer is composed by one or more parts, corresponding to single server answers.
+
+* REMOVED: Whois::Answer#i_am_feeling_lucky (formerly Whois::Answer#i_am_feeling_lucky) become obsolete since the introduction of Answer parsers.
+
+
+== Release 0.6.0
+
+* ADDED: new more convenient method to query a whois server in addition to the existing Whois::whois method.
+
+    Whois::query("domain.com")
+    # same as Whois::whois but added to normalize application interfaces.
+
+    Whois::available?("domain.com")
+    # returns true if the domain is available.
+
+    Whois::registered?("domain.com")
+    # returns true if the domain is registered.
+
+* ADDED: Experimental support for whois response parsing. This release is shipped with two parsers for the .it and .net TLD.
+
+    r = Whois::query("google.it")
+    r.available?
+    # => false
+    r.created_on
+    # => Time.parse("1999-12-10 00:00:00")
+    r.Nameservers
+    # => ["ns1.google.com", "ns2.google.com", ...]
+
+* CHANGED: A whois query now returns a custom Whois::Response object instead of a simple string.
+  The previous interface is still supported, so you can continue to compare the response with Strings
+  but this behavior will be deprecated in a future release.
+  
+    r = Whois::query("domain.com")
+    # supported but deprecated in a future version
+    r == "NOT FOUND"
+    # explicitly cast the object to string instead
+    r.to_s == "NOT FOUND"
+    # or use one of the other Whois::Response methods.
+
+Note. This is an experimental version (EAP) and it should not be considered production-ready.
+API might change at any time without previous notice.
+
+
 == Release 0.5.3
 
 FIXED: self.valid_ipv6?(addr) references valid_v4? instead of valid_ipv4? (closes #300)

data/Manifest

@@ -6,6 +6,19 @@ data/make_ip6_del.pl
 data/make_ip_del.pl
 data/make_tld_serv.pl
 data/tld_serv_list
+lib/whois/answer/contact.rb
+lib/whois/answer/parser/base.rb
+lib/whois/answer/parser/blank.rb
+lib/whois/answer/parser/README.rdoc
+lib/whois/answer/parser/whois.crsnic.net.rb
+lib/whois/answer/parser/whois.denic.de.rb
+lib/whois/answer/parser/whois.nic.it.rb
+lib/whois/answer/parser/whois.publicinterestregistry.net.rb
+lib/whois/answer/parser.rb
+lib/whois/answer/part.rb
+lib/whois/answer/registrar.rb
+lib/whois/answer/super_struct.rb
+lib/whois/answer.rb
 lib/whois/client.rb
 lib/whois/definitions/ipv4.rb
 lib/whois/definitions/ipv4.txt
@@ -33,22 +46,44 @@ Manifest
 Rakefile
 README.rdoc
 tasks/server.rake
-test/adapters/afilias_test.rb
-test/adapters/none_test.rb
-test/adapters/not_implemented_test.rb
-test/adapters/pir_test.rb
-test/adapters/standard_test.rb
-test/adapters/verisign_test.rb
-test/adapters/web_test.rb
+test/answer/parser/base_test.rb
+test/answer/parser/blank_test.rb
+test/answer/parser/whois_crsnic_net_test.rb
+test/answer/parser/whois_denic_de_test.rb
+test/answer/parser/whois_nic_it_test.rb
+test/answer/parser/whois_publicinterestregistry_net_test.rb
+test/answer/parser_test.rb
+test/answer_test.rb
 test/client_test.rb
 test/deprecated_test.rb
+test/integration_test.rb
+test/server/adapters/afilias_test.rb
+test/server/adapters/base_test.rb
+test/server/adapters/formatted_test.rb
+test/server/adapters/none_test.rb
+test/server/adapters/not_implemented_test.rb
+test/server/adapters/pir_test.rb
+test/server/adapters/standard_test.rb
+test/server/adapters/verisign_test.rb
+test/server/adapters/web_test.rb
 test/server_test.rb
 test/test_helper.rb
 test/testcases/referrals/afilias.bz.txt
 test/testcases/referrals/crsnic.com.txt
 test/testcases/referrals/niccc.cc.txt
 test/testcases/referrals/pir.org.txt
-test/testcases/responses/it.txt
+test/testcases/responses/super_struct_test.rb
+test/testcases/responses/whois.crsnic.net/available.txt
+test/testcases/responses/whois.crsnic.net/registered.txt
+test/testcases/responses/whois.denic.de/available.txt
+test/testcases/responses/whois.denic.de/registered.txt
+test/testcases/responses/whois.nic.it/available.txt
+test/testcases/responses/whois.nic.it/registered.txt
+test/testcases/responses/whois.nic.it/status_active.txt
+test/testcases/responses/whois.nic.it/status_available.txt
+test/testcases/responses/whois.publicinterestregistry.net/available.txt
+test/testcases/responses/whois.publicinterestregistry.net/registered.txt
 test/whois_test.rb
+utils/bm_delegation_vs_inheritance.rb
 utils/bm_shell_vs_pure.rb
 utils/tlds.txt

data/README.rdoc

@@ -1,21 +1,24 @@
 = Whois
 
-Whois is an intelligent pure Ruby WHOIS client.
+Whois is an intelligent pure Ruby WHOIS client and parser.
 
 It is a os-independent library and doesn't require external C libraries or GEMS: it is a 100% Ruby software with all the advantages and disadvantages that it involves.
 
-This software was developed to power RoboDomain[http://www.robodomain.com] and, despite it has been using in a production environment since July 2009, it should not be considered production-ready yet. It is currently in its beta stage.
+This software was developed to power RoboDomain[http://www.robodomain.com] and, since July 2009, it run more than thousands requests.
 
 An extensive test suite is available to verify the library correctness but you must be aware that registrant might change Whois interfaces without notice and at any time causing queries to specific hosts to stop working.
 
 
 == Features
 
-* Written in pure Ruby without any additional dependency
-* Flexible and extensible with custom server
+* Pure Ruby library without any external dependency other than Ruby itself
+* Intelligent Ruby client
+* Flexible and extensible configuration with support for user-defined servers
+* Powerful whois response parser
 * Support for ipv6, ipv4 and top level domain whois queries
 * Object oriented design
 * Compatible with older Whois version (Whois 0.4.2, see below)
+* Compatible with Ruby 1.8.6 and greater, including Ruby 1.9
 
 
 == Requirements
@@ -43,26 +46,28 @@ You might need administrator privileges on your system to install it.
 
 == Getting Started
 
-Note. This section covers only the essentials for getting started with the Whois library. If you want to take the full advantage of all its features, visit the {documentation page}[http://code.simonecarletti.com/wiki/whois].
+Note. This section covers only the essentials for getting started with the Whois library. The {documentation}[http://code.simonecarletti.com/wiki/whois] provides a more accurate explanation including tutorials, more examples and technical details about the client/server/answer/parser architecture.
 
-Whois provides the ability to get whois information for hostnames, ipv4 and ipv6 ip addresses. The client is smart enough to guess the best whois server according to given query, send the request and return the response.
+=== Querying the Server
+
+Whois provides the ability to get WHOIS information for hostnames, ipv4 and ipv6 ip addresses. The client is smart enough to guess the best WHOIS server according to given query, send the request and return the response.
 
 Checkout the following examples:
 
   # Domain Whois
   w = Whois::Client.new
   w.query("google.com")
-  # => whois response for google.com
+  # => #<Whois::Answer>
 
   # IPv4 Whois
   w = Whois::Client.new
   w.query("74.125.67.100")
-  # => whois response for 74.125.67.100
+  # => #<Whois::Answer>
 
   # IPv6 Whois
   w = Whois::Client.new
   w.query("2001:db8::1428:57ab")
-  # => whois response for 2001:db8::1428:57ab
+  # => #<Whois::Answer>
 
 The query method is stateless. For this reason, you can safely re-use the same client instance for multiple queries.
 
@@ -72,6 +77,43 @@ The query method is stateless. For this reason, you can safely re-use the same c
   w.query("2001:db8::1428:57ab")
   w.query("google.it")
 
+If you just need a WHOIS response and you don't care about a full control of the WHOIS Client, Whois comes with a simple method called whois. This is the simplest way to send a WHOIS request.
+
+  Whois.whois("google.com")
+  # => #<Whois::Answer>
+
+=== Consuming the Answer
+
+As of release 0.8, a WHOIS query no longer returns a simple string. Instead, you get a full Whois::Answer instance and this is just the beginning of the story.
+
+Whois::Answer is a super powerful object. It encapsulates the full WHOIS answer and it provides you the ability to parse the WHOIS response with a full object oriented notation.
+
+  a = Whois.whois("google.it")
+  # => #<Whois::Answer>
+  
+  a.available?
+  # => false
+  a.registered?
+  # => true
+  
+  a.created_on
+  # => Fri Dec 10 00:00:00 +0100 1999
+  
+  t = a.techinical
+  # => #<Whois::Answer::Contact>
+  t.id
+  # => "TS7016-ITNIC"
+  t.name
+  # => "Technical Services"
+  
+  a.nameservers.each do |nameserver|
+    puts nameserver
+  end
+
+This feature is made possible by the Whois answer parsers. Unfortunately, due to the lack of a global standard, each WHOIS server requires a specific parser. For this reason, the library doesn't support all existing WHOIS servers.
+
+If you create a new parser, please consider releasing it to the public so that it can be included in a next version.
+
 === Timeout
 
 By default, each query run though the client has a timeout value of 5 seconds. If the execution exceeds timeout limit, the client raises a <tt>Timeout::Error</tt> exception.
@@ -101,7 +143,7 @@ The parser architecture (yet to come) has been inspired by the PHPWhois[http://p
 Despite I spent weeks reading source code from the available whois libraries, Ruby Whois has been built from scratch trying to focus on long-term maintainability and flexibility and cannot be considered a Ruby port of any of other existing Whois libraries.
 
 
-== Notice for users of Whois 0.4.2 (or previous version)
+== Notice for users of Whois 0.4 (or previous version)
 
 As of release 0.5.0, the Whois GEM has been completely rewritten. As I explained in the Acknowledgment section, Cyril Mougel (the author of the original Whois package) yield me the privilege to use the Whois RubyForge project for my new Whois client.
 
@@ -117,7 +159,7 @@ Copyright (c) 2007 by Cyril Mougel (cyril.mougel@gmail.com)
 == Credits
 
 Author:: {Simone Carletti}[http://www.simonecarletti.com/] <weppos@weppos.net>
-First Whois Version:: {Cyril Mougel}[http://blog.shingara.fr/] <cyril.mougel@gmail.com>
+Author (Whois 0.4):: {Cyril Mougel}[http://blog.shingara.fr/] <cyril.mougel@gmail.com>
 
 
 == FeedBack and Bug reports
@@ -132,8 +174,6 @@ Bug reports and Feature suggestions {are welcomed}[http://code.simonecarletti.co
 * {Homepage}[http://code.simonecarletti.com/whois]
 * {GitHub}[http://github.com/weppos/whois]
 * {RubyForge}[http://rubyforge.org/projects/whois/]
-
-* {Documentation}[http://code.simonecarletti.com/wiki/whois]
 * {API}[http://whois.rubyforge.org/]
 * {Discussion Group}[http://groups.google.com/group/ruby-whois]
 
@@ -143,13 +183,6 @@ Bug reports and Feature suggestions {are welcomed}[http://code.simonecarletti.co
 See the CHANGELOG.rdoc file for details.
 
 
-== Roadmap
-
-* Implement intelligent Whois response parsing
-
-For more details visit the {roadmap page}[http://code.simonecarletti.com/projects/roadmap/whois].
-
-
 == License
 
 Copyright (c) 2009 Simone Carletti, Whois is released under the MIT license.

data/lib/whois.rb

@@ -18,6 +18,7 @@ require 'whois/version'
 require 'whois/errors'
 require 'whois/client'
 require 'whois/server'
+require 'whois/answer'
 require 'whois/whois'
 
 
@@ -26,8 +27,75 @@ module Whois
   NAME            = 'Whois'
   GEM             = 'whois'
   AUTHORS         = ['Simone Carletti <weppos@weppos.net>']
-  
+
+
+  # Queries the right whois server for <tt>qstring</tt> and returns
+  # a <tt>Whois::Answer</tt> instance containing the response from the server.
+  #
+  #   Whois.query("google.com")
+  #   # => #<Whois::Answer>
+  #
+  # This is equivalent to
+  #
+  #   Whois::Client.new.query("google.com")
+  #   # => #<Whois::Answer>
+  #
   def self.whois(qstring)
+    query(qstring)
+  end
+
+  # Returns <tt>true</tt> whether <tt>qstring</tt> is available.
+  # <tt>qstring</tt> is intended to be a domain name,
+  # otherwise this method may return unexpected responses.
+  #
+  #   Whois.available?("google.com")
+  #   # => false
+  #   
+  #   Whois.available?("google-is-not-available-try-again-later.com")
+  #   # => true
+  #
+  # Warning: this method is only available if a Whois parser exists
+  # for <tt>qstring</tt> top level domain. Otherwise you'll get a warning message
+  # and the method will return <tt>nil</tt>.
+  # This is a technical limitation. Browse the lib/whois/answer/parsers folder
+  # to view all available parsers.
+  #
+  def self.available?(qstring)
+    query(qstring).available?
+  rescue ParserNotFound => e
+    $stderr.puts  "This method is not available for this kind of object.\n" +
+                  "Use Whois.query('#{qstring}') instead."
+    nil
+  end
+
+  # Returns <tt>true</tt> whether <tt>qstring</tt> is registered.
+  # <tt>qstring</tt> is intended to be a domain name,
+  # otherwise this method may return unexpected responses.
+  #
+  #   Whois.registered?("google.com")
+  #   # => true
+  #   
+  #   Whois.registered?("google-is-not-available-try-again-later.com")
+  #   # => false
+  #
+  # Warning: this method is only available if a Whois parser exists
+  # for <tt>qstring</tt> top level domain. Otherwise you'll get a warning message
+  # and the method will return <tt>nil</tt>.
+  # This is a technical limitation. Browse the lib/whois/answer/parsers folder
+  # to view all available parsers.
+  #
+  def self.registered?(qstring)
+    query(qstring).registered?
+  rescue ParserNotFound => e
+    $stderr.puts  "This method is not available for this kind of object.\n" +
+                  "Use Whois.query('#{qstring}') instead."
+    nil
+  end
+
+
+  # See Whois#whois.
+  def self.query(qstring)
     Client.new.query(qstring)
   end
+
 end

data/lib/whois/answer.rb

@@ -0,0 +1,126 @@
+#
+# = Ruby Whois
+#
+# An intelligent pure Ruby WHOIS client.
+#
+#
+# Category::    Net
+# Package::     Whois
+# Author::      Simone Carletti <weppos@weppos.net>
+# License::     MIT License
+#
+#--
+#
+#++
+
+
+require 'whois/answer/parser'
+require 'whois/answer/parser/base'
+
+
+module Whois
+
+  class Answer
+
+    attr_reader :server
+    attr_reader :parts
+
+    def initialize(server, parts)
+      @parts  = parts
+      @server = server
+    end
+
+    
+    def to_s
+      content.to_s
+    end
+    
+    def inspect
+      content.inspect
+    end
+    
+    # Invokes <tt>match</tt> on answer <tt>@content</tt>
+    # and returns the <tt>MatchData</tt> or <tt>nil</tt>.
+    def match(pattern)
+      content.match(pattern)
+    end
+    
+    # Returns true if the <tt>object</tt> is the same object,
+    # or is a string and has the same content.
+    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)
+    end
+    
+    # Delegates to ==.
+    def eql?(other)
+      self == other
+    end
+
+
+    # Returns the content of this answer as a string.
+    # This method joins all answer parts into a single string
+    # and separates each response with a newline character.
+    #
+    #   answer = Whois::Answer.new([Whois::Answer::Part.new("First answer.")])
+    #   answer.content
+    #   # => "First answer."
+    #
+    #   answer = Whois::Answer.new([Whois::Answer::Part.new("First answer."), Whois::Answer::Part.new("Second answer.")])
+    #   answer.content
+    #   # => "First answer.\nSecond answer."
+    #
+    def content
+      @content ||= parts.map { |part| part.response }.join("\n")
+    end
+
+    # Returns whether this answer changed compared to <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>.
+    def changed?(other)
+      !unchanged?(other)
+    end
+
+    # The opposite of <tt>changed?</tt>.
+    def unchanged?(other)
+      self == other ||
+      parser.unchanged?(other.parser)
+    end
+
+
+    # Invokes <tt>match</tt> and returns <tt>true</tt> if <tt>pattern</tt>
+    # matches <tt>@content</tt>, <tt>false</tt> otherwise.
+    def match?(pattern)
+      !content.match(pattern).nil?
+    end
+
+
+    # Lazy-loads and returns a <tt>Whois::Answer::Parser</tt> proxy for current answer.
+    def parser
+      @parser ||= Parser.new(self)
+    end
+
+
+    protected
+      
+      # Delegates all method calls to the internal parser.
+      def method_missing(method, *args, &block)
+        if Parser.registrable_methods.include?(method)
+          parser.send(method, *args, &block)
+        else
+          super
+        end
+      end
+      
+  end
+
+end