geocaching 0.5.0 → 0.6.0

data/lib/geocaching/cache_type.rb

@@ -1,5 +1,9 @@
+# encoding: utf-8
+
 module Geocaching
-  # This class represents a cache type.
+  # The {CacheType} class represents a cache type.
+  #
+  # == Usage
   #
   #  if @cache.type == :traditional
   #    puts "Cache is a Traditional Cache"
@@ -24,7 +28,7 @@ module Geocaching
       :ape          => [9,    "Project APE Cache"]
     }
 
-    # Return a {CacheType} object for the given cache type id, or
+    # Returns a {CacheType} object for the given cache type id, or
     # nil if no appropriate cache id is found.
     #
     # @return [Geocaching::CacheType]
@@ -35,7 +39,7 @@ module Geocaching
       end
     end
 
-    # Return a {CacheType} object for the given cache type title, or
+    # Returns a {CacheType} object for the given cache type title, or
     # nil if no appropriate cache type is found.
     #
     # @return [Geocaching::CacheType]
@@ -46,43 +50,43 @@ module Geocaching
       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}.
+    # Creates 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.
+    # Returns the cache type’s ID.
     #
-    # @return [Fixnum]
+    # @return [Fixnum] Cache type ID
     def id
       @info[1][0]
     end
 
-    # Return the cache type’s name.
+    # Returns the cache type’s name.
     #
-    # @return [String]
+    # @return [String] Cache type name
     def name
       @info[1][1]
     end
 
     alias to_s name
 
-    # Return the symbol that describes this cache type. See the {TYPES}
+    # Returns the symbol that describes this cache type.  See the {TYPES}
     # hash for a list of cache type symbols.
     #
-    # @return [Symbol]
+    # @return [Symbol] Cache type symbol
     def to_sym
       @info[0]
     end
 
-    # Overload the == operator.
+    # Overloads the +==+ operator to compare by symbol.
     #
     #  if @cache.type == :multi
     #    puts "It's a multi cache."
     #  end
     #
-    # @return [Boolean]
+    # @return [Boolean] Does object match with argument?
     def ==(s)
       to_sym == s
     end

data/lib/geocaching/http.rb

@@ -5,6 +5,7 @@ require "net/http"
 require "timeout"
 
 module Geocaching
+  # The {HTTP} class handles the HTTP communication with geocaching.com.
   class HTTP
     # An array of user agent strings.  A random one is chosen.
     USER_AGENTS = [
@@ -61,8 +62,8 @@ module Geocaching
       end
 
       # Alias for +Geocaching::HTTP.instance.post+.
-      def post(path, data = {})
-        self.instance.post(path, data)
+      def post(path, data = {}, extra_headers = {})
+        self.instance.post(path, data, extra_headers)
       end
 
       # Converts HTML entities to the corresponding UTF-8 symbols.
@@ -89,9 +90,6 @@ module Geocaching
     #
     # @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
@@ -112,9 +110,6 @@ module Geocaching
     # 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
 
@@ -124,9 +119,9 @@ module Geocaching
       get("/login/default.aspx?RESET=Y")
     end
 
-    # Returns whether this lib is logged in as a user.
+    # Returns whether you‘ve already logged in.
     #
-    # @return [Boolean] Logged in?
+    # @return [Boolean] Already logged in?
     def loggedin?
       @loggedin and @cookie
     end
@@ -134,11 +129,9 @@ module Geocaching
     # Sends a GET request to +path+.  The authentication cookie is sent
     # with the request if available.
     #
-    # @param [String] path
+    # @param [String] path Request 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
@@ -173,11 +166,14 @@ module Geocaching
     # @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("&")
+    def post(path, params = {}, extra_headers = {})
+      if params.kind_of?(Hash)
+        params = params.merge(metadata(path)).map { |k,v| "#{k}=#{v}" }.join("&")
+      end
+
       resp = data = nil
 
-      header = default_header
+      header = default_header.merge(extra_headers)
       header["Cookie"] = @cookie if @cookie
 
       begin

data/lib/geocaching/log.rb

@@ -1,7 +1,11 @@
 # encoding: utf-8
 
 module Geocaching
-  # This class represents a log on geocaching.com.
+  # The {Log} class represents a log on geocaching.com.
+  #
+  # This class does caching.  That means that multiple calls of, for example,
+  # the {#date} method only do one HTTP request.  If you want to override the
+  # cached information, call the {#fetch} method manually.
   class Log
     # Creates a new instance and calls the {#fetch} method afterwards.
     # +:guid+ must be specified as an attribute.
@@ -10,8 +14,6 @@ module Geocaching
     # @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
@@ -22,15 +24,13 @@ module Geocaching
     # 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, :date, :cache].include?(key)
+        if [:guid, :title, :date, :cache, :user].include?(key)
           if key == :cache and not value.kind_of?(Geocaching::Cache)
             raise TypeError, "Attribute `cache' must be an instance of Geocaching::Cache"
           end
@@ -39,6 +39,10 @@ module Geocaching
             raise TypeError, "Attribute `type' must be an instance of Time"
           end
 
+          if key == :user and not value.kind_of?(User)
+            raise TypeError, "Attribute `user' must be an instance of Geocaching::User"
+          end
+
           instance_variable_set("@#{key}", value)
         else
           raise ArgumentError, "Trying to set unknown attribute `#{key}'"
@@ -50,26 +54,30 @@ module Geocaching
     #
     # @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?
+      raise LoginError unless HTTP.loggedin?
 
       resp, @data = HTTP.get(path)
       @doc = Nokogiri::HTML.parse(@data)
     end
 
-    # Whether information have successfully been fetched
+    # Returns whether log information have successfully been fetched
     # from geocaching.com.
     #
-    # @return [Boolean] Have information beed fetched?
+    # @return [Boolean] Have log information beed fetched?
     def fetched?
       @data and @doc
     end
 
-    # The cache that belongs to this log.
+    # Returns the log’s GUID.
+    #
+    # @return [String] GUID
+    def guid
+      @guid
+    end
+
+    # Returns the cache that belongs to this log.
     #
     # @return [Geocaching::Cache] Cache
     def cache
@@ -80,43 +88,33 @@ module Geocaching
       end
     end
 
+    # Returns the log’s type.
+    #
+    # @return [Geocaching::LogType] Log type
     def type
       @type ||= LogType.for_title(title)
     end
 
-    def 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.
+    # Returns the the user that posted the 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
+    # @return [Geocaching::User] User
+    def user
+      @user ||= begin
         raise NotFetchedError unless fetched?
 
         elements = @doc.search("#ctl00_ContentBody_LogBookPanel1_lbLogText > a")
 
         if elements.size > 0
-          HTTP.unescape(elements.first.inner_html)
+          User.new(:name => HTTP.unescape(elements.first.inner_html))
         else
-          raise ExtractError, "Could not extract username from website"
+          raise ParseError, "Could not extract username from website"
         end
       end
     end
 
+    # Returns the date the log was written at.
+    #
+    # @return [Time] Log date
     def date
       @date ||= begin
         raise NotFetchedError unless fetched?
@@ -126,16 +124,14 @@ module Geocaching
         if elements.size == 1
           Time.parse(elements.first.content)
         else
-          raise ExtractError, "Could not extract date from website"
+          raise ParseError, "Could not extract date from website"
         end
       end
     end
 
-    # The log’s raw message with all format codes.
+    # Returns 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
+    # @return [String] Raw log message
     def message
       @message ||= begin
         raise NotFetchedError unless fetched?
@@ -143,28 +139,46 @@ module Geocaching
         if meta[:description]
           meta[:description].gsub(/\r\n/, "\n")
         else
-          raise ExtractError, "Could not extract message from website"
+          raise ParseError, "Could not extract message from website"
         end
       end
     end
 
-    # The short coord.info URL for this log.
+    # Returns thehe short coord.info URL for the 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"
+          raise ParseError, "Could not extract short URL from website"
         end
       end
     end
 
   private
 
+    # Returns the log’s title which is used internally to get the log type.
+    #
+    # @return [String] Log title
+    def title
+      @title ||= begin
+        raise NotFetchedError unless fetched?
+
+        imgs = @doc.search("#ctl00_ContentBody_LogBookPanel1_LogImage")
+
+        unless imgs.size == 1 and imgs.first["alt"]
+          raise ParseError, "Could not extract title from website"
+        end
+
+        imgs.first["alt"]
+      end
+    end
+
+    # Returns the UUID of the cache that belongs to this log.
+    #
+    # @return [String] Cache UUID
     def cache_guid
       if @cache.kind_of?(Geocaching::Cache) and @cache.guid
         @cache.guid
@@ -177,11 +191,15 @@ module Geocaching
           elements[1]["href"] =~ /guid=([a-f0-9-]{36})/
           $1
         else
-          raise ExtractError, "Could not extract cache GUID from website"
+          raise ParseError, "Could not extract cache GUID from website"
         end
       end
     end
 
+    # Returns an array of information that are provided on the website
+    # in <meta> tags.
+    #
+    # @return [Hash] Log information
     def meta
       @meta ||= begin
         elements = @doc.search("meta").select { |e| e["name"] =~ /^og:/ }.flatten
@@ -195,6 +213,9 @@ module Geocaching
       end
     end
 
+    # Returns the HTTP request path.
+    #
+    # @return [String] HTTP request path
     def path
       "/seek/log.aspx?LUID=#{@guid}"
     end

data/lib/geocaching/log_type.rb

@@ -1,5 +1,9 @@
+# encoding: utf-8
+
 module Geocaching
-  # This class represents a log type.
+  # The {LogType} class represents a log type.
+  #
+  # == Usage
   #
   #  if @log.type == :archive
   #    puts "#{@log.cache.code} has been archived"
@@ -28,7 +32,7 @@ module Geocaching
       :reviewer_note      => ["big_smile",          "Post Reviewer Note"]
     }
 
-    # Return a {LogType} object for the given log type icon, or nil if
+    # Returns a {LogType} object for the given log type icon, or nil if
     # no appropriate log type is found.
     #
     # @return [Geocaching::LogType]
@@ -39,7 +43,7 @@ module Geocaching
       end
     end
 
-    # Return a {LogType} object for the given log type title, or nil if
+    # Returns a {LogType} object for the given log type title, or nil if
     # no appropriate log type is found.
     #
     # @return [Geocaching::LogType]
@@ -50,43 +54,43 @@ module Geocaching
       end
     end
 
-    # Create a new instance. You should not need to create an instance
-    # of this class on your own. Use {for_icon} and {for_title}.
+    # Creates 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.
+    # Returns the log type’s icon.
     #
-    # @return [String]
+    # @return [String] Icon
     def icon
       @info[1][0]
     end
 
-    # Return the log type’s title.
+    # Returns the log type’s description.
     #
-    # @return [String]
+    # @return [String] Description
     def description
       @info[1][1]
     end
 
     alias to_s description
 
-    # Return the symbol representatin of the log type. See the {TYPES}
+    # Returns the symbol representaton of the log type.  See the {TYPES}
     # hash for a list of log type symbols.
     #
-    # @return [Symbol]
+    # @return [Symbol] Log type symbol
     def to_sym
       @info[0]
     end
 
-    # Overload the == operator.
+    # Overloads the +==+ operator to compare by symbol.
     #
     #  if @log.type == :dnf
     #    puts "Someone could not find the cache"
     #  end
     #
-    # @return [Boolean]
+    # @return [Boolean] Does object match with argument?
     def ==(s)
       to_sym == s
     end