Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 180 lines (115 sloc) 6.128 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
0fffa90 @weppos Update README.md
authored
3 <tt>Whois</tt> 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
0fffa90 @weppos Update README.md
authored
7 <tt>Whois</tt> 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
0fffa90 @weppos Update README.md
authored
9 This library was created to power [RoboWhois](https://www.robowhois.com/) and [RoboDomain](https://www.robodomain.com/). It has been performing queries in production since July 2009.
6949606 @weppos Starting with some basic documentation
authored
10
11
0fffa90 @weppos Update README.md
authored
12 ## Donate a coffee
6949606 @weppos Starting with some basic documentation
authored
13
0fffa90 @weppos Update README.md
authored
14 <p id="pledgie" class="alignright"><a href="https://pledgie.com/campaigns/11383"><img alt="Click here to lend your support to: whois and make a donation at pledgie.com !" src="https://pledgie.com/campaigns/11383.png?skin_name=chrome" border="0" style="max-width:100%;"></a></p>
235a703 @weppos Move donations section at the top.
authored
15
0fffa90 @weppos Update README.md
authored
16 <tt>Whois</tt> is free software, but it requires a lot of coffee to write, test, and distribute it. You can support the development by [donating a coffee](https://pledgie.com/campaigns/11383).
235a703 @weppos Move donations section at the top.
authored
17
18
ae63104 @weppos whois.nic.ki parser must support `Delegated' status (closes #119)
authored
19 ## Features
4cb5142 @weppos Added feature list and expected roadmap
authored
20
9c0711b @weppos Ruby 1.8 is no longer supported
authored
21 - Ability to query registry data for [IPv4, IPv6, TLDs, and domain names](http://www.ruby-whois.org/manual/usage/#usage-objects)
22 - Ability to [parse WHOIS responses](http://www.ruby-whois.org/manual/parser/)
23 - Flexible and extensible interface (e.g. You can define [custom servers](http://www.ruby-whois.org/manual/server/) on the fly)
24 - Object oriented design, featuring 10 different design patterns
25 - Pure Ruby library, without any external dependency other than Ruby itself
26 - Successfully tested against several [Ruby implementations](http://www.ruby-whois.org/manual/interpreters/)
4cb5142 @weppos Added feature list and expected roadmap
authored
27
28
ae63104 @weppos whois.nic.ki parser must support `Delegated' status (closes #119)
authored
29 ## Requirements
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
30
3c3d4e8 @weppos Drop support for Ruby 1.8
authored
31 * Ruby >= 1.9.2
afd063a @weppos Minimum Ruby version is now 1.8.7
authored
32
0fffa90 @weppos Update README.md
authored
33 For older versions of Ruby, see the [CHANGELOG](CHANGELOG.md).
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
34
35
a8459dc @weppos Donate a Coffee
authored
36 ## Installation
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
37
a8459dc @weppos Donate a Coffee
authored
38 The best way to install <tt>Whois</tt> is via [RubyGems](https://rubygems.org/) - [Learn more](http://www.ruby-whois.org/manual/installing/).
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
39
ae63104 @weppos whois.nic.ki parser must support `Delegated' status (closes #119)
authored
40 $ gem install whois
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
41
42
14b0c98 @weppos RDoc => MarkDown
authored
43 ## Getting Started
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
44
8399772 @weppos Update links to the ruby-whois site
authored
45 Note. This section covers only the essentials for getting started with the Whois library. The [documentation](http://www.ruby-whois.org/documentation/) 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
46
0fffa90 @weppos Update README.md
authored
47 ### Querying a WHOIS
6a4ee3a @weppos Updated the information in the README file
authored
48
0fffa90 @weppos Update README.md
authored
49 <tt>Whois</tt> 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
50
b369326 @soult Fix some errors in the README
soult authored
51 Check out the following examples:
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
52
7ac638d @weppos Ruby syntax
authored
53 ```ruby
54 # Domain WHOIS
55 w = Whois::Client.new
56 w.lookup("google.com")
57 # => #<Whois::Record>
58
59 # TLD WHOIS
60 w = Whois::Client.new
61 w.lookup(".com")
62 # => #<Whois::Record>
63
64 # IPv4 WHOIS
65 w = Whois::Client.new
66 w.lookup("74.125.67.100")
67 # => #<Whois::Record>
68
69 # IPv6 WHOIS
70 w = Whois::Client.new
71 w.lookup("2001:db8::1428:57ab")
72 # => #<Whois::Record>
73 ```
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
74
75 The query method is stateless. For this reason, you can safely re-use the same client instance for multiple queries.
76
568290f @weppos Ruby syntax
authored
77 ```ruby
7ac638d @weppos Ruby syntax
authored
78 w = Whois::Client.new
79 w.lookup("google.com")
80 w.lookup(".com")
81 w.lookup("74.125.67.100")
82 w.lookup("2001:db8::1428:57ab")
83 w.lookup("google.it")
84 ```
334801e @weppos Added ability to query IANA for TLD WHOIS information. [aadlani]
authored
85
568290f @weppos Ruby syntax
authored
86 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.
14b0c98 @weppos RDoc => MarkDown
authored
87
7ac638d @weppos Ruby syntax
authored
88 ```ruby
89 Whois.whois("google.com")
90 # => #<Whois::Record>
91 ```
14b0c98 @weppos RDoc => MarkDown
authored
92
93 Did I mention you can even use blocks?
94
7ac638d @weppos Ruby syntax
authored
95 ```ruby
96 Whois::Client.new do |w|
97 w.lookup("google.com")
98 w.lookup(".com")
99 w.lookup("74.125.67.100")
100 w.lookup("2001:db8::1428:57ab")
101 w.lookup("google.it")
102 end
103 ```
334801e @weppos Added ability to query IANA for TLD WHOIS information. [aadlani]
authored
104
14b0c98 @weppos RDoc => MarkDown
authored
105 ### Consuming the Record
6a4ee3a @weppos Updated the information in the README file
authored
106
826d25b @weppos Add donations section.
authored
107 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
108
826d25b @weppos Add donations section.
authored
109 `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
110
7ac638d @weppos Ruby syntax
authored
111 ```ruby
112 r = Whois.whois("google.it")
113 # => #<Whois::Record>
114
115 r.available?
116 # => false
117 r.registered?
118 # => true
119
120 r.created_on
121 # => Fri Dec 10 00:00:00 +0100 1999
122
123 t = r.technical_contact
124 # => #<Whois::Record::Contact>
125 t.id
126 # => "TS7016-ITNIC"
127 t.name
128 # => "Technical Services"
129
130 r.nameservers.each do |nameserver|
131 puts nameserver
132 end
133 ```
6a4ee3a @weppos Updated the information in the README file
authored
134
0fffa90 @weppos Update README.md
authored
135 This feature is made possible by the <tt>Whois</tt> 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
136
137 If you create a new parser, please consider releasing it to the public so that it can be included in a next version.
138
14b0c98 @weppos RDoc => MarkDown
authored
139 ### Timeout
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
140
826d25b @weppos Add donations section.
authored
141 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
142
14b0c98 @weppos RDoc => MarkDown
authored
143 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
144
7ac638d @weppos Ruby syntax
authored
145 ```ruby
146 w = Whois::Client.new(:timeout => 10)
147 w.timeout # => 10
148 w.timeout = 5
149 w.timeout # => 5
150
151 w.lookup("google.com")
152 ```
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
153
154
826d25b @weppos Add donations section.
authored
155 ## Credits
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
156
0fffa90 @weppos Update README.md
authored
157 <tt>Whois</tt> was created and is maintained by [Simone Carletti](http://www.simonecarletti.com/). Many improvements and bugfixes were contributed by the [open source community](https://github.com/weppos/whois/graphs/contributors).
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
158
159
0fffa90 @weppos Update README.md
authored
160 ## Contributing
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
161
0fffa90 @weppos Update README.md
authored
162 Direct questions and discussions to [Stack Overflow](http://stackoverflow.com/questions/tagged/whois-ruby).
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
163
0fffa90 @weppos Update README.md
authored
164 [Pull requests](https://github.com/weppos/whois/pulls) are very welcome! Please include spec and/or feature coverage for every patch, and create a topic branch for every separate change you make.
67196a8 @weppos Update README.md
authored
165
166 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
167
168
0fffa90 @weppos Update README.md
authored
169 ## More Information
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
170
826d25b @weppos Add donations section.
authored
171 - [Homepage](http://www.ruby-whois.org/)
0fffa90 @weppos Update README.md
authored
172 - [RubyGems](https://rubygems.org/gems/whois)
173 - [Issues](https://github.com/weppos/whois)
174 - [Stack Overflow](http://stackoverflow.com/questions/tagged/whois-ruby)
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
175
176
14b0c98 @weppos RDoc => MarkDown
authored
177 ## License
44d4a24 @weppos Initial documentation including information about the old Whois library.
authored
178
50dabf6 @weppos Welcome 2014
authored
179 Copyright (c) 2009-2014 Simone Carletti. This is Free Software distributed under the MIT license.
Something went wrong with that request. Please try again.