= Whois

Whois is an intelligent pure Ruby WHOIS client.

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.

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
* Support for ipv6, ipv4 and top level domain whois queries
* Object oriented design
* Compatible with older Whois version (Whois 0.4.2, see below)


== Requirements

* Ruby >= 1.8.6 (not tested with previous versions)

Whois has been {successfully tested}[http://code.simonecarletti.com/wiki/whois/Platforms] against the following Ruby platforms:

* Ruby 1.8.6 / 1.8.7 / 1.9.1
* MacRuby 0.4
* Ruby Enterprise Edition

Do you run any other Ruby platform or version? Are you experiencing any problem? Join our {discussion group}[http://groups.google.com/group/ruby-whois].


== Installation

This library is intended to be installed via the
RubyGems[http://rubyforge.org/projects/rubygems/] system.

  $ gem install whois

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].

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

  # IPv4 Whois
  w = Whois::Client.new
  w.query("74.125.67.100")
  # => whois response for 74.125.67.100

  # IPv6 Whois
  w = Whois::Client.new
  w.query("2001:db8::1428:57ab")
  # => whois response for 2001:db8::1428:57ab

The query method is stateless. For this reason, you can safely re-use the same client instance for multiple queries.

  w = Whois::Client.new
  w.query("google.com")
  w.query("74.125.67.100")
  w.query("2001:db8::1428:57ab")
  w.query("google.it")

=== 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.

Off course, you can customize the timeout value setting a different value. If timeout is <tt>nil</tt>, the client will until the response is sent back from the server or the process is killed. Don't disable the timeout unless you really know you are doing!

  w = Whois::Client.new(:timeout => 10)
  w.timeout # => 10
  w.timeout = 5
  w.timeout # => 5
  
  w.query("google.com")


== Acknowledgments

First of all, I would like to express my most sincere thanks to Cyril Mougel, the author of the first Ruby Whois GEM that has been available since 2007. Cyril has been kind enough to yield me the privilege of using the RubyForge Whois project and the Whois package name to publish this library.
To express all my gratitude, the Release 0.5.0 of the new Ruby Whois is 100% compatible with Cyril's Whois (as of release 0.4.2).

Whois is largely inspired by other notable Whois projects, most of all the Debian Whois library written and mainained by Marco D'Itri. Other good ideas and design decisions come from the PERL Net::DRI package.

I would lie if I say I'm completely unaware of the other Ruby Whois projects. Before starting this Ruby Whois library I deeply investigated the available resources and, despite none of them was a good candidate for a refactoring, some of them expose a really cool API.
They didn't directly influence this library or any design decision, but they have been a really interesting code-reading.

The parser architecture (yet to come) has been inspired by the PHPWhois[http://phpwhois.sourceforge.net/] project. The authors puts lot of effort to create whois-specific parsers normalizing the different responses in a single tree-based structure. So far, this is the only one opensource project that offers such this feature in all the programming language ecosystem.

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)

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.

My Whois client provides all the features offered by Cyril's library, with some nice additions like the ability to get top level domain query information. All existing users won't be affected by this change since the new Whois library comes with a compatibility adapter that translates all the requests from the deprecated interface to the new one.

The adapter will be removed in a future version so make sure to check your application for deprecation warnings and fix them before upgrading to a newest release that doesn't belong to the 0.5.x series.

Ruby Whois 0.4.2 is released under the MIT license.

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>


== FeedBack and Bug reports

If you use this library and find yourself missing any functionality I have missed, please {let me know}[mailto:weppos@weppos.net].

Bug reports and Feature suggestions {are welcomed}[http://code.simonecarletti.com/projects/whois/issues].


== Resources

* {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]


== Changelog

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.