better_ipaddr 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 871dfdaf9d8e064ae09988a53d3e991544d414a9
-  data.tar.gz: 3d3229104847532b1713497982473e6f08520ee1
+SHA256:
+  metadata.gz: 5cd953909cfae8bb5422a297acdd4592ec96957c262072587add707a78ca9dd3
+  data.tar.gz: 32ff0ee9fb1aa6fc91a1fd2db3802add0d9b10af29c97ecbb066b3805ca5dcf3
 SHA512:
-  metadata.gz: d24bedd14d52e7f729af783387d2fe956b9ad4da55bbbfc624ec041046da05854dfcb573b855d131bc727aaa5f74cf879ff3dee01b592b635403c7ce60c5c4a3
-  data.tar.gz: 90bcb07ddb3ee7899fa8d8c53d193806004c016e4bf9cc21a1ed3160155edc944f420be46284e4a441cfbc361477a3fe9c447fa751b1ecd24dbcc5aab293b7f9
+  metadata.gz: 4ac0277a9876f20973dd0418547093ec41342ecbd1186c2da235c2463a0cd70f9cf39c623242ebad8cb2aa2156528a1d9735317c82a04310385ae93624beec75
+  data.tar.gz: 2d8f9e58dc03ea59d6af81995345e37395fd259bb1a615ef6ad9cd0d6e19a5b9cfb5f1ef3cc2891574861e99ae9280ee72288ed5d29308483b4d909041f7dba1

data/.rubocop.yml

@@ -0,0 +1,60 @@
+AllCops:
+  Exclude:
+    - 'spec/extra/**/*'
+
+Layout/EmptyLinesAroundArguments:
+  Enabled: false
+
+Lint/UnusedMethodArgument:
+  AllowUnusedKeywordArguments: true
+
+Metrics/AbcSize:
+  Max: 20
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/ClassLength:
+  Exclude:
+    - 'lib/better_ipaddr/classes.rb'
+    - 'lib/better_ipaddr/space.rb'
+
+Metrics/MethodLength:
+  Max: 15
+
+Metrics/ModuleLength:
+  Exclude:
+    - 'lib/better_ipaddr/methods.rb'
+
+Naming/BinaryOperatorParameterName:
+  Enabled: false
+
+Naming/MethodName:
+  Exclude:
+    - 'lib/better_ipaddr/kernel_method.rb'
+
+Style/Alias:
+  EnforcedStyle: prefer_alias_method
+
+Style/CommentedKeyword:
+  Enabled: false
+
+Style/Documentation:
+  Exclude:
+    - 'lib/better_ipaddr/core_extension.rb'
+    - 'lib/better_ipaddr/kernel_method.rb'
+    - 'spec/**/*'
+
+Style/MutableConstant:
+  Exclude:
+    - 'lib/better_ipaddr/constants.rb'
+
+Style/NumericPredicate:
+  EnforcedStyle: comparison
+
+Style/StringLiterals:
+  Enabled: false
+
+Style/YodaCondition:
+  Enabled: false

data/.travis.yml

@@ -1,9 +1,12 @@
 language: ruby
 rvm:
   - 2.0.0
-  - 2.1.8
-  - 2.2.4
-  - 2.3.0
+  - 2.1.10
+  - 2.2.10
+  - 2.3.7
+  - 2.4.4
+  - 2.5.1
+  - jruby-9.1.16.0
 matrix:
   include:
     - rvm: jruby

data/README.md

@@ -10,6 +10,8 @@ require "better_ipaddr"
 addr = IPAddr::V4[some_source] # shortcut for .new, because your test suite
                                #   contains a zillion IP addresses and you're
                                #   tired of typing Socket::AF_INET
+addr.inspect                   #
+#=> "IPAddr::V4['1.2.3.0/24']" # inspect emits readable, copy-pastable ruby code
 addr.host?                     # is it a host address?
 addr.network?                  # or a network address?
 addr.cidr                      # what is the CIDR representation?
@@ -77,6 +79,16 @@ class_c = addr << 8 # => IPAddr::V4["1.0.0.0/24"]
 IPAddr.new("1.0.0.0/24").summarize_with(IPAddr["1.0.1.0/24"]) # => IPAddr::V4["1.0.0.0/23"]
 ```
 
+This approach introduces at least one incompatibility: addresses that differ
+only in their netmask are considered equal in ipaddr, but not in better_ipaddr:
+
+```ruby
+require 'ipaddr'
+IPAddr.new('1.0.0.0/32') == IPAddr.new('1.0.0.0/8') # => true
+require 'better_ipaddr/core_extension'
+IPAddr.new('1.0.0.0/32') == IPAddr.new('1.0.0.0/8') # => false
+```
+
 The recommended way is to `require "better_ipaddr"` and use
 the `IPAddr` subclasses explicitly.
 

data/Rakefile

@@ -7,4 +7,9 @@ Rake::TestTask.new(:spec) do |t|
   t.test_files = FileList["spec/**/*_spec.rb"]
 end
 
-task default: :spec
+Rake::TestTask.new(:spec_ipaddr) do |t|
+  t.libs << "lib"
+  t.test_files = FileList["spec/extra/**/test_ipaddr.rb"]
+end
+
+task default: %i[spec spec_ipaddr]

data/better_ipaddr.gemspec

@@ -1,5 +1,4 @@
-# coding: utf-8
-lib = File.expand_path('../lib', __FILE__)
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'better_ipaddr/version'
 
@@ -13,13 +12,18 @@ Gem::Specification.new do |spec|
   spec.homepage      = "https://github.com/bjmllr/better_ipaddr"
   spec.license       = "GPL-3.0"
 
-  spec.files         = `git ls-files -z`.split("\x0")
+  spec.files         = `git ls-files -z`
+                       .split("\x0")
                        .reject { |f| f.match(%r{^(test|spec|features)/}) }
+
   spec.bindir        = "exe"
-  spec.executables   = spec.files.grep(%r(^exe/)) { |f| File.basename(f) }
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
   spec.add_development_dependency "bundler", "~> 1.0"
-  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "ipaddr", ">= 1.2.0"
   spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rubocop", "~> 0.54" if RUBY_VERSION > '2.1'
+  spec.add_development_dependency "test-unit"
 end

data/lib/better_ipaddr/classes.rb

@@ -3,6 +3,7 @@ require "better_ipaddr/methods"
 require "better_ipaddr/host_methods"
 
 class IPAddr
+  # An intermediate superclass for all BetterIpaddr classes
   class Base < IPAddr
     include BetterIpaddr::Constants
     include BetterIpaddr::InstanceMethods
@@ -17,8 +18,9 @@ class IPAddr
     # @param address [Integer, IPAddr, String]
     # @param mask [Integer, IPAddr, String, Nil]
     # @param family [Integer]
+    # @param classful [Boolean] see Base.from_string
     # @return [IPAddr, Nil]
-    def self.[](address, mask = nil, family: self::FAMILY)
+    def self.[](address, mask = nil, family: self::FAMILY, classful: false)
       prefix_length = mask && object_to_prefix_length(mask, family)
 
       case address
@@ -27,7 +29,7 @@ class IPAddr
       when IPAddr
         from_ipaddr(address, prefix_length, family: family)
       when String
-        from_string(address, prefix_length, family: family)
+        from_string(address, prefix_length, family: family, classful: classful)
       end
     end
 
@@ -42,16 +44,24 @@ class IPAddr
     # content.
     #
     # @param address [Integer, IPAddr, String]
+    # @param exception [Boolean] If true, then when the given object can't be
+    #   converted to an IPAddr, a TypeError will be raise rather than returning
+    #   nil.
+    # @param classful [Boolean] see Base.from_string
     # @return [IPAddr, Nil]
-    def self.from(address)
+    def self.from(address, exception: false, classful: false)
       case address
       when IPAddr
         specialize address
       when Regex::IPV4, 0..V4::MAX_INT
-        V4[address]
+        V4[address, classful: classful]
       when Regex::IPV6, 0..V6::MAX_INT
         V6[address]
-      end
+      end || (
+        if exception
+          raise TypeError, "can't convert #{address.inspect} to #{self}"
+        end
+      )
     end
 
     # Create an IPAddr host subclass from the given object, guessing the type of
@@ -59,12 +69,16 @@ class IPAddr
     #
     # Uses .from internally, so the same concerns apply, though the returned
     # object is guaranteed to be of a Host class or nil.
+    #
+    # @param address [Integer, IPAddr, String]
+    # @param exception [Boolean] See IPAddr::Base.from
+    # @return [IPAddr::Host, Nil]
 
-    def self.host_from(address)
-      ip = from(address)
-      if ip.ipv4?
+    def self.host_from(address, exception: false)
+      ip = from(address, exception: exception)
+      if ip && ip.ipv4?
         V4::Host[ip]
-      elsif ip.ipv6?
+      elsif ip && ip.ipv6?
         V6::Host[ip]
       end
     end
@@ -95,12 +109,26 @@ class IPAddr
     # @param address [String]
     # @param mask [Integer, String] a netmask or prefix length
     # @param family [Integer, Nil]
+    # @param classful [Boolean] controls the conversion of IPv4 addresses
+    #   without a prefix length in CIDR notation. When false, these are assumed
+    #   to be host networks (/32). When true, these are assumed to be classful
+    #   (rfc791) networks, with an implicit prefix length. Has no effect on IPv6
+    #   addresses.
     # @return [IPAddr]
-    def self.from_string(address, mask = nil, family: self::FAMILY)
+    def self.from_string(
+      address,
+      mask = nil,
+      family: self::FAMILY,
+      classful: false
+    )
       if mask
         new(address, family).mask(mask)
-      else
+      elsif !classful || address.include?('/')
         new(address, family)
+      else
+        ipaddr = new(address, family)
+        return ipaddr unless ipaddr.ipv4?
+        ipaddr.classful || ipaddr
       end
     end
 
@@ -230,26 +258,65 @@ class IPAddr
     end
   end
 
+  # An IPv4 address, 32 bits
   class V4 < Base
     specialize_constants Family::IPV4
 
     REGEX = Regex::IPV4
 
+    NETWORK_CLASSES = {
+      new('0.0.0.0/1')   =>  8, # A
+      new('128.0.0.0/2') => 16, # B
+      new('192.0.0.0/3') => 24  # C
+    }.freeze
+
+    # If the address falls in one of the address classes defined in rfc791,
+    # return a new IPAddr with the appropriate prefix length, otherwise return
+    # nil.
+    #
+    # * Class A: networks of 16,777,216 addresses each,
+    #   from 0.0.0.0/8 to 127.0.0.0/8
+    # * Class B: networks of 65,537 addresses each,
+    #   from 128.0.0.0/16 to 191.255.0.0/16
+    # * Class C: networks of 256 addresses each,
+    #   from 192.0.0.0/24 to 223.255.255.0/24
+    #
+    # @return [IPAddr::V4, nil]
+    def classful
+      prefix_length = classful_prefix_length || return
+      mask(prefix_length)
+    end
+
+    # If the address falls in one of the address classes defined in rfc791,
+    # return the corresponding prefix length, otherwise return nil.
+    #
+    # @return [Integer, nil]
+    def classful_prefix_length
+      key = NETWORK_CLASSES.keys.find do |block|
+        block.to_range(&:to_i).cover?(to_i)
+      end
+      NETWORK_CLASSES[key]
+    end
+
+    # An IPv4 host address, 32 bits
     class Host < V4
       include BetterIpaddr::HostMethods
     end
   end
 
+  # An IPv6 address, 128 bits
   class V6 < Base
     specialize_constants Family::IPV6
 
     REGEX = Regex::IPV6
 
+    # An IPv6 host address, 128 bits
     class Host < V6
       include BetterIpaddr::HostMethods
     end
   end
 
+  # A MAC address, 48 bits
   class MAC < Base
     specialize_constants Family::EUI48
   end

data/lib/better_ipaddr/constants.rb

@@ -1,6 +1,7 @@
 require "socket"
 
 module BetterIpaddr
+  # Namespace for constants used by BetterIpaddr
   module Constants
     # Integer codes representing supported address clases.
     # Reuse values from Socket namespace where possible.
@@ -28,7 +29,7 @@ module BetterIpaddr
         /[0-9]/
       )
 
-      IPV4 = /\A#{OCTET}#{TRAILING_OCTET}{3}(?:\/#{IPV4_PL})?\z/
+      IPV4 = %r{\A#{OCTET}#{TRAILING_OCTET}{3}(?:\/#{IPV4_PL})?\z}
 
       # IPv6 regex adapted from http://stackoverflow.com/a/17871737
       QUAD = /[0-9a-zA-Z]{1,4}/
@@ -64,7 +65,7 @@ module BetterIpaddr
         /#{LEADING_QUAD}{1,4}:#{IPV4}/
       )
 
-      IPV6 = /\A#{IPV6_ADDRESS}(?:\/#{IPV6_PL})?\z/
+      IPV6 = %r{\A#{IPV6_ADDRESS}(?:\/#{IPV6_PL})?\z}
     end
 
     # Map well known address family names to constants.
@@ -74,7 +75,7 @@ module BetterIpaddr
       eui48: Family::EUI48,
       eui64: Family::EUI64,
       mac: Family::EUI48
-    }
+    }.freeze
 
     # Map each address family to the size of its address space, in bits.
     FAMILY_TO_BIT_LENGTH = {
@@ -82,7 +83,7 @@ module BetterIpaddr
       Family::IPV6 => 128,
       Family::EUI48 => 48,
       Family::EUI64 => 64
-    }
+    }.freeze
 
     # Map all possible prefix lengths to the corresponding netmasks.
     PREFIX_LENGTH_TO_NETMASK = {}
@@ -93,6 +94,7 @@ module BetterIpaddr
       end
       PREFIX_LENGTH_TO_NETMASK[family] = netmasks
     end
+    PREFIX_LENGTH_TO_NETMASK.freeze
 
     # Map all possible netmasks to the corresponding prefix lengths.
     NETMASK_TO_PREFIX_LENGTH = {}
@@ -100,5 +102,6 @@ module BetterIpaddr
       NETMASK_TO_PREFIX_LENGTH[family] =
         Hash[hash.map.with_index { |e, i| [e, i] }]
     end
+    NETMASK_TO_PREFIX_LENGTH.freeze
   end
 end

data/lib/better_ipaddr/core_extension.rb

@@ -4,7 +4,6 @@ require "better_ipaddr/classes"
 
 class IPAddr
   include BetterIpaddr::Constants
-  extend BetterIpaddr::ClassMethods
   prepend BetterIpaddr::InstanceMethods
   include Comparable
   include Enumerable

data/lib/better_ipaddr/host_methods.rb

@@ -1,4 +1,5 @@
 module BetterIpaddr
+  # Methods included in IPAddr::IPV4::Host and IPAddr::IPV6::Host
   module HostMethods
     def initialize(*)
       super

data/lib/better_ipaddr/kernel_method.rb

@@ -1,13 +1,38 @@
 require "better_ipaddr/classes"
 
 module Kernel
-  def IPAddr(object)
-    IPAddr::Base.from(object)
+  # @see IPAddr::Base.from
+  def IPAddr(object, exception: false, classful: false)
+    IPAddr::Base.from(object, exception: exception, classful: classful)
   end
 end
 
 class IPAddr
-  def self.Host(object)
-    Base.host_from(object)
+  # @see IPAddr::Base.host_from
+  def self.Host(object, exception: false)
+    Base.host_from(object, exception: exception)
+  end
+end
+
+module BetterIpaddr
+  module InstanceMethods
+    # Emits a snippet of ruby code that can be copied and pasted. Uses the
+    # string representation of the address, by default in CIDR notation, instead
+    # of the harder-to-read mask notation.
+    #
+    # @return String
+    def inspect(cidr: true, full: false)
+      "#{self.class}['#{better_to_s(cidr: cidr, full: full)}']"
+    end
+  end
+
+  module HostMethods
+    # Same as BetterIpaddr::InstanceMethods#inspect but doesn't by default
+    # include the CIDR prefix length.
+    #
+    # @return String
+    def inspect(cidr: false, full: false)
+      "#{self.class}['#{better_to_s(cidr: cidr, full: full)}']"
+    end
   end
 end

data/lib/better_ipaddr/methods.rb

@@ -2,46 +2,7 @@ require "ipaddr"
 require "better_ipaddr/constants"
 
 module BetterIpaddr
-  module ClassMethods
-    include Constants
-
-    # @overload [](address, family)
-    #   @param address [Integer] the integer representation of the address
-    #   @param family [Symbol] a symbol named for the address's
-    #     address family, one of +:ipv4+, +:ipv6+, or +:mac+.
-    #   @return [IPAddr]
-    #   Wrapper for IPAddr.new that accepts a symbolic family name and
-    #   returns a specialized IPAddr subclass.
-    #
-    # @overload [](address, family)
-    #   @param address [Integer] the integer representation of the address
-    #   @param family [Integer] the magic number representing the address's
-    #     address family.
-    #   @return [IPAddr]
-    #   Wrapper for IPAddr.new that accepts a symbolic family name and
-    #   returns a specialized IPAddr subclass.
-    #
-    # @overload [](address)
-    #   @param address [String] the string representation of the address
-    #   @return [IPAddr]
-    #   Wrapper for IPAddr.new that accepts the string representation
-    #   of an address returns a specialized IPAddr subclass.
-
-    def [](address, family = nil)
-      instance = case family
-                 when Symbol
-                   self[address, SYMBOL_TO_FAMILY.fetch(family)]
-                 when IPAddr
-                   address
-                 when nil
-                   new(address)
-                 else
-                   new(address, family)
-                 end
-      IPAddr::Base.specialize(instance)
-    end
-  end
-
+  # Methods included in IPAddr::Base and its descendants
   module InstanceMethods
     include Constants
 
@@ -85,7 +46,7 @@ module BetterIpaddr
     # @return [IPAddr]
 
     def -(offset)
-      self + (-offset)
+      self + -offset
     end
 
     # @overload <=>(other)
@@ -105,7 +66,7 @@ module BetterIpaddr
         family_difference = family <=> other.family
         return family_difference unless family_difference == 0
       elsif !other.is_a?(Integer)
-        fail ArgumentError, "Can't compare #{self.class} with #{other.class}"
+        return nil
       end
 
       address_difference = to_i <=> other.to_i
@@ -137,7 +98,7 @@ module BetterIpaddr
     # @return [IPAddr] the address at the given index
 
     def [](offset)
-      return self if offset.zero? && host?
+      return self if offset == 0 && host?
       offset2 = offset >= 0 ? offset : size + offset
       self.class[to_i + offset2, family: family]
     end
@@ -256,6 +217,7 @@ module BetterIpaddr
       NETMASK_TO_PREFIX_LENGTH[family][mask_addr]
     end
 
+    alias_method :prefix, :prefix_length unless 1.respond_to?(:positive?)
     alias_method :prefixlen, :prefix_length
 
     # Return a new address with the prefix length increased by the

data/lib/better_ipaddr/space.rb

@@ -2,6 +2,7 @@ require "ipaddr"
 require "better_ipaddr/classes"
 
 module BetterIpaddr
+  # Address space utilities
   class Space
     include Enumerable
 
@@ -14,8 +15,8 @@ module BetterIpaddr
       @space = space
       outlier = @networks.find { |net| !@space.cover?(net) }
       return unless outlier
-      fail ArgumentError, "Address space #{@space.inspect} does not cover "\
-                          "network #{outlier.inspect}"
+      raise ArgumentError, "Address space #{@space.inspect} does not cover "\
+                           "network #{outlier.inspect}"
     end
 
     def +(other)
@@ -96,7 +97,7 @@ module BetterIpaddr
     def infer_address_family(*networks)
       example = networks.find { |net| net.respond_to?(:family) }
       return example.family if example
-      fail "Unable to infer address family"
+      raise "Unable to infer address family"
     end
 
     def export(new_networks, space: nil)

data/lib/better_ipaddr/version.rb

@@ -1,3 +1,3 @@
 module BetterIpaddr
-  VERSION = "0.5.0"
+  VERSION = "0.6.0".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: better_ipaddr
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Ben Miller
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-12-09 00:00:00.000000000 Z
+date: 2018-08-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -24,6 +24,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: ipaddr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.0
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -39,19 +67,33 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '10.0'
 - !ruby/object:Gem::Dependency
-  name: minitest
+  name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '0.54'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '0.54'
+- !ruby/object:Gem::Dependency
+  name: test-unit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: 
 email:
 - bmiller@rackspace.com
@@ -60,6 +102,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".rubocop.yml"
 - ".travis.yml"
 - CODE_OF_CONDUCT.md
 - Gemfile
@@ -98,7 +141,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.7.3
 signing_key: 
 specification_version: 4
 summary: IPAddr enhancements for network management.