regentanz 0.2.0

data/.gitignore

@@ -0,0 +1,5 @@
+.DS_Store
+pkg
+*~
+*.swp
+Gemfile.lock

data/CHANGELOG.rdoc

@@ -0,0 +1,22 @@
+== CHANGELOG
+
+=== v0.1.4 // 2011-10-14
+* Fixed bug that caused forecast to have the current day only
+* present? now properly returns its true state (as opposed to always false)
+* Known issue: {current_date_time node always returns the beginning of The Epoch}[https://github.com/carpodaster/regentanz/issues/1] (API problem)
+
+=== v0.1.2 // 2011-04-19
+* Retry state is tracked by cache backend
+* Removed OpenStruct by adding Conditions::Forecast and Conditions::Current
+* XML-Parsing is down in parser class
+
+=== v0.1.0 // 2011-04-16
+* Moved caching into separate module
+
+=== v0.0.5 // 2011-04-15
+* Removed RAILS_ROOT
+* Moved constants into class-wide configuration
+* Callback-stubs
+
+=== v0.0.1 // 2011-04-13
+* Initially packaged model as a gem

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in regentanz.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,24 @@
+Copyright (c) 2011, Carsten Zimmermann
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * Neither the name of the original author / copyright holder nor the
+      names of its contributors may be used to endorse or promote products
+      derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.rdoc

@@ -0,0 +1,46 @@
+== Regentanz
+*Regentanz* (German: <i>rain dance</i>) is a Ruby library to connect to Google's
+innofficial (ie. undocumented and unsupported) weather API.
+
+=== Installation
+The gem is not published yet and can be installed from github:
+ git clone git://github.com/kaupertmedia/regentanz.git
+ cd regentanz
+ gem build regentanz.gemspec
+ gem install regentanz-<gemversion>.gem
+
+Much easier using bundler:
+ # Gemfile
+ gem 'regentanz', :git => "git://github.com/carpodaster/regentanz"
+
+=== Usage
+Supply a location and a language to retrieve weather:
+  weather = Regentanz::GoogleWeather.new(:location => "Berlin, Germany", :lang => :en)
+  weather.current   # current condition
+  weather.forecast  # array with forecast conditions
+
+It uses <b>file-based caching</b> by default, other cache backends will follow.
+See {Regentanz::Cache::Base}[https://github.com/carpodaster/regentanz/blob/master/lib/regentanz/cache/base.rb]
+for details (and if you want to create your own backend).
+
+=== Configuration
+*Regentanz* can either be configured through a configure block or directly via
+its configuration object. It uses sane defaults so there should be no need for
+configuration to start right off. If you're using *Regentanz* with Rails,
+a file in <tt>config/initializers</tt> is your friend.
+
+Configure block:
+ Regentanz.configure do |config|
+   config.cache_backend Regentanz::Cache::File 
+   config.cache_dir "/path/to/cache_file"
+ end
+
+Direct configuration:
+ Regentanz.configuration.cache_dir = "/some/other/path"
+ 
+See {Regentanz::Configuration}[https://github.com/carpodaster/regentanz/blob/master/lib/regentanz/configuration.rb]
+for a full list of configurable options.
+
+=== Credits
+*Regentanz* is based upon and extracted from a standalone Ruby class made for
+{berlin.kauperts.de}[http://berlin.kauperts.de] by {kaupert media gmbh}[http://kaupertmedia.de].

data/Rakefile

@@ -0,0 +1,23 @@
+require 'rubygems'
+require 'bundler'
+Bundler::GemHelper.install_tasks
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Regentanz'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/lib/regentanz/astronomy.rb

@@ -0,0 +1,69 @@
+module Regentanz
+  # :nodoc:
+  # Code taken from http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/264573
+  module Astronomy
+    include Math
+    
+    private
+    # :doc:
+
+    def sun_rise_set(mode, lat, lng, zenith = 90.8333)
+      #step 1: first calculate the day of the year
+      mode = mode.to_sym
+      date = Date.today
+      n=date.yday
+
+      #step 2: convert the longitude to hour value and calculate an approximate time
+      lng_hour=lng/15
+      t = n+ ((6-lng_hour)/24) if mode==:sunrise
+      t = n+ ((18-lng_hour)/24) if mode==:sunset
+
+      #step 3: calculate the sun's mean anomaly
+      m = (0.9856 * t) - 3.289
+
+      #step 4: calculate the sun's true longitude
+      l = (m+(1.1916 * sin(deg_to_rad(m))) + (0.020 * sin(deg_to_rad(2*m))) + 282.634) % 360
+
+      #step 5a: calculate the sun's right ascension
+      ra = rad_to_deg(atan(0.91764 * tan(deg_to_rad(l)))) % 360
+
+      #step 5b: right ascension value needs to be in the same quadrant as L
+      lquadrant  = (l/90).floor*90
+      raquadrant = (ra/90).floor*90
+      ra         = ra+(lquadrant-raquadrant)
+
+      #step 5c: right ascension value needs to be converted into hours
+      ra/=15
+
+      #step 6: calculate the sun's declination
+      sin_dec = 0.39782 * sin(deg_to_rad(l))
+      cos_dec = cos(asin(sin_dec))
+      #step 7a: calculate the sun's local hour angle
+      cos_h = (cos(deg_to_rad(zenith)) - (sin_dec * sin(deg_to_rad(lat)))) / (cos_dec * cos(deg_to_rad(lat)))
+
+      return nil if (not (-1..1).include? cos_h)
+
+      #step 7b: finish calculating H and convert into hours
+      h = (360 - rad_to_deg(acos(cos_h)))/15 if mode==:sunrise
+      h = (rad_to_deg(acos(cos_h)))/15       if mode==:sunset
+
+      #step 8: calculate local mean time
+      t = h + ra - (0.06571 * t) - 6.622
+      t %=24
+
+      #step 9: convert to UTC
+      return (date.to_datetime+(t - lng_hour)/24).to_time.getlocal
+    end
+
+    # Convenience helper
+    def deg_to_rad(degrees)
+      degrees*PI/180
+    end
+
+    # Convenience helper
+    def rad_to_deg(radians)
+      radians*180/PI
+    end
+
+  end
+end

data/lib/regentanz/cache/base.rb

@@ -0,0 +1,51 @@
+module Regentanz
+
+  module Cache
+
+    class Base
+
+      # Checks if +instance_or_class+ complies to cache backend duck type,
+      # ie. if it reponds to all mandatory methods
+      def self.lint(instance_or_class)
+        instance = instance_or_class.is_a?(Class) ? instance_or_class.new : instance_or_class
+        [:set, :get, :available?, :expire!, :valid?].inject(true) do |memo, method|
+          memo && instance.respond_to?(method)
+        end
+      end
+
+      # Returns a alpha-numeric cache key
+      def self.sanitize_key(key)
+        Digest::SHA1.hexdigest(key.to_s)
+      end
+
+      # Stores cache +value+ as +key+.
+      def set(key, value); end
+
+      # Retrieves cached value from +key+.
+      def get(key); end
+
+      # Checks if cache under +key+ is available.
+      def available?(key); end
+
+      # Deletes cache under +key+.
+      def expire!(key); end
+
+      # Checks if cache under +key+ is still valid.
+      def valid?(key); end
+
+      # Returns whether or not weather retrieval from the API
+      # is currently waiting for a timeout to expire
+      def waiting_for_retry?; end
+
+      # Checks if we've waited enough. Unsets a possible retry
+      # state (and returns true) if so or returns false if not
+      def unset_retry_state!; end
+
+      # Persists a timeout state
+      def set_retry_state!; end
+
+    end
+
+  end
+  
+end

data/lib/regentanz/cache/file.rb

@@ -0,0 +1,86 @@
+module Regentanz
+
+  module Cache
+
+    # Implements file-based caching. Cache files are stored in
+    # +Regentanz.configuration.cache_dir+ and are prefixed with
+    # +Regentanz.configuration.cache_prefix+.
+    class File < Regentanz::Cache::Base
+
+      # Cache is available (n.b. not necessarily #valid?) if a file
+      # exists for +key+
+      def available?(key)
+        ::File.exists?(filename(key)) rescue nil
+      end
+
+      # Unlinks the cache file for +key+
+      def expire!(key)
+        return false unless available?(key)
+        begin
+          ::File.delete(filename(key))
+          true
+        rescue
+        end
+      end
+
+      def filename(key)
+        ::File.join(Regentanz.configuration.cache_dir, "#{Regentanz.configuration.cache_prefix}_#{key}.xml")
+      end
+
+      # Retrieves content of #filename for +key+
+      def get(key)
+        if available?(key)
+          ::File.open(filename(key), "r") { |file| file.read } rescue nil
+        end
+      end
+
+      # Stores +value+ in #filename for +key+
+      def set(key, value)
+        begin
+          ::File.open(filename(key), "w") { |file| file.puts value }
+          filename(key)
+        rescue
+        end
+      end
+
+      def valid?(key)
+        return false unless available?(key)
+        begin
+          # TODO delegate XML parsing and verification
+          doc  = REXML::Document.new(get(key))
+          node = doc.elements["xml_api_reply/weather/forecast_information/current_date_time"]
+          time = node.attribute("data").to_s.to_time if node
+          time > Regentanz.configuration.cache_ttl.seconds.ago
+        rescue
+          # TODO pass exception upstream until properly delegated in the first place?
+        end
+      end
+
+      # Returns whether or not weather retrieval from the API
+      # is currently waiting for a timeout to expire; here: existence of
+      # a retry marker file
+      def waiting_for_retry?
+        ::File.exists?(Regentanz.configuration.retry_marker)
+      end
+
+      # Checks if we've waited long enough. Deletes a possible retry
+      # marker file (and returns true) if so or returns false if not
+      def unset_retry_state!
+        marker = Regentanz.configuration.retry_marker
+        if waiting_for_retry? and ::File.new(marker).mtime < Regentanz.configuration.retry_ttl.seconds.ago
+          ::File.delete(marker) if ::File.exists?(marker)
+          true
+        end
+      end
+
+      # Persists the timeout state by writing a retry_marker file
+      def set_retry_state!
+        ::File.open(Regentanz.configuration.retry_marker, "w+").close
+        waiting_for_retry?
+      end
+
+    end
+
+  end
+
+end

data/lib/regentanz/cache.rb

@@ -0,0 +1,2 @@
+require 'regentanz/cache/base'
+require 'regentanz/cache/file'

data/lib/regentanz/callbacks.rb

@@ -0,0 +1,18 @@
+module Regentanz
+  module Callbacks
+
+    CALLBACKS = [:api_failure_detected, :api_failure_resumed]
+
+    CALLBACKS.each do |callback_method|
+      # Define no-op stubs for all CALLBACKS
+      define_method(callback_method) {}
+      private callback_method
+    end
+
+    def self.included(base)
+      base.send :include, ActiveSupport::Callbacks
+      base.define_callbacks *CALLBACKS
+    end
+    
+  end
+end

data/lib/regentanz/conditions/base.rb

@@ -0,0 +1,16 @@
+module Regentanz
+  module Conditions
+    class Base
+
+      attr_accessor :condition, :style, :icon
+
+      def initialize(attributes = {})
+        attributes.symbolize_keys!
+        attributes.keys.each do |attr|
+          self.send(:"#{attr}=", attributes[attr]) if respond_to?(:"#{attr}=")
+        end
+      end
+      
+    end
+  end
+end

data/lib/regentanz/conditions/current.rb

@@ -0,0 +1,14 @@
+module Regentanz
+  module Conditions
+    
+    class Current < Regentanz::Conditions::Base
+
+      attr_reader   :temp_c, :temp_f
+      attr_accessor :humidity, :wind_condition
+
+      def temp_c=temp; @temp_c = temp.to_i; end
+      def temp_f=temp; @temp_f = temp.to_i; end
+
+    end
+  end
+end

data/lib/regentanz/conditions/forecast.rb

@@ -0,0 +1,14 @@
+module Regentanz
+  module Conditions
+    
+    class Forecast < Regentanz::Conditions::Base
+
+      attr_reader   :high, :low
+      attr_accessor :day_of_week
+
+      def high=temp; @high = temp.to_i; end
+      def low=temp; @low = temp.to_i; end
+
+    end
+  end
+end

data/lib/regentanz/conditions.rb

@@ -0,0 +1,3 @@
+require 'regentanz/conditions/base'
+require 'regentanz/conditions/current'
+require 'regentanz/conditions/forecast'

data/lib/regentanz/configuration.rb

@@ -0,0 +1,55 @@
+module Regentanz
+  require "tmpdir"
+
+  class Configuration
+
+    DEFAULT_OPTIONS = [
+      :base_url,
+      :cache_backend,
+      :cache_dir,
+      :cache_prefix,
+      :cache_ttl,
+      :retry_marker,
+      :retry_ttl
+    ]
+
+    OPTIONS = DEFAULT_OPTIONS + [
+      :do_not_get_weather,
+      :suppress_stderr_output
+    ]
+
+    # Define default values
+    @@default_base_url      = "http://www.google.com/ig/api"
+    @@default_cache_backend = Regentanz::Cache::File
+    @@default_cache_dir     = Dir.tmpdir
+    @@default_cache_prefix  = "regentanz"
+    @@default_cache_ttl     = 14400 # 4 hours
+    @@default_retry_ttl     = 3600  # 1 hour
+    @@default_retry_marker  = File.join(@@default_cache_dir, "#{@@default_cache_prefix}_api_retry.txt")
+    
+    OPTIONS.each { |opt|  attr_accessor(opt) }
+    DEFAULT_OPTIONS.each { |cvar| cattr_reader(:"default_#{cvar}", :instance_reader => false) } # class getter for all DEFAULT_OPTION cvars
+
+    # Stores global configuration information for +Regentanz+.
+    #
+    # == Default Options
+    # * +base_url+: HTTP API, request-specific calls will be appended (default: +http://www.google.com/ig/api+)
+    # * +cache_backend+: defaults to +Regentanz::Cache::File+
+    # * +cache_dir+: defaults to +Dir.tmpdir+
+    # * +cache_prefix+: String to prefix both cache file and retry_marker (if not specified otherwise) with
+    # * +cache_ttl+: time in seconds for which cache data is considered valid. Default: 14400 (4 hours).
+    # * +retry_ttl+: time in seconds Regentanz should wait until it tries to call the API again when it failed before. Default: 3600 (1 hour).
+    # * +retry_marker+: persist a marker-file here to indicate a failed API state. Supply a full pathname.
+    #
+    # == Options
+    # * +do_not_get_weather+: don't try to retrieve weather data, neither from cache nor remote API. Intended for testing.
+    # * +suppress_stderr_output+: called from GoogleWeather#error_output, silences Regentanz' output. Intended for testing.
+    def initialize(*args)
+      DEFAULT_OPTIONS.each do |option|
+        self.send(:"#{option}=", self.class.send(:class_variable_get, :"@@default_#{option}") )
+      end
+    end
+
+  end
+
+end

data/lib/regentanz/configurator.rb

@@ -0,0 +1,22 @@
+module Regentanz
+  class << self
+
+    attr_writer :configuration
+    def configuration #:nodoc:
+      @configuration ||= Configuration.new
+    end
+
+    # Call this method to modify defaults in your initializers.
+    # See Regentanz::Configuration for supported config options.
+    #
+    # === Example usage
+    #   Regentanz.configure do |config|
+    #     config.<supported_config_option> = :bar
+    #   end
+    def configure
+      self.configuration ||= Configuration.new
+        yield(configuration)
+    end
+
+  end
+end

data/lib/regentanz/google_weather.rb

@@ -0,0 +1,151 @@
+module Regentanz
+  class GoogleWeather
+    require 'net/http'
+    require 'rexml/document'
+    require 'ostruct'
+
+    include Astronomy
+    include Callbacks
+
+    attr_accessor :location, :cache_id
+    attr_reader   :cache, :current, :forecast, :lang, :parser, :xml
+
+    # Creates an object and queries the weather API.
+    #
+    # === Parameters
+    # * +options+ A hash
+    #
+    # === Available options
+    # * +location+ String to pass to Google's weather API (mandatory)
+    # * +cache_id+ enables caching with a unique identifier to locate a cached file
+    # * +geodata+ a hash with keys :lat and :lng, required for sunset/-rise calculations
+    # * +lang+ Desired language for the returned results (Defaults to "de")
+    def initialize(*args)
+      options = args.extract_options!
+      @options  = options.symbolize_keys
+      @parser = Parser::GoogleWeather.new
+      self.location = args.first || options[:location]
+      self.lang = options[:lang]
+
+      # Activate caching
+      if Regentanz.configuration.cache_backend
+        @cache    = Regentanz.configuration.cache_backend.new if Regentanz.configuration.cache_backend
+        @cache_id = options[:cache_id] || Regentanz.configuration.cache_backend.sanitize_key(@location)
+      end
+
+      @geodata  = options[:geodata] if options[:geodata] and options[:geodata][:lat] and options[:geodata][:lng]
+      get_weather() unless Regentanz.configuration.do_not_get_weather
+    end
+
+    # Loads weather data from known data sources (ie. cache or external API)
+    def get_weather!; get_weather(); end
+
+    # Input sanitizer-setter, defaults to "de"
+    def lang=(lang)
+      @lang = lang.present? ? lang.to_s : "de"
+    end
+
+    # Provide an accessor to see if we actually got weather info at all.
+    def present?
+      current.present? or forecast.present?
+    end
+
+    def sunrise
+      @sunrise ||= @geodata.blank? ? nil : sun_rise_set(:sunrise, @geodata[:lat], @geodata[:lng])
+    end
+
+    def sunset
+      @sunset  ||= @geodata.blank? ? nil : sun_rise_set(:sunset, @geodata[:lat], @geodata[:lng])
+    end
+
+    def waiting_for_retry?
+      @cache && @cache.waiting_for_retry?
+    end
+
+    private
+
+    # Encapsulate output of error messages. Will output to $stderr unless
+    # Regentanz.configuration.suppress_stderr_output is set
+    #
+    # === Parameters
+    # * +output+: String to output
+    def error_output(output)
+      $stderr.puts output unless Regentanz.configuration.suppress_stderr_output
+    end
+
+    # Proxies +do_request+ and +parse_request+
+    def get_weather
+      if cache_valid?
+        @xml = @parser.convert_encoding(@cache.get(@cache_id))
+      else
+        @xml = @parser.convert_encoding(do_request(Regentanz.configuration.base_url + "?weather=#{CGI::escape(@location)}&hl=#{@lang}"))
+        if @cache
+          @cache.expire!(@cache_id)
+          @cache.set(@cache_id, @xml)
+        end
+    end
+      parse_xml() if @xml
+    end
+
+    # Makes an outbound HTTP-request and returns the request body (ie. the XML)
+    #
+    # === Parameters
+    # * +url+ API-URL with protocol, fqdn and URI
+    def do_request(url)
+      begin
+        Net::HTTP.get_response(URI.parse(url)).body
+      rescue => e
+        error_output(e.message)
+      end
+    end
+
+    # Parses the raw data and Sets the +current+ and +forecast+ variables.
+    #
+    # Assumes the instance var +xml+ is set.
+    def parse_xml
+      begin
+        @current = @parser.parse_current!(@xml)
+        @forecast = @parser.parse_forecast!(@xml)
+      rescue REXML::ParseException => e
+        error_output(e.message)
+      end
+    end
+
+    # Returns +true+ if a given cache file contains data not older than Regentanz::Configuration#cache_ttl seconds
+    # TODO properly use cache backend's #valid?
+    def cache_valid?
+      validity = false
+      if @cache and @cache.available?(@cache_id)
+        begin
+          doc  = REXML::Document.new(@cache.get(@cache_id))
+          node = doc.elements["xml_api_reply/weather/forecast_information/current_date_time"]
+          time = node.attribute("data").to_s.to_time if node
+          validity = time ? time > Regentanz.configuration.cache_ttl.seconds.ago : false
+        rescue REXML::ParseException
+          retry_after_incorrect_api_reply
+          validity = waiting_for_retry? # not really valid, but we need to wait a bit.
+        end
+      end
+      validity
+    end
+
+    # Brings the outbound API-calls to a halt for Regentanz::Configuration#retry_ttl seconds by creating
+    # a marker file. Flushes the incorrect cached API response after Regentanz::Configuration#retry_ttl
+    # seconds.
+    def retry_after_incorrect_api_reply
+      if !waiting_for_retry? and @cache
+        # We are run for the first time, create the marker file
+        # TODO remove dependency to SupportMailer class
+        api_failure_detected # callback
+        SupportMailer.deliver_weather_retry_marker_notification!(self, :set)
+        @cache.set_retry_state!
+      elsif @cache and @cache.unset_retry_state!
+        # Marker file is old enough, delete the (invalid) cache file and remove the marker_file
+        @cache.expire!(@cache_id)
+        api_failure_resumed # callback
+        SupportMailer.deliver_weather_retry_marker_notification!(self, :unset)
+      end
+    end
+
+  end
+end