public_suffix 1.5.3 → 2.0.0

data/lib/public_suffix.rb

@@ -1,28 +1,30 @@
-#
-# Public Suffix
+# = Public Suffix
 #
 # Domain name parser based on the Public Suffix List.
 #
-# Copyright (c) 2009-2015 Simone Carletti <weppos@weppos.net>
-#
+# Copyright (c) 2009-2016 Simone Carletti <weppos@weppos.net>
 
-require 'public_suffix/domain'
-require 'public_suffix/version'
-require 'public_suffix/errors'
-require 'public_suffix/rule'
-require 'public_suffix/list'
+require "public_suffix/domain"
+require "public_suffix/version"
+require "public_suffix/errors"
+require "public_suffix/rule"
+require "public_suffix/list"
 
+# PublicSuffix is a Ruby domain name parser based on the Public Suffix List.
+#
+# The [Public Suffix List](https://publicsuffix.org) is a cross-vendor initiative
+# to provide an accurate list of domain name suffixes.
+#
+# The Public Suffix List is an initiative of the Mozilla Project,
+# but is maintained as a community resource. It is available for use in any software,
+# but was originally created to meet the needs of browser manufacturers.
 module PublicSuffix
 
-  # Parses +domain+ and returns the
-  # {PublicSuffix::Domain} instance.
-  #
-  # @param  [String, #to_s] domain
-  #   The domain name or fully qualified domain name to parse.
-  # @param  [PublicSuffix::List] list
-  #   The rule list to search, defaults to the default {PublicSuffix::List}
-  #
-  # @return [PublicSuffix::Domain]
+  DOT   = ".".freeze
+  BANG  = "!".freeze
+  STAR  = "*".freeze
+
+  # Parses +name+ and returns the {PublicSuffix::Domain} instance.
   #
   # @example Parse a valid domain
   #   PublicSuffix.parse("google.com")
@@ -48,47 +50,37 @@ module PublicSuffix
   #   PublicSuffix.parse("http://www.google.com")
   #   # => PublicSuffix::DomainInvalid
   #
+  #
+  # @param  [String, #to_s] name The domain name or fully qualified domain name to parse.
+  # @param  [PublicSuffix::List] list The rule list to search, defaults to the default {PublicSuffix::List}
+  # @param  [Boolean] ignore_private
+  # @return [PublicSuffix::Domain]
+  #
   # @raise [PublicSuffix::Error]
   #   If domain is not a valid domain.
   # @raise [PublicSuffix::DomainNotAllowed]
-  #   If a rule for +domain+ is found, but the rule
-  #   doesn't allow +domain+.
-  #
-  def self.parse(domain, list = List.default)
-    domain = domain.to_s.downcase
-    rule   = list.find(domain)
+  #   If a rule for +domain+ is found, but the rule doesn't allow +domain+.
+  def self.parse(name, list: List.default, default_rule: list.default_rule, ignore_private: false)
+    what = normalize(name)
+    raise what if what.is_a?(DomainInvalid)
+
+    rule = list.find(what, default: default_rule, ignore_private: ignore_private)
 
     if rule.nil?
-      raise DomainInvalid, "`#{domain}' is not a valid domain"
+      raise DomainInvalid, "`#{what}` is not a valid domain"
     end
-    if !rule.allow?(domain)
-      raise DomainNotAllowed, "`#{domain}' is not allowed according to Registry policy"
+    if rule.decompose(what).last.nil?
+      raise DomainNotAllowed, "`#{what}` is not allowed according to Registry policy"
     end
 
-    left, right = rule.decompose(domain)
-
-    parts = left.split(".")
-    # If we have 0 parts left, there is just a tld and no domain or subdomain
-    # If we have 1 part  left, there is just a tld, domain and not subdomain
-    # If we have 2 parts left, the last part is the domain, the other parts (combined) are the subdomain
-    tld = right
-    sld = parts.empty? ? nil : parts.pop
-    trd = parts.empty? ? nil : parts.join(".")
-
-    Domain.new(tld, sld, trd)
+    decompose(what, rule)
   end
 
-  # Checks whether +domain+ is assigned and allowed,
-  # without actually parsing it.
+  # Checks whether +domain+ is assigned and allowed, without actually parsing it.
   #
   # This method doesn't care whether domain is a domain or subdomain.
   # The validation is performed using the default {PublicSuffix::List}.
   #
-  # @param  [String, #to_s] domain
-  #   The domain name or fully qualified domain name to validate.
-  #
-  # @return [Boolean]
-  #
   # @example Validate a valid domain
   #   PublicSuffix.valid?("example.com")
   #   # => true
@@ -97,9 +89,9 @@ module PublicSuffix
   #   PublicSuffix.valid?("www.example.com")
   #   # => true
   #
-  # @example Validate a not-assigned domain
-  #   PublicSuffix.valid?("example.qqq")
-  #   # => false
+  # @example Validate a not-listed domain
+  #   PublicSuffix.valid?("example.tldnotlisted")
+  #   # => true
   #
   # @example Validate a not-allowed domain
   #   PublicSuffix.valid?("example.do")
@@ -117,10 +109,62 @@ module PublicSuffix
   #   PublicSuffix.valid?("http://www.example.com")
   #   # => false
   #
-  def self.valid?(domain)
-    domain = domain.to_s.downcase
-    rule   = List.default.find(domain)
-    !rule.nil? && rule.allow?(domain)
+  #
+  # @param  [String, #to_s] name The domain name or fully qualified domain name to validate.
+  # @param  [Boolean] ignore_private
+  # @return [Boolean]
+  def self.valid?(name, list: List.default, default_rule: nil, ignore_private: false)
+    what = normalize(name)
+    return false if what.is_a?(DomainInvalid)
+
+    default_rule ||= list.default_rule
+    rule = list.find(what, default: default_rule, ignore_private: ignore_private)
+
+    !rule.nil? && !rule.decompose(what).last.nil?
+  end
+
+  # Attempt to parse the name and returns the domain, if valid.
+  #
+  # This method doesn't raise. Instead, it returns nil if the domain is not valid for whatever reason.
+  #
+  # @param  [String, #to_s] name The domain name or fully qualified domain name to parse.
+  # @param  [PublicSuffix::List] list The rule list to search, defaults to the default {PublicSuffix::List}
+  # @param  [Boolean] ignore_private
+  # @return [String]
+  def self.domain(name, **options)
+    parse(name, **options).domain
+  rescue PublicSuffix::Error
+    nil
+  end
+
+
+  # private
+
+  def self.decompose(name, rule)
+    left, right = rule.decompose(name)
+
+    parts = left.split(DOT)
+    # If we have 0 parts left, there is just a tld and no domain or subdomain
+    # If we have 1 part  left, there is just a tld, domain and not subdomain
+    # If we have 2 parts left, the last part is the domain, the other parts (combined) are the subdomain
+    tld = right
+    sld = parts.empty? ? nil : parts.pop
+    trd = parts.empty? ? nil : parts.join(DOT)
+
+    Domain.new(tld, sld, trd)
+  end
+
+  # Pretend we know how to deal with user input.
+  def self.normalize(name)
+    name = name.to_s.dup
+    name.strip!
+    name.chomp!(DOT)
+    name.downcase!
+
+    return DomainInvalid.new("Name is blank") if name.empty?
+    return DomainInvalid.new("Name starts with a dot") if name.start_with?(DOT)
+    return DomainInvalid.new("%s is not expected to contain a scheme" % name) if name.include?("://")
+    name
   end
 
 end

data/lib/public_suffix/domain.rb

@@ -1,37 +1,33 @@
-#
-# Public Suffix
+# = Public Suffix
 #
 # Domain name parser based on the Public Suffix List.
 #
-# Copyright (c) 2009-2015 Simone Carletti <weppos@weppos.net>
-#
+# Copyright (c) 2009-2016 Simone Carletti <weppos@weppos.net>
 
 module PublicSuffix
 
+  # Domain represents a domain name, composed by a TLD, SLD and TRD.
   class Domain
 
-    # Splits a string into its possible labels
-    # as a domain in reverse order from the input string.
-    #
-    # The input is not validated, but it is assumed to be a valid domain.
+    # Splits a string into the labels, that is the dot-separated parts.
     #
-    # @param  [String, #to_s] domain
-    #   The domain name to split.
-    #
-    # @return [Array<String>]
+    # The input is not validated, but it is assumed to be a valid domain name.
     #
     # @example
     #
-    #   domain_to_labels('google.com')
-    #   # => ['com', 'google']
+    #   name_to_labels('example.com')
+    #   # => ['example', 'com']
     #
-    #   domain_to_labels('google.co.uk')
-    #   # => ['uk', 'co', 'google']
+    #   name_to_labels('example.co.uk')
+    #   # => ['example', 'co', 'uk']
     #
-    def self.domain_to_labels(domain)
-      domain.to_s.split(".").reverse
+    # @param  name [String, #to_s] The domain name to split.
+    # @return [Array<String>]
+    def self.name_to_labels(name)
+      name.to_s.split(DOT)
     end
 
+
     attr_reader :tld, :sld, :trd
 
     # Creates and returns a new {PublicSuffix::Domain} instance.
@@ -64,7 +60,7 @@ module PublicSuffix
     #   PublicSuffix::Domain.new("com", "example", "wwww")
     #   # => #<PublicSuffix::Domain @tld="com", @trd=nil, @sld="example">
     #
-    def initialize(*args, &block)
+    def initialize(*args)
       @tld, @sld, @trd = args
       yield(self) if block_given?
     end
@@ -105,7 +101,7 @@ module PublicSuffix
     #   # => "www.google.com"
     #
     def name
-      [@trd, @sld, @tld].compact.join(".")
+      [@trd, @sld, @tld].compact.join(DOT)
     end
 
     # Returns a domain-like representation of this object
@@ -123,10 +119,6 @@ module PublicSuffix
     # This method doesn't validate the input. It handles the domain
     # as a valid domain name and simply applies the necessary transformations.
     #
-    #   # This is an invalid domain
-    #   PublicSuffix::Domain.new("qqq", "google").domain
-    #   # => "google.qqq"
-    #
     # This method returns a FQD, not just the domain part.
     # To get the domain part, use <tt>#sld</tt> (aka second level domain).
     #
@@ -136,18 +128,15 @@ module PublicSuffix
     #   PublicSuffix::Domain.new("com", "google", "www").sld
     #   # => "google"
     #
-    # @return [String]
-    #
     # @see #domain?
     # @see #subdomain
     #
+    # @return [String]
     def domain
-      if domain?
-        [@sld, @tld].join(".")
-      end
+      [@sld, @tld].join(DOT) if domain?
     end
 
-    # Returns a domain-like representation of this object
+    # Returns a subdomain-like representation of this object
     # if the object is a {#subdomain?}, <tt>nil</tt> otherwise.
     #
     #   PublicSuffix::Domain.new("com").subdomain
@@ -162,11 +151,7 @@ module PublicSuffix
     # This method doesn't validate the input. It handles the domain
     # as a valid domain name and simply applies the necessary transformations.
     #
-    #   # This is an invalid domain
-    #   PublicSuffix::Domain.new("qqq", "google", "www").subdomain
-    #   # => "www.google.qqq"
-    #
-    # This method returns a FQD, not just the domain part.
+    # This method returns a FQD, not just the subdomain part.
     # To get the subdomain part, use <tt>#trd</tt> (aka third level domain).
     #
     #   PublicSuffix::Domain.new("com", "google", "www").subdomain
@@ -175,25 +160,12 @@ module PublicSuffix
     #   PublicSuffix::Domain.new("com", "google", "www").trd
     #   # => "www"
     #
-    # @return [String]
-    #
     # @see #subdomain?
     # @see #domain
     #
+    # @return [String]
     def subdomain
-      if subdomain?
-        [@trd, @sld, @tld].join(".")
-      end
-    end
-
-    # Returns the rule matching this domain
-    # in the default {PublicSuffix::List}.
-    #
-    # @return [PublicSuffix::Rule::Base, nil]
-    #   The rule instance a rule matches current domain,
-    #   nil if no rule is found.
-    def rule
-      List.default.find(name)
+      [@trd, @sld, @tld].join(DOT) if subdomain?
     end
 
     # Checks whether <tt>self</tt> looks like a domain.
@@ -204,8 +176,6 @@ module PublicSuffix
     # If you also want to validate the domain,
     # use {#valid_domain?} instead.
     #
-    # @return [Boolean]
-    #
     # @example
     #
     #   PublicSuffix::Domain.new("com").domain?
@@ -219,11 +189,12 @@ module PublicSuffix
     #
     #   # This is an invalid domain, but returns true
     #   # because this method doesn't validate the content.
-    #   PublicSuffix::Domain.new("qqq", "google").domain?
+    #   PublicSuffix::Domain.new("com", nil).domain?
     #   # => true
     #
     # @see #subdomain?
     #
+    # @return [Boolean]
     def domain?
       !(@tld.nil? || @sld.nil?)
     end
@@ -236,8 +207,6 @@ module PublicSuffix
     # If you also want to validate the domain,
     # use {#valid_subdomain?} instead.
     #
-    # @return [Boolean]
-    #
     # @example
     #
     #   PublicSuffix::Domain.new("com").subdomain?
@@ -251,115 +220,16 @@ module PublicSuffix
     #
     #   # This is an invalid domain, but returns true
     #   # because this method doesn't validate the content.
-    #   PublicSuffix::Domain.new("qqq", "google", "www").subdomain?
+    #   PublicSuffix::Domain.new("com", "example", nil).subdomain?
     #   # => true
     #
     # @see #domain?
     #
+    # @return [Boolean]
     def subdomain?
       !(@tld.nil? || @sld.nil? || @trd.nil?)
     end
 
-    # Checks whether <tt>self</tt> is exclusively a domain,
-    # and not a subdomain.
-    #
-    # @return [Boolean]
-    def is_a_domain?
-      domain? && !subdomain?
-    end
-
-    # Checks whether <tt>self</tt> is exclusively a subdomain.
-    #
-    # @return [Boolean]
-    def is_a_subdomain?
-      subdomain?
-    end
-
-    # Checks whether <tt>self</tt> is assigned and allowed
-    # according to default {List}.
-    #
-    # This method triggers a new rule lookup in the default {List},
-    # which is a quite intensive task.
-    #
-    # @return [Boolean]
-    #
-    # @example Check a valid domain
-    #   Domain.new("com", "example").valid?
-    #   # => true
-    #
-    # @example Check a valid subdomain
-    #   Domain.new("com", "example", "www").valid?
-    #   # => true
-    #
-    # @example Check a not-assigned domain
-    #   Domain.new("qqq", "example").valid?
-    #   # => false
-    #
-    # @example Check a not-allowed domain
-    #   Domain.new("do", "example").valid?
-    #   # => false
-    #   Domain.new("do", "example", "www").valid?
-    #   # => true
-    #
-    def valid?
-      r = rule
-      !r.nil? && r.allow?(name)
-    end
-
-    # Checks whether <tt>self</tt> looks like a domain and validates
-    # according to default {List}.
-    #
-    # @return [Boolean]
-    #
-    # @example
-    #
-    #   PublicSuffix::Domain.new("com").domain?
-    #   # => false
-    #
-    #   PublicSuffix::Domain.new("com", "google").domain?
-    #   # => true
-    #
-    #   PublicSuffix::Domain.new("com", "google", "www").domain?
-    #   # => true
-    #
-    #   # This is an invalid domain
-    #   PublicSuffix::Domain.new("qqq", "google").false?
-    #   # => true
-    #
-    # @see #domain?
-    # @see #valid?
-    #
-    def valid_domain?
-      domain? && valid?
-    end
-
-    # Checks whether <tt>self</tt> looks like a subdomain and validates
-    # according to default {List}.
-    #
-    # @return [Boolean]
-    #
-    # @example
-    #
-    #   PublicSuffix::Domain.new("com").subdomain?
-    #   # => false
-    #
-    #   PublicSuffix::Domain.new("com", "google").subdomain?
-    #   # => false
-    #
-    #   PublicSuffix::Domain.new("com", "google", "www").subdomain?
-    #   # => true
-    #
-    #   # This is an invalid domain
-    #   PublicSuffix::Domain.new("qqq", "google", "www").subdomain?
-    #   # => false
-    #
-    # @see #subdomain?
-    # @see #valid?
-    #
-    def valid_subdomain?
-      subdomain? && valid?
-    end
-
   end
 
 end