sitemap_generator 1.5.2 → 2.0.0

data/VERSION

@@ -1 +1 @@
-1.5.2
+2.0.0

data/lib/sitemap_generator.rb

@@ -1,5 +1,5 @@
-require 'sitemap_generator/builder'
 require 'sitemap_generator/sitemap_namer'
+require 'sitemap_generator/builder'
 require 'sitemap_generator/link_set'
 require 'sitemap_generator/templates'
 require 'sitemap_generator/utilities'
@@ -8,6 +8,8 @@ require 'sitemap_generator/sitemap_location'
 require 'active_support/core_ext/numeric'
 
 module SitemapGenerator
+  autoload(:Interpreter, 'sitemap_generator/interpreter')
+
   SitemapError = Class.new(StandardError)
   SitemapFullError = Class.new(SitemapError)
   SitemapFinalizedError = Class.new(SitemapError)
@@ -22,13 +24,24 @@ module SitemapGenerator
     # Lazy-initialize the LinkSet instance
     Sitemap = (Class.new do
       def method_missing(*args, &block)
-        (@link_set ||= LinkSet.new).send(*args, &block)
+        (@link_set ||= reset!).send(*args, &block)
+      end
+
+      # Use a new LinkSet instance
+      def reset!
+        @link_set = LinkSet.new
       end
     end).new
   end
 
   class << self
     attr_accessor :root, :app, :templates
+    attr_writer :yield_sitemap
+  end
+
+  # Returns true if we should yield the sitemap instance to the block, false otherwise.
+  def self.yield_sitemap?
+    !!@yeild_sitemap
   end
 
   self.root = File.expand_path(File.join(File.dirname(__FILE__), '../'))

data/lib/sitemap_generator/builder/sitemap_file.rb

@@ -14,21 +14,14 @@ module SitemapGenerator
     class SitemapFile
       include ActionView::Helpers::NumberHelper
       include ActionView::Helpers::TextHelper   # Rails 2.2.2 fails with missing 'pluralize' otherwise
-      attr_reader :link_count, :filesize, :filename, :location
+      attr_reader :link_count, :filesize, :location
 
-      # Options:
+      # === Options
       #
-      # <tt>location</tt> a SitemapGenerator::SitemapLocation instance
-      #
-      # <tt>filename</tt> a symbol giving the base of the sitemap fileaname.  Default: :sitemap
-      #
-      # <tt>namer</tt> (optional) if provided is used to get the next sitemap filename, overriding :filename
+      # * <tt>location</tt> - a SitemapGenerator::SitemapLocation instance or a Hash of options
+      #   from which a SitemapLocation will be created for you.
       def initialize(opts={})
-        SitemapGenerator::Utilities.assert_valid_keys(opts, [:location, :filename, :namer])
-
-        @location = opts.delete(:location) || SitemapGenerator::SitemapLocation.new
-        @namer = opts.delete(:namer) || new_namer(opts.delete(:filename))
-        @filename = @location[:filename] = @namer.next
+        @location = opts.is_a?(Hash) ? SitemapGenerator::SitemapLocation.new(opts) : opts
         @link_count = 0
         @xml_content = '' # XML urlset content
         @xml_wrapper_start = <<-HTML
@@ -102,20 +95,25 @@ module SitemapGenerator
 
         # Ensure that the directory exists
         dir = @location.directory
-        path = @location.path
         if !File.exists?(dir)
           FileUtils.mkdir_p(dir)
         elsif !File.directory?(dir)
           raise SitemapError.new("#{dir} should be a directory!")
         end
 
-        open(path, 'wb') do |file|
+        # Write out the file
+        open(@location.path, 'wb') do |file|
           gz = Zlib::GzipWriter.new(file)
           gz.write @xml_wrapper_start
           gz.write @xml_content
           gz.write @xml_wrapper_end
           gz.close
         end
+
+        # Increment the namer (SitemapFile only)
+        @location.namer.next if @location.namer
+
+        # Cleanup and freeze the object
         @xml_content = @xml_wrapper_start = @xml_wrapper_end = ''
         freeze
       end
@@ -125,8 +123,10 @@ module SitemapGenerator
       end
 
       # Return a new instance of the sitemap file with the same options, and the next name in the sequence.
-      def next
-        self.class.new(:location => @location.dup, :namer => @namer)
+      def new
+        location = @location.dup
+        location.delete(:filename) if location.namer
+        self.class.new(location)
       end
 
       # Return a summary string
@@ -136,26 +136,12 @@ module SitemapGenerator
         "+ #{'%-21s' % @location.path_in_public} #{'%13s' % @link_count} links / #{'%10s' % uncompressed_size} / #{'%10s' % compressed_size} gzipped"
       end
 
-      # Create a new namer given a filename base and set the filename of this sitemap from it.
-      # It is a bit confusing because the setter takes a filename base whereas the getter
-      # returns a full filename including extension.
-      def filename=(base)
-        @namer = new_namer(base)
-        @filename = @location[:filename] = @namer.next
-      end
-
       protected
 
-      # Return a new namer given a filename base and set the filename of this sitemap from it.
-      # Default filename base is 'sitemap'.
-      def new_namer(base=nil)
-        SitemapGenerator::SitemapNamer.new(base ||= :sitemap)
-      end
-
       # Return the bytesize length of the string.  Ruby 1.8.6 compatible.
       def bytesize(string)
         string.respond_to?(:bytesize) ? string.bytesize : string.length
       end
     end
   end
-end
+end

data/lib/sitemap_generator/builder/sitemap_index_file.rb

@@ -1,16 +1,13 @@
 module SitemapGenerator
   module Builder
     class SitemapIndexFile < SitemapFile
-      attr_accessor :sitemaps
 
+      # === Options
+      #
+      # * <tt>location</tt> - a SitemapGenerator::SitemapIndexLocation instance or a Hash of options
+      #   from which a SitemapLocation will be created for you.
       def initialize(opts={})
-        @options = [:location, :filename]
-        SitemapGenerator::Utilities.assert_valid_keys(opts, @options)
-
-        @location = opts.delete(:location) || SitemapGenerator::SitemapLocation.new
-        @filename = "#{opts.fetch(:filename, :sitemap_index)}.xml.gz"
-        @location[:filename] = @filename
-        
+        @location = opts.is_a?(Hash) ? SitemapGenerator::SitemapIndexLocation.new(opts) : opts
         @link_count = 0
         @sitemaps_link_count = 0
         @xml_content = '' # XML urlset content
@@ -37,16 +34,19 @@ module SitemapGenerator
         super(SitemapGenerator::Builder::SitemapIndexUrl.new(link, options))
       end
 
+      # Return a boolean indicating whether the sitemap file can fit another link
+      # of <tt>bytes</tt> bytes in size.  You can also pass a string and the
+      # bytesize will be calculated for you.
+      def file_can_fit?(bytes)
+        bytes = bytes.is_a?(String) ? bytesize(bytes) : bytes
+        (@filesize + bytes) < SitemapGenerator::MAX_SITEMAP_FILESIZE && @link_count < SitemapGenerator::MAX_SITEMAP_FILES
+      end
+
       # Return the total number of links in all sitemaps reference by this index file
       def total_link_count
         @sitemaps_link_count
       end
 
-      # Set a new filename on the instance.  Should not include any extensions e.g. :sitemap_index
-      def filename=(filename)
-        @filename = @location[:filename] = "#{filename}_index.xml.gz"
-      end
-
       # Return a summary string
       def summary(opts={})
         uncompressed_size = number_to_human_size(@filesize) rescue "#{@filesize / 8} KB"
@@ -60,4 +60,4 @@ module SitemapGenerator
       end
     end
   end
-end
+end

data/lib/sitemap_generator/interpreter.rb

@@ -2,8 +2,8 @@ require 'sitemap_generator'
 
 module SitemapGenerator
 
-  # Evaluate a sitemap config file within the context of a class that includes the
-  # Rails URL helpers.
+  # Provide a class for evaluating blocks, making the URL helpers from the framework
+  # and API methods available to it.
   class Interpreter
 
     if SitemapGenerator.app.rails3?
@@ -16,26 +16,54 @@ module SitemapGenerator
     # Call with a block to evaluate a dynamic config.  The only method exposed for you is
     # `add` to add a link to the sitemap object attached to this interpreter.
     #
-    # @param sitemap a sitemap object
-    # @param sitemap_config_file full path to the config file (default is config/sitemap.rb)
-    def initialize(sitemap, sitemap_config_file=nil, &block)
-      @sitemap = sitemap
-      if block_given?
-        instance_eval(&block)
-      else
-        sitemap_config_file ||= SitemapGenerator.app.root + 'config/sitemap.rb'
-        eval(File.read(sitemap_config_file), nil, sitemap_config_file.to_s)
-      end
+    # === Options
+    # * <tt>link_set</tt> - a LinkSet instance to use.  Default is SitemapGenerator::Sitemap.
+    #
+    # All other options are passed to the LinkSet by setting them using accessor methods.
+    def initialize(opts={}, &block)
+      opts.reverse_merge!(:link_set => SitemapGenerator::Sitemap)
+      @linkset = opts.delete :link_set
+      @linkset.send(:set_options, opts)
+      eval(&block) if block_given?
     end
 
     def add(*args)
-      @sitemap.add(*args)
+      @linkset.add(*args)
+    end
+
+    # Start a new group of sitemaps.  Any of the options to SitemapGenerator.new may
+    # be passed.  Pass a block with calls to +add+ to add links to the sitemaps.
+    #
+    # All groups use the same sitemap index.
+    def group(*args, &block)
+      @linkset.group(*args, &block)
     end
 
-    # Evaluate the sitemap config file in this namespace which includes the
-    # URL helpers.
-    def self.run
-      new(SitemapGenerator::Sitemap)
+    # Evaluate the block in the interpreter.  Pass :yield_sitemap => true to
+    # yield the Interpreter instance to the block...for old-style calling.
+    def eval(opts={}, &block)
+      if block_given?
+        if opts[:yield_sitemap]
+          yield self
+        else
+          instance_eval(&block)
+        end
+      end
+    end
+
+    # Run the interpreter on a config file using
+    # the default <tt>SitemapGenerator::Sitemap</tt> sitemap object.
+    #
+    # === Options
+    # * <tt>:config_file</tt> - full path to the config file to evaluate.
+    #   Default is config/sitemap.rb in your application's root directory.
+    # All other options are passed to +new+.
+    def self.run(opts={}, &block)
+      config_file = opts.delete(:config_file)
+      config_file ||= SitemapGenerator.app.root + 'config/sitemap.rb'
+      interpreter = self.new(opts)
+      interpreter.instance_eval(File.read(config_file), config_file.to_s)
+      interpreter
     end
   end
-end
+end

data/lib/sitemap_generator/link_set.rb

@@ -4,100 +4,90 @@ require 'builder'
 # which lists all the sitemap files written.
 module SitemapGenerator
   class LinkSet
+    @@requires_finalization_opts = [:filename, :sitemaps_path, :sitemaps_namer, :sitemaps_host]
+    @@new_location_opts = [:filename, :sitemaps_path, :sitemaps_namer]
 
-    attr_reader :default_host, :public_path, :sitemaps_path, :filename, :sitemap, :location
-    attr_accessor :verbose, :yahoo_app_id, :include_root, :include_index
+    attr_reader :default_host, :sitemaps_path, :filename
+    attr_accessor :verbose, :yahoo_app_id, :include_root, :include_index, :sitemaps_host
 
-    # Evaluate the sitemap config file and write all sitemaps.
+    # Add links to the link set by evaluating the block.  The block should
+    # contains calls to sitemap methods like:
+    # * +add+   - Add a link to the current sitemap
+    # * +group+ - Start a new group of sitemaps
     #
-    # The Sitemap Interpreter includes the URL helpers and API methods
-    # that the block argument to `add_links` is evaluted within.
+    # == Options
     #
-    # TODO: Refactor so that we can have multiple instances
-    # of LinkSet.
-    def create(config_file = 'config/sitemap.rb', &block)
-      require 'sitemap_generator/interpreter'
-
-      # Clear out the current objects.  New objects will be lazy-initialized.
-      @sitemap_index = @sitemap = nil
-
-      start_time = Time.now
-      SitemapGenerator::Interpreter.new(self, config_file, &block)
-      finalize_sitemap
-      finalize_sitemap_index
-      end_time = Time.now
+    # Any option supported by +new+ can be passed.  The options will be
+    # set on the instance using the accessor methods.  This is provided mostly
+    # as a convenience.
+    #
+    # In addition to the options to +new+, the following options are supported:
+    # * <tt>:finalize</tt> - The sitemaps are written as they get full and at the end
+    # of the block.  Pass +false+ as the value to prevent the sitemap or sitemap index
+    # from being finalized.  Default is +true+.
+    def create(opts={}, &block)
+      @sitemap_index = nil if @sitemap_index && @sitemap_index.finalized? && !@protect_index
+      @sitemap = nil if @sitemap && @sitemap.finalized?
+      set_options(opts)
+      start_time = Time.now if @verbose
+      interpreter.eval(:yield_sitemap => @yield_sitemap || SitemapGenerator.yield_sitemap?, &block)
+      finalize!
+      end_time = Time.now if @verbose
+      puts sitemap_index.stats_summary(:time_taken => end_time - start_time) if @verbose
+      self
+    end
 
-      puts sitemap_index.stats_summary(:time_taken => end_time - start_time) if verbose
+    # Dreprecated.  Use create.
+    def add_links(&block)
+      @yield_sitemap = true
+      create(&block)
+      @yield_sitemap = false
     end
 
     # Constructor
     #
-    # Call with a hash of options.  Options:
+    # == Options:
+    # * <tt>:default_host</tt> - host including protocol to use in all sitemap links
+    #   e.g. http://en.google.ca
     #
-    # <tt>public_path</tt> full path to the directory to write sitemaps in.
-    #   Defaults to your Rails <tt>public/</tt> directory.
+    # * <tt>:public_path</tt> - Full or relative path to the directory to write sitemaps into.
+    #   Defaults to the <tt>public/</tt> directory in your application root directory or
+    #   the current working directory.
     #
-    # <tt>sitemaps_path</tt> path fragment within public to write sitemaps
+    # * <tt>:sitemaps_host</tt> - host (including protocol) to use in links to the sitemaps.  Useful if your sitemaps
+    #   are hosted o different server e.g. 'http://amazon.aws.com/'
+    #
+    # * <tt>:sitemaps_path</tt> - path fragment within public to write sitemaps
     #   to e.g. 'en/'.  Sitemaps are written to <tt>public_path</tt> + <tt>sitemaps_path</tt>
     #
-    # <tt>default_host</tt> host including protocol to use in all sitemap links
-    #   e.g. http://en.google.ca
+    # * <tt>:filename</tt> - symbol giving the base name for files (default <tt>:sitemap</tt>).
+    #   The sitemap names are generated like "#{filename}1.xml.gz", "#{filename}2.xml.gz"
+    #   and the index name is like "#{filename}_index.xml.gz".
     #
-    # <tt>filename</tt> symbol giving the base name for files (default <tt>:sitemap</tt>).
-    #   The sitemap names are generated like "#{@filename}1.xml.gzip", "#{@filename}2.xml.gzip"
-    #   and the index name is like "#{@filename}_index.xml.gzip".
+    # * <tt>:sitemaps_namer</tt> - A +SitemapNamer+ instance for generating the sitemap names.
     #
-    # <tt>include_root</tt> whether to include the root url i.e. '/' in each group of sitemaps.
-    #   Default is false.
+    # * <tt>:include_root</tt> - whether to include the root url i.e. '/' in each group of sitemaps.
+    #   Default is true.
     #
-    # <tt>include_index</tt> whether to include the sitemap index URL in each group of sitemaps.
-    #   Default is false.
-    def initialize(*args)
-
-      # Extract options
-      options = if (!args.first.nil? && !args.first.is_a?(Hash)) || args.size > 1
-        warn "Deprecated. Please call with an options hash instead."
-        [:public_path, :sitemaps_path, :default_host, :filename].each_with_index.inject({}) do |hash, arg|
-          hash[arg[0]] = args[arg[1]]
-          hash
-        end
-      else
-        args.first || {}
-      end
-
-      # Option defaults
+    # * <tt>:include_index</tt> - whether to include the sitemap index URL in each group of sitemaps.
+    #   Default is true.
+    #
+    # * <tt>:verbose</tt> - If +true+, output a summary line for each sitemap and sitemap
+    #   index that is created.  Default is +false+.
+    def initialize(options={})
       options.reverse_merge!({
         :include_root => true,
         :include_index => true,
         :filename => :sitemap,
-        :public_path => SitemapGenerator.app.root + 'public/',
-        :sitemaps_path => nil
+        :verbose => false
       })
       options.each_pair { |k, v| instance_variable_set("@#{k}".to_sym, v) }
 
-
-      # Create a location object to store all the location options
-      @location = SitemapGenerator::SitemapLocation.new(
-        :sitemaps_path => @sitemaps_path,
-        :public_path => @public_path,
-        :host => @default_host
-      )
-    end
-
-    # Entry point for users.
-    #
-    # Called within the user's eval'ed sitemap config file.  Add links to sitemap files
-    # passing a block.  This instance is passed in as an argument.  You can call
-    # `add` on it to add links.
-    #
-    # Example:
-    #   add_links do |sitemap|
-    #     sitemap.add '/'
-    #   end
-    def add_links
-      sitemap.add('/', :lastmod => Time.now, :changefreq => 'always', :priority => 1.0, :host => @location.host) if include_root
-      sitemap.add(sitemap_index, :lastmod => Time.now, :changefreq => 'always', :priority => 1.0) if include_index
-      yield self
+      # If an index is passed in, protect it from modification.
+      # Sitemaps can be added to the index but nothing else can be changed.
+      if options[:sitemap_index]
+        @protect_index = true
+      end
     end
 
     # Add a link to a Sitemap.  If a new Sitemap is required, one will be created for
@@ -107,15 +97,69 @@ module SitemapGenerator
     # options - see README.
     #   host - host for the link, defaults to your <tt>default_host</tt>.
     def add(link, options={})
-      sitemap.add(link, options.reverse_merge!(:host => @location.host))
+      add_default_links if !@added_default_links
+      sitemap.add(link, options.reverse_merge!(:host => @default_host))
     rescue SitemapGenerator::SitemapFullError
-      finalize_sitemap
+      finalize_sitemap!
       retry
     rescue SitemapGenerator::SitemapFinalizedError
-      @sitemap = sitemap.next
+      @sitemap = sitemap.new
       retry
     end
 
+    # Create a new group of sitemaps.  Returns a new LinkSet instance with options set on it.
+    #
+    # All groups share this LinkSet's sitemap index, which is not modified by any of the options
+    # passed to +group+.
+    #
+    # === Options
+    # Any of the options to LinkSet.new.  Except for <tt>:public_path</tt> which is shared
+    # by all groups.
+    #
+    # The current options are inherited by the new group of sitemaps.  The only exceptions
+    # being <tt>:include_index</tt> and <tt>:include_root</tt> which default to +false+.
+    #
+    # Pass a block to add links to the new LinkSet.  If you pass a block the sitemaps will
+    # be finalized when the block returns.
+    #
+    # If you are not changing any of the location settings like <tt>filename<tt>,
+    # <tt>sitemaps_path</tt>, <tt>sitemaps_host</tt> or <tt>sitemaps_namer</tt>
+    # the current sitemap will be used in the group.  All of the options you have
+    # specified which affect the way the links are generated will still be applied
+    # for the duration of the group.
+    def group(opts={}, &block)
+      @created_group = true
+      original_opts = opts.dup
+
+      if (@@requires_finalization_opts & original_opts.keys).empty?
+        # If no new filename or path is specified reuse the default sitemap file.
+        # A new location object will be set on it for the duration of the group.
+        opts[:sitemap] = sitemap
+      elsif original_opts.key?(:sitemaps_host) && (@@new_location_opts & original_opts.keys).empty?
+        # If no location options are provided we are creating the next sitemap in the
+        # current series, so finalize and inherit the namer.
+        finalize_sitemap!
+        opts[:sitemaps_namer] = sitemaps_namer
+      end
+
+      opts = options_for_group(opts)
+      @group = SitemapGenerator::LinkSet.new(opts)
+      if opts.key?(:sitemap)
+        # If the group is sharing the current sitemap, set the
+        # new location options on the location object.
+        @original_location = @sitemap.location.dup
+        @sitemap.location.merge!(@group.sitemap_location)
+        if block_given?
+          @group.interpreter.eval(:yield_sitemap => @yield_sitemap || SitemapGenerator.yield_sitemap?, &block)
+          @sitemap.location.merge!(@original_location)
+        end
+      elsif block_given?
+        @group.interpreter.eval(:yield_sitemap => @yield_sitemap || SitemapGenerator.yield_sitemap?, &block)
+        @group.finalize_sitemap!
+      end
+      @group
+    end
+
     # Ping search engines.
     #
     # @see http://en.wikipedia.org/wiki/Sitemap_index
@@ -135,7 +179,9 @@ module SitemapGenerator
       search_engines.each do |engine, link|
         next if engine == :yahoo && !self.yahoo_app_id
         begin
-          open(link)
+          Timeout::timeout(10) {
+            open(link)
+          }
           puts "Successful ping of #{engine.to_s.titleize}" if verbose
         rescue Timeout::Error, StandardError => e
           puts "Ping failed for #{engine.to_s.titleize}: #{e.inspect} (URL #{link})" if verbose
@@ -159,84 +205,218 @@ module SitemapGenerator
       sitemap_index.total_link_count
     end
 
-    # Set the host name, including protocol, that will be used by default on each
-    # of your sitemap links.  You can pass a different host in your options to `add`
-    # if you need to change it on a per-link basis.
-    def default_host=(value)
-      update_location_info(:host, value)
+    # Return the host to use in links to the sitemap files.  This defaults to your
+    # +default_host+.
+    def sitemaps_host
+      @sitemaps_host || @default_host
     end
 
-    # Set the public_path.  This path gives the location of your public directory.
-    # The default is the public/ directory in your Rails root.  Or if Rails is not
-    # found, it defaults to public/ in the current directory (of the process).
-    #
-    # Example: 'tmp/' if you don't want to generate in public for some reason.
-    #
-    # Set to nil to use the current directory.
-    def public_path=(value)
-      update_location_info(:public_path, value)
+    # Lazy-initialize a sitemap instance when it's accessed
+    def sitemap
+      @sitemap ||= SitemapGenerator::Builder::SitemapFile.new(sitemap_location)
     end
 
-    # Set the sitemaps_path.  This path gives the location to write sitemaps to
-    # relative to your public_path.
-    # Example: 'sitemaps/' to generate your sitemaps in 'public/sitemaps/'.
-    def sitemaps_path=(value)
-      update_location_info(:sitemaps_path, value)
+    # Lazy-initialize a sitemap index instance when it's accessed
+    def sitemap_index
+      @sitemap_index ||= SitemapGenerator::Builder::SitemapIndexFile.new(sitemap_index_location)
     end
 
-    # Set the filename base to use when generating sitemaps and sitemap indexes.
-    def filename=(value)
-      @filename = value
-      update_sitemap_info(:filename, value)
+    def finalize!
+      finalize_sitemap!
+      finalize_sitemap_index!
     end
 
-    # Lazy-initialize a sitemap instance when it's accessed
-    def sitemap
-      @sitemap ||= SitemapGenerator::Builder::SitemapFile.new(
-        :location => @location.dup,
-        :filename => @filename
-      )
+    protected
+
+    # Set each option on this instance using accessor methods.  This will affect
+    # both the sitemap and the sitemap index.
+    def set_options(opts={})
+      opts.each_pair do |key, value|
+        send("#{key}=", value)
+      end
     end
 
-    # Lazy-initialize a sitemap index instance when it's accessed
-    def sitemap_index
-      @sitemap_index ||= SitemapGenerator::Builder::SitemapIndexFile.new(
-        :location => @location.dup,
-        :filename => "#{@filename}_index"
+    # Given +opts+, return a hash of options prepped for creating a new group from this LinkSet.
+    # If <tt>:public_path</tt> is present in +opts+ it is removed because groups cannot
+    # change the public path.
+    def options_for_group(opts)
+      opts.delete(:public_path)
+      opts.reverse_merge!(
+        :include_index => false,
+        :include_root => false,
+        :sitemap_index => sitemap_index
       )
+
+      # Reverse merge the current settings
+      current_settings = [
+        :include_root,
+        :include_index,
+        :sitemaps_path,
+        :public_path,
+        :sitemaps_host,
+        :verbose,
+        :default_host
+      ].inject({}) do |hash, key|
+        if value = instance_variable_get(:"@#{key}")
+          hash[key] = value
+        end
+        hash
+      end
+      opts.reverse_merge!(current_settings)
+      opts
     end
 
-    protected
+    # Add default links if those options are turned on.  Record the fact that we have done so
+    # in an instance variable.
+    def add_default_links
+      sitemap.add('/', :lastmod => Time.now, :changefreq => 'always', :priority => 1.0, :host => @default_host) if include_root
+      sitemap.add(sitemap_index, :lastmod => Time.now, :changefreq => 'always', :priority => 1.0) if include_index
+      @added_default_links = true
+    end
 
     # Finalize a sitemap by including it in the index and outputting a summary line.
     # Do nothing if it has already been finalized.
-    def finalize_sitemap
-      return if sitemap.finalized?
+    #
+    # Don't finalize if the sitemap is empty and a group has been created.  The reason
+    # being that the group will have written out its sitemap.
+    #
+    # Add the default links if they have not been added yet and no groups have been created.
+    # If the default links haven't been added we know that the sitemap is empty,
+    # because they are added on the first call to add().  This ensure that if the
+    # block passed to create() is empty the default links are still included in the
+    # sitemap.
+    def finalize_sitemap!
+      add_default_links if !@added_default_links && !@created_group
+      return if sitemap.finalized? || sitemap.empty? && @created_group
       sitemap_index.add(sitemap)
       puts sitemap.summary if verbose
     end
 
     # Finalize a sitemap index and output a summary line.  Do nothing if it has already
     # been finalized.
-    def finalize_sitemap_index
-      return if sitemap_index.finalized?
+    def finalize_sitemap_index!
+      return if @protect_index || sitemap_index.finalized?
       sitemap_index.finalize!
       puts sitemap_index.summary if verbose
     end
 
-    # Update the given attribute on the current sitemap index and sitemap files.  But
-    # don't create the index or sitemap files yet if they are not already created.
-    def update_sitemap_info(attribute, value)
-      sitemap_index.send("#{attribute}=", value) if @sitemap_index && !@sitemap_index.finalized?
-      sitemap.send("#{attribute}=", value) if @sitemap && !@sitemap.finalized?
+    # Return the interpreter linked to this instance.
+    def interpreter
+      require 'sitemap_generator/interpreter'
+      @interpreter ||= SitemapGenerator::Interpreter.new(:link_set => self)
     end
 
-    # Update the given attribute on the current sitemap index and sitemap file location objects.
-    # But don't create the index or sitemap files yet if they are not already created.
-    def update_location_info(attribute, value)
-      @location.merge!(attribute => value)
-      sitemap_index.location.merge!(attribute => value) if @sitemap_index && !@sitemap_index.finalized?
-      sitemap.location.merge!(attribute => value) if @sitemap && !@sitemap.finalized?
+    module LocationHelpers
+      public
+
+      # Set the host name, including protocol, that will be used by default on each
+      # of your sitemap links.  You can pass a different host in your options to `add`
+      # if you need to change it on a per-link basis.
+      def default_host=(value)
+        @default_host = value
+        update_location_info(:host, value)
+      end
+
+      # Set the public_path.  This path gives the location of your public directory.
+      # The default is the public/ directory in your Rails root.  Or if Rails is not
+      # found, it defaults to public/ in the current directory (of the process).
+      #
+      # Example: 'tmp/' if you don't want to generate in public for some reason.
+      #
+      # Set to nil to use the current directory.
+      def public_path=(value)
+        @public_path = Pathname.new(value.to_s)
+        @public_path = SitemapGenerator.app.root + @public_path if @public_path.relative?
+        update_location_info(:public_path, @public_path)
+        @public_path
+      end
+
+      # Return a Pathname with the full path to the public directory
+      def public_path
+        @public_path ||= self.send(:public_path=, 'public/')
+      end
+
+      # Set the sitemaps_path.  This path gives the location to write sitemaps to
+      # relative to your public_path.
+      # Example: 'sitemaps/' to generate your sitemaps in 'public/sitemaps/'.
+      def sitemaps_path=(value)
+        @sitemaps_path = value
+        update_location_info(:sitemaps_path, value)
+      end
+
+      # Set the host name, including protocol, that will be used on all links to your sitemap
+      # files.  Useful when the server that hosts the sitemaps is not on the same host as
+      # the links in the sitemap.
+      def sitemaps_host=(value)
+        @sitemaps_host = value
+        update_location_info(:host, value)
+      end
+
+      # Set the filename base to use when generating sitemaps and sitemap indexes.
+      # The index name will be +value+ with <tt>_index.xml.gz</tt> appended.
+      # === Example
+      # <tt>filename = :sitemap</tt>
+      def filename=(value)
+        @filename = value
+        self.sitemaps_namer = SitemapGenerator::SitemapNamer.new(@filename)
+        self.sitemap_index_namer = SitemapGenerator::SitemapIndexNamer.new("#{@filename}_index")
+      end
+
+      # Set the namer to use when generating SitemapFiles (does not apply to the
+      # SitemapIndexFile)
+      def sitemaps_namer=(value)
+        @sitemaps_namer = value
+        @sitemap.location[:namer] = value if @sitemap && !@sitemap.finalized?
+      end
+
+      # Return the current sitemaps namer object.  If it not set, looks for it on
+      # the current sitemap and if there is no sitemap, creates a new one using
+      # the current filename.
+      def sitemaps_namer
+        @sitemaps_namer ||= @sitemap && @sitemap.location.namer || SitemapGenerator::SitemapNamer.new(@filename)
+      end
+
+      # Set the namer to use when generating SitemapFiles (does not apply to the
+      # SitemapIndexFile)
+      def sitemap_index_namer=(value)
+        @sitemap_index_namer = value
+        @sitemap_index.location[:namer] = value if @sitemap_index && !@sitemap_index.finalized? && !@protect_index
+      end
+
+      def sitemap_index_namer
+        @sitemap_index_namer ||= @sitemap_index && @sitemap_index.location.namer || SitemapGenerator::SitemapIndexNamer.new("#{@filename}_index")
+      end
+
+      # Return a new +SitemapLocation+ instance with the current options included
+      def sitemap_location
+        SitemapGenerator::SitemapLocation.new(
+          :host => sitemaps_host,
+          :namer => sitemaps_namer,
+          :public_path => public_path,
+          :sitemaps_path => @sitemaps_path
+        )
+      end
+
+      # Return a new +SitemapIndexLocation+ instance with the current options included
+      def sitemap_index_location
+        SitemapGenerator::SitemapLocation.new(
+          :host => sitemaps_host,
+          :namer => sitemap_index_namer,
+          :public_path => public_path,
+          :sitemaps_path => @sitemaps_path
+        )
+      end
+
+      protected
+
+      # Update the given attribute on the current sitemap index and sitemap file location objects.
+      # But don't create the index or sitemap files yet if they are not already created.
+      def update_location_info(attribute, value, opts={})
+        opts.reverse_merge!(:include_index => !@protect_index)
+        @sitemap_index.location[attribute] = value if opts[:include_index] && @sitemap_index && !@sitemap_index.finalized?
+        @sitemap.location[attribute] = value if @sitemap && !@sitemap.finalized?
+      end
     end
+    include LocationHelpers
   end
-end
+end