public_suffix 1.5.3 → 2.0.0

data/lib/public_suffix/errors.rb

@@ -1,19 +1,16 @@
-#
-# 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
 
   class Error < StandardError
   end
 
-  # Raised when trying to parse an invalid domain.
-  # A domain is considered invalid when no rule is found
-  # in the definition list.
+  # Raised when trying to parse an invalid name.
+  # A name is considered invalid when no rule is found in the definition list.
   #
   # @example
   #
@@ -26,10 +23,7 @@ module PublicSuffix
   class DomainInvalid < Error
   end
 
-  # Raised when trying to parse a domain
-  # which is formally defined by a rule,
-  # but the rules set a requirement which is not satisfied
-  # by the input you are trying to parse.
+  # Raised when trying to parse a name that matches a suffix.
   #
   # @example
   #
@@ -42,10 +36,4 @@ module PublicSuffix
   class DomainNotAllowed < DomainInvalid
   end
 
-  # Backward Compatibility
-  #
-  # @deprecated Use {PublicSuffix::DomainInvalid}.
-  #
-  InvalidDomain = DomainInvalid
-
 end

data/lib/public_suffix/list.rb

@@ -1,10 +1,8 @@
-#
-# 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
 
@@ -42,17 +40,16 @@ module PublicSuffix
   class List
     include Enumerable
 
-    class << self
-      attr_writer :default_definition
-    end
+    DEFAULT_LIST_PATH = File.join(File.dirname(__FILE__), "..", "..", "data", "list.txt")
 
     # Gets the default rule list.
+    #
     # Initializes a new {PublicSuffix::List} parsing the content
-    # of {PublicSuffix::List.default_definition}, if required.
+    # of {PublicSuffix::List.default_list_content}, if required.
     #
     # @return [PublicSuffix::List]
-    def self.default
-      @default ||= parse(default_definition)
+    def self.default(**options)
+      @default ||= parse(File.read(DEFAULT_LIST_PATH), options)
     end
 
     # Sets the default rule list to +value+.
@@ -65,25 +62,6 @@ module PublicSuffix
       @default = value
     end
 
-    # Shows if support for private (non-ICANN) domains is enabled or not
-    #
-    # @return [Boolean]
-    def self.private_domains?
-      @private_domains != false
-    end
-
-    # Enables/disables support for private (non-ICANN) domains
-    # Implicitly reloads the list
-    #
-    # @param [Boolean] value
-    #   enable/disable support
-    #
-    # @return [PublicSuffix::List]
-    def self.private_domains=(value)
-      @private_domains = !!value
-      self.clear
-    end
-
     # Sets the default rule list to +nil+.
     #
     # @return [self]
@@ -92,92 +70,89 @@ module PublicSuffix
       self
     end
 
-    # Resets the default rule list and reinitialize it
-    # parsing the content of {PublicSuffix::List.default_definition}.
-    #
-    # @return [PublicSuffix::List]
-    def self.reload
-      self.clear.default
-    end
-
-    DEFAULT_DEFINITION_PATH = File.join(File.dirname(__FILE__), "..", "..", "data", "definitions.txt")
-
-    # Gets the default definition list.
-    # Can be any <tt>IOStream</tt> including a <tt>File</tt>
-    # or a simple <tt>String</tt>.
-    # The object must respond to <tt>#each_line</tt>.
-    #
-    # @return [File]
-    def self.default_definition
-      @default_definition || File.new(DEFAULT_DEFINITION_PATH, "r:utf-8")
-    end
+    # rubocop:disable Metrics/MethodLength
 
     # Parse given +input+ treating the content as Public Suffix List.
     #
     # See http://publicsuffix.org/format/ for more details about input format.
     #
-    # @param [String] input The rule list to parse.
-    #
+    # @param  string [#each_line] The list to parse.
+    # @param  private_domain [Boolean] whether to ignore the private domains section.
     # @return [Array<PublicSuffix::Rule::*>]
-    def self.parse(input)
+    def self.parse(input, private_domains: true)
+      comment_token = "//".freeze
+      private_token = "===BEGIN PRIVATE DOMAINS===".freeze
+      section = nil # 1 == ICANN, 2 == PRIVATE
+
       new do |list|
         input.each_line do |line|
           line.strip!
-          break if !private_domains? && line.include?('===BEGIN PRIVATE DOMAINS===')
-          # strip blank lines
-          if line.empty?
+          case # rubocop:disable Style/EmptyCaseCondition
+
+          # skip blank lines
+          when line.empty?
             next
-          # strip comments
-          elsif line =~ %r{^//}
+
+          # include private domains or stop scanner
+          when line.include?(private_token)
+            break if !private_domains
+            section = 2
+
+          # skip comments
+          when line.start_with?(comment_token)
             next
-          # append rule
+
           else
-            list.add(Rule.factory(line), false)
+            list.add(Rule.factory(line, private: section == 2), reindex: false)
+
           end
         end
       end
     end
+    # rubocop:enable Metrics/MethodLength
+
 
     # Gets the array of rules.
     #
     # @return [Array<PublicSuffix::Rule::*>]
     attr_reader :rules
 
-    # Gets the naive index, a hash that with the keys being the first label of
-    # every rule pointing to an array of integers (indexes of the rules in @rules).
-    #
-    # @return [Array]
-    attr_reader :indexes
 
     # Initializes an empty {PublicSuffix::List}.
     #
     # @yield [self] Yields on self.
     # @yieldparam [PublicSuffix::List] self The newly created instance.
     #
-    def initialize(&block)
-      @rules   = []
+    def initialize
+      @rules = []
       yield(self) if block_given?
-      create_index!
+      reindex!
     end
 
+
     # Creates a naive index for +@rules+. Just a hash that will tell
     # us where the elements of +@rules+ are relative to its first
     # {PublicSuffix::Rule::Base#labels} element.
     #
     # For instance if @rules[5] and @rules[4] are the only elements of the list
-    # where Rule#labels.first is 'us' @indexes['us'] #=> [5,4], that way in 
+    # where Rule#labels.first is 'us' @indexes['us'] #=> [5,4], that way in
     # select we can avoid mapping every single rule against the candidate domain.
-    def create_index!
+    def reindex!
       @indexes = {}
-      @rules.map { |l| l.labels.first }.each_with_index do |elm, inx|
-        if !@indexes.has_key?(elm)
-          @indexes[elm] = [inx]
-        else
-          @indexes[elm] << inx
-        end
+      @rules.each_with_index do |rule, index|
+        tld = Domain.name_to_labels(rule.value).last
+        @indexes[tld] ||= []
+        @indexes[tld] << index
       end
     end
 
+    # Gets the naive index, a hash that with the keys being the first label of
+    # every rule pointing to an array of integers (indexes of the rules in @rules).
+    def indexes
+      @indexes.dup
+    end
+
+
     # Checks whether two lists are equal.
     #
     # List <tt>one</tt> is equal to <tt>two</tt>, if <tt>two</tt> is an instance of
@@ -190,39 +165,31 @@ module PublicSuffix
     # @return [Boolean]
     def ==(other)
       return false unless other.is_a?(List)
-      self.equal?(other) ||
-      self.rules == other.rules
+      equal?(other) || rules == other.rules
     end
-    alias :eql? :==
+    alias eql? ==
 
     # Iterates each rule in the list.
     def each(*args, &block)
       @rules.each(*args, &block)
     end
 
-    # Gets the list as array.
-    #
-    # @return [Array<PublicSuffix::Rule::*>]
-    def to_a
-      @rules
-    end
 
-    # Adds the given object to the list
-    # and optionally refreshes the rule index.
+    # Adds the given object to the list and optionally refreshes the rule index.
     #
     # @param [PublicSuffix::Rule::*] rule
     #   The rule to add to the list.
-    # @param [Boolean] index
+    # @param [Boolean] reindex
     #   Set to true to recreate the rule index
     #   after the rule has been added to the list.
     #
     # @return [self]
     #
-    # @see #create_index!
+    # @see #reindex!
     #
-    def add(rule, index = true)
+    def add(rule, reindex: true)
       @rules << rule
-      create_index! if index == true
+      reindex! if reindex
       self
     end
     alias << add
@@ -233,7 +200,6 @@ module PublicSuffix
     def size
       @rules.size
     end
-    alias length size
 
     # Checks whether the list is empty.
     #
@@ -247,54 +213,73 @@ module PublicSuffix
     # @return [self]
     def clear
       @rules.clear
+      reindex!
       self
     end
 
-    # Returns the most appropriate rule for domain.
+    # Finds and returns the most appropriate rule for the domain name.
     #
     # From the Public Suffix List documentation:
     #
-    # * If a hostname matches more than one rule in the file,
+    # - If a hostname matches more than one rule in the file,
     #   the longest matching rule (the one with the most levels) will be used.
-    # * An exclamation mark (!) at the start of a rule marks an exception to a previous wildcard rule.
+    # - An exclamation mark (!) at the start of a rule marks an exception to a previous wildcard rule.
     #   An exception rule takes priority over any other matching rule.
     #
-    # == Algorithm description
-    #
-    # * Match domain against all rules and take note of the matching ones.
-    # * If no rules match, the prevailing rule is "*".
-    # * If more than one rule matches, the prevailing rule is the one which is an exception rule.
-    # * If there is no matching exception rule, the prevailing rule is the one with the most labels.
-    # * If the prevailing rule is a exception rule, modify it by removing the leftmost label.
-    # * The public suffix is the set of labels from the domain
-    #   which directly match the labels of the prevailing rule (joined by dots).
-    # * The registered domain is the public suffix plus one additional label.
-    #
-    # @param  [String, #to_s] domain The domain name.
-    #
-    # @return [PublicSuffix::Rule::*, nil]
-    def find(domain)
-      rules = select(domain)
-      rules.detect { |r|   r.type == :exception } ||
-      rules.inject { |t,r| t.length > r.length ? t : r }
+    # ## Algorithm description
+    #
+    # 1. Match domain against all rules and take note of the matching ones.
+    # 2. If no rules match, the prevailing rule is "*".
+    # 3. If more than one rule matches, the prevailing rule is the one which is an exception rule.
+    # 4. If there is no matching exception rule, the prevailing rule is the one with the most labels.
+    # 5. If the prevailing rule is a exception rule, modify it by removing the leftmost label.
+    # 6. The public suffix is the set of labels from the domain
+    #    which directly match the labels of the prevailing rule (joined by dots).
+    # 7. The registered domain is the public suffix plus one additional label.
+    #
+    # @param  name [String, #to_s] The domain name.
+    # @param  [PublicSuffix::Rule::*] default The default rule to return in case no rule matches.
+    # @return [PublicSuffix::Rule::*]
+    def find(name, default: default_rule, **options)
+      rule = select(name, **options).inject do |l, r|
+        return r if r.class == Rule::Exception
+        l.length > r.length ? l : r
+      end
+      rule || default
     end
 
     # Selects all the rules matching given domain.
     #
-    # Will use +@indexes+ to try only the rules that share the same first label,
-    # that will speed up things when using +List.find('foo')+ a lot.
+    # Internally, the lookup heavily rely on the `@indexes`. The input is split into labels,
+    # and we retriever from the index only the rules that end with the input label. After that,
+    # a sequential scan is performed. In most cases, where the number of rules for the same label
+    # is limited, this algorithm is efficient enough.
     #
-    # @param  [String, #to_s] domain The domain name.
+    # If `ignore_private` is set to true, the algorithm will skip the rules that are flagged as private domain.
+    # Note that the rules will still be part of the loop. If you frequently need to access lists
+    # ignoring the private domains, you should create a list that doesn't include these domains setting the
+    # `private_domains: false` option when calling {.parse}.
     #
+    # @param  [String, #to_s] name The domain name.
+    # @param  [Boolean] ignore_private
     # @return [Array<PublicSuffix::Rule::*>]
-    def select(domain)
-      # raise DomainInvalid, "Blank domain"
-      return [] if domain.to_s =~ /\A\s*\z/
-      # raise DomainInvalid, "`#{domain}' is not expected to contain a scheme"
-      return [] if domain.include?("://")
-
-      indices = (@indexes[Domain.domain_to_labels(domain).first] || [])
-      @rules.values_at(*indices).select { |rule| rule.match?(domain) }
+    def select(name, ignore_private: false)
+      name = name.to_s
+      indices = (@indexes[Domain.name_to_labels(name).last] || [])
+
+      finder = @rules.values_at(*indices).lazy
+      finder = finder.select { |rule| rule.match?(name) }
+      finder = finder.select { |rule| !rule.private } if ignore_private
+      finder.to_a
+    end
+
+    # Gets the default rule.
+    #
+    # @see PublicSuffix::Rule.default_rule
+    #
+    # @return [PublicSuffix::Rule::*]
+    def default_rule
+      PublicSuffix::Rule.default
     end
 
   end

data/lib/public_suffix/rule.rb

@@ -1,17 +1,15 @@
-#
-# 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
 
   # A Rule is a special object which holds a single definition
   # of the Public Suffix List.
   #
-  # There are 3 types of ruleas, each one represented by a specific
+  # There are 3 types of rules, each one represented by a specific
   # subclass within the +PublicSuffix::Rule+ namespace.
   #
   # To create a new Rule, use the {PublicSuffix::Rule#factory} method.
@@ -21,12 +19,11 @@ module PublicSuffix
   #
   module Rule
 
-    #
     # = Abstract rule class
     #
     # This represent the base class for a Rule definition
-    # in the {Public Suffix List}[http://publicsuffix.org].
-    # 
+    # in the {Public Suffix List}[https://publicsuffix.org].
+    #
     # This is intended to be an Abstract class
     # and you shouldn't create a direct instance. The only purpose
     # of this class is to expose a common interface
@@ -36,28 +33,21 @@ module PublicSuffix
     # * {PublicSuffix::Rule::Exception}
     # * {PublicSuffix::Rule::Wildcard}
     #
-    # == Properties
+    # ## Properties
     #
     # A rule is composed by 4 properties:
     #
-    # name    - The name of the rule, corresponding to the rule definition
-    #           in the public suffix list
-    # value   - The value, a normalized version of the rule name.
+    # value   - A normalized version of the rule name.
     #           The normalization process depends on rule tpe.
-    # type    - The rule type (:normal, :wildcard, :exception)
-    # labels  - The canonicalized rule name
     #
     # Here's an example
     #
     #   PublicSuffix::Rule.factory("*.google.com")
     #   #<PublicSuffix::Rule::Wildcard:0x1015c14b0
-    #       @labels=["com", "google"],
-    #       @name="*.google.com",
-    #       @type=:wildcard,
     #       @value="google.com"
     #   >
     #
-    # == Rule Creation
+    # ## Rule Creation
     #
     # The best way to create a new rule is passing the rule name
     # to the <tt>PublicSuffix::Rule.factory</tt> method.
@@ -71,35 +61,34 @@ module PublicSuffix
     # This method will detect the rule type and create an instance
     # from the proper rule class.
     #
-    # == Rule Usage
+    # ## Rule Usage
     #
-    # A rule describes the composition of a domain name
-    # and explains how to tokenize the domain name
-    # into tld, sld and trd.
+    # A rule describes the composition of a domain name and explains how to tokenize
+    # the name into tld, sld and trd.
     #
-    # To use a rule, you first need to be sure the domain you want to tokenize
+    # To use a rule, you first need to be sure the name you want to tokenize
     # can be handled by the current rule.
     # You can use the <tt>#match?</tt> method.
     #
     #   rule = PublicSuffix::Rule.factory("com")
-    #   
+    #
     #   rule.match?("google.com")
     #   # => true
-    #   
+    #
     #   rule.match?("google.com")
     #   # => false
     #
-    # Rule order is significant. A domain can match more than one rule.
+    # Rule order is significant. A name can match more than one rule.
     # See the {Public Suffix Documentation}[http://publicsuffix.org/format/]
     # to learn more about rule priority.
     #
     # When you have the right rule, you can use it to tokenize the domain name.
-    # 
+    #
     #   rule = PublicSuffix::Rule.factory("com")
-    # 
+    #
     #   rule.decompose("google.com")
     #   # => ["google", "com"]
-    # 
+    #
     #   rule.decompose("www.google.com")
     #   # => ["www.google", "com"]
     #
@@ -107,145 +96,107 @@ module PublicSuffix
     #
     class Base
 
-      attr_reader :name, :value, :labels
+      # @return [String] the rule definition
+      attr_reader :value
 
-      # Initializes a new rule with name and value.
-      # If value is +nil+, name also becomes the value for this rule.
-      #
-      # @param [String] name
-      #   The name of the rule
-      # @param [String] value
-      #   The value of the rule. If nil, defaults to +name+.
-      #
-      def initialize(name, value = nil)
-        @name   = name.to_s
-        @value  = value || @name
-        @labels = Domain.domain_to_labels(@value)
-      end
+      # @return [Boolean] true if the rule is a private domain
+      attr_reader :private
 
-      #
-      # The rule type name.
-      #
-      # @return [Symbol]
-      #
-      def self.type
-        @type ||= self.name.split("::").last.downcase.to_sym
-      end
 
+      # Initializes a new rule with name and value.
+      # If value is +nil+, name also becomes the value for this rule.
       #
-      # @see {type}
-      #
-      def type
-        self.class.type
+      # @param value [String] the value of the rule
+      def initialize(value, private: false)
+        @value    = value.to_s
+        @private  = private
       end
 
       # Checks whether this rule is equal to <tt>other</tt>.
       #
-      # @param [PublicSuffix::Rule::*] other
-      #   The rule to compare.
-      #
+      # @param  [PublicSuffix::Rule::*] other The rule to compare
       # @return [Boolean]
       #   Returns true if this rule and other are instances of the same class
       #   and has the same value, false otherwise.
       def ==(other)
-        return false unless other.is_a?(self.class)
-        self.equal?(other) ||
-        self.name == other.name
+        equal?(other) || (self.class == other.class && value == other.value)
       end
-      alias :eql? :==
+      alias eql? ==
 
-      # Checks if this rule matches +domain+.
+      # Checks if this rule matches +name+.
       #
-      # @param [String, #to_s] domain
-      #   The domain name to check.
+      # A domain name is said to match a rule if and only if
+      # all of the following conditions are met:
       #
-      # @return [Boolean]
+      # - When the domain and rule are split into corresponding labels,
+      #   that the domain contains as many or more labels than the rule.
+      # - Beginning with the right-most labels of both the domain and the rule,
+      #   and continuing for all labels in the rule, one finds that for every pair,
+      #   either they are identical, or that the label from the rule is "*".
+      #
+      # @see https://publicsuffix.org/list/
       #
       # @example
-      #   rule = Rule.factory("com")
-      #   # #<PublicSuffix::Rule::Normal>
-      #   rule.match?("example.com")
+      #   Rule.factory("com").match?("example.com")
       #   # => true
-      #   rule.match?("example.net")
+      #   Rule.factory("com").match?("example.net")
       #   # => false
       #
-      def match?(domain)
-        l1 = labels
-        l2 = Domain.domain_to_labels(domain)
-        odiff(l1, l2).empty?
-      end
-
-      # Checks if this rule allows +domain+.
-      #
-      # @param [String, #to_s] domain
-      #   The domain name to check.
-      #
+      # @param  name [String, #to_s] The domain name to check.
       # @return [Boolean]
-      #
-      # @example
-      #   rule = Rule.factory("*.do")
-      #   # => #<PublicSuffix::Rule::Wildcard>
-      #   rule.allow?("example.do")
-      #   # => false
-      #   rule.allow?("www.example.do")
-      #   # => true
-      #
-      def allow?(domain)
-        !decompose(domain).last.nil?
-      end
-
-      # Gets the length of this rule for comparison.
-      # The length usually matches the number of rule +parts+.
-      #
-      # Subclasses might actually override this method.
-      #
-      # @return [Integer] The number of parts.
-      def length
-        parts.length
+      def match?(name)
+        # Note: it works because of the assumption there are no
+        # rules like foo.*.com. If the assumption is incorrect,
+        # we need to properly walk the input and skip parts according
+        # to wildcard component.
+        diff = name.chomp(value)
+        diff.empty? || diff[-1] == "."
       end
 
-      #
-      # @raise  [NotImplementedError]
       # @abstract
       def parts
-        raise(NotImplementedError,"#{self.class}##{__method__} is not implemented")
+        raise NotImplementedError
       end
 
-      #
-      # @param [String, #to_s] domain
-      #   The domain name to decompose.
-      #
-      # @return [Array<String, nil>]
-      #
-      # @raise  [NotImplementedError]
       # @abstract
-      def decompose(domain)
-        raise(NotImplementedError,"#{self.class}##{__method__} is not implemented")
+      def length
+        raise NotImplementedError
       end
 
-      private
-
-      def odiff(one, two)
-        ii = 0
-
-        while(ii < one.size && one[ii] == two[ii])
-          ii += 1
-        end
-
-        one[ii..one.length]
+      # @abstract
+      # @param  [String, #to_s] name The domain name to decompose
+      # @return [Array<String, nil>]
+      def decompose(*)
+        raise NotImplementedError
       end
 
     end
 
+    # Normal represents a standard rule (e.g. com).
     class Normal < Base
 
-      # Initializes a new rule with +name+.
+      # Initializes a new rule from +definition+.
+      #
+      # @param definition [String] the rule as defined in the PSL
+      def initialize(definition, **options)
+        super(definition, **options)
+      end
+
+      # Gets the original rule definition.
       #
-      # @param [String] name
-      #   The name of this rule.
+      # @return [String] The rule definition.
+      def rule
+        value
+      end
+
+      # Decomposes the domain name according to rule properties.
       #
-      def initialize(name)
-        super(name, name)
+      # @param  [String, #to_s] name The domain name to decompose
+      # @return [Array<String>] The array with [trd + sld, tld].
+      def decompose(domain)
+        suffix = parts.join('\.')
+        matches = domain.to_s.match(/^(.*)\.(#{suffix})$/)
+        matches ? matches[1..2] : [nil, nil]
       end
 
       # dot-split rule value and returns all rule parts
@@ -253,74 +204,96 @@ module PublicSuffix
       #
       # @return [Array<String>]
       def parts
-        @parts ||= @value.split(".")
+        @value.split(DOT)
       end
 
-      # Decomposes the domain according to rule properties.
-      #
-      # @param [String, #to_s] domain
-      #   The domain name to decompose.
+      # Gets the length of this rule for comparison,
+      # represented by the number of dot-separated parts in the rule.
       #
-      # @return [Array<String>]
-      #   The array with [trd + sld, tld].
-      #
-      def decompose(domain)
-        domain.to_s.chomp(".") =~ /^(.*)\.(#{parts.join('\.')})$/
-        [$1, $2]
+      # @return [Integer] The length of the rule.
+      def length
+        @length ||= parts.length
       end
 
     end
 
+    # Wildcard represents a wildcard rule (e.g. *.co.uk).
     class Wildcard < Base
 
-      # Initializes a new rule with +name+.
+      # Initializes a new rule from +definition+.
       #
-      # @param [String] name
-      #   The name of this rule.
+      # The wildcard "*" is removed from the value, as it's common
+      # for each wildcard rule.
       #
-      def initialize(name)
-        super(name, name.to_s[2..-1])
+      # @param definition [String] the rule as defined in the PSL
+      def initialize(definition, **options)
+        super(definition.to_s[2..-1], **options)
       end
 
-      # dot-split rule value and returns all rule parts
-      # in the order they appear in the value.
+      # Gets the original rule definition.
       #
-      # @return [Array<String>]
-      def parts
-        @parts ||= @value.split(".")
+      # @return [String] The rule definition.
+      def rule
+        value == "" ? STAR : STAR + DOT + value
       end
 
-      # Overwrites the default implementation to cope with
-      # the +*+ char.
+      # Decomposes the domain name according to rule properties.
       #
-      # @return [Integer] The number of parts.
-      def length
-        parts.length + 1 # * counts as 1
+      # @param  [String, #to_s] name The domain name to decompose
+      # @return [Array<String>] The array with [trd + sld, tld].
+      def decompose(domain)
+        suffix = ([".*?"] + parts).join('\.')
+        matches = domain.to_s.match(/^(.*)\.(#{suffix})$/)
+        matches ? matches[1..2] : [nil, nil]
       end
 
-      # Decomposes the domain according to rule properties.
-      #
-      # @param [String, #to_s] domain
-      #   The domain name to decompose.
+      # dot-split rule value and returns all rule parts
+      # in the order they appear in the value.
       #
       # @return [Array<String>]
-      #   The array with [trd + sld, tld].
+      def parts
+        @value.split(DOT)
+      end
+
+      # Gets the length of this rule for comparison,
+      # represented by the number of dot-separated parts in the rule
+      # plus 1 for the *.
       #
-      def decompose(domain)
-        domain.to_s.chomp(".") =~ /^(.*)\.(.*?\.#{parts.join('\.')})$/
-        [$1, $2]
+      # @return [Integer] The length of the rule.
+      def length
+        @length ||= parts.length + 1 # * counts as 1
       end
 
     end
 
+    # Exception represents an exception rule (e.g. !parliament.uk).
     class Exception < Base
 
-      # Initializes a new rule with +name+.
+      # Initializes a new rule from +definition+.
+      #
+      # The bang ! is removed from the value, as it's common
+      # for each wildcard rule.
+      #
+      # @param definition [String] the rule as defined in the PSL
+      def initialize(definition, **options)
+        super(definition.to_s[1..-1], **options)
+      end
+
+      # Gets the original rule definition.
       #
-      # @param  [String] name   The name of this rule.
+      # @return [String] The rule definition.
+      def rule
+        BANG + value
+      end
+
+      # Decomposes the domain name according to rule properties.
       #
-      def initialize(name)
-        super(name, name.to_s[1..-1])
+      # @param  [String, #to_s] name The domain name to decompose
+      # @return [Array<String>] The array with [trd + sld, tld].
+      def decompose(domain)
+        suffix = parts.join('\.')
+        matches = domain.to_s.match(/^(.*)\.(#{suffix})$/)
+        matches ? matches[1..2] : [nil, nil]
       end
 
       # dot-split rule value and returns all rule parts
@@ -329,42 +302,28 @@ module PublicSuffix
       #
       # See http://publicsuffix.org/format/:
       # If the prevailing rule is a exception rule,
-      # modify it by removing the leftmost label. 
+      # modify it by removing the leftmost label.
       #
       # @return [Array<String>]
       def parts
-        @parts ||= @value.split(".")[1..-1]
+        @value.split(DOT)[1..-1]
       end
 
-      # Decomposes the domain according to rule properties.
-      #
-      # @param [String, #to_s] domain
-      #   The domain name to decompose.
-      #
-      # @return [Array<String>]
-      #   The array with [trd + sld, tld].
+      # Gets the length of this rule for comparison,
+      # represented by the number of dot-separated parts in the rule.
       #
-      def decompose(domain)
-        domain.to_s.chomp(".") =~ /^(.*)\.(#{parts.join('\.')})$/
-        [$1, $2]
+      # @return [Integer] The length of the rule.
+      def length
+        @length ||= parts.length
       end
 
     end
 
-    RULES = {
-      '*' => Wildcard,
-      '!' => Exception
-    }
-    RULES.default = Normal
 
     # Takes the +name+ of the rule, detects the specific rule class
     # and creates a new instance of that class.
     # The +name+ becomes the rule +value+.
     #
-    # @param  [String] name The rule definition.
-    #
-    # @return [PublicSuffix::Rule::*] A rule instance.
-    #
     # @example Creates a Normal rule
     #   PublicSuffix::Rule.factory("ar")
     #   # => #<PublicSuffix::Rule::Normal>
@@ -377,8 +336,28 @@ module PublicSuffix
     #   PublicSuffix::Rule.factory("!congresodelalengua3.ar")
     #   # => #<PublicSuffix::Rule::Exception>
     #
-    def self.factory(name)
-      RULES[name.to_s[0,1]].new(name)
+    # @param  [String] content The rule content.
+    # @return [PublicSuffix::Rule::*] A rule instance.
+    def self.factory(content, **options)
+      case content.to_s[0, 1]
+      when STAR
+        Wildcard
+      when BANG
+        Exception
+      else
+        Normal
+      end.new(content, **options)
+    end
+
+    # The default rule to use if no rule match.
+    #
+    # The default rule is "*". From https://publicsuffix.org/list/:
+    #
+    # > If no rules match, the prevailing rule is "*".
+    #
+    # @return [PublicSuffix::Rule::Wildcard] The default rule.
+    def self.default
+      factory(STAR)
     end
 
   end