Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 211 lines (126 sloc) 8.967 kb
ae63104 @weppos whois.nic.ki parser must support `Delegated' status (closes #119)
authored
1 # Whois
c49b6f5 @weppos Release Whois 0.1.0
authored
2
67196a8 @weppos Update README.md
authored
3 *Whois* is an intelligent pure Ruby WHOIS client and parser.
cf1f55a @weppos Improved documentation. Added Timeout section.
authored
4
c8af3e1 @weppos Add build status.
authored
5 [![Build Status](https://secure.travis-ci.org/weppos/whois.png)](http://travis-ci.org/weppos/whois)
6
67196a8 @weppos Update README.md
authored
7 *Whois* is a OS-independent library and doesn't require any external binaries or C libraries: it is a 100% Ruby software.
6949606 @weppos Starting with some basic documentation
authored
8
ef19897 @weppos Mention RoboWhois as well.
authored
9 This library was developed to power [RoboDomain](https://www.robodomain.com/) and [RoboWhois](http://www.robowhois.com/). It has been performing queries in production since July 2009.
6949606 @weppos Starting with some basic documentation
authored
10
67196a8 @weppos Update README.md
authored
11 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.
6949606 @weppos Starting with some basic documentation
authored
12
13
ae63104 @weppos whois.nic.ki parser must support `Delegated' status (closes #119)
authored
14 ## Features
4cb5142 @weppos Added feature list and expected roadmap
authored
15
ae63104 @weppos whois.nic.ki parser must support `Delegated' status (closes #119)
authored
16 * Ability to query registry data for [IPv4, IPv6, TLDs, and domain names](http://www.ruby-whois.org/manual/usage.html#usage-objects)
17 * Ability to [parse WHOIS responses](http://www.ruby-whois.org/manual/parser.html)
18 * Flexible and extensible interface (e.g. You can define [custom servers](http://www.ruby-whois.org/manual/server.html) on the fly)
d0b985b @weppos Update features section
authored
19 * Object oriented design, featuring 10 different design patterns
20 * Pure Ruby library, without any external dependency other than Ruby itself
ae63104 @weppos whois.nic.ki parser must support `Delegated' status (closes #119)
authored
21 * Compatible with [Ruby 1.8.7 and greater](http://www.ruby-whois.org/manual/installing.html#installation-requirements), including Ruby 1.9 branch
22 * Successfully tested against several [Ruby implementations](http://www.ruby-whois.org/manual/interpreters.html)
4cb5142 @weppos Added feature list and expected roadmap
authored
23
24
ae63104 @weppos whois.nic.ki parser must support `Delegated' status (closes #119)
authored
25 ## Requirements
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
26
afd063a @weppos Minimum Ruby version is now 1.8.7
authored
27 * Ruby >= 1.8.7
28
67196a8 @weppos Update README.md
authored
29 *Whois* >= 1.5 requires Ruby 1.8.7 or newer.
afd063a @weppos Minimum Ruby version is now 1.8.7
authored
30 For older versions of Ruby, see the CHANGELOG.rdoc file.
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
31
f8156ed @weppos More links. Delegate "Interpreters" details to the docs.
authored
32 In addition to the standard Ruby interpreter (MRI),
33 Whois has been successfully tested against several
ae63104 @weppos whois.nic.ki parser must support `Delegated' status (closes #119)
authored
34 [Ruby implementations](http://www.ruby-whois.org/manual/interpreters.html).
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
35
36
ae63104 @weppos whois.nic.ki parser must support `Delegated' status (closes #119)
authored
37 ## Installation
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
38
5446f48 @weppos Standardize README
authored
39 The best way to install *Whois* is via [RubyGems](https://rubygems.org/).
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
40
ae63104 @weppos whois.nic.ki parser must support `Delegated' status (closes #119)
authored
41 $ gem install whois
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
42
5446f48 @weppos Standardize README
authored
43 You might need administrator privileges on your system to install the gem.
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
44
45
ae63104 @weppos whois.nic.ki parser must support `Delegated' status (closes #119)
authored
46 ## Upgrade
e959f0b @weppos Add Upgrade information in the README.
authored
47
48 Install the newer version via RubyGems.
49
ae63104 @weppos whois.nic.ki parser must support `Delegated' status (closes #119)
authored
50 $ gem install whois
e959f0b @weppos Add Upgrade information in the README.
authored
51
826d25b @weppos Add donations section.
authored
52 Minor and bugfix releases normally won't break backwards-compatibility. You can read the CHANGELOG.md file to learn about the changes in each release.
e959f0b @weppos Add Upgrade information in the README.
authored
53
14b0c98 @weppos RDoc => MarkDown
authored
54 Read the [Upgrading](http://www.ruby-whois.org/manual/upgrading.html) documentation page for detailed information about incompatible changes and further instructions.
e959f0b @weppos Add Upgrade information in the README.
authored
55
56
14b0c98 @weppos RDoc => MarkDown
authored
57 ## Getting Started
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
58
14b0c98 @weppos RDoc => MarkDown
authored
59 Note. This section covers only the essentials for getting started with the Whois library. The [documentation](http://www.ruby-whois.org/documentation.html) provides a more accurate explanation including tutorials, more examples and technical details about the client/server/record/parser architecture.
cf1f55a @weppos Improved documentation. Added Timeout section.
authored
60
14b0c98 @weppos RDoc => MarkDown
authored
61 ### Querying the Server
6a4ee3a @weppos Updated the information in the README file
authored
62
334801e @weppos Added ability to query IANA for TLD WHOIS information. [aadlani]
authored
63 Whois provides the ability to get WHOIS information for TLD, domain names, IPv4 and IPv6 addresses. The client is smart enough to guess the best WHOIS server according to given query, send the request and return the response.
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
64
b369326 @soult Fix some errors in the README
soult authored
65 Check out the following examples:
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
66
14b0c98 @weppos RDoc => MarkDown
authored
67 # Domain WHOIS
68 w = Whois::Client.new
69 w.query("google.com")
70 # => #<Whois::Record>
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
71
14b0c98 @weppos RDoc => MarkDown
authored
72 # TLD WHOIS
73 w = Whois::Client.new
74 w.query(".com")
75 # => #<Whois::Record>
334801e @weppos Added ability to query IANA for TLD WHOIS information. [aadlani]
authored
76
14b0c98 @weppos RDoc => MarkDown
authored
77 # IPv4 WHOIS
78 w = Whois::Client.new
79 w.query("74.125.67.100")
80 # => #<Whois::Record>
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
81
14b0c98 @weppos RDoc => MarkDown
authored
82 # IPv6 WHOIS
83 w = Whois::Client.new
84 w.query("2001:db8::1428:57ab")
85 # => #<Whois::Record>
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
86
87 The query method is stateless. For this reason, you can safely re-use the same client instance for multiple queries.
88
14b0c98 @weppos RDoc => MarkDown
authored
89 w = Whois::Client.new
334801e @weppos Added ability to query IANA for TLD WHOIS information. [aadlani]
authored
90 w.query("google.com")
91 w.query(".com")
92 w.query("74.125.67.100")
93 w.query("2001:db8::1428:57ab")
94 w.query("google.it")
95
14b0c98 @weppos RDoc => MarkDown
authored
96 If you just need a WHOIS response and you don't care about a full control of the WHOIS client, the {Whois} module provides an all-in-one method called {Whois.whois}. This is the simplest way to send a WHOIS request.
97
98 Whois.whois("google.com")
99 # => #<Whois::Record>
100
101 Did I mention you can even use blocks?
102
103 Whois::Client.new do |w|
104 w.query("google.com")
105 w.query(".com")
106 w.query("74.125.67.100")
107 w.query("2001:db8::1428:57ab")
108 w.query("google.it")
109 end
334801e @weppos Added ability to query IANA for TLD WHOIS information. [aadlani]
authored
110
14b0c98 @weppos RDoc => MarkDown
authored
111 ### Consuming the Record
6a4ee3a @weppos Updated the information in the README file
authored
112
826d25b @weppos Add donations section.
authored
113 Any WHOIS query returns a `Whois::Record`. This object looks like a String, but it's way more powerful.
6a4ee3a @weppos Updated the information in the README file
authored
114
826d25b @weppos Add donations section.
authored
115 `Whois::Record` encapsulates a WHOIS record and provides the ability to parse the WHOIS response programmatically, by using an object oriented syntax.
6a4ee3a @weppos Updated the information in the README file
authored
116
14b0c98 @weppos RDoc => MarkDown
authored
117 r = Whois.whois("google.it")
118 # => #<Whois::Record>
6a4ee3a @weppos Updated the information in the README file
authored
119
14b0c98 @weppos RDoc => MarkDown
authored
120 r.available?
121 # => false
122 r.registered?
123 # => true
6a4ee3a @weppos Updated the information in the README file
authored
124
14b0c98 @weppos RDoc => MarkDown
authored
125 r.created_on
126 # => Fri Dec 10 00:00:00 +0100 1999
6a4ee3a @weppos Updated the information in the README file
authored
127
14b0c98 @weppos RDoc => MarkDown
authored
128 t = r.technical_contact
129 # => #<Whois::Record::Contact>
130 t.id
131 # => "TS7016-ITNIC"
132 t.name
133 # => "Technical Services"
6a4ee3a @weppos Updated the information in the README file
authored
134
14b0c98 @weppos RDoc => MarkDown
authored
135 r.nameservers.each do |nameserver|
136 puts nameserver
137 end
6a4ee3a @weppos Updated the information in the README file
authored
138
67196a8 @weppos Update README.md
authored
139 This feature is made possible by the *Whois* record 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.
6a4ee3a @weppos Updated the information in the README file
authored
140
141 If you create a new parser, please consider releasing it to the public so that it can be included in a next version.
142
14b0c98 @weppos RDoc => MarkDown
authored
143 ### Timeout
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
144
826d25b @weppos Add donations section.
authored
145 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 `Timeout::Error` exception.
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
146
14b0c98 @weppos RDoc => MarkDown
authored
147 Off course, you can customize the timeout value setting a different value. If timeout is `nil`, 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!
cf1f55a @weppos Improved documentation. Added Timeout section.
authored
148
14b0c98 @weppos RDoc => MarkDown
authored
149 w = Whois::Client.new(:timeout => 10)
150 w.timeout # => 10
151 w.timeout = 5
152 w.timeout # => 5
cf1f55a @weppos Improved documentation. Added Timeout section.
authored
153
14b0c98 @weppos RDoc => MarkDown
authored
154 w.query("google.com")
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
155
156
14b0c98 @weppos RDoc => MarkDown
authored
157 ## Acknowledgments
6949606 @weppos Starting with some basic documentation
authored
158
67196a8 @weppos Update README.md
authored
159 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 and all sub sequential versions of the new Whois up to 0.9.x are 100% compatible with Cyril's Whois.
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
160
14b0c98 @weppos RDoc => MarkDown
authored
161 Whois is largely inspired by other notable Whois projects, most of all the Debian Whois library written and maintained by Marco D'Itri. Other good ideas and design decisions come from the PERL `Net::DRI` package.
6949606 @weppos Starting with some basic documentation
authored
162
163 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.
164 They didn't directly influence this library or any design decision, but they have been a really interesting code-reading.
165
14b0c98 @weppos RDoc => MarkDown
authored
166 The parser architecture 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 open source project that offers such this feature in all the programming language ecosystem.
6949606 @weppos Starting with some basic documentation
authored
167
67196a8 @weppos Update README.md
authored
168 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.
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
169
170
826d25b @weppos Add donations section.
authored
171 ## Credits
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
172
826d25b @weppos Add donations section.
authored
173 - [Simone Carletti](http://www.simonecarletti.com/) <weppos@weppos.net> - Author
174 - [Contributors](https://github.com/weppos/whois/contributors)
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
175
176
67196a8 @weppos Update README.md
authored
177 ## Contribute
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
178
67196a8 @weppos Update README.md
authored
179 Direct questions and discussions to the [mailing list](http://groups.google.com/group/ruby-whois).
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
180
67196a8 @weppos Update README.md
authored
181 Pull requests are very welcome! Please include spec and/or feature coverage for every patch, and create a topic branch for every separate change you make.
182
183 Report issues or feature requests to [GitHub Issues](https://github.com/weppos/whois/issues).
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
184
185
826d25b @weppos Add donations section.
authored
186 ## Donations
187
188 [Support Whois at Pledgie](http://www.pledgie.com/campaigns/11383).
189
190 <a href='http://www.pledgie.com/campaigns/11383'><img alt='Click here to lend your support to: whois and make a donation at www.pledgie.com !' src='http://www.pledgie.com/campaigns/11383.png?skin_name=chrome' border='0' /></a>
191
192 Whois is free software, but it costs money to write, test, and distribute it. You can support the development by sending a donation. **Any amount, even $5, is greatly appreciated**.
193
194
14b0c98 @weppos RDoc => MarkDown
authored
195 ## More
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
196
826d25b @weppos Add donations section.
authored
197 - [Homepage](http://www.ruby-whois.org/)
198 - [Repository](https://github.com/weppos/whois)
2e3a4d0 @weppos Fix link to /api
authored
199 - [Documentation](http://www.ruby-whois.org/documentation.html) - The official documentation, see also the [API Documentation](http://www.ruby-whois.org/api).
826d25b @weppos Add donations section.
authored
200 - [Discussion Group](http://groups.google.com/group/ruby-whois)
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
201
202
14b0c98 @weppos RDoc => MarkDown
authored
203 ## Changelog
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
204
b8df043 @weppos Add link to CHANGELOG.md file
authored
205 See the [CHANGELOG](CHANGELOG.md) file for details.
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
206
207
14b0c98 @weppos RDoc => MarkDown
authored
208 ## License
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
209
8ca8811 @weppos Change YARD `@api internal` to `@api private` to trigger "private api" m...
authored
210 Copyright (c) 2009-2012 Simone Carletti. This is Free Software distributed under the MIT license.
Something went wrong with that request. Please try again.