README.rdoc in ipaddress-0.6.0 vs README.rdoc in ipaddress-0.7.0

- old
+ new

@@ -41,13 +41,17 @@ * store both the address and the prefix information * quickly find the broadcast address of a network * iterate over hosts * perform subnetting or network aggregation -Moreover, many methods and procedures are so old that they have been -declared deprecated by the IETF. +Many methods and procedures are so old that they have been +declared deprecated by the IETF, and some others have bugs in their +implementation. +Moreover, IPAddress is more robust and is already around 50% faster than IPAddr, +in addition to provide an organic API with logical separation and OO structure. + We hope that IPAddress will address all these issues and meet all your needs in network programming. == Installation @@ -75,24 +79,19 @@ documentation with Rake: ipaddress$ rake rdoc The latest documentation can be found online at -{this address}[http://marcoceresa.com/ipaddress] +{this address}[http://rubydoc.info/github/bluemonk/ipaddress/master/frames] + +== IPv4 -== Usage - -In this section I will illustrate how to use the IPAddress library -through some examples of common tasks. - -=== IPv4 - Class IPAddress::IPv4 is used to handle IPv4 type addresses. IPAddress is similar to other IP Addresses libraries, like Ruby's own IPAddr. However it works slightly different, as we will see. -==== Create a new IPv4 address +=== Create a new IPv4 address The usual way to express an IP Address is using its dotted decimal form, such as 172.16.10.1, and a prefix, such as 24, separated by a slash. @@ -100,57 +99,45 @@ To create a new IPv4 object, you can use IPv4 own class ip = IPAddress::IPv4.new "172.16.10.1/24" -or, in a easier way, using the IPAddress wrapper method +or, in a easier way, using the IPAddress parse method + ip = IPAddress.parse "172.16.10.1/24" + +which accepts and parses any kind of IP (IPv4, IPV6 and +IPv4 IPv6 Mapped addresses). + +If you like sintactic sugar, you can use the wrapper method +IPAddress(), which is built around IPAddress::parse: + ip = IPAddress "172.16.10.1/24" You can specify an IPv4 address in any of two ways: IPAddress "172.16.10.1/24" IPAddress "172.16.10.1/255.255.255.0" In this example, prefix /24 and netmask 255.255.255.0 are the same and you have the flexibility to use either one of them. -==== Classful networks +If you don't explicitly specify the prefix (or the subnet mask), +IPAddress thinks you're dealing with host addresses and not with +networks. Therefore, the default prefix will be /32, or +255.255.255.255. For example: -If you don't specify a prefix (or a subnet mask), then the library -will create an object base on the CLASSFUL network from the given -IP. Remember the CLASSFUL network are the following (RFC 791) + # let's declare an host address + host = IPAddress::IPv4.new "10.1.1.1." + +The new created object will have prefix /32, which is the same +as we created the following: -* Class A, from 0.0.0.0 to 127.255.255.255 -* Class B, from 128.0.0.0 to 191.255.255.255 -* Class C, from 192.0.0.0 to 255.255.255.255 - -Since classful networks here are only considered to calculate the default -prefix number, classes D and E are not considered. - -You can easily check which CLASSFUL network the IP belongs: - - ip = IPAddress("10.0.0.1/24") - ip.a? - #=> true + host = IPAddress::IPv4.new "10.1.1.1/32" - ip = IPAddress("172.16.10.1/24") - ip.b? - #=> true - - ip = IPAddress("192.168.1.1/30") - ip.c? - #=> true +=== Handling the IPv4 address -These methods are only checking the address portion of an IP, and are -indipendent from its prefix. - -For more information on CLASSFUL networks visit the -{Wikipedia page}[http://en.wikipedia.org/wiki/Classful_network] - -==== Handling the IPv4 address - Once created, you can obtain the attributes for an IPv4 object: ip = IPAddress("172.16.10.1/24") ip.address @@ -180,11 +167,11 @@ use IPv4#to_string ip.to_string #=> "172.16.10.l/24" -==== Changing netmask +=== Changing netmask You can set a new prefix (netmask) after creating an IPv4 object. For example: ip.prefix = 25 @@ -198,11 +185,11 @@ ip.netmask = "255.255.255.252" ip.to_string #=> "172.16.10.1/30" -==== Working with networks, broadcasts and addresses +=== Working with networks, broadcasts and addresses Some very important topics in dealing with IP addresses are the concepts of +network+ and +broadcast+, as well as the addresses included in a range. @@ -219,11 +206,11 @@ This is very important because, for instance, IP "172.16.10.1/16" is very different to the previous one, belonging to the very different network "172.16.0.0/16". -===== Networks +==== Networks With IPAddress it's very easy to calculate the network for an IP address: ip = IPAddress "172.16.10.1/24" @@ -249,11 +236,11 @@ ip1.network? #=> false ip2.network? #=> true -===== Broadcast +==== Broadcast The broadcast address is the contrary than the network number: where the network number has all zeroes in the host portion, the broadcast address has all one's. For example, ip "172.16.10.1/24" has broadcast "172.16.10.255/24", where ip "172.16.10.1/16" has broadcast @@ -270,11 +257,11 @@ @prefix=24, @address="172.16.10.255"> bcast.to_string #=> "172.16.10.255/24" -===== Addresses, ranges and iterators +==== Addresses, ranges and iterators So we see that the netmask essentially specifies a range for IP addresses that are included in a network: all the addresses between the network number and the broadcast. IPAddress has many methods to iterate between those addresses. Let's start with IPv4#each, which @@ -308,11 +295,11 @@ #=> "172.16.10.1/24" ip.last.to_string #=> "172.16.10.254/24" -==== IP special formats +=== IP special formats The IPAddress library provides a complete set of methods to access an IPv4 address in special formats, such as binary, 32 bits unsigned int, data and hexadecimal. @@ -350,9 +337,56 @@ suitable to use in IPv4-IPv6 mapped addresses: ip.to_ipv6 #=> "ac10:0a01" +=== Classful networks + +IPAddress allows you to create and manipulate objects using the old +and deprecated (but apparently still popular) classful networks concept. + +Classful networks and addresses don't have a prefix: their subnet mask +is univocally identified by their address, and therefore diveded in classes. +As per RFC 791, these classes are: + +* Class A, from 0.0.0.0 to 127.255.255.255 +* Class B, from 128.0.0.0 to 191.255.255.255 +* Class C, from 192.0.0.0 to 255.255.255.255 + +Since classful networks here are only considered to calculate the default +prefix number, classes D and E are not considered. + +To create a classful IP and prefix from an IP address, use the +IPv4::parse_classful method: + + # classful ip + ip = IPAddress::IPv4::parse_classful "10.1.1.1" + + ip.prefix + #=> 8 + +The method automatically created a new IPv4 object and assigned it +the correct prefix. + +You can easily check which CLASSFUL network an IPv4 object belongs: + + ip = IPAddress("10.0.0.1/24") + ip.a? + #=> true + + ip = IPAddress("172.16.10.1/24") + ip.b? + #=> true + + ip = IPAddress("192.168.1.1/30") + ip.c? + #=> true + +Remember that these methods are only checking the address portion of an IP, and are +indipendent from its prefix, as classful networks have no concept of prefix. + +For more information on CLASSFUL networks visit the +{Wikipedia page}[http://en.wikipedia.org/wiki/Classful_network] === Network design with IPAddress IPAddress includes a lot of useful methods to manipulate IPv4 and IPv6 networks and do some basic network design. \ No newline at end of file