geocaching 0.5.0 → 0.6.0

data/lib/geocaching/my_logs.rb

@@ -1,48 +1,48 @@
+# encoding: utf-8
+
 module Geocaching
-  # This class provides access to the logs the user currently logged in
-  # has written.
+  # The {MyLogs} class provides access to the logs the user
+  # you’re logged in with has written.
+  #
+  # This class does caching.  If you want to override the cached information,
+  # call the {#fetch} method manually.
+  #
+  # == Usage
   #
   #  mylogs = Geocaching::MyLogs.fetch
   #  puts "I've written #{mylogs.size} logs."
   class MyLogs
-    # Create a new instance and call {fetch} afterwards.
+    # Creates a new instance and calls {#fetch} afterwards.
     #
     # @return [Geocaching::MyLogs]
-    # @raise [Geocaching::LoginError] Need to be logged in to fetch own logs
-    # @raise [Geocaching::TimeoutError] Timeout hit
-    # @raise [Geocaching::HTTPError] HTTP request failed
     def self.fetch
       mylogs = new
       mylogs.fetch
       mylogs
     end
 
-    # Fetch logs from geocaching.com.
+    # Fetches logs from geocaching.com.
     #
     # @return [void]
-    # @raise [Geocaching::LoginError] Need to be logged in to fetch own logs
-    # @raise [Geocaching::TimeoutError] Timeout hit
-    # @raise [Geocaching::HTTPError] HTTP request failed
     def fetch
-      raise LoginError, "Need to be logged in to fetch your logs" unless HTTP.loggedin?
+      raise LoginError unless HTTP.loggedin?
 
       resp, @data = HTTP.get(path)
       @doc = Nokogiri::HTML.parse(@data)
     end
 
-    # Return whether logs have successfully been fetched from
-    # geocaching.com.
+    # Returns whether logs have successfully been fetched
+    # from geocaching.com.
     #
-    # @return [Boolean]
+    # @return [Boolean] Have logs been fetched?
     def fetched?
       @data and @doc
     end
 
-    # Return an array of logs the user you’re logged in with has
+    # Returns an array of logs the user you’re logged in with has
     # written.
     #
     # @return [Array<Geocaching::Log>]
-    # @raise [Geocaching::NotFetchedError] Need to call {fetch} first.
     def logs
       @logs ||= begin
         raise NotFetchedError unless fetched?
@@ -72,10 +72,16 @@ module Geocaching
 
   private
 
+    # Returns the HTTP request path.
+    #
+    # @return [String] HTTP request path
     def path
       "/my/logs.aspx?s=1"
     end
 
+    # Extracts information from a HTML table row node.
+    #
+    # @return [Hash] Extracted information
     def extract_info_from_row(row)
       info = {}
 

data/lib/geocaching/pocket_query.rb

@@ -0,0 +1,213 @@
+# encoding: utf-8
+
+module Geocaching
+  # The {PocketQuery} class represents a Pocket Query.
+  #
+  # == Usage
+  #
+  # === Downloading a Pocket Query
+  #
+  #  avail_pqs = Geocaching::PocketQuery.ready_for_download
+  #  pq = avail_pqs.first
+  #  
+  #  pq.download
+  #  pq.parse
+  #  
+  #  puts "The PQ contains #{pq.caches.size} caches."
+  #
+  # === Reading a Pocket Query from file
+  #
+  #  pq = Geocaching::PocketQuery.from_file("123456.gpx")
+  #  puts "The PQ’s name is #{pq.name}."
+  #
+  class PocketQuery
+    # Reads a Pocket Query from file and parses it.  The file may either be a
+    # GPX file or a zip file containing the GPX file.
+    #
+    # @param [String] file File name
+    # @return [Geocaching::PocketQuery] Pocket Query
+    def self.from_file(file)
+      pq = new(:raw => File.read(file))
+      pq.parse
+      pq
+    end
+
+    # Returns an array of Pocket Queries that are ready for download.  You
+    # need to be logged in and a Premium Member to use this feature.
+    #
+    # @return [Array<Geocaching::PocketQuery>]
+    #   Array of Pocket Queries ready for download
+    def self.ready_for_download
+      raise LoginError unless HTTP.loggedin?
+
+      pqs = []
+      resp, data = HTTP.get("/pocket/default.aspx")
+      doc = Nokogiri::HTML.parse(data)
+
+      elements = doc.search("table#uxOfflinePQTable")
+      raise ParseError unless elements.size == 1
+
+      elements = elements.first.search("tr")[1..-1]
+
+      elements.each do |row|
+        # Name
+        elements = row.search("td:nth-child(3) > a")
+        next unless elements.size == 1
+        name = elements.first.text.strip
+
+        # GUID
+        if elements.first["href"] =~ /g=([a-f0-9-]{36})/
+          guid = $1
+        else
+          next
+        end
+
+        # Number of results
+        elements = row.search("td:nth-child(5)")
+        next unless elements.size == 1
+        results = elements.first.text.to_i
+
+        # Last Generated date
+        elements = row.search("td:nth-child(6)")
+        next unless elements.size == 1
+        if elements.first.text =~ /(\d{2})\/(\d{2})\/(\d{4})/
+          date = Time.mktime($3, $1, $2)
+        end
+
+        if guid and name and results and date
+          pq = PocketQuery.new \
+            :guid              => guid,
+            :name              => name,
+            :results           => results,
+            :last_generated_at => date
+          pqs << pq
+        end
+      end
+
+      pqs
+    end
+
+    class << self
+      alias ready ready_for_download
+    end
+
+    # Adds the ”My Finds“ Pocket Query to the Queue.
+    #
+    # @return [void]
+    def self.schedule_my_finds
+      resp, data = HTTP.post("/pocket/default.aspx", {
+        "ctl00$ContentBody$PQListControl1$btnScheduleNow" => "Yes"
+      })
+
+      !!(data =~ /Your 'My Finds' Pocket Query has been scheduled to run./)
+    end
+
+    # Creates a new instance.  The following attributes may be specified
+    # as parameters:
+    #
+    # * +:guid+ — The Pocket Query’s GUID
+    #
+    # @param [Hash] attributes A hash of attributes
+    # @raise [ArgumentError] Trying to set an unknown attribute
+    def initialize(attributes = {})
+      attributes.each do |key, value|
+        if [:guid, :name, :results, :last_generated_at, :raw].include?(key)
+          if key == :last_generated_at and not value.kind_of?(Time)
+            raise TypeError, \
+              "Attribute `last_generated_at' must be an instance of Time"
+          end
+
+          if key == :results and not value.kind_of?(Fixnum)
+            raise TypeError, "Attribute `results' must be a number"
+          end
+
+          instance_variable_set("@#{key}", value)
+        else
+          raise ArgumentError, "Trying to set unknown attribute `#{key}'"
+        end
+      end
+    end
+
+    # Returns the Pocket Query’s GUID.
+    #
+    # @return [String] GUID
+    def guid
+      @guid
+    end
+
+    # Returns the Pocket Query’s name.
+    #
+    # @return [String] Name
+    def name
+      @name ||= begin
+        @gpx.xpath("/xmlns:gpx/xmlns:name").content if @gpx
+      end
+    end
+
+    # Returns the date the Pocket Query was last generated at.
+    #
+    # @return [Time] Last generated date
+    def last_generated_at
+      @last_generated_at ||= begin
+        if @gpx
+          # ...
+        end
+      end
+    end
+
+    # Returns the number of results inside the Pocket Query.
+    #
+    # @return [Fixnum] Number of results
+    def results
+      @results ||= begin
+        @caches.size if @caches
+      end
+    end
+
+    # Returns the Pocket Query’s raw data.  This may be either zipped data
+    # or a GPX document.
+    #
+    # @return [String] Raw data (zip or gpx)
+    def raw
+      @raw || begin
+        raise NotFetchedError, "You have to download the Pocket Query first"
+      end
+    end
+
+    # Returns the Nokogiri XML document object for the GPX tree.
+    #
+    # @return [Nokogiri::XML::Document] Nokogiri XML document
+    def gpx
+      @gpx || begin
+        raise NotFetchedError, "You have to download the Pocket Query first"
+      end
+    end
+
+    # Downloads and parses the Pocket Query.
+    #
+    # @return [void]
+    def download
+      raise LoginError unless HTTP.loggedin?
+
+      resp, @raw = HTTP.get("/pocket/downloadpq.ashx?g=#{guid}")
+      parse
+    end
+
+  private
+
+    # Parses the Pocket Query’s GPX document.
+    #
+    # @return [void]
+    def parse
+      unless @raw
+        raise NotFetchedError, "You have to download the Pocket Query first"
+      end
+
+      if @raw[0..2] == "PK"
+        raise "Support for zip Pocket Query isn’t implemented yet"
+      else
+        @gpx = Nokogiri::XML.parse(@raw)
+      end
+    end
+  end
+end

data/lib/geocaching/user.rb

@@ -1,18 +1,23 @@
+# encoding: utf-8
+
 require "time"
 
 module Geocaching
-  # This class represents an user on geocaching.com.
+  # The {User} class represents a user on geocaching.com.
+  #
+  # This class does caching.  If you want to override the cached information,
+  # call the {#fetch} method manually.
+  #
+  # == Usage
   #
   #  user = Geocaching::User.fetch(:guid => "...")
   #  puts user.name #=> "Jack"
   class User
-    # Create a new instance and call the {fetch} method afterwards.
-    # +:guid+ must be giveb as an attribute.
+    # Creates a new instance and calls the {fetch} method afterwards.
+    # +:guid+ must be given as an attribute.
     #
     # @param [Hash] attributes A hash of attributes
     # @raise [ArgumentError] No GUID given
-    # @raise [Geocaching::TimeoutError] Timeout hit
-    # @raise [Geocaching::HTTPError] HTTP request failed
     # @return [Geocaching::User]
     def self.fetch(attributes)
       user = new(attributes)
@@ -20,10 +25,11 @@ module Geocaching
       user
     end
 
-    # Create a new instance. The following attributes may be specified
+    # Creates a new instance.  The following attributes may be specified
     # as parameters:
     #
     # * +:guid+ — The user’s Globally Unique Identifier (GUID)
+    # * +:name+ — The user‘s name
     #
     # @param [Hash] attributes A hash of attributes
     # @raise [ArgumentError] Trying to set an unknown attribute
@@ -31,7 +37,7 @@ module Geocaching
       @data, @doc, @guid = nil, nil, nil
 
       attributes.each do |key, value|
-        if [:guid].include?(key)
+        if [:guid, :name].include?(key)
           instance_variable_set("@#{key}", value)
         else
           raise ArgumentError, "Trying to set unknown attribute `#{key}'"
@@ -39,12 +45,10 @@ module Geocaching
       end
     end
 
-    # Fetch user information from geocaching.com.
+    # Fetches user information from geocaching.com.
     #
     # @return [void]
     # @raise [ArgumentError] No GUID given
-    # @raise [Geocaching::TimeoutError] Timeout hit
-    # @raise [Geocaching::HTTPError] HTTP request failed
     def fetch
       raise ArgumentError, "No GUID given" unless @guid
 
@@ -52,27 +56,24 @@ module Geocaching
       @doc = Nokogiri::HTML.parse(@data)
     end
 
-    # Return whether user information have successfully been fetched
+    # Returns whether user information have successfully been fetched
     # from geocaching.com.
     #
-    # @return [Boolean]
+    # @return [Boolean] Have user information been fetched?
     def fetched?
       @data and @doc
     end
 
-    # Return the user’s Globally Unique Identifier (GUID).
+    # Returns the user’s Globally Unique Identifier (GUID).
     #
     # @return [String]
     def guid
       @guid
     end
 
-    # Return the user’s name.
+    # Returns the user’s name.
     #
     # @return [String]
-    # @raise [Geocaching::TimeoutError] Timeout hit
-    # @raise [Geocaching::HTTPError] HTTP request failed
-    # @raise [Geocaching::ExtractError] Could not extract name from website
     def name
       @name ||= begin
         raise NotFetchedError unless fetched?
@@ -82,17 +83,14 @@ module Geocaching
         if elements.size == 1 and elements.first.content =~ /Profile for User|Reviewer: (.+)/
           HTTP.unescape($1)
         else
-          raise ExtractError, "Could not extract name from website"
+          raise ParseError, "Could not extract name from website"
         end
       end
     end
 
-    # Return the user’s occupation.
+    # Returns the user’s occupation.
     #
-    # @return [String]
-    # @raise [Geocaching::TimeoutError] Timeout hit
-    # @raise [Geocaching::HTTPError] HTTP request failed
-    # @raise [Geocaching::ExtractError] Could not extract information from website
+    # @return [String] Occupation
     def occupation
       @occupation ||= begin
         raise NotFetchedError unless fetched?
@@ -102,17 +100,14 @@ module Geocaching
         if elements.size == 1
           HTTP.unescape(elements.first.content)
         else
-          raise ExtractError, "Could not extract occupation from website"
+          raise ParseError, "Could not extract occupation from website"
         end
       end
     end
 
-    # Return the user’s location.
+    # Returns the user’s location.
     #
-    # @return [String]
-    # @raise [Geocaching::TimeoutError] Timeout hit
-    # @raise [Geocaching::HTTPError] HTTP request failed
-    # @raise [Geocaching::ExtractError] Could not extract information from website
+    # @return [String] Location
     def location
       @location ||= begin
         raise NotFetchedError unless fetched?
@@ -122,17 +117,14 @@ module Geocaching
         if elements.size == 1
           HTTP.unescape(elements.first.content)
         else
-          raise ExtractError, "Could not extract location from website"
+          raise ParseError, "Could not extract location from website"
         end
       end
     end
 
-    # Return the user’s forum title.
+    # Returns the user’s forum title.
     #
-    # @return [String]
-    # @raise [Geocaching::TimeoutError] Timeout hit
-    # @raise [Geocaching::HTTPError] HTTP request failed
-    # @raise [Geocaching::ExtractError] Could not extract information from website
+    # @return [String] Forum title
     def forum_title
       @forum_title ||= begin
         raise NotFetchedError unless fetched?
@@ -142,17 +134,14 @@ module Geocaching
         if elements.size == 1
           HTTP.unescape(elements.first.content)
         else
-          raise ExtractError, "Could not extract forum title from website"
+          raise ParseError, "Could not extract forum title from website"
         end
       end
     end
 
-    # Return the user’s homepage.
+    # Returns the user’s homepage.
     #
-    # @return [String]
-    # @raise [Geocaching::TimeoutError] Timeout hit
-    # @raise [Geocaching::HTTPError] HTTP request failed
-    # @raise [Geocaching::ExtractError] Could not extract information from website
+    # @return [String] Homepage
     def homepage
       @homepage ||= begin
         raise NotFetchedError unless fetched?
@@ -162,12 +151,9 @@ module Geocaching
       end
     end
 
-    # Return the user’s statuses.
+    # Returns the user’s statuses.
     #
-    # @return [Array<String>]
-    # @raise [Geocaching::TimeoutError] Timeout hit
-    # @raise [Geocaching::HTTPError] HTTP request failed
-    # @raise [Geocaching::ExtractError] Could not extract information from website
+    # @return [Array<String>] Array of statuses
     def status
       @status ||= begin
         raise NotFetchedError unless fetched?
@@ -177,17 +163,14 @@ module Geocaching
         if elements.size == 1
           HTTP.unescape(elements.first.content).split(",").map(&:strip)
         else
-          raise ExtractError, "Could not extract status from website"
+          raise ParseError, "Could not extract status from website"
         end
       end
     end
 
-    # Return the user’s last visit date.
+    # Returns the user’s last visit date.
     #
-    # @return [Time]
-    # @raise [Geocaching::TimeoutError] Timeout hit
-    # @raise [Geocaching::HTTPError] HTTP request failed
-    # @raise [Geocaching::ExtractError] Could not extract information from website
+    # @return [Time] Last visit date
     def last_visit
       @last_visit ||= begin
         raise NotFetchedError unless fetched?
@@ -197,17 +180,14 @@ module Geocaching
         if elements.size == 1
           Time.parse(elements.first.content)
         else
-          raise ExtractError, "Could not extract last visit date from website"
+          raise ParseError, "Could not extract last visit date from website"
         end
       end
     end
 
-    # Return the user’s member since date.
+    # Returns the user’s member since date.
     #
-    # @return [Time]
-    # @raise [Geocaching::TimeoutError] Timeout hit
-    # @raise [Geocaching::HTTPError] HTTP request failed
-    # @raise [Geocaching::ExtractError] Could not extract information from website
+    # @return [Time] Member since date
     def member_since
       @member_since ||= begin
         raise NotFetchedError unless fetched?
@@ -217,33 +197,30 @@ module Geocaching
         if elements.size == 1
           Time.parse(elements.first.content)
         else
-          raise ExtractError, "Could not extract member since date from website"
+          raise ParseError, "Could not extract member since date from website"
         end
       end
     end
 
-    # Return whether the user is a reviewer.
+    # Returns whether the user is a reviewer.
     #
-    # @return [Boolean]
-    # @raise [Geocaching::TimeoutError] Timeout hit
-    # @raise [Geocaching::HTTPError] HTTP request failed
-    # @raise [Geocaching::ExtractError] Could not extract information from website
+    # @return [Boolean] Is user a reviewer?
     def reviewer?
       status.include?("Reviewer")
     end
 
-    # Return whether the user is a premium member.
+    # Returns whether the user is a Premium Member.
     #
-    # @return [Boolean]
-    # @raise [Geocaching::TimeoutError] Timeout hit
-    # @raise [Geocaching::HTTPError] HTTP request failed
-    # @raise [Geocaching::ExtractError] Could not extract information from website
+    # @return [Boolean] Is user a Premium Member?
     def premium_member?
       status.include?("Premium Member")
     end
 
   private
 
+    # Returns the HTTP request path.
+    #
+    # @return [String] HTTP request path
     def path
       "/profile/?guid=#{guid}"
     end