public_suffix_service 0.6.0 → 0.7.0

data/CHANGELOG.rdoc

@@ -1,12 +1,21 @@
 = Changelog
 
+== Release 0.7.0
+
+* CHANGED: Using YARD to document the code instead of RDoc.
+
+* FIXED: RuleList cache is not recreated when a new rule is appended to the list (#6)
+
+* FIXED: PublicSuffixService.valid? should return false if the domain is not defined or not allowed (#4, #5)
+
+
 == Release 0.6.0
 
-* ADDED: PublicSuffixService.parse raises DomainNotAllowed when trying to parse a domain name
-         which exists, but is not allowed by the current definition list (#3)
+* NEW:  PublicSuffixService.parse raises DomainNotAllowed when trying to parse a domain name
+        which exists, but is not allowed by the current definition list (#3)
 
-         PublicSuffixService.parse("nic.do")
-         # => PublicSuffixService::DomainNotAllowed
+          PublicSuffixService.parse("nic.do")
+          # => PublicSuffixService::DomainNotAllowed
 
 * CHANGED: Renamed PublicSuffixService::InvalidDomain to PublicSuffixService::DomainInvalid
 
@@ -51,11 +60,11 @@
 
 == Release 0.2.0
 
-* ADDED: DomainName#valid?
+* NEW: DomainName#valid?
 
-* ADDED: DomainName#parse and DomainName#parse!
+* NEW: DomainName#parse and DomainName#parse!
 
-* ADDED: DomainName#valid_domain? and DomainName#valid_subdomain?
+* NEW: DomainName#valid_domain? and DomainName#valid_subdomain?
 
 * CHANGED: Make sure RuleList lookup is only performed once.
 

data/Rakefile

@@ -28,13 +28,6 @@ Rake::TestTask.new do |t|
   t.verbose = true
 end
 
-# Generate documentation
-Rake::RDocTask.new do |rd|
-  rd.main = "README.rdoc"
-  rd.rdoc_files.include("*.rdoc", "lib/**/*.rb")
-  rd.rdoc_dir = "rdoc"
-end
-
 # Run test by default.
 task :default => ["test"]
 
@@ -73,7 +66,7 @@ spec = Gem::Specification.new do |s|
   # s.add_dependency("some_other_gem", "~> 0.1.0")
 
   # If your tests use any gems, include them here
-  s.add_development_dependency("mocha")
+  s.add_development_dependency("rr")
 end
 
 # This task actually builds the gem. We also regenerate a static
@@ -96,25 +89,67 @@ task :clean => [:clobber] do
 end
 
 desc "Remove any generated file"
-task :clobber => [:clobber_rdoc, :clobber_rcov, :clobber_package]
+task :clobber => [:clobber_rdoc, :clobber_package]
 
 desc "Package the library and generates the gemspec"
 task :package => [:gemspec]
 
+
+desc "Generate RDoc documentation"
+Rake::RDocTask.new do |r|
+  r.main = "README.rdoc"
+  r.rdoc_files.include("*.rdoc", "lib/**/*.rb")
+  r.rdoc_dir = "rdoc"
+end
+
+namespace :rdoc do
+  desc "Publish RDoc documentation to the site"
+  task :publish => [:clobber_rdoc, :rdoc] do
+    ENV["username"] || raise(ArgumentError, "Missing ssh username")
+    sh "rsync -avz --delete rdoc/ #{ENV["username"]}@code:/var/www/apps/code/#{PKG_NAME}/rdoc"
+  end
+end
+
+
+begin
+  require "yard"
+  require "yard/rake/yardoc_task"
+
+  YARD::Rake::YardocTask.new(:yardoc)
+
+  namespace :yardoc do
+    desc "Publish YARD documentation to the site"
+    task :publish => ["yardoc:clobber", "yardoc"] do
+      ENV["username"] || raise(ArgumentError, "Missing ssh username")
+      sh "rsync -avz --delete yardoc/ #{ENV["username"]}@code:/var/www/apps/code/#{PKG_NAME}/api"
+    end
+
+    desc "Remove YARD products"
+    task :clobber do
+      rm_r "yardoc" rescue nil
+    end
+  end
+
+  task :clobber => "yardoc:clobber"
+rescue LoadError
+  puts "YARD is not available"
+end
+
+
 begin
   require "rcov/rcovtask"
 
   desc "Create a code coverage report"
   Rcov::RcovTask.new do |t|
     t.test_files = FileList["test/**/*_test.rb"]
-    t.ruby_opts << "-Itest -x mocha,rcov,Rakefile"
+    t.ruby_opts << "-Itest -x rr,rcov,Rakefile"
     t.verbose = true
   end
 rescue LoadError
-  task :clobber_rcov
   puts "RCov is not available"
 end
 
+
 desc "Open an irb session preloaded with this library"
 task :console do
   sh "irb -rubygems -I lib -r public_suffix_service.rb"
@@ -131,11 +166,6 @@ rescue LoadError
   puts "CodeStatistics (Rails) is not available"
 end
 
-desc "Publish documentation to the site"
-task :publish_rdoc => [:clobber_rdoc, :rdoc] do
-  ENV["username"] || raise(ArgumentError, "Missing ssh username")
-  sh "rsync -avz --delete rdoc/ #{ENV["username"]}@code:/var/www/apps/code/#{PKG_NAME}/api"
-end
 
 desc <<-DESC
   Downloads the Public Suffix List file from the repository \

data/lib/public_suffix_service.rb

@@ -28,35 +28,48 @@ module PublicSuffixService
   AUTHORS         = ["Simone Carletti <weppos@weppos.net>"]
 
 
-  # Parses <tt>domain</tt> and returns the
-  # PubliSuffixService::Domain instance.
+  # Parses +domain+ and returns the
+  # {PublicSuffixService::Domain} instance.
   #
-  # domain - The String domain name to parse.
+  # Parsing uses the default {PublicSuffixService::RuleList}.
   #
-  # Examples
+  # @param  [String, #to_s] domain
+  #   The domain name to parse.
   #
+  # @return [PublicSuffixService::Domain]
+  #
+  # @example Parse a valid domain
   #   PublicSuffixService.parse("google.com")
   #   # => #<PubliSuffixService::Domain ...>
   #   
+  # @example Parse a valid subdomain
   #   PublicSuffixService.parse("www.google.com")
   #   # => #<PubliSuffixService::Domain ...>
-  #   
-  #   PublicSuffixService.parse("http://www.google.com")
-  #   # => PublicSuffixService::DomainInvalid
-  #   
+  #
+  # @example Parse an invalid domain
   #   PublicSuffixService.parse("x.yz")
   #   # => PublicSuffixService::DomainInvalid
   #
-  # Raises PublicSuffixService::Error if domain is not a valid domain
+  # @example Parse an URL (not supported, only domains)
+  #   PublicSuffixService.parse("http://www.google.com")
+  #   # => PublicSuffixService::DomainInvalid
+  #
+  # @raise [PublicSuffixService::Error]
+  #   If domain is not a valid domain.
+  # @raise [PublicSuffixService::DomainNotAllowed]
+  #   If a rule for +domain+ is found, but the rule
+  #   doesn't allow +domain+.
   #
-  # Returns the PubliSuffixService::Domain domain.
   def self.parse(domain)
-    rule = RuleList.default.find(domain) || raise(DomainInvalid, "`#{domain}' is not a valid domain")
+    rule = RuleList.default.find(domain)
+    if rule.nil?
+      raise(DomainInvalid, "`#{domain}' is not a valid domain")
+    end
+    if !rule.allow?(domain)
+      raise DomainNotAllowed, "`#{domain}' is not allowed according to Registry policy"
+    end
 
     left, right = rule.decompose(domain)
-    if right.nil?
-      raise DomainNotAllowed, "Rule `#{rule.name}' doesn't allow `#{domain}'"
-    end
 
     parts = left.split(".")
     # If we have 0 parts left, there is just a tld and no domain or subdomain
@@ -69,30 +82,42 @@ module PublicSuffixService
     Domain.new(tld, sld, trd)
   end
 
-  # Checks whether <tt>domain</tt> is a valid domain name.
+  # Checks whether +domain+ is assigned and allowed,
+  # without actually parsing it.
   #
   # This method doesn't care whether domain is a domain or subdomain.
-  # The check is performed using the default PublicSuffixService::RuleList.
+  # The check is performed using the default {PublicSuffixService::RuleList}.
   #
-  # domain - The String domain name to parse.
+  # @param  [String, #to_s] domain
+  #   The domain name to check.
   #
-  # Examples
+  # @return [Boolean]
   #
-  #   PublicSuffixService.valid?("google.com")
+  # @example Check a valid domain
+  #   PublicSuffixService.valid?("example.com")
   #   # => true
-  #   
-  #   PublicSuffixService.valid?("www.google.com")
+  #
+  # @example Check a valid subdomain
+  #   PublicSuffixService.valid?("www.example.com")
   #   # => true
-  #   
-  #   PublicSuffixService.valid?("http://www.google.com")
+  #
+  # @example Check a not-assigned domain
+  #   PublicSuffixService.valid?("example.zip")
   #   # => false
-  #   
-  #   PublicSuffixService.valid?("x.yz")
+  #
+  # @example Check a not-allowed domain
+  #   PublicSuffixService.valid?("example.do")
+  #   # => false
+  #   PublicSuffixService.valid?("www.example.do")
+  #   # => true
+  #
+  # @example Check an URL (which is not a valid domain)
+  #   PublicSuffixService.valid?("http://www.example.com")
   #   # => false
   #
-  # Returns Boolean.
   def self.valid?(domain)
-    !RuleList.default.find(domain).nil?
+    rule = RuleList.default.find(domain)
+    !rule.nil? && rule.allow?(domain)
   end
 
 end

data/lib/public_suffix_service/domain.rb

@@ -18,79 +18,127 @@ module PublicSuffixService
 
   class Domain
 
-    # Splits a string into its possible labels as a domain in reverse order
-    # from the input string.
+    # 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.
     #
-    # domain - The String domain to be split.
+    # @param  [String, #to_s] domain
+    #   The domain name to split.
+    #
+    # @return [Array<String>]
     #
-    # Examples
+    # @example
     #
-    #   domain_to_labels('google.com.uk')
-    #   # => ['uk', 'com', 'google']
+    #   domain_to_labels('google.com')
+    #   # => ['com', 'google']
+    #
+    #   domain_to_labels('google.co.uk')
+    #   # => ['uk', 'co', 'google']
     #
-    # Returns an Array of String representing the possible labels.
     def self.domain_to_labels(domain)
       domain.to_s.split(".").reverse
     end
 
+    # Creates and returns a new {PublicSuffixService::Domain} instance.
+    #
+    # @overload initialize(tld)
+    #   Initializes with a +tld+.
+    #   @param [String] tld The TLD (extension)
+    # @overload initialize(tld, sld)
+    #   Initializes with a +tld+ and +sld+.
+    #   @param [String] tld The TLD (extension)
+    #   @param [String] sld The TRD (domain)
+    # @overload initialize(tld, sld, trd)
+    #   Initializes with a +tld+, +sld+ and +trd+.
+    #   @param [String] tld The TLD (extension)
+    #   @param [String] sld The SLD (domain)
+    #   @param [String] tld The TRD (subdomain)
+    #
+    # @yield [self] Yields on self.
+    # @yieldparam [PublicSuffixService::Domain] self The newly creates instance
+    #
+    # @example Initialize with a TLD
+    #   PublicSuffixService::Domain.new("com")
+    #   # => #<PublicSuffixService::Domain @tld="com">
+    #
+    # @example Initialize with a TLD and SLD
+    #   PublicSuffixService::Domain.new("com", "example")
+    #   # => #<PublicSuffixService::Domain @tld="com", @trd=nil>
+    #
+    # @example Initialize with a TLD, SLD and TRD
+    #   PublicSuffixService::Domain.new("com", "example", "wwww")
+    #   # => #<PublicSuffixService::Domain @tld="com", @trd=nil, @sld="example">
+    #
     def initialize(*args, &block)
       @tld, @sld, @trd = args
       yield(self) if block_given?
     end
 
-    # Gets a String representation of this object.
+    # Returns a string representation of this object.
     #
-    # Returns a String with the domain name.
+    # @return [String]
     def to_s
       name
     end
 
+    # Returns an array containing the domain parts.
+    #
+    # @return [Array<String, nil>]
+    #
+    # @example
+    #
+    #   PublicSuffixService::Domain.new("google.com").to_a
+    #   # => [nil, "google", "com"]
+    #
+    #   PublicSuffixService::Domain.new("www.google.com").to_a
+    #   # => [nil, "google", "com"]
+    #
     def to_a
       [trd, sld, tld]
     end
 
 
-    # Gets the Top Level Domain part, aka the extension.
+    # Returns the Top Level Domain part, aka the extension.
     #
-    # Returns a String if tld is set, nil otherwise.
+    # @return [String, nil]
     def tld
       @tld
     end
 
-    # Gets the Second Level Domain part, aka the domain part.
+    # Returns the Second Level Domain part, aka the domain part.
     #
-    # Returns a String if sld is set, nil otherwise.
+    # @return [String, nil]
     def sld
       @sld
     end
 
-    # Gets the Third Level Domain part, aka the subdomain part.
+    # Returns the Third Level Domain part, aka the subdomain part.
     #
-    # Returns a String if trd is set, nil otherwise.
+    # @return [String, nil]
     def trd
       @trd
     end
 
 
-    # Gets the domain name.
+    # Returns the full domain name.
     #
-    # Examples
+    # @return [String]
     #
+    # @example Gets the domain name of a domain
     #   PublicSuffixService::Domain.new("com", "google").name
     #   # => "google.com"
     #
+    # @example Gets the domain name of a subdomain
     #   PublicSuffixService::Domain.new("com", "google", "www").name
     #   # => "www.google.com"
     #
-    # Returns a String with the domain name.
     def name
       [trd, sld, tld].reject { |part| part.nil? }.join(".")
     end
 
     # Returns a domain-like representation of this object
-    # if the object is a <tt>domain?</tt>,
-    # <tt>nil</tt> otherwise.
+    # if the object is a {#domain?}, <tt>nil</tt> otherwise.
     #
     #   PublicSuffixService::Domain.new("com").domain
     #   # => nil
@@ -117,15 +165,18 @@ module PublicSuffixService
     #   PublicSuffixService::Domain.new("com", "google", "www").sld
     #   # => "google"
     #
-    # Returns a String or nil.
+    # @return [String]
+    #
+    # @see #domain?
+    # @see #subdomain
+    #
     def domain
       return unless domain?
       [sld, tld].join(".")
     end
 
     # Returns a domain-like representation of this object
-    # if the object is a <tt>subdomain?</tt>,
-    # <tt>nil</tt> otherwise.
+    # if the object is a {#subdomain?}, <tt>nil</tt> otherwise.
     #
     #   PublicSuffixService::Domain.new("com").subdomain
     #   # => nil
@@ -152,17 +203,22 @@ module PublicSuffixService
     #   PublicSuffixService::Domain.new("com", "google", "www").trd
     #   # => "www"
     #
-    # Returns a String or nil.
+    # @return [String]
+    #
+    # @see #subdomain?
+    # @see #domain
+    #
     def subdomain
       return unless subdomain?
       [trd, sld, tld].join(".")
     end
 
-    # Gets the rule matching this domain
-    # in the default PublicSuffixService::RuleList.
+    # Returns the rule matching this domain
+    # in the default {PublicSuffixService::RuleList}.
     #
-    # Returns the PublicSuffixService::Rule::Base instance
-    # if a rule matches current domain, nil if no rule is found.
+    # @return [PublicSuffixService::Rule::Base, nil]
+    #   The rule instance a rule matches current domain,
+    #   nil if no rule is found.
     def rule
       RuleList.default.find(name)
     end
@@ -172,11 +228,13 @@ module PublicSuffixService
     #
     # This method doesn't actually validate the domain.
     # It only checks whether the instance contains
-    # a value for the <tt>tld</tt> and <tt>sld</tt> attributes.
+    # a value for the {#tld} and {#sld} attributes.
     # If you also want to validate the domain,
-    # use <tt>#valid_domain?</tt> instead.
+    # use {#valid_domain?} instead.
+    #
+    # @return [Boolean]
     #
-    # Examples
+    # @example
     #
     #   PublicSuffixService::Domain.new("com").domain?
     #   # => false
@@ -192,7 +250,8 @@ module PublicSuffixService
     #   PublicSuffixService::Domain.new("zip", "google").domain?
     #   # => true
     #
-    # Returns Boolean.
+    # @see #subdomain?
+    #
     def domain?
       !(tld.nil? || sld.nil?)
     end
@@ -201,11 +260,13 @@ module PublicSuffixService
     #
     # This method doesn't actually validate the subdomain.
     # It only checks whether the instance contains
-    # a value for the <tt>tld</tt>, <tt>sld</tt> and <tt>trd</tt> attributes.
+    # a value for the {#tld}, {#sld} and {#trd} attributes.
     # If you also want to validate the domain,
-    # use <tt>#valid_subdomain?</tt> instead.
+    # use {#valid_subdomain?} instead.
     #
-    # Examples
+    # @return [Boolean]
+    #
+    # @example
     #
     #   PublicSuffixService::Domain.new("com").subdomain?
     #   # => false
@@ -221,7 +282,8 @@ module PublicSuffixService
     #   PublicSuffixService::Domain.new("zip", "google", "www").subdomain?
     #   # => true
     #
-    # Returns Boolean.
+    # @see #domain?
+    #
     def subdomain?
       !(tld.nil? || sld.nil? || trd.nil?)
     end
@@ -229,35 +291,56 @@ module PublicSuffixService
     # Checks whether <tt>self</tt> is exclusively a domain,
     # and not a subdomain.
     #
-    # Returns Boolean.
+    # @return [Boolean]
     def is_a_domain?
       domain? && !subdomain?
     end
 
     # Checks whether <tt>self</tt> is exclusively a subdomain.
     #
-    # Returns Boolean.
+    # @return [Boolean]
     def is_a_subdomain?
       subdomain?
     end
 
-    # Checks whether <tt>self</tt> is valid
-    # according to default <tt>RuleList</tt>.
+    # Checks whether <tt>self</tt> is assigned and allowed
+    # according to default {RuleList}.
     #
-    # Note: this method triggers a new rule lookup in the default RuleList,
+    # This method triggers a new rule lookup in the default {RuleList},
     # which is a quite intensive task.
     #
-    # Returns Boolean.
+    # @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("zip", "example").valid?
+    #   # => false
+    #
+    # @example Check a not-allowed domain
+    #   Domain.new("do", "example").valid?
+    #   # => false
+    #   Domain.new("do", "example", "www").valid?
+    #   # => true
+    #
     def valid?
-      !rule.nil?
+      r = rule
+      !r.nil? && r.allow?(name)
     end
 
+
     # Checks whether <tt>self</tt> looks like a domain and validates
-    # according to default <tt>RuleList</tt>.
+    # according to default {RuleList}.
     #
-    # See also <tt>#domain?</tt> and <tt>#valid?</tt>.
+    # @return [Boolean]
     #
-    # Examples
+    # @example
     #
     #   PublicSuffixService::Domain.new("com").domain?
     #   # => false
@@ -272,17 +355,19 @@ module PublicSuffixService
     #   PublicSuffixService::Domain.new("zip", "google").false?
     #   # => true
     #
-    # Returns true if this instance looks like a domain and is valid.
+    # @see #domain?
+    # @see #valid?
+    #
     def valid_domain?
       domain? && valid?
     end
 
     # Checks whether <tt>self</tt> looks like a subdomain and validates
-    # according to default <tt>RuleList</tt>.
+    # according to default {RuleList}.
     #
-    # See also <tt>#subdomain?</tt> and <tt>#valid?</tt>.
+    # @return [Boolean]
     #
-    # Examples
+    # @example
     #
     #   PublicSuffixService::Domain.new("com").subdomain?
     #   # => false
@@ -297,7 +382,9 @@ module PublicSuffixService
     #   PublicSuffixService::Domain.new("zip", "google", "www").subdomain?
     #   # => false
     #
-    # Returns true if this instance looks like a domain and is valid.
+    # @see #subdomain?
+    # @see #valid?
+    #
     def valid_subdomain?
       subdomain? && valid?
     end