geocaching 0.3.0 → 0.4.0

data/README.markdown

@@ -5,6 +5,12 @@ This Ruby library provides an API for geocaching.com.  As Groundspeak
 doesn’t offer an official API yet, this library parses the website’s
 HTML code.
 
+Documentation
+-------------
+
+Documentation is available at
+[rdoc.info](http://rdoc.info/projects/nano/ruby-geocaching).
+
 Example
 -------
 

data/geocaching.gemspec

@@ -1,6 +1,8 @@
+require "#{File.dirname(__FILE__)}/lib/geocaching/version"
+
 Gem::Specification.new do |s|
   s.name = "geocaching"
-  s.version = "0.3.0"
+  s.version = Geocaching::VERSION
 
   s.summary = "Ruby API for geocaching.com"
   s.description = "A Ruby library that provides an API for geocaching.com"

data/lib/geocaching.rb

@@ -1,6 +1,7 @@
 # encoding: utf-8
 
 require "nokogiri"
+require "geocaching/version"
 
 # 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
@@ -71,5 +72,7 @@ module Geocaching
   autoload :Cache, "geocaching/cache"
   autoload :CacheType, "geocaching/cache_type"
   autoload :Log, "geocaching/log"
-  autoload :MyLogs, "geocaching/mylogs"
+  autoload :LogType, "geocaching/log_type"
+  autoload :MyLogs, "geocaching/my_logs"
+  autoload :User, "geocaching/user"
 end

data/lib/geocaching/cache.rb

@@ -29,7 +29,7 @@ module Geocaching
   #  puts cache.archived? #=> false
   #
   class Cache
-    # Creates a new instance and calls the {#fetch} methods afterwards.
+    # Create a new instance and call the {#fetch} methods afterwards.
     # One of +:code+ or +:guid+ must be provided as attributes.
     #
     # @param [Hash] attributes A hash of attributes, see {#initialize}
@@ -42,7 +42,7 @@ module Geocaching
       cache
     end
 
-    # Creates a new instance.  The following attributes may be specified
+    # Create a new instance. The following attributes may be specified
     # as parameters:
     #
     # * +:code+ — The cache’s GC code
@@ -54,7 +54,11 @@ module Geocaching
       @data, @doc, @code, @guid = nil, nil, nil, nil
 
       attributes.each do |key, value|
-        if [:code, :guid].include?(key)
+        if [:code, :guid, :name, :type].include?(key)
+          if key == :type and not value.kind_of?(CacheType)
+            raise TypeError, "Attribute `type' must be an instance of Geocaching::CacheType"
+          end
+
           instance_variable_set("@#{key}", value)
         else
           raise ArgumentError, "Trying to set unknown attribute `#{key}'"
@@ -62,7 +66,7 @@ module Geocaching
       end
     end
 
-    # Fetches cache information from geocaching.com.
+    # Fetche cache information from geocaching.com.
     #
     # @return [void]
     # @raise [ArgumentError] Neither code nor GUID are given
@@ -75,7 +79,7 @@ module Geocaching
       @doc = Nokogiri::HTML.parse(@data)
     end
 
-    # Whether information have successfully been fetched
+    # Return whether information have successfully been fetched
     # from geocaching.com.
     #
     # @return [Boolean] Have information been fetched?
@@ -83,7 +87,7 @@ module Geocaching
       @data and @doc
     end
 
-    # The cache’s code (GCXXXXXX).
+    # Return the cache’s code (GCXXXXXX).
     #
     # @return [String] Code
     # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
@@ -101,7 +105,7 @@ module Geocaching
       end
     end
 
-    # The cache’s Globally Unique Identifier.
+    # Return the cache’s Globally Unique Identifier (GUID).
     #
     # @return [String] GUID
     # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
@@ -123,7 +127,7 @@ module Geocaching
       end
     end
 
-    # The cache’s type ID.
+    # Return the cache’s type ID.
     #
     # @return [Fixnum] Type ID
     # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
@@ -140,7 +144,7 @@ module Geocaching
       end
     end
 
-    # The cache’s type.
+    # Return the cache’s type.
     #
     # @return [Geocaching::CacheType] Type
     # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
@@ -149,7 +153,7 @@ module Geocaching
       @type ||= CacheType.for_id(type_id)
     end
 
-    # The cache’s name.
+    # Return the cache’s name.
     #
     # @return [String] Name
     # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
@@ -167,7 +171,35 @@ module Geocaching
       end
     end
 
-    # The cache’s difficulty rating.
+    # Return the cache’s owner.
+    #
+    # @return [Geocaching::User]
+    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
+    # @raise [Geocaching::ExtractError] Could not extract info from website"
+    def owner
+      @owner ||= begin
+        raise NotFetchedError unless fetched?
+
+        if @data =~ /<strong>\s*?A[(n\s*?Event)]*\s*?cache\s*?<\/strong>\s*?by\s*?<a.*?guid=([a-f0-9-]{36}).*?>(.*?)<\/a>/
+          @owner_display_name = HTTP.unescape($2)
+          User.new(:guid => $1)
+        else
+          raise ExtractError, "Could not extract owner from website"
+        end
+      end
+    end
+
+    # Return the displayed cache owner name.
+    #
+    # @return [String]
+    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
+    # @raise [Geocaching::ExtractError] Could not extract info from website"
+    def owner_display_name
+      owner unless @owner_display_name
+      @owner_display_name
+    end
+
+    # Return the cache’s difficulty rating.
     #
     # @return [Float] Difficulty rating
     # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
@@ -184,7 +216,7 @@ module Geocaching
       end
     end
 
-    # The cache’s terrain rating.
+    # Return the cache’s terrain rating.
     #
     # @return [Float] Terrain rating
     # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
@@ -201,7 +233,7 @@ module Geocaching
       end
     end
 
-    # The date the cache has been hidden at.
+    # Return the date the cache has been hidden at.
     #
     # @return [Time] Hidden date
     # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
@@ -218,7 +250,7 @@ module Geocaching
       end
     end
 
-    # The date the event has been held.
+    # Return the date the event has been held.
     #
     # @return [Time] Event date
     # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
@@ -236,7 +268,7 @@ module Geocaching
       end
     end
 
-    # The cache’s container size.
+    # Return the cache’s container size.
     #
     # @return [Symbol] Cache container size
     # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
@@ -256,7 +288,7 @@ module Geocaching
       end
     end
 
-    # The cache’s latitude.
+    # Return the cache’s latitude.
     #
     # @return [Float] Latitude
     # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
@@ -279,7 +311,7 @@ module Geocaching
       end
     end
 
-    # The cache’s longitude.
+    # Return the cache’s longitude.
     #
     # @return [Float] Longitude
     # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
@@ -302,7 +334,7 @@ module Geocaching
       end
     end
 
-    # The cache’s location name (State, Country).
+    # Return the cache’s location name (State, Country).
     #
     # @return [String] Location name
     # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
@@ -326,7 +358,7 @@ module Geocaching
       end
     end
 
-    # Whether the cache has been archived or not.
+    # Return whether the cache has been archived or not.
     #
     # @return [Boolean] Has cache been archived?
     # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
@@ -337,7 +369,7 @@ module Geocaching
       end
     end
 
-    # Whether the cache is only viewable to Premium Member only.
+    # Return whether the cache is only viewable to Premium Member only.
     #
     # @return [Boolean] Is cache PM-only?
     # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
@@ -350,7 +382,19 @@ module Geocaching
       end
     end
 
-    # Returns an array of logs for this cache.  A log is an instance of
+    # Return whether the cache is currently in review.
+    #
+    # @return [Boolean] Is cache currently in review?
+    # @raise [Geocaching::NotFetchedError] Need to call {#fetch} first
+    def in_review?
+      @in_review ||= begin
+        raise NotFetchedError unless fetched?
+        [!!@data.match(/<p class="Warning">Sorry, you cannot view this cache listing until it has been published/),
+         !!@data.match(/<p class="Warning">This cache listing has not been reviewed yet/)].any?
+      end
+    end
+
+    # Return an array of logs for this cache. A log is an instance of
     # {Geocaching::Log}.
     #
     # @return [Geocaching::LogsArray<Geocaching::Log>] Array of logs

data/lib/geocaching/cache_type.rb

@@ -1,44 +1,88 @@
 module Geocaching
+  # This class represents a cache type.
+  #
+  #  if @cache.type == :traditional
+  #    puts "Cache is a Traditional Cache"
+  #  end
   class CacheType
+    # A mapping of cache types to their corresponding ID and name
+    # on geocaching.com.
     TYPES = {
-      :traditional  => [2, "Traditional Cache"],
-      :multi        => [3, "Multi Cache"],
-      :mystery      => [8, "Mystery Cache"],
-      :letterbox    => [5, "Letterbox Hybrid"],
-      :wherigo      => [1858, "Wherigo"],
-      :event        => [6, "Event Cache"],
-      :megaevent    => [453, "Mega Event Cache"],
-      :cito         => [13, "Cache In Trash Out Event"],
-      :earthcache   => [137, "EarthCache"],
+      :traditional  => [2,    "Traditional Cache"],
+      :multi        => [3,    "Multi-cache"],
+      :mystery      => [8,    "Unknown Cache"],
+      :letterbox    => [5,    "Letterbox Hybrid"],
+      :wherigo      => [1858, "Wherigo Cache"],
+      :event        => [6,    "Event Cache"],
+      :megaevent    => [453,  "Mega-Event Cache"],
+      :cito         => [13,   "Cache In Trash Out Event"],
+      :earthcache   => [137,  "Earthcache"],
       :lfevent      => [3653, "Lost and Found Event Cache"],
-      :locationless => [12, "Locationless Reverse Cache"],
-      :webcam       => [11, "Webcam Cache"],
-      :virtual      => [4, "Virtual Cache"],
-      :ape          => [32, "Project A.P.E. Cache"] # XXX
+      :locationless => [12,   "Locationless (Reverse) Cache"],
+      :webcam       => [11,   "Webcam Cache"],
+      :virtual      => [4,    "Virtual Cache"],
+      :ape          => [9,    "Project APE Cache"]
     }
 
+    # Return a {CacheType} object for the given cache type id, or
+    # nil if no appropriate cache id is found.
+    #
+    # @return [Geocaching::CacheType]
+    # @return [nil] If no appropriate cache type is found
     def self.for_id(id)
       if info = TYPES.to_a.select { |(k,v)| v[0] == id } and info.size == 1
         new(info.first)
       end
     end
 
+    # Return a {CacheType} object for the given cache type title, or
+    # nil if no appropriate cache type is found.
+    #
+    # @return [Geocaching::CacheType]
+    # @return [nil] If no appropriate cache type is found
+    def self.for_title(title)
+      if info = TYPES.to_a.select { |(k,v)| v[1] == title } and info.size == 1
+        new(info.first)
+      end
+    end
+
+    # Create a new instance. You should not need to create an instance
+    # of this class on your own. Use {for_id} and {for_title}.
     def initialize(info)
       @info = info
     end
 
+    # Return the cache type’s ID.
+    #
+    # @return [Fixnum]
     def id
       @info[1][0]
     end
 
+    # Return the cache type’s name.
+    #
+    # @return [String]
     def name
       @info[1][1]
     end
 
+    alias to_s name
+
+    # Return the symbol that describes this cache type. See the {TYPES}
+    # hash for a list of cache type symbols.
+    #
+    # @return [Symbol]
     def to_sym
       @info[0]
     end
 
+    # Overload the == operator.
+    #
+    #  if @cache.type == :multi
+    #    puts "It's a multi cache."
+    #  end
+    #
+    # @return [Boolean]
     def ==(s)
       to_sym == s
     end

data/lib/geocaching/log.rb

@@ -30,11 +30,15 @@ module Geocaching
       @data, @doc, @guid, @cache = nil, nil, nil, nil
 
       attributes.each do |key, value|
-        if [:guid, :title, :cache].include?(key)
+        if [:guid, :title, :date, :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
 
+          if key == :date and not value.kind_of?(Time)
+            raise TypeError, "Attribute `type' must be an instance of Time"
+          end
+
           instance_variable_set("@#{key}", value)
         else
           raise ArgumentError, "Trying to set unknown attribute `#{key}'"
@@ -76,8 +80,22 @@ module Geocaching
       end
     end
 
+    def type
+      @type ||= LogType.for_title(title)
+    end
+
     def title
-      @title
+      @title ||= begin
+        raise NotFetchedError unless fetched?
+
+        imgs = @doc.search("#ctl00_ContentBody_LogBookPanel1_LogImage")
+
+        unless imgs.size == 1 and imgs.first["alt"]
+          raise ExtractError, "Could not extract title from website"
+        end
+
+        imgs.first["alt"]
+      end
     end
 
     # The name of the user that has posted this log.
@@ -99,6 +117,20 @@ module Geocaching
       end
     end
 
+    def date
+      @date ||= begin
+        raise NotFetchedError unless fetched?
+
+        elements = @doc.search("#ctl00_ContentBody_LogBookPanel1_LogDate")
+
+        if elements.size == 1
+          Time.parse(elements.first.content)
+        else
+          raise ExtractError, "Could not extract date from website"
+        end
+      end
+    end
+
     # The log’s raw message with all format codes.
     #
     # @return [String] Log message

data/lib/geocaching/log_type.rb

@@ -1,54 +1,92 @@
 module Geocaching
+  # This class represents a log type.
+  #
+  #  if @log.type == :archive
+  #    puts "#{@log.cache.code} has been archived"
+  #  end
   class LogType
+    # Mapping of log types to their corresponding icon and title
+    # on geocaching.com.
     TYPES = {
-      :published          => ["icon_greenlight", "Publish Listing"],
-      :retracted          => ["", ""], # TODO
-      :dnf                => ["icon_sad", "Didn't find it"],
-      :found              => ["icon_smile", "Found it"],
-      :webcam_photo_taken => ["", ""], # TODO
-      :will_attend        => ["icon_rsvp", "Will Attend"],
-      :announcement       => ["icon_announcement", "Announcement"],
-      :attended           => ["icon_attended", "Attended"],
-      :needs_maintenance  => ["icon_needsmaint", "Needs Maintenance"],
-      :owner_maintenance  => ["icon_maint", "Owner Maintenance"],
-      :disabled           => ["icon_disabled", "Temporarily Disable Listing"],
-      :enabled            => ["icon_enabled", "Enable Listing"],
-      :note               => ["icon_note", "Write Note"],
-      :needs_archived     => ["icon_remove", "Needs Archived"],
-      :archived           => ["traffic_cone", "Archive"],
-      :unarchived         => ["traffic_cone", "Unarchive"],
-      :coords_updated     => ["coord_update", "Update Coordinates"],
-      :reviewer_note      => ["big_smile", "Post Reviewer Note"]
+      :publish            => ["icon_greenlight",    "Publish Listing"],
+      :retract            => ["icon_redlight",      "Retract Listing"],
+      :dnf                => ["icon_sad",           "Didn't find it"],
+      :found              => ["icon_smile",         "Found it"],
+      :webcam_photo_taken => ["icon_camera",        "Webcam Photo Taken"],
+      :will_attend        => ["icon_rsvp",          "Will Attend"],
+      :announcement       => ["icon_announcement",  "Announcement"],
+      :attended           => ["icon_attended",      "Attended"],
+      :needs_maintenance  => ["icon_needsmaint",    "Needs Maintenance"],
+      :owner_maintenance  => ["icon_maint",         "Owner Maintenance"],
+      :disable            => ["icon_disabled",      "Temporarily Disable Listing"],
+      :enable             => ["icon_enabled",       "Enable Listing"],
+      :note               => ["icon_note",          "Write note"],
+      :needs_archived     => ["icon_remove",        "Needs Archived"],
+      :archive            => ["traffic_cone",       "Archive"],
+      :unarchive          => ["traffic_cone",       "Unarchive"],
+      :coords_update      => ["coord_update",       "Update Coordinates"],
+      :reviewer_note      => ["big_smile",          "Post Reviewer Note"]
     }
 
+    # Return a {LogType} object for the given log type icon, or nil if
+    # no appropriate log type is found.
+    #
+    # @return [Geocaching::LogType]
+    # @return [nil] If no appropriate log type is found
     def self.for_icon(icon)
       if info = TYPES.to_a.select { |(k,v)| v[0] == icon } and info.size == 1
         new(info.first)
       end
     end
 
+    # Return a {LogType} object for the given log type title, or nil if
+    # no appropriate log type is found.
+    #
+    # @return [Geocaching::LogType]
+    # @return [nil] If no appropriate log type is found
     def self.for_title(title)
       if info = TYPES.to_a.select { |(k,v)| v[1] == title } and info.size == 1
         new(info.first)
       end
     end
 
-    def new(info)
+    # Create a new instance. You should not need to create an instance
+    # of this class on your own. Use {for_icon} and {for_title}.
+    def initialize(info)
       @info = info
     end
 
+    # Return the log type’s icon.
+    #
+    # @return [String]
     def icon
       @info[1][0]
     end
 
+    # Return the log type’s title.
+    #
+    # @return [String]
     def description
       @info[1][1]
     end
 
+    alias to_s description
+
+    # Return the symbol representatin of the log type. See the {TYPES}
+    # hash for a list of log type symbols.
+    #
+    # @return [Symbol]
     def to_sym
       @info[0]
     end
 
+    # Overload the == operator.
+    #
+    #  if @log.type == :dnf
+    #    puts "Someone could not find the cache"
+    #  end
+    #
+    # @return [Boolean]
     def ==(s)
       to_sym == s
     end