attack-barometer 0.1.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Mark
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,266 @@
+= barometer
+
+A multi API consuming weather forecasting superstar.
+
+Barometer provides a common public API to one or more weather services (APIs)
+of your choice.  Weather services can co-exist to retrieve extensive
+information, or they can be used in a hierarchical configuration where lower
+preferred weather services are only used if previous services are
+unavailable.
+
+== status
+
+Currently this project is in development and will only work for a few weather
+services (wunderground, google, yahoo).
+
+Features to be added before first release:
+- gem setup/config, apply to rubyforge
+
+Features to be added in future releases:
+- even more weather service drivers (noaa, weather.com, weatherbug)
+- ability to query multiple services and combine/average the results
+- support iaco as a query format
+
+= dependencies
+
+=== HTTParty
+
+Why? HTTParty was created and designed specifically for consuming web services.
+I choose to use this over using the Net::HTTP library directly to allow for
+faster development of this project.
+
+HTTParty is also extended to include configurable Timoout support.
+
+=== tzinfo
+
+Why? Barometer deals with time information for locations all over the world.
+This information doesn't mean that much if it can't be converted to times 
+that don't correspond to the applicable timezone.
+Tzinfo handles this time zone manipulation.
+
+=== graticule (very soft dependency)
+
+Why? Barometer returns the weather for a given location.  Most weather service
+APIs are somewhat restricted on the query format they receive.  To bridge
+this gap and allow for maximum flexibility on the 'barometer' query format,
+the query will be geo-coded using the Google geocoding service, if required.
+Graticule can provide this geocoding interface.
+
+Using Graticule requires a free Google API key for geocoding.  It is possible
+to use barometer without geocoding, though your query format will be
+limited to that of the weather service API.
+
+ALTERNATE: If you supply a Google API key but don't install the Graticule gem,
+HTTParty will be used instead to provide the same geocoding.  Basically
+Graticule is only used if it exists.
+
+NOTE: you can force Barometer not to use Graticule, even if you have it installed
+using the following:
+
+  Barometer.skip_graticule = true
+
+= usage
+
+You can use barometer right out of the box, as it is configured to use one
+register-less (no API key required) international weather service
+(wunderground.com).
+
+For better results, signup for a google-map key and enhance your barometer
+with geo-coding.
+
+  require 'barometer'
+  
+  Barometer.google_geocode_key = "THE_GOOGLE_API_KEY"
+  barometer = Barometer.new("Paris")
+  weather = barometer.measure
+  
+  puts weather.current.temperture
+  
+== multiple weather API, with hierarchy
+
+  require 'barometer'
+  
+  Barometer.google_geocode_key = "THE_GOOGLE_API_KEY"
+  # use yahoo and google, if they both fail, use wunderground
+  Barometer.selection = { 1 => [:yahoo, :google], 2 => :wunderground }
+
+  barometer = Barometer.new("Paris")
+  weather = barometer.measure
+
+  puts weather.current.temperture
+  
+== command line
+
+You can use barometer from the command line. 
+  
+  # barometer berlin
+  
+This will output the weather information for the given query.
+  
+=== fail
+
+What would cause a weather service to fail?  The most obvious is that the
+particular weather service in currently unavailable or not reachable.
+Other possible reasons would include not having the API (or a valid API
+key for the particular weather service, if required), not providing a
+valid query, or providing a query for a location not supported by the
+weather service.
+
+For example, if you look at the example above, the query of "Paris" refers
+to a city in France.  Yahoo weather services only supports
+weather results for USA (at least at the time of writing).  Therefore, 
+Barometer would not use Yahoo, just Google and failover to use Wunderground
+(if needed).
+
+=== bootstrapping
+
+You can use weather service drivers directly.  Below is an example to use
+Wunderground, but since the driver interface is abstracted it will be the
+same for all supported services.
+
+  require 'barometer'
+  Barometer.google_geocode_key = "THE_GOOGLE_API_KEY"
+  
+  query = Barometer::Query.new("Paris")
+  weather = Barometer::Service.source(:wunderground).measure(query)
+  
+  puts weather.current.temperture
+  
+  # OR, even more raw
+  
+  measurement = Barometer::Measurement.new
+  weather = Barometer::Wunderground.measure_all(measurement, "Paris")
+  
+  puts weather.current.temperture
+  
+  
+NOTE: The disadvantage to using the drivers directly is that you lose the
+advantage of redundancy/failover added by the Module as a whole.
+
+NOTE: You still must create the Barometer::Query object with your query
+string instead of directly feeding the query string to the service (as in
+bootstrap example #1).  The Barometer::Query object has behavior required
+by the service that a regular String doesn't have. Using a driver directly
+WILL accept a String (as in bootstrap example #2).
+
+== searching
+
+After you have measured the data, Barometer provides several methods to help
+you get the data you are after. All examples assume you already have measured
+the data as shown in the above examples.
+
+=== by preference (default service)
+
+  weather.default         # returns measurement for default source
+  weather.current         # returns current_measurement for default
+  weather.now             # returns current_measurement for default
+  weather.forecast        # returns all forecast_measurements for default
+  weather.today           # returns forecast_measurement for default today
+  weather.tomorrow        # returns forecast_measurement for default tomorrow
+  
+  puts weather.now.temperature.c
+  puts weather.tomorrow.high.c
+
+=== by source
+
+  weather.source(:wunderground)   # returns measurement for specified source
+  weather.sources                 # lists all successful sources
+  
+  puts weather.source(:wunderground).current.temperature.c
+
+=== by date
+
+  # note, the date is the date of the locations weather, not the date of the
+  # user measuring the weather
+  date = Date.parse("01-01-2009")
+  weather.for(date)       # returns forecast_measurement for default on date 
+  weather.source(:wunderground).for(date)   # same as above but specific source
+  
+  puts weather.source(:wunderground).for(date).high.c
+
+=== by time
+
+  # note, the time is the time of the locations weather, not the time of the
+  # user measuring the weather
+  time = Time.parse("13:00 01-01-2009")
+  weather.for(time)       # returns forecast_measurement for default at time 
+  weather.source(:wunderground).for(time)   # same as above but specific source
+  
+  puts weather.source(:wunderground).for(time).low.f
+  
+== simple answers
+
+After you have measured the data, Barometer provides several "simple answer"
+methods to help you get answers to some basic questions. All examples assume
+you already have measured the data as shown in the above examples.
+
+All of these questions are ultimately specific to the weather source(s) you
+are configured to use.  All sources that have successfully measured data
+will be asked, but if there is no data that can answer the question then
+there will be no answer.
+
+=== is it windy?
+
+  # 1st parameter is the threshold wind speed for being windy
+  # 2nd parameter is the utc_time for which you want to know the answer,
+  #   this defaults to the current time
+  # NOTE: in my example the values are metric, so the threshold is 10 kph
+
+  weather.windy?(10)
+  
+=== is it wet?
+
+  # 1st parameter is the threshold pop (%) for being wet
+  # 2nd parameter is the utc_time for which you want to know the answer,
+  #   this defaults to the current time
+  # NOTE: in my example the threshold is 50 %
+
+  weather.wet?(50)
+
+=== is it sunny?
+
+  # 1st parameter is the utc_time for which you want to know the answer,
+  #   this defaults to the current time
+
+  weather.sunny?
+
+=== is it day?
+
+  # 1st parameter is the utc_time for which you want to know the answer,
+  #   this defaults to the current time
+
+  weather.day?
+
+=== is it night?
+
+  # 1st parameter is the utc_time for which you want to know the answer,
+  #   this defaults to the current time
+
+  weather.night?
+
+= design
+
+- create a Barometer instance
+- supply a query, there are very little restrictions on the format:
+  - city, country, specific address (basically anything Google will geocode)
+  - US zip code (skips geocoding if weather service accepts this directly)
+  - postal code (skips geocoding if weather service accepts this directly)
+  - latitude and longitude (skips geocoding if weather service accepts this
+    directly)
+  - TODO: international airport code (skips geocoding if weather service
+    accepts this directly)
+- if geocoding required, geocode the query
+- determine which weather services will be queried (one or multiple)
+- query the weather services
+- save the data
+- repeat weather service queries as needed
+
+= extending
+
+Barometer attempts to be a common API to any weather service API.  I have included
+several weather service 'drivers', but I know there are many more available.
+Please use the provided ones as examples to create more.
+
+== copyright
+
+Copyright (c) 2009 Mark G. See LICENSE for details.

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:major: 0
+:minor: 1
+:patch: 0

data/bin/barometer

@@ -0,0 +1,63 @@
+#!/usr/bin/env ruby
+ 
+require File.dirname(__FILE__) + '/../lib/barometer'
+#require 'rubygems'
+#require 'attack-barometer'
+
+# TODO
+
+# set default Google Key ... maybe need a config file?
+Barometer.google_geocode_key = "ABQIAAAAq8TH4offRcGrok8JVY_MyxRi_j0U6kJrkFvY4-OX2XYmEAa76BSFwMlSow1YgX8BOPUeve_shMG7xw"
+
+# take command line paramters
+# service: --yahoo, --wunderground, --google
+# units: -m --metric, -i --imperial
+# geocode: -g --geocode (force geocode)
+# timeout: -t 15 --timeout 15
+# skip: --skip (skip graticule)
+# help: -h --help
+# wet threshold: -w --wet
+# windy threshold: -v --wind
+# pop threshold: -p --pop
+# time: -a --at
+
+# prettier output
+# show simple answers
+# more help
+# error display (out of sources, etc.)
+ 
+if ARGV.size == 0
+  puts 'Barometer [Powered by wunderground]'
+  puts 'USAGE: barometer [query]'
+  puts 'EXAMPLES:'
+  puts ' barometer paris'
+  exit
+end
+ 
+barometer = Barometer.new(ARGV[0])
+weather = barometer.measure(true)
+
+def y(value)
+  value ? "yes" : "no"
+end
+
+if weather
+  puts "###################################################"
+  puts "#  #{weather.default.location.name}"
+  puts "#"
+  puts "#  (lat: #{weather.default.location.latitude}, long: #{weather.default.location.longitude})"
+  puts "###################################################"
+  puts " -- CURRENT --"
+  puts " temperature: #{weather.now.temperature}"
+  puts
+  puts " -- QUESTIONS --"
+  puts " day?  : #{y(weather.day?)}"
+  puts " sunny?: #{y(weather.sunny?)}"
+  puts " windy?: #{y(weather.windy?)}"
+  puts " wet?  : #{y(weather.wet?)}"
+  puts
+  puts
+  puts " -- INFO --"
+  puts " http://github.com/attack/barometer"
+  puts "---------------------------------------------------"
+end

data/lib/barometer/base.rb

@@ -0,0 +1,52 @@
+module Barometer
+
+  class Base
+    
+    # allow the configuration of specific weather APIs to be used,
+    # and the order in which they would be used
+    @@selection = { 1 => [:wunderground] }
+    def self.selection; @@selection; end;
+    def self.selection=(hash); @@selection = hash; end;
+    
+    attr_reader   :query
+    attr_accessor :weather, :success
+    
+    def initialize(query=nil)
+      @query = Barometer::Query.new(query)
+      @weather = Barometer::Weather.new
+      @success = false
+    end
+    
+    def measure(metric=nil)
+      return nil unless @query
+
+      level = 1
+      until self.success?
+        if sources = @@selection[level]
+          if sources.is_a?(Array)
+            sources.each do |source|
+              measurement = Barometer.source(source.to_sym).measure(@query, metric)
+              @success = true if measurement.success?
+              @weather.measurements << measurement
+            end
+          else  
+            measurement = Barometer.source(sources.to_sym).measure(@query, metric)
+            @success = true if measurement.success?
+            @weather.measurements << measurement
+          end
+        else
+          raise OutOfSources
+        end
+        level += 1
+      end
+      
+      @weather
+    end
+    
+    def success?
+      @success
+    end
+
+  end
+
+end

data/lib/barometer/data/current.rb

@@ -0,0 +1,93 @@
+module Barometer
+  #
+  # Current Measurement
+  # a data class for current weather conditions
+  #
+  # This is basically a data holding class for the current weather
+  # conditions.
+  #
+  class CurrentMeasurement
+    
+    attr_accessor :time, :local_time
+    attr_reader :humidity, :icon, :condition
+    attr_reader :temperature, :dew_point, :heat_index, :wind_chill
+    attr_reader :wind, :pressure, :visibility, :sun
+    
+    def time=(time)
+      #raise ArgumentError unless time.is_a?(Time)
+      @time = time
+    end
+    
+    def humidity=(humidity)
+      raise ArgumentError unless
+        (humidity.is_a?(Fixnum) || humidity.is_a?(Float))
+      @humidity = humidity
+    end
+    
+    def icon=(icon)
+      raise ArgumentError unless icon.is_a?(String)
+      @icon = icon
+    end
+    
+    def condition=(condition)
+      raise ArgumentError unless condition.is_a?(String)
+      @condition = condition
+    end
+    
+    def temperature=(temperature)
+      raise ArgumentError unless temperature.is_a?(Barometer::Temperature)
+      @temperature = temperature
+    end
+    
+    def dew_point=(dew_point)
+      raise ArgumentError unless dew_point.is_a?(Barometer::Temperature)
+      @dew_point = dew_point
+    end
+    
+    def heat_index=(heat_index)
+      raise ArgumentError unless heat_index.is_a?(Barometer::Temperature)
+      @heat_index = heat_index
+    end
+    
+    def wind_chill=(wind_chill)
+      raise ArgumentError unless wind_chill.is_a?(Barometer::Temperature)
+      @wind_chill = wind_chill
+    end
+    
+    def wind=(wind)
+      raise ArgumentError unless wind.is_a?(Barometer::Speed)
+      @wind = wind
+    end
+    
+    def pressure=(pressure)
+      raise ArgumentError unless pressure.is_a?(Barometer::Pressure)
+      @pressure = pressure
+    end
+    
+    def visibility=(visibility)
+      raise ArgumentError unless visibility.is_a?(Barometer::Distance)
+      @visibility = visibility
+    end
+    
+    def sun=(sun)
+      raise ArgumentError unless sun.is_a?(Barometer::Sun)
+      @sun = sun
+    end
+    
+    #
+    # helpers
+    #
+    
+    # creates "?" helpers for all attributes (which maps to nil?)
+    def method_missing(method,*args)
+      # if the method ends in ?, then strip it off and see if we
+      # respond to the method without the ?
+      if (call_method = method.to_s.chomp!("?")) && respond_to?(call_method)
+        return send(call_method).nil? ? false : true
+      else
+        super(method,*args)
+      end
+    end
+    
+  end
+end

data/lib/barometer/data/distance.rb

@@ -0,0 +1,131 @@
+module Barometer
+  #
+  # A simple Distance class
+  # 
+  # Think of this like the Integer class. Enhancement
+  # is that you can create a number (in a certain unit), then
+  # get that number back already converted to another unit.
+  #
+  # All comparison operations will be done in metric
+  # 
+  # NOTE: this currently only supports the scale of
+  #       kilometers (km) and miles (m).  There is currently
+  #       no way to scale to smaller units (eg km -> m -> mm)
+  class Distance < Barometer::Units
+    
+    METRIC_UNITS = "km"
+    IMPERIAL_UNITS = "m"
+    
+    attr_accessor :kilometers, :miles
+    
+    def initialize(metric=true)
+      @kilometers = nil
+      @miles = nil
+      super(metric)
+    end
+    
+    def metric_default=(value); self.km = value; end
+    def imperial_default=(value); self.m = value; end
+
+    #
+    # CONVERTERS
+    #
+    
+    def self.km_to_m(km)
+      return nil unless km && (km.is_a?(Integer) || km.is_a?(Float))
+      km.to_f * 0.622
+    end
+    
+    def self.m_to_km(m)
+      return nil unless m && (m.is_a?(Integer) || m.is_a?(Float))
+      m.to_f * 1.609
+    end
+    
+    #
+    # ACCESSORS
+    #
+    
+    # store kilometers
+    def km=(km)
+      return if !km || !(km.is_a?(Integer) || km.is_a?(Float))
+      @kilometers = km.to_f
+      self.update_miles(km.to_f)
+    end
+    
+    # store miles
+    def m=(m)
+      return if !m || !(m.is_a?(Integer) || m.is_a?(Float))
+      @miles = m.to_f
+      self.update_kilometers(m.to_f)
+    end
+    
+    # return the stored kilometers or convert from miles
+    def km(as_integer=true)
+      km = (@kilometers || Distance.m_to_km(@miles))
+      km ? (as_integer ? km.to_i : (100*km).round/100.0) : nil
+    end
+    
+    # return the stored miles or convert from kilometers
+    def m(as_integer=true)
+      m = (@miles || Distance.km_to_m(@kilometers))
+      m ? (as_integer ? m.to_i : (100*m).round/100.0) : nil
+    end
+    
+    #
+    # OPERATORS
+    #
+    
+    def <=>(other)
+      self.km <=> other.km
+    end
+    
+    #
+    # HELPERS
+    #
+    
+    # will just return the value (no units)
+    def to_i(metric=nil)
+      (metric || (metric.nil? && self.metric?)) ? self.km : self.m
+    end
+    
+    # will just return the value (no units) with more precision
+    def to_f(metric=nil)
+      (metric || (metric.nil? && self.metric?)) ? self.km(false) : self.m(false)
+    end
+    
+    # will return the value with units
+    def to_s(metric=nil)
+      (metric || (metric.nil? && self.metric?)) ? "#{self.km} #{METRIC_UNITS}" : "#{self.m} #{IMPERIAL_UNITS}"
+    end
+    
+    # will just return the units (no value)
+    def units(metric=nil)
+      (metric || (metric.nil? && self.metric?)) ? METRIC_UNITS : IMPERIAL_UNITS
+    end
+    
+    # when we set miles, it is possible the a non-equivalent value of
+    # kilometers remains.  if so, clear it.
+    def update_kilometers(m)
+      return unless @kilometers
+      difference = Distance.m_to_km(m.to_f) - @kilometers
+      # only clear kilometers if the stored kilometers is off be more then 1 unit
+      # then the conversion of miles
+      @kilometers = nil unless difference.abs <= 1.0
+    end
+    
+    # when we set kilometers, it is possible the a non-equivalent value of
+    # miles remains.  if so, clear it.
+    def update_miles(km)
+      return unless @miles
+      difference = Distance.km_to_m(km.to_f) - @miles
+      # only clear miles if the stored miles is off be more then 1 unit
+      # then the conversion of kilometers
+      @miles = nil unless difference.abs <= 1.0
+    end
+    
+    def nil?
+      (@kilometers || @miles) ? false : true
+    end
+    
+  end
+end

data/lib/barometer/data/forecast.rb

@@ -0,0 +1,66 @@
+require 'date'
+module Barometer
+  #
+  # Forecast Measurement
+  # a data class for forecasted weather conditions
+  #
+  # This is basically a data holding class for the forecasted weather
+  # conditions.
+  #
+  class ForecastMeasurement
+    
+    attr_reader :date, :icon, :condition
+    attr_reader :low, :high, :pop, :sun
+    
+    def date=(date)
+      raise ArgumentError unless date.is_a?(Date)
+      @date = date
+    end
+    
+    def icon=(icon)
+      raise ArgumentError unless icon.is_a?(String)
+      @icon = icon
+    end
+    
+    def condition=(condition)
+      raise ArgumentError unless condition.is_a?(String)
+      @condition = condition
+    end
+    
+    def high=(high)
+      raise ArgumentError unless high.is_a?(Barometer::Temperature)
+      @high = high
+    end
+    
+    def low=(low)
+      raise ArgumentError unless low.is_a?(Barometer::Temperature)
+      @low = low
+    end
+    
+    def pop=(pop)
+      raise ArgumentError unless pop.is_a?(Fixnum)
+      @pop = pop
+    end
+    
+    def sun=(sun)
+      raise ArgumentError unless sun.is_a?(Barometer::Sun)
+      @sun = sun
+    end
+    
+    #
+    # helpers
+    #
+    
+    # creates "?" helpers for all attributes (which maps to nil?)
+    def method_missing(method,*args)
+      # if the method ends in ?, then strip it off and see if we
+      # respond to the method without the ?
+      if (call_method = method.to_s.chomp!("?")) && respond_to?(call_method)
+        return send(call_method).nil? ? false : true
+      else
+        super(method,*args)
+      end
+    end
+    
+  end
+end