geocaching 0.1.0

data/README.markdown

@@ -0,0 +1,40 @@
+Ruby library for accessing geocaching.com information
+=====================================================
+
+This Ruby library provides access to cache and log information
+on geocaching.com.  It works by parsing the website’s content as
+Groundspeak does not offer an API yet.
+
+
+Example
+-------
+
+    require "geocaching"
+    
+    Geocaching::HTTP.login("username", "password")
+    
+    cache = Geocaching::Cache.fetch(:code => "GCF00")
+    log = Geocaching::Log.fetch(:guid => "...")
+    
+    puts cache.name #=> "Bridge Over Troubled Waters"
+    puts cache.difficulty #=> 2.5
+    puts cache.logs.size #=> 194
+    
+    puts log.username #=> "Chris"
+    puts log.message #=> "TFTC ..."
+    puts log.cache #=> #<Geocaching::Cache:...>
+    
+    Geocaching::HTTP.logout
+
+Altough some cache information are available without being logged in,
+most information will only be accessible after a successful login.
+
+
+Tests
+-----
+
+Tests are written using RSpec.
+
+    $ export GC_USERNAME="username"
+    $ export GC_PASSWORD="password"
+    $ rake test

data/Rakefile

@@ -0,0 +1,9 @@
+task :default => :test
+
+task :test do
+  sh "spec -c -f specdoc spec"
+end
+
+task :console do
+  sh "irb -I lib -r geocaching"
+end

data/geocaching.gemspec

@@ -0,0 +1,21 @@
+Gem::Specification.new do |s|
+  s.name        = "geocaching"
+  s.version     = "0.1.0"
+
+  s.summary     = "Library for accessing information on geocaching.com"
+  s.description = <<-EOD
+A Ruby library that allows to access information on geocaching.com
+in an object-oriented manner.
+EOD
+
+  s.author      = "nano"
+  s.email       = "nano@fooo.org"
+  s.homepage    = "http://nano.github.com/geocaching"
+
+  s.has_rdoc    = false
+  s.has_yardoc  = true
+
+  s.files       = %w(README.markdown Rakefile geocaching.gemspec)
+  s.files      += Dir.glob("lib/**/*")
+  s.files      += Dir.glob("spec/**/*")
+end

data/lib/geocaching.rb

@@ -0,0 +1,66 @@
+require "hpricot"
+
+# This is a Ruby library to access information on geocaching.com.  As
+# Groundspeak does not provide a public API yet, one needs to parse the
+# website content.  That’s what this library does.
+#
+# * {Geocaching::Cache} — Represents a cache
+# * {Geocaching::Log} — Represents a log
+#
+# == Usage
+#
+# To have access to all information, you will need to provide the
+# credentials for an account on geocaching.com and log in:
+#
+#  Geocaching::HTTP.login("username", "password")
+#
+# Make sure to log out when you’re done:
+#
+#  Geocaching::HTTP.logout
+# 
+# You know have access to all information that are available for the
+# account you provided.
+#
+#  cache = Geocaching::Cache.fetch(:code => "GCTEST")
+#  p cache.difficulty #=> 3.5
+#  p cache.latitude #=> 49.17518
+#  p cache.pmonly? #=> false
+#  p cache.logs.size #=> 41
+#
+#  log = Geocaching::Log.new(:guid => "07208985-f7b2-456a-b0a8-bbc26f28b5a9")
+#  log.fetch
+#  p log.cache #=> #<Geocaching::Cache:...>
+#  p log.username #=> Foobar
+#
+module Geocaching
+  # This exception is raised when a method that requires being
+  # logged in is called when not logged in.
+  class LoginError < Exception
+  end
+
+  # This exception is raised when a timeout is hit.
+  class TimeoutError < Exception
+  end
+
+  # This exception is raised when a method is called that requires
+  # the +#fetch+ method to be called first.
+  class NotFetchedError < Exception
+    def initialize
+      super "Need to call the #fetch method first"
+    end
+  end
+
+  # This exception is raised when information could not be
+  # extracted out of the website’s HTML code.  For example,
+  # this may happen if Groundspeak changed their website.
+  class ExtractError < Exception
+  end
+
+  # This exception is raised when a HTTP request fails.
+  class HTTPError < Exception
+  end
+
+  autoload :HTTP, "geocaching/http"
+  autoload :Cache, "geocaching/cache"
+  autoload :Log, "geocaching/log"
+end

data/lib/geocaching/cache.rb

@@ -0,0 +1,356 @@
+require "time"
+
+module Geocaching
+  # This class is subclass of Array and is used to store all logs
+  # that belong to a cache.  It implements the {#fetch_all} method to
+  # fetch the information of all logs inside the array.
+  class LogsArray < Array
+    # Calls {Geocaching::Log#fetch} for each log inside the array.
+    #
+    # @return [Boolean] Whether all logs could be fetched successfully
+    def fetch_all
+      each { |log| log.fetch }
+      map { |log| log.fetched? }.all?
+    end
+  end
+
+  # This class represents a cache on geocaching.com.  Altough some
+  # information are available without being logged in, most information
+  # will only be accessible after a successful login.
+  #
+  # == Example
+  #
+  #  cache = Geocaching::Cache.fetch(:code => "GCTEST")
+  #  
+  #  puts cache.difficulty #=> 3.5
+  #  puts cache.latitude #=> 49.741541
+  #  puts cache.archived? #=> false
+  #
+  class Cache
+    # Creates a new instance and calls the {#fetch} methods afterwards.
+    # One of +:code+ or +:guid+ must be provided as attributes.
+    #
+    # @param [Hash] attributes A hash of attributes, see {#initialize}
+    # @return [Geocaching::Cache]
+    # @raise [ArgumentError] Tried to set an unknown attribute
+    # @raise [ArgumentError] Neither code nor GUID given
+    def self.fetch(attributes)
+      cache = new(attributes)
+      cache.fetch
+      cache
+    end
+
+    # Creates a new instance.  The following attributes may be specified
+    # as parameters:
+    #
+    # * +:code+ — The cache’s GC code
+    # * +:guid+ — The cache’s Globally Unique Identifier
+    #
+    # @param [Hash] attributes A hash of attributes
+    # @raise [ArgumentError] Trying to set an unknown attribute
+    def initialize(attributes = {})
+      @data, @doc, @code, @guid = nil, nil, nil, nil
+
+      attributes.each do |key, value|
+        if [:code, :guid].include?(key)
+          instance_variable_set("@#{key}", value)
+        else
+          raise ArgumentError, "Trying to set unknown attribute `#{key}'"
+        end
+      end
+    end
+
+    # Fetches cache information from geocaching.com.
+    #
+    # @return [void]
+    # @raise [ArgumentError] Neither code nor GUID are given
+    # @raise [Geocaching::TimeoutError] Timeout hit
+    # @raise [Geocaching::HTTPError] HTTP request failed
+    def fetch
+      raise ArgumentError, "Neither code nor GUID given" unless @code or @guid
+
+      resp, @data = HTTP.get(path)
+      @doc = Hpricot(@data)
+    end
+
+    # Whether information have successfully been fetched
+    # from geocaching.com.
+    #
+    # @return [Boolean] Have information been fetched?
+    def fetched?
+      @data and @doc
+    end
+
+    # The cache’s code (GCXXXXXX).
+    #
+    # @return [String] Code
+    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
+    # @raise [Geocaching::ExtractError] Could not extract code from website
+    def code
+      @code ||= begin
+        raise NotFetchedError unless fetched?
+        elements = @doc.search("#ctl00_uxWaypointName.GCCode")
+
+        if elements.size == 1 and elements.first.inner_html =~ /(GC[A-Z0-9]+)/
+          HTTP.unescape($1)
+        else
+          raise ExtractError, "Could not extract code from website"
+        end
+      end
+    end
+
+    # The cache’s Globally Unique Identifier.
+    #
+    # @return [String] GUID
+    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
+    # @raise [Geocaching::ExtractError] Could not extract GUID from website
+    def guid
+      @guid ||= begin
+        raise NotFetchedError unless fetched?
+
+        elements = @doc.search("#ctl00_ContentBody_lnkPrintFriendly")
+        guid = nil
+
+        if elements.size == 1 and href = elements.first.attributes["href"]
+          guid = $1 if href =~ /guid=([0-9a-f-]{36})/
+        end
+
+        guid || begin
+          raise ExtractError, "Could not extract GUID from website"
+        end
+      end
+    end
+
+    # The cache’s type ID.
+    #
+    # @return [Fixnum] Type ID
+    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
+    # @raise [Geocaching::ExtractError] Could not extract cache type ID from website
+    def type_id
+      @type_id ||= begin
+        raise NotFetchedError unless fetched?
+
+        if @data =~ /<a.*?title="About Cache Types"><img.*?WptTypes\/(\d+)\.gif".*?<\/a>/
+          $1.to_i
+        else
+          raise ExtractError, "Could not extract cache type ID from website"
+        end
+      end
+    end
+
+    # The cache’s name.
+    #
+    # @return [String] Name
+    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
+    # @raise [Geocaching::ExtractError] Could not extract name from website"
+    def name
+      @name ||= begin
+        raise NotFetchedError unless fetched?
+        elements = @doc.search("span#ctl00_ContentBody_CacheName")
+
+        if elements.size == 1
+          HTTP.unescape(elements.first.inner_html)
+        else
+          raise ExtractError, "Could not extract name from website"
+        end
+      end
+    end
+
+    # The cache’s difficulty rating.
+    #
+    # @return [Float] Difficulty rating
+    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
+    # @raise [Geocaching::ExtractError] Could not extract difficulty rating from website
+    def difficulty
+      @difficulty ||= begin
+        raise NotFetchedError unless fetched?
+
+        if @data =~ /<strong>\s*?Difficulty:<\/strong>\s*?<img.*?alt="([\d\.]{1,3}) out of 5" \/>/
+          $1.to_f
+        else
+          raise ExtractError, "Could not extract difficulty rating from website"
+        end
+      end
+    end
+
+    # The cache’s terrain rating.
+    #
+    # @return [Float] Terrain rating
+    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
+    # @raise [Geocaching::ExtractError] Could not extract terrain rating from website
+    def terrain
+      @terrain ||= begin
+        raise NotFetchedError unless fetched?
+
+        if @data =~ /<strong>\s+?Terrain:<\/strong>\s+?<img.*?alt="([\d\.]{1,3}) out of 5" \/>/
+          $1.to_f
+        else
+          raise ExtractError, "Could not extract terrain rating from website"
+        end
+      end
+    end
+
+    # The date the cache has been hidden at.
+    #
+    # @return [Time] Hidden date
+    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
+    # @raise [Geocaching::ExtractError] Could not extract hidden date from website
+    def hidden_at
+      @hidden_at ||= begin
+        raise NotFetchedError unless fetched?
+
+        if @data =~ /<strong>\s+?Hidden\s+?:<\/strong>\s+?(\d{1,2})\/(\d{1,2})\/(\d{4})/
+          Time.parse([$3, $1, $2].join("-"))
+        else
+          raise ExtractError, "Could not extract hidden date from website"
+        end
+      end
+    end
+
+    # The cache’s container size.
+    #
+    # @return [Symbol] Cache container size
+    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
+    # @raise [Geocaching::ExtractError] Could not extract cache container size from website
+    def size
+      @size ||= begin
+        raise NotFetchedError unless fetched?
+        size = nil
+
+        if @data =~ /<img src="\/images\/icons\/container\/(.*?)\.gif" alt="Size: .*?" \/>/
+          size = $1.to_sym if %w(micro small regular large other not_chosen).include?($1)
+        end
+
+        size || begin
+          raise ExtractError, "Could not extract cache container size from website"
+        end
+      end
+    end
+
+    # The cache’s latitude.
+    #
+    # @return [Float] Latitude
+    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
+    # @raise [Geocaching::ExtractError] Could not extract latitude from website
+    def latitude
+      @latitude ||= begin
+        raise NotFetchedError unless fetched?
+
+        latitude = nil
+        elements = @doc.search("a#ctl00_ContentBody_lnkConversions")
+
+        if elements.size == 1 and href = elements.first.attributes["href"]
+          latitude = $1.to_f if href =~ /lat=(-?[0-9\.]+)/
+        end
+
+        latitude || begin
+          raise ExtractError, "Could not extract latitude from website"
+        end
+      end
+    end
+
+    # The cache’s longitude.
+    #
+    # @return [Float] Longitude
+    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
+    # @raise [Geocaching::ExtractError] Could not extract longitude from website
+    def longitude
+      @longitude ||= begin
+        raise NotFetchedError unless fetched?
+
+        longitude = nil
+        elements = @doc.search("a#ctl00_ContentBody_lnkConversions")
+
+        if elements.size == 1 and href = elements.first.attributes["href"]
+          longitude = $1.to_f if href =~ /lon=(-?[0-9\.]+)/
+        end
+
+        longitude || begin
+          raise ExtractError, "Could not extract longitude from website"
+        end
+      end
+    end
+
+    # The cache’s location name (State, Country).
+    #
+    # @return [String] Location name
+    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
+    # @raise [Geocaching::ExtractError] Could not extract location from website
+    def location
+      @location ||= begin
+        raise NotFetchedError unless fetched?
+
+        location = nil
+        elements = @doc.search("span#ctl00_ContentBody_Location")
+
+        if elements.size == 1
+          text = @doc.search("span#ctl00_ContentBody_Location").inner_html
+          location = $1.strip if text =~ /In ([^<]+)/
+        end
+
+        location || begin
+          raise ExtractError, "Could not extract location from website"
+        end
+      end
+    end
+
+    # Whether the cache has been archived or not.
+    #
+    # @return [Boolean] Has cache been archived?
+    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
+    def archived?
+      @is_archived ||= begin
+        raise NotFetchedError unless fetched?
+        !!(@data =~ /<li>This cache has been archived/)
+      end
+    end
+
+    # Whether the cache is only viewable to Premium Member only.
+    #
+    # @return [Boolean] Is cache PM-only?
+    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
+    def pmonly?
+      @is_pmonly ||= begin
+        raise NotFetchedError unless fetched?
+        !!(@data =~ /<p class="Warning">Sorry, the owner of this listing has made it viewable to Premium Members only\./)
+      end
+    end
+
+    # Returns an array of logs for this cache.  A log is an instance of
+    # {Geocaching::Log}.
+    #
+    # @return [Geocaching::LogsArray<Geocaching::Log>] Array of logs
+    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
+    # @raise [Geocaching::ExtractError] Could not extract logs from website
+    def logs
+      @logs ||= begin
+        raise NotFetchedError unless fetched?
+
+        logs = LogsArray.new
+        elements = @doc.search("table.Table.LogsTable > tr > td > strong")
+
+        if elements.size == 0
+          raise ExtractError, "Could not extract logs from website"
+        end
+
+        elements.each do |node|
+          img = node.search("img")
+          a = node.search("a")
+
+          title = img[0]["title"] if img.size == 1 and img[0]["title"]
+          guid = $1 if a.size == 1 and a[0]["href"] and a[0]["href"] =~ /guid=([a-f0-9-]{36})/
+
+          logs << Log.new(:guid => guid, :title => title, :cache => self)
+        end
+
+        logs
+      end
+    end
+
+  private
+
+    def path
+      "/seek/cache_details.aspx?log=y&" + (@code ? "wp=#{@code}" : "guid=#{@guid}")
+    end
+  end
+end

data/lib/geocaching/http.rb

@@ -0,0 +1,219 @@
+require "cgi"
+require "net/http"
+require "timeout"
+
+module Geocaching
+  class HTTP
+    # The user agent sent with each request.
+    @user_agent = "Mozilla/5.0 (Windows; U; Windows NT 5.1; en-GB; rv:1.9.0.13) Gecko/2009073022 Firefox/3.0.13 (.NET CLR 3.5.30729)"
+
+    # Timeout for sending and receiving HTTP data.
+    @timeout = 8
+
+    class << self
+      attr_accessor :user_agent, :timeout, :username, :password
+
+      # Returns the singleton instance of this class.
+      #
+      # @return [HTTP] Singleton instance of this class
+      def instance
+        @instance ||= new
+      end
+
+      # Alias for:
+      #
+      #  Geocaching::HTTP.username = username
+      #  Geocaching::HTTP.password = password
+      #  Geocaching::HTTP.instance.login
+      def login(username = nil, password = nil)
+        self.username, self.password = username, password if username && password
+        self.instance.login
+      end
+
+      # Alias for +Geocaching::HTTP.instance.logout+.
+      def logout
+        self.instance.logout
+      end
+
+      # Alias for +Geocaching::HTTP.instance.loggedin?+.
+      def loggedin?
+        self.instance.loggedin?
+      end
+
+      # Alias for +Geocaching::HTTP.instance.get+.
+      def get(path)
+        self.instance.get(path)
+      end
+
+      # Alias for +Geocaching::HTTP.instance.post+.
+      def post(path, data = {})
+        self.instance.post(path, data)
+      end
+
+      # Converts HTML entities to the corresponding UTF-8 symbols.
+      #
+      # @return [String] The converted string
+      def unescape(str)
+        CGI.unescapeHTML(str.gsub(/&#(\d{3});/) { [$1.to_i].pack("U") })
+      end
+    end
+
+    # Creates a new instance.
+    def initialize
+      @loggedin = false
+      @cookie = nil
+    end
+
+    # Logs in into geocaching.com.  Username and password need to be set
+    # before calling this method.
+    #
+    #  HTTP.username = "username"
+    #  HTTP.password = "password"
+    #
+    # @return [void]
+    # @raise [ArgumentError] Username or password missing
+    # @raise [Geocaching::LoginError] Already logged in
+    # @raise [Geocaching::TimeoutError] Timeout hit
+    # @raise [Geocaching::HTTPError] HTTP request failed
+    def login
+      raise ArgumentError, "Missing username" unless self.class.username
+      raise ArgumentError, "Missing password" unless self.class.password
+
+      raise LoginError, "Already logged in" if @loggedin
+
+      resp, data = post("/login/default.aspx", {
+        "ctl00$ContentBody$myUsername"  => self.class.username,
+        "ctl00$ContentBody$myPassword"  => self.class.password,
+        "ctl00$ContentBody$Button1"     => "Login",
+        "ctl00$ContentBody$cookie"      => "on"
+      })
+
+      @cookie = resp.response["set-cookie"]
+      @loggedin = true
+    end
+
+    # Logs out from geocaching.com.
+    #
+    # @return [void]
+    # @raise [Geocaching::LoginError] Not logged in
+    # @raise [Geocaching::TimeoutError] Timeout hit
+    # @raise [Geocaching::HTTPError] HTTP request failed
+    def logout
+      raise LoginError, "Not logged in" unless @loggedin
+
+      @loggedin = false
+      @cookie = nil
+
+      get("/login/default.aspx?RESET=Y")
+    end
+
+    # Returns whether this lib is logged in as a user.
+    #
+    # @return [Boolean] Logged in?
+    def loggedin?
+      @loggedin and @cookie
+    end
+
+    # Sends a GET request to +path+.  The authentication cookie is sent
+    # with the request if available.
+    #
+    # @param [String] path
+    # @return [Net::HTTP::Response] Reponse object from +Net::HTTP+
+    # @return [String] Actual content
+    # @raise [Geocaching::TimeoutError] Timeout hit
+    # @raise [Geocaching::HTTPError] HTTP request failed
+    def get(path)
+      resp = data = nil
+      header = default_header
+      header["Cookie"] = @cookie if @cookie
+
+      begin
+        Timeout::timeout(self.class.timeout) do
+          resp, data = http.get(path, header)
+        end
+      rescue Timeout::Error
+        raise TimeoutError, "Timeout hit for GET #{path}"
+      rescue
+        raise HTTPError
+      end
+
+      unless resp.kind_of?(Net::HTTPSuccess) or resp.kind_of?(Net::HTTPRedirection)
+        raise HTTPError
+      end
+
+      [resp, data]
+    end
+
+    # Sends a POST request to +path+ with the data given in the
+    # +params+ hash.  The authentication cookie is sent with the
+    # request if available.
+    #
+    # Before sending the POST request, a GET request is sent to obtain the
+    # information like +__VIEWPORT+ that are used on geocaching.com to protect
+    # from Cross Site Request Forgery.
+    #
+    # @return [Net::HTTP::Response] Reponse object from +Net::HTTP+
+    # @return [String] Actual content
+    # @raise [Geocaching::TimeoutError] Timeout hit
+    # @raise [Geocaching::HTTPError] HTTP request failed
+    def post(path, params = {})
+      params = params.merge(metadata(path)).map { |k,v| "#{k}=#{v}" }.join("&")
+      resp = data = nil
+
+      header = default_header
+      header["Cookie"] = @cookie if @cookie
+
+      begin
+        Timeout::timeout(self.class.timeout) do
+          resp, data = http.post(path, params, header)
+        end
+      rescue Timeout::Error
+        raise TimeoutError, "Timeout hit for POST #{path}"
+      rescue
+        raise HTTPError
+      end
+
+      unless resp.kind_of?(Net::HTTPSuccess)
+        raise HTTPError
+      end
+
+      [resp, data]
+    end
+
+  private
+
+    # Sends a GET request to +path+ to obtain form meta data used on
+    # geocaching.com to protect from CSRF.
+    #
+    # @return [Hash] Meta information
+    def metadata(path)
+      resp, data = get(path)
+      meta = {}
+
+      data.scan(/<input type="hidden" name="__([A-Z]+)" id="__[A-Z]+" value="(.*?)" \/>/).each do |match|
+        meta["__#{match[0]}"] = CGI.escape(match[1])
+      end
+
+      meta
+    end
+
+    # Returns an hash with the HTTP headers sent with each request.
+    #
+    # @return [Hash] Default HTTP headers
+    def default_header
+      {
+        "User-Agent" => self.class.user_agent
+      }
+    end
+
+    # Returns the instance of {Net::HTTP} or creates a new one for
+    # +www.geocaching.com+.
+    #
+    # @return [Net::HTTP]
+    def http
+      @http ||= begin
+        Net::HTTP.new("www.geocaching.com")
+      end
+    end
+  end
+end

data/lib/geocaching/log.rb

@@ -0,0 +1,168 @@
+module Geocaching
+  # This class represents a log on geocaching.com.
+  class Log
+    # Creates a new instance and calls the {#fetch} method afterwards.
+    # +:guid+ must be specified as an attribute.
+    #
+    # @param [Hash] attributes Hash of attributes
+    # @return [Geocaching::Log]
+    # @raise [ArgumentError] Unknown attribute provided
+    # @raise [TypeError] Invalid attribute provided
+    # @raise [Geocaching::TimeoutError] Timeout hit
+    # @raise [Geocaching::HTTPError] HTTP request failed
+    def self.fetch(attributes)
+      log = new(attributes)
+      log.fetch
+      log
+    end
+
+    # Creates a new instance.  The following attributes may be specified
+    # as parameters:
+    #
+    # * +:guid+ — The log’s Globally Unique Identifier
+    # * +:cache+ — A {Geocaching::Cache} that belongs to this log
+    #
+    # @raise [ArgumentError] Trying to set an unknown attribute
+    # @raise [TypeError] +:code+ is not an instance of {Geocaching::Cache}
+    def initialize(attributes = {})
+      @data, @doc, @guid, @cache = nil, nil, nil, nil
+
+      attributes.each do |key, value|
+        if [:guid, :title, :cache].include?(key)
+          if key == :cache and not value.kind_of?(Geocaching::Cache)
+            raise TypeError, "Attribute `cache' must be an instance of Geocaching::Cache"
+          end
+
+          instance_variable_set("@#{key}", value)
+        else
+          raise ArgumentError, "Trying to set unknown attribute `#{key}'"
+        end
+      end
+    end
+
+    # Fetches log information from geocaching.com.
+    #
+    # @return [void]
+    # @raise [ArgumentError] GUID is not given
+    # @raise [Geocaching::LoginError] Not logged in
+    # @raise [Geocaching::TimeoutError] Timeout hit
+    # @raise [Geocaching::HTTPError] HTTP request failed
+    def fetch
+      raise ArgumentError, "No GUID given" unless @guid
+      raise LoginError, "Need to be logged in to fetch log information" unless HTTP.loggedin?
+
+      resp, @data = HTTP.get(path)
+      @doc = Hpricot(@data)
+    end
+
+    # Whether information have successfully been fetched
+    # from geocaching.com.
+    #
+    # @return [Boolean] Have information beed fetched?
+    def fetched?
+      @data and @doc
+    end
+
+    # The cache that belongs to this log.
+    #
+    # @return [Geocaching::Cache] Cache
+    def cache
+      @cache ||= begin
+        if guid = cache_guid
+          Cache.new(:guid => guid)
+        end
+      end
+    end
+
+    def title
+      @title
+    end
+
+    # The name of the user that has posted this log.
+    #
+    # @return [String] Username
+    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} before
+    # @raise [Geocaching::ExtractError] Could not extract username from website
+    def username
+      @username ||= begin
+        raise NotFetchedError unless fetched?
+
+        elements = @doc.search("#ctl00_ContentBody_LogBookPanel1_lbLogText > a")
+
+        if elements.size > 0
+          HTTP.unescape(elements.first.inner_html)
+        else
+          raise ExtractError, "Could not extract username from website"
+        end
+      end
+    end
+
+    # The log’s raw message with all format codes.
+    #
+    # @return [String] Log message
+    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} before
+    # @raise [Geocaching::ExtractError] Could not extract message from website
+    def message
+      @message ||= begin
+        raise NotFetchedError unless fetched?
+
+        if meta[:description]
+          meta[:description].gsub(/\r\n/, "\n")
+        else
+          raise ExtractError, "Could not extract message from website"
+        end
+      end
+    end
+
+    # The short coord.info URL for this log.
+    #
+    # @return [String] coord.info URL
+    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} before
+    # @raise [Geocaching::ExtractError] Could not extract short URL from website
+    def short_url
+      @short_url ||= begin
+        raise NotFetchedError unless fetched?
+
+        meta[:url] || begin
+          raise ExtractError, "Could not extract short URL from website"
+        end
+      end
+    end
+
+  private
+
+    def cache_guid
+      if @cache.kind_of?(Geocaching::Cache) and @cache.guid
+        @cache.guid
+      else
+        raise NotFetchedError unless fetched?
+
+        elements = @doc.search("#ctl00_ContentBody_LogBookPanel1_lbLogText > a")
+
+        if elements.size == 2 and elements[1]["href"]
+          elements[1]["href"] =~ /guid=([a-f0-9-]{36})/
+          $1
+        else
+          raise ExtractError, "Could not extract cache GUID from website"
+        end
+      end
+    end
+
+    def meta
+      @meta ||= begin
+        elements = @doc.search("meta").select { |e| e.attributes["name"] =~ /^og:/ }.flatten
+        info = {}
+
+        elements.each do |element|
+          info[element["name"].gsub(/^og:/, "").to_sym] = element["content"]
+        end
+
+        info
+      end
+    end
+
+    def path
+      "/seek/log.aspx?LUID=#{@guid}"
+    end
+  end
+end

data/spec/cache_spec.rb

@@ -0,0 +1,74 @@
+$:.unshift File.join(File.dirname(__FILE__), "..", "lib")
+
+require "geocaching"
+require "helper"
+
+share_as :GCF00 do
+  it "should return the correct GC code" do
+    @cache.code.should == "GCF00"
+  end
+
+  it "should return the correct GUID" do
+    @cache.guid.should == "66274935-40d5-43d8-8cc3-c819e38f9dcc"
+  end
+
+  it "should return correct cache type ID" do
+    @cache.type_id.should == 2
+  end
+
+  it "should return the correct name" do
+    @cache.name.should == "Bridge Over Troubled Waters"
+  end
+
+  it "should return the correct latitude" do
+    @cache.latitude.should == 32.6684
+  end
+
+  it "should return the correct longitude" do
+    @cache.longitude.should == -97.436783
+  end
+
+  it "should return the correct difficulty rating" do
+    @cache.difficulty.should == 2.5
+  end
+
+  it "should return the correct terrain rating" do
+    @cache.terrain.should == 1.5
+  end
+
+  it "should return the correct hidden at date" do
+    @cache.hidden_at.should == Time.parse("2001-07-05")
+  end
+
+  it "should return the correct location" do
+    @cache.location.should == "Texas, United States"
+  end
+
+  it "should say cache is not archived" do
+    @cache.archived?.should == false
+  end
+
+  it "should say cache is not PM-only" do
+    @cache.pmonly?.should == false
+  end
+
+  it "should return a plausible number of total logs" do
+    @cache.logs.size.should >= 230
+  end
+end
+
+describe "Geocaching::Cache for GCF00" do
+  before :all do
+    @cache = Geocaching::Cache.fetch(:code => "GCF00")
+  end
+
+  include GCF00
+end
+
+describe "Geocaching::Cache for 66274935-40d5-43d8-8cc3-c819e38f9dcc" do
+  before :all do
+    @cache = Geocaching::Cache.fetch(:guid => "66274935-40d5-43d8-8cc3-c819e38f9dcc")
+  end
+
+  include GCF00
+end

data/spec/helper.rb

@@ -0,0 +1,12 @@
+unless ENV["GC_USERNAME"] and ENV["GC_PASSWORD"]
+  $stderr.puts "You need to provide your geocaching.com account credentials"
+  $stderr.puts "by setting the environment variables GC_USERNAME and GC_PASSWORD."
+  exit 1
+end
+
+begin
+  Geocaching::HTTP.login(ENV["GC_USERNAME"], ENV["GC_PASSWORD"])
+rescue Geocaching::Error => e
+  $stderr.puts "Failed to log in: #{e.message}"
+  exit 1
+end

data/spec/log_message.txt

@@ -0,0 +1,5 @@
+We almost made this really tough to get to with the surrounding terrain, then we spotted a better way.  Sneaky grab as pearle and I cached our way across southern FW.
+[br]
+Thanks for the fun!
+[br]
+[b][green]CC [:P][/b][/green]

data/spec/log_spec.rb

@@ -0,0 +1,23 @@
+$:.unshift File.join(File.dirname(__FILE__), "..", "lib")
+
+require "geocaching"
+require "helper"
+
+describe "Geocaching::Log for a3237dec-6931-4221-8f00-5d62923b411a" do
+  before :all do
+    @log = Geocaching::Log.fetch(:guid => "a3237dec-6931-4221-8f00-5d62923b411a")
+  end
+
+  it "should return the correct username" do
+    @log.username.should == "CampinCrazy"
+  end
+
+  it "should return the correct cache GUID" do
+    @log.cache.guid.should == "66274935-40d5-43d8-8cc3-c819e38f9dcc"
+  end
+
+  it "should return the correct message" do
+    should_message = File.read(File.join(File.dirname(__FILE__), "log_message.txt"))
+    @log.message.should == should_message.gsub(/\r\n/, "\n")
+  end
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification 
+name: geocaching
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- nano
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-07-25 00:00:00 +02:00
+default_executable: 
+dependencies: []
+
+description: |
+  A Ruby library that allows to access information on geocaching.com
+  in an object-oriented manner.
+
+email: nano@fooo.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README.markdown
+- Rakefile
+- geocaching.gemspec
+- lib/geocaching/cache.rb
+- lib/geocaching/http.rb
+- lib/geocaching/log.rb
+- lib/geocaching.rb
+- spec/cache_spec.rb
+- spec/helper.rb
+- spec/log_message.txt
+- spec/log_spec.rb
+has_rdoc: yard
+homepage: http://nano.github.com/geocaching
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Library for accessing information on geocaching.com
+test_files: []
+