resolv.rb -- doc patch.
From:
Hugh Sasse <hgs@...>
Date:
2006-08-01 17:34:30 UTC
List:
ruby-core #8478
This is an attempt to get the RD format docs for resolv.rb into
the Rdoc format we use now. This will certainly need more work.
Again, it is a patch against the stable snapshot.
HTH
Hugh
--- ./lib/resolv.rb.orig 2006-05-07 03:56:06.000000000 +0100
+++ ./lib/resolv.rb 2006-08-01 18:09:05.115673000 +0100
@@ -1,4 +1,4 @@
-=begin
+=begin rdoc
= resolv library
resolv.rb is a resolver library written in Ruby.
Since it is written in Ruby, it is thread-aware.
@@ -15,173 +15,6 @@
p dns.getresources("ruby-lang.org", Resolv::DNS::Resource::IN::MX).collect {|r| [r.exchange.to_s, r.preference]}
}
-== Resolv class
-
-=== class methods
---- Resolv.getaddress(name)
---- Resolv.getaddresses(name)
---- Resolv.each_address(name) {|address| ...}
- They lookups IP addresses of ((|name|)) which represents a hostname
- as a string by default resolver.
-
- getaddress returns first entry of lookupped addresses.
- getaddresses returns lookupped addresses as an array.
- each_address iterates over lookupped addresses.
-
---- Resolv.getname(address)
---- Resolv.getnames(address)
---- Resolv.each_name(address) {|name| ...}
- lookups hostnames of ((|address|)) which represents IP address as a string.
-
- getname returns first entry of lookupped names.
- getnames returns lookupped names as an array.
- each_names iterates over lookupped names.
-
-== Resolv::Hosts class
-hostname resolver using /etc/hosts format.
-
-=== class methods
---- Resolv::Hosts.new(hosts='/etc/hosts')
-
-=== methods
---- Resolv::Hosts#getaddress(name)
---- Resolv::Hosts#getaddresses(name)
---- Resolv::Hosts#each_address(name) {|address| ...}
- address lookup methods.
-
---- Resolv::Hosts#getname(address)
---- Resolv::Hosts#getnames(address)
---- Resolv::Hosts#each_name(address) {|name| ...}
- hostnames lookup methods.
-
-== Resolv::DNS class
-DNS stub resolver.
-
-=== class methods
---- Resolv::DNS.new(config_info=nil)
-
- ((|config_info|)) should be nil, a string or a hash.
- If nil is given, /etc/resolv.conf and platform specific information is used.
- If a string is given, it should be a filename which format is same as /etc/resolv.conf.
- If a hash is given, it may contains information for nameserver, search and ndots as follows.
-
- Resolv::DNS.new({:nameserver=>["210.251.121.21"], :search=>["ruby-lang.org"], :ndots=>1})
-
---- Resolv::DNS.open(config_info=nil)
---- Resolv::DNS.open(config_info=nil) {|dns| ...}
-
-=== methods
---- Resolv::DNS#close
-
---- Resolv::DNS#getaddress(name)
---- Resolv::DNS#getaddresses(name)
---- Resolv::DNS#each_address(name) {|address| ...}
- address lookup methods.
-
- ((|name|)) must be a instance of Resolv::DNS::Name or String. Lookupped
- address is represented as an instance of Resolv::IPv4 or Resolv::IPv6.
-
---- Resolv::DNS#getname(address)
---- Resolv::DNS#getnames(address)
---- Resolv::DNS#each_name(address) {|name| ...}
- hostnames lookup methods.
-
- ((|address|)) must be a instance of Resolv::IPv4, Resolv::IPv6 or String.
- Lookupped name is represented as an instance of Resolv::DNS::Name.
-
---- Resolv::DNS#getresource(name, typeclass)
---- Resolv::DNS#getresources(name, typeclass)
---- Resolv::DNS#each_resource(name, typeclass) {|resource| ...}
- They lookup DNS resources of ((|name|)).
- ((|name|)) must be a instance of Resolv::Name or String.
-
- ((|typeclass|)) should be one of follows:
- * Resolv::DNS::Resource::IN::ANY
- * Resolv::DNS::Resource::IN::NS
- * Resolv::DNS::Resource::IN::CNAME
- * Resolv::DNS::Resource::IN::SOA
- * Resolv::DNS::Resource::IN::HINFO
- * Resolv::DNS::Resource::IN::MINFO
- * Resolv::DNS::Resource::IN::MX
- * Resolv::DNS::Resource::IN::TXT
- * Resolv::DNS::Resource::IN::ANY
- * Resolv::DNS::Resource::IN::A
- * Resolv::DNS::Resource::IN::WKS
- * Resolv::DNS::Resource::IN::PTR
- * Resolv::DNS::Resource::IN::AAAA
-
- Lookupped resource is represented as an instance of (a subclass of)
- Resolv::DNS::Resource.
- (Resolv::DNS::Resource::IN::A, etc.)
-
-== Resolv::DNS::Resource::IN::NS class
---- name
-== Resolv::DNS::Resource::IN::CNAME class
---- name
-== Resolv::DNS::Resource::IN::SOA class
---- mname
---- rname
---- serial
---- refresh
---- retry
---- expire
---- minimum
-== Resolv::DNS::Resource::IN::HINFO class
---- cpu
---- os
-== Resolv::DNS::Resource::IN::MINFO class
---- rmailbx
---- emailbx
-== Resolv::DNS::Resource::IN::MX class
---- preference
---- exchange
-== Resolv::DNS::Resource::IN::TXT class
---- data
-== Resolv::DNS::Resource::IN::A class
---- address
-== Resolv::DNS::Resource::IN::WKS class
---- address
---- protocol
---- bitmap
-== Resolv::DNS::Resource::IN::PTR class
---- name
-== Resolv::DNS::Resource::IN::AAAA class
---- address
-
-== Resolv::DNS::Name class
-
-=== class methods
---- Resolv::DNS::Name.create(name)
-
-=== methods
---- Resolv::DNS::Name#to_s
-
-== Resolv::DNS::Resource class
-
-== Resolv::IPv4 class
-=== class methods
---- Resolv::IPv4.create(address)
-
-=== methods
---- Resolv::IPv4#to_s
---- Resolv::IPv4#to_name
-
-=== constants
---- Resolv::IPv4::Regex
- regular expression for IPv4 address.
-
-== Resolv::IPv6 class
-=== class methods
---- Resolv::IPv6.create(address)
-
-=== methods
---- Resolv::IPv6#to_s
---- Resolv::IPv6#to_name
-
-=== constants
---- Resolv::IPv6::Regex
- regular expression for IPv6 address.
-
== Bugs
* NIS is not supported.
* /etc/nsswitch.conf is not supported.
@@ -195,26 +28,40 @@
require 'thread'
class Resolv
+ # lookup IP address of #name (which is a string
+ # representing a hostname) using default resolver.
+ # getaddress returns the first address looked up
def self.getaddress(name)
DefaultResolver.getaddress(name)
end
- def self.getaddresses(name)
+ # lookup IP address of +name+ (which is a string
+ # representing a hostname) using default resolver.
+ # getaddresses returns looked up addresses as an array.
+ def selr.getaddresses(name)
DefaultResolver.getaddresses(name)
end
+ # lookup IP address of +name+ (which is a string
+ # representing a hostname) using default resolver.
+ # each_address iterates over looked up addresses.
def self.each_address(name, &block)
DefaultResolver.each_address(name, &block)
end
+ # lookup first hostname of +address+ which represents IP address as a string.
def self.getname(address)
DefaultResolver.getname(address)
end
+ # lookup hostnames of +address+ which represents IP address as a string.
+ # Return an array.
def self.getnames(address)
DefaultResolver.getnames(address)
end
+ # lookup hostnames of #address which represents IP address as a string.
+ # Iterate over the results.
def self.each_name(address, &proc)
DefaultResolver.each_name(address, &proc)
end
@@ -277,6 +124,7 @@
class ResolvTimeout < TimeoutError
end
+ # hostname resolver using /etc/hosts format.
class Hosts
if /mswin32|cygwin|mingw|bccwin/ =~ RUBY_PLATFORM
require 'win32/resolv'
@@ -285,6 +133,10 @@
DefaultFileName = '/etc/hosts'
end
+
+ # +filenam+ is the hosts file, defaulting to
+ # /etc/hosts on Unix and Win32::Resolv.get_hosts_path
+ # on windows.
def initialize(filename = DefaultFileName)
@filename = filename
@mutex = Mutex.new
@@ -322,17 +174,21 @@
self
end
+ # lookup +name+ and return first IP address.
def getaddress(name)
each_address(name) {|address| return address}
raise ResolvError.new("#{@filename} has no name: #{name}")
end
+ # lookup IP addresses for +name+.
+ # return an array of addresses.
def getaddresses(name)
ret = []
each_address(name) {|address| ret << address}
return ret
end
+ # Iterate over addresses found for +name+.
def each_address(name, &proc)
lazy_initialize
if @name2addr.include?(name)
@@ -340,17 +196,21 @@
end
end
+ # lookup +address+ and return first host name.
def getname(address)
each_name(address) {|name| return name}
raise ResolvError.new("#{@filename} has no address: #{address}")
end
+ # lookup +address+ and return first host name.
+ # return an array of names.
def getnames(address)
ret = []
each_name(address) {|name| ret << name}
return ret
end
+ # Iterate over names found for +address+.
def each_name(address, &proc)
lazy_initialize
if @addr2name.include?(address)
@@ -359,6 +219,7 @@
end
end
+ # DNS stub resolver.
class DNS
# STD0013 (RFC 1035, etc.)
# ftp://ftp.isi.edu/in-notes/iana/assignments/dns-parameters
@@ -368,6 +229,9 @@
DNSThreadGroup = ThreadGroup.new
+ # Create a new Resolv::DNS object, and if a block is given
+ # yield to the block before calling #close. Takes the same
+ # arguments as new.
def self.open(*args)
dns = new(*args)
return dns unless block_given?
@@ -378,6 +242,13 @@
end
end
+ # +config_info+ should be +nil+, a string or a hash.
+ # If +nil+ is given, /etc/resolv.conf and platform specific
+ # information is used. If a string is given, it should be a
+ # filename which format is same as /etc/resolv.conf. If a hash
+ # is given, it may contains information for nameserver, search
+ # and ndots as follows.
+ # Resolv::DNS.new({:nameserver=>["210.251.121.21"], :search=>["ruby-lang.org"], :ndots=>1})
def initialize(config_info=nil)
@mutex = Mutex.new
@config = Config.new(config_info)
@@ -411,32 +282,52 @@
}
end
+ # lookup +name+ and return first IP address.
+ # +name+ must be a instance of Resolv::DNS::Name or String. Looked up
+ # address is represented as an instance of Resolv::IPv4 or Resolv::IPv6.
def getaddress(name)
each_address(name) {|address| return address}
raise ResolvError.new("DNS result has no information for #{name}")
end
+ # lookup IP addresses for +name+.
+ # return an array of addresses.
+ # +name+ must be a instance of Resolv::DNS::Name or String. Looked up
+ # address is represented as an instance of Resolv::IPv4 or Resolv::IPv6.
def getaddresses(name)
ret = []
each_address(name) {|address| ret << address}
return ret
end
+ # Iterate over addresses found for +name+.
+ # +name+ must be a instance of Resolv::DNS::Name or String. Looked up
+ # address is represented as an instance of Resolv::IPv4 or Resolv::IPv6.
def each_address(name)
each_resource(name, Resource::IN::A) {|resource| yield resource.address}
end
+ # lookup +address+ and return first host name.
+ # +address+ must be a instance of Resolv::IPv4, Resolv::IPv6 or String.
+ # Looked up name is represented as an instance of Resolv::DNS::Name.
def getname(address)
each_name(address) {|name| return name}
raise ResolvError.new("DNS result has no information for #{address}")
end
+ # lookup +address+ and return first host name.
+ # return an array of names.
+ # +address+ must be a instance of Resolv::IPv4, Resolv::IPv6 or String.
+ # Looked up name is represented as an instance of Resolv::DNS::Name.
def getnames(address)
ret = []
each_name(address) {|name| ret << name}
return ret
end
+ # Iterate over names found for +address+.
+ # +address+ must be a instance of Resolv::IPv4, Resolv::IPv6 or String.
+ # Looked up name is represented as an instance of Resolv::DNS::Name.
def each_name(address)
case address
when Name
@@ -451,17 +342,80 @@
each_resource(ptr, Resource::IN::PTR) {|resource| yield resource.name}
end
+ # Lookup DNS resource of +name+.
+ # +name+ must be a instance of Resolv::Name or String.
+ #
+ # +typeclass+ should be one of follows:
+ # * Resolv::DNS::Resource::IN::ANY
+ # * Resolv::DNS::Resource::IN::NS
+ # * Resolv::DNS::Resource::IN::CNAME
+ # * Resolv::DNS::Resource::IN::SOA
+ # * Resolv::DNS::Resource::IN::HINFO
+ # * Resolv::DNS::Resource::IN::MINFO
+ # * Resolv::DNS::Resource::IN::MX
+ # * Resolv::DNS::Resource::IN::TXT
+ # * Resolv::DNS::Resource::IN::ANY
+ # * Resolv::DNS::Resource::IN::A
+ # * Resolv::DNS::Resource::IN::WKS
+ # * Resolv::DNS::Resource::IN::PTR
+ # * Resolv::DNS::Resource::IN::AAAA
+ #
+ # Lookupped resource is represented as an instance of (a subclass of)
+ # Resolv::DNS::Resource.
+ # (Resolv::DNS::Resource::IN::A, etc.)
def getresource(name, typeclass)
each_resource(name, typeclass) {|resource| return resource}
raise ResolvError.new("DNS result has no information for #{name}")
end
+ # Lookup DNS resources of +name+.
+ # +name+ must be a instance of Resolv::Name or String.
+ #
+ # +typeclass+ should be one of follows:
+ # * Resolv::DNS::Resource::IN::ANY
+ # * Resolv::DNS::Resource::IN::NS
+ # * Resolv::DNS::Resource::IN::CNAME
+ # * Resolv::DNS::Resource::IN::SOA
+ # * Resolv::DNS::Resource::IN::HINFO
+ # * Resolv::DNS::Resource::IN::MINFO
+ # * Resolv::DNS::Resource::IN::MX
+ # * Resolv::DNS::Resource::IN::TXT
+ # * Resolv::DNS::Resource::IN::ANY
+ # * Resolv::DNS::Resource::IN::A
+ # * Resolv::DNS::Resource::IN::WKS
+ # * Resolv::DNS::Resource::IN::PTR
+ # * Resolv::DNS::Resource::IN::AAAA
+ #
+ # Lookupped resource is represented as an instance of (a subclass of)
+ # Resolv::DNS::Resource.
+ # (Resolv::DNS::Resource::IN::A, etc.)
def getresources(name, typeclass)
ret = []
each_resource(name, typeclass) {|resource| ret << resource}
return ret
end
+ # Iterate over looked-up DNS resource(s) of +name+.
+ # +name+ must be a instance of Resolv::Name or String.
+ #
+ # +typeclass+ should be one of follows:
+ # * Resolv::DNS::Resource::IN::ANY
+ # * Resolv::DNS::Resource::IN::NS
+ # * Resolv::DNS::Resource::IN::CNAME
+ # * Resolv::DNS::Resource::IN::SOA
+ # * Resolv::DNS::Resource::IN::HINFO
+ # * Resolv::DNS::Resource::IN::MINFO
+ # * Resolv::DNS::Resource::IN::MX
+ # * Resolv::DNS::Resource::IN::TXT
+ # * Resolv::DNS::Resource::IN::ANY
+ # * Resolv::DNS::Resource::IN::A
+ # * Resolv::DNS::Resource::IN::WKS
+ # * Resolv::DNS::Resource::IN::PTR
+ # * Resolv::DNS::Resource::IN::AAAA
+ #
+ # Lookupped resource is represented as an instance of (a subclass of)
+ # Resolv::DNS::Resource.
+ # (Resolv::DNS::Resource::IN::A, etc.)
def each_resource(name, typeclass, &proc)
lazy_initialize
q = Queue.new
@@ -1712,6 +1666,7 @@
end
class IPv4
+ # regular expression for IPv4 address.
Regex = /\A(\d+)\.(\d+)\.(\d+)\.(\d+)\z/
def self.create(arg)
@@ -1788,6 +1743,7 @@
(\d+)\.(\d+)\.(\d+)\.(\d+)
\z/x
+ # regular expression for IPv6 address.
Regex = /
(?:#{Regex_8Hex}) |
(?:#{Regex_CompressedHex}) |