cartographer 1.0.0

data/History.txt

@@ -0,0 +1,6 @@
+=== 1.0.0 / 2011-03-23
+
+* 1 major enhancement
+
+  * Birthday!
+

data/Manifest.txt

@@ -0,0 +1,8 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+lib/cartographer.rb
+lib/xml/sitemap.haml
+lib/xml/sitemap_uri.haml
+test/test_cartographer.rb

data/README.txt

@@ -0,0 +1,85 @@
+= Cartographer
+
+http://github.com/erikh/cartographer/
+
+== DESCRIPTION:
+
+Assists in the creation of sitemaps that google, yahoo, etc, use. Has finding,
+rewriting, and attribute manipulation before generation. Does not require any
+external dependency other than haml.
+
+== FEATURES/PROBLEMS:
+
+* Does not require rails or any web framework.
+* Works with static generators.
+* Is able to transform a subtree of documents into a proper sitemap.
+
+== SYNOPSIS:
+
+  sm = Cartographer.new("http://example.org")
+  sm.add(Cartographer::URL.new(:location => URI.parse("http://example.org/ethereal")))
+  sm.add_tree("/some/doc/root") #=> adds all the files in the docroot
+  puts sm.to_xml #=> outputs your sitemap.
+
+  #
+  # filtering and remapping
+  #
+  sm = Cartographer.new("http://example.org")
+  # pass a block to get the paths found and rewrite them.
+  # return nil if you want that path (and sub-paths) to be omitted.
+  sm.add_tree("/some/doc/root") { |x| x.sub(/.html$/, '/') }
+  File.open('sitemap.xml', 'w') { |f| f << sm.to_xml }
+
+See Cartographer and Cartographer::URL RDoc for more information.
+
+If you need more information about the sitemap format:
+http://en.wikipedia.org/wiki/Sitemaps
+
+== REQUIREMENTS:
+
+Users:: haml
+Developers:: minitest, hoe-roodi, hoe-git, hoe-reek, nokogiri
+
+== INSTALL:
+
+* gem install cartographer
+
+== DEVELOPERS:
+
+For developers that use rvm, a 'rake install' task has been provided that will
+avoid using sudo. You will still need to install the dependencies manually
+instead of using 'rake newb'.
+
+For everyone else..
+
+After checking out the source, run:
+
+  $ rake newb
+
+This task will install any missing dependencies, run the tests/specs,
+and generate the RDoc.
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2011 Erik Hollensbe and Zetetic, LLC.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,32 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+
+Hoe.plugins.delete :rubyforge
+Hoe.plugin :git
+Hoe.plugin :rcov
+Hoe.plugin :roodi
+Hoe.plugin :reek
+Hoe.plugin :minitest
+
+spec = Hoe.spec 'cartographer' do
+  developer('Erik Hollensbe', 'erik@hollensbe.org')
+  developer('Team Zetetic', 'support@zetetic.net')
+
+  self.rubyforge_name = nil
+
+  extra_deps << ['haml', '>= 0']
+
+  extra_dev_deps << ['minitest', '>= 0']
+  extra_dev_deps << ['hoe-roodi', '>= 0']
+  extra_dev_deps << ['hoe-reek', '>= 0']
+  extra_dev_deps << ['hoe-git', '>= 0']
+  extra_dev_deps << ['nokogiri', '>= 0']
+end
+
+task :install => [:gem] do
+  sh "gem install pkg/#{spec.name}-#{spec.version}.gem"
+end
+
+# vim: syntax=ruby

data/lib/cartographer.rb

@@ -0,0 +1,172 @@
+require 'find'
+require 'haml'
+require 'uri'
+require 'time'
+
+#
+# Cartographer is a sitemap manipulation library.
+#
+# 
+#   sm = Cartographer.new("http://example.org")
+#   sm.add(Cartographer::URL.new(:location => URI.parse("http://example.org/ethereal")))
+#   sm.add_tree("/some/doc/root") #=> adds all the files in the docroot
+#   puts sm.to_xml #=> outputs your sitemap.
+#   
+#   
+#   # filtering and remapping
+#   sm = Cartographer.new("http://example.org")
+#   # pass a block to get the paths found and rewrite them.
+#   # return nil if you want that path (and sub-paths) to be omitted.
+#   sm.add_tree("/some/doc/root") { |x| x.sub(/.html$/, '/') }
+#   File.open('sitemap.xml', 'w') { |f| f << sm.to_xml }
+# 
+# See Cartographer and Cartographer::URL RDoc for more information.
+#
+class Cartographer
+  VERSION = '1.0.0'
+
+  ##
+  # List of Cartographer::URL objects
+  attr_reader :urls
+  
+  ##
+  # Your site's root path.
+  attr_reader :root_uri
+
+  ##
+  # The default change frequency for all URLs.
+  attr_accessor :default_changefreq
+
+  XML_TEMPLATE = File.expand_path("xml/sitemap.haml", File.dirname(File.expand_path(__FILE__)))
+
+  ##
+  # Constructor.
+  #
+  # Takes a root_uri which can be anything resolvable as a string, or URI::HTTP.
+  #
+  # Also takes a default change frequency which is just a string corresponding
+  # to the different types. 
+  def initialize(root_uri, default_changefreq=nil)
+    @urls = []
+    @root_uri = root_uri.kind_of?(URI::HTTP) ? root_uri : URI.parse(root_uri.to_s)
+    @default_changefreq = default_changefreq
+  end
+
+  ##
+  #
+  # Adds a Cartographer::URL to the list of URLs for processing.
+  #
+  def add(url)
+    raise ArgumentError, "Please pass Cartographer::URL objects to this method" unless url.kind_of?(URL)
+    @urls.push(url)
+  end
+
+  ##
+  #
+  # Given a path, walks the path and transforms all the files and directories
+  # in it into Cartographer::URL objects.
+  #
+  # If given a block, it will yield each relative path to this block as the
+  # first argument. The return value of this block is used as the path, making
+  # them transformable. If you return nil, this path (and any sub-paths) are
+  # pruned from the find.
+  #
+  # See the Constructor for examples or README.txt.
+  #
+  def add_tree(base_path)
+    Find.find(base_path) do |path|
+      new_path = path.sub %r!^#{Regexp.escape base_path}!, ''
+      uri = root_uri.dup
+      stat = File.stat(path)
+
+      if File.directory?(path)
+        new_path += "/"
+      end
+
+      if block_given?
+        new_path = yield new_path
+        unless new_path
+          Find.prune
+        end
+      end
+
+      uri.path = new_path
+      add URL.new(:location => uri, :lastmod => stat.mtime, :changefreq => @default_changefreq)
+    end
+  end
+
+  ##
+  #
+  # Transforms the given Cartographer::URL list to the sitemap XML format.
+  #
+  def to_xml
+    Haml::Engine.new(File.read(XML_TEMPLATE)).render(self)
+  end
+
+  ##
+  # Cartographer::URL is a structure to enforce the sitemap format.
+  #
+  class URL
+    XML_TEMPLATE = File.expand_path("xml/sitemap_uri.haml", File.dirname(File.expand_path(__FILE__)))
+
+    ##
+    # Location of item, stored as a kind of URI::Generic. Required.
+    attr_accessor :location
+    
+    ##
+    # Last modification time of this item.
+    attr_accessor :lastmod
+
+    ##
+    # Change frequency, stored as a string.
+    attr_accessor :changefreq
+
+    ##
+    # Priority, stored as a Numeric object, from 0 to 1 with decimal values included.
+    attr_accessor :priority
+
+
+    ##
+    #
+    # Constructor. Takes a hash of arguments:
+    #
+    # location:: A kind of URI::Generic
+    # lastmod:: A Time object which represents the last modification time.
+    # changefreq:: A string which contains the frequency.
+    # priority:: A decimal value (any kind of Numeric will do) from 0 - 1.
+    #
+    def initialize(args)
+      args.each do |key, value|
+        send(key.to_s + "=", value)
+      end
+
+      unless self.location
+        raise ArgumentError, "the location argument is required."
+      end
+      
+      unless self.location.kind_of?(URI::Generic)
+        raise ArgumentError, "location must be a kind of URI::Generic"
+      end
+
+      if self.lastmod and !self.lastmod.kind_of?(Time)
+        raise ArgumentError, "lastmod must be a kind of Time." 
+      end
+
+      if self.changefreq and !self.changefreq.kind_of?(String)
+        raise ArgumentError, "changefreq must be a kind of String"
+      end
+
+      if self.priority and !self.priority.kind_of?(Numeric)
+        raise ArgumentError, "priority must be a kind of Numeric"
+      end
+    end
+
+    ##
+    #
+    # Convert this object to the <url>...</url> representation.
+    #
+    def to_xml
+      Haml::Engine.new(File.read(XML_TEMPLATE)).render(self)
+    end
+  end
+end

data/lib/xml/sitemap.haml

@@ -0,0 +1,4 @@
+!!! XML
+%urlset{:xmlns => "http://www.sitemaps.org/schemas/sitemap/0.9"}
+  - @urls.each do |url|
+    %url=url.to_xml

data/lib/xml/sitemap_uri.haml

@@ -0,0 +1,7 @@
+%loc=location.to_s
+- if lastmod
+  %lastmod=lastmod.iso8601
+- if changefreq
+  %changefreq=changefreq
+- if priority
+  %priority=priority

data/test/test_cartographer.rb

@@ -0,0 +1,74 @@
+require "minitest/unit"
+require "cartographer"
+require 'nokogiri'
+
+class TestCartographer < MiniTest::Unit::TestCase
+  def test_constructor
+    sm = Cartographer.new("http://example.org")
+    assert_equal [], sm.urls
+    assert_kind_of URI::HTTP, sm.root_uri
+    assert_equal "http://example.org", sm.root_uri.to_s
+    refute sm.default_changefreq
+
+    sm = Cartographer.new("http://example.org", "always")
+    assert_equal "always", sm.default_changefreq
+  end
+
+  def test_add
+    sm = Cartographer.new("http://example.org")
+    assert_raises(ArgumentError) { sm.add("fart") }
+    sm.add(Cartographer::URL.new(:location => URI.parse("http://example.org/fart")))
+  end
+
+  def test_add_tree
+    sm = Cartographer.new("http://example.org")
+    sm.add_tree(File.expand_path("test"))
+    
+    assert_includes(
+      sm.urls.map(&:location), 
+      URI.parse("http://example.org/test_cartographer.rb")
+    )
+
+    sm = Cartographer.new("http://example.org", "always")
+    sm.add_tree(File.expand_path("test"))
+
+    url = sm.urls.select { |x| x.location.to_s == "http://example.org/test_cartographer.rb" }[0]
+
+    assert_equal "always", url.changefreq
+    assert_equal File.stat(__FILE__).mtime, url.lastmod
+
+    sm = Cartographer.new("http://example.org")
+    sm.add_tree(File.expand_path("test")) { |x| x.sub(/\.rb$/, '/') }
+
+    assert_includes(
+      sm.urls.map(&:location), 
+      URI.parse("http://example.org/test_cartographer/")
+    )
+  end
+
+  def test_to_xml
+    sm = Cartographer.new("http://example.org")
+    sm.add_tree(File.expand_path("test"))
+
+    xml = Nokogiri::XML.parse(sm.to_xml)
+    assert_equal [ "http://example.org/", "http://example.org/test_cartographer.rb" ],
+      xml.root.xpath('//xmlns:loc', xml.root.namespaces).map(&:content)
+    
+    sm = Cartographer.new("http://example.org", "always")
+    sm.add_tree(File.expand_path("test"))
+    
+    xml = Nokogiri::XML.parse(sm.to_xml)
+    assert_equal [ "http://example.org/", "http://example.org/test_cartographer.rb" ],
+      xml.root.xpath('//xmlns:loc', xml.root.namespaces).map(&:content)
+    
+    assert_equal [ "always", "always" ],
+      xml.root.xpath('//xmlns:changefreq', xml.root.namespaces).map(&:content)
+
+    sm = Cartographer.new("http://example.org")
+    sm.add_tree(File.expand_path("test")) { |x| x.sub(/\.rb$/, '/') }
+    
+    xml = Nokogiri::XML.parse(sm.to_xml)
+    assert_equal [ "http://example.org/", "http://example.org/test_cartographer/" ],
+      xml.root.xpath('//xmlns:loc', xml.root.namespaces).map(&:content)
+  end
+end

metadata

@@ -0,0 +1,149 @@
+--- !ruby/object:Gem::Specification 
+name: cartographer
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 1.0.0
+platform: ruby
+authors: 
+- Erik Hollensbe
+- Team Zetetic
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-03-26 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: haml
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: minitest
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: hoe-roodi
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: hoe-reek
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: hoe-git
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: nokogiri
+  prerelease: false
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id006
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  prerelease: false
+  requirement: &id007 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 2.9.1
+  type: :development
+  version_requirements: *id007
+description: |-
+  Assists in the creation of sitemaps that google, yahoo, etc, use. Has finding,
+  rewriting, and attribute manipulation before generation. Does not require any
+  external dependency other than haml.
+email: 
+- erik@hollensbe.org
+- support@zetetic.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- History.txt
+- Manifest.txt
+- README.txt
+files: 
+- History.txt
+- Manifest.txt
+- README.txt
+- Rakefile
+- lib/cartographer.rb
+- lib/xml/sitemap.haml
+- lib/xml/sitemap_uri.haml
+- test/test_cartographer.rb
+- .gemtest
+has_rdoc: true
+homepage: http://github.com/erikh/cartographer/
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- README.txt
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: Assists in the creation of sitemaps that google, yahoo, etc, use
+test_files: 
+- test/test_cartographer.rb