green-button-data 0.2.1 → 0.3.0

data/lib/green-button-data/core_ext.rb

@@ -1,2 +1,3 @@
 require 'green-button-data/core_ext/date'
 require 'green-button-data/core_ext/fixnum'
+require 'green-button-data/core_ext/string'

data/lib/green-button-data/core_ext/string.rb

@@ -0,0 +1,35 @@
+class String
+  def camelize
+    self.gsub(/(?<=_|^)(\w)/) { $1.upcase }
+        .gsub(/(?:_)(\w)/,'\1')
+  end
+
+  def underscore
+    # Shamelessly copied from Rails' ActiveSupport gem
+    self.gsub(/::/, '/')
+        .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+        .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+        .tr("-", "_")
+        .downcase
+  end
+
+  def pluralize
+    result = self.dup
+
+    if self.empty?
+      return result
+    else
+      [
+        [/([^aeiouy]|qu)y$/i, '\1ies'],
+        [/s$/i, 's'],
+        [/$/, 's']
+      ].each { |(rule, replacement)| break if result.sub!(rule, replacement) }
+
+      return result
+    end
+  end
+
+  def dasherize
+    self.tr('_', '-')
+  end
+end

data/lib/green-button-data/dst.rb

@@ -1,5 +1,7 @@
 module GreenButtonData
   module Dst
+    include Utilities
+
     # From ESPI XML schema:
     # [extension] Bit map encoded rule from which is calculated the start or
     # end time, within the current year, to which daylight savings time offset
@@ -45,5 +47,60 @@ module GreenButtonData
     BITSHIFT_DAY_OF_MONTH = 20
     BITSHIFT_DST_RULE = 25
     BITSHIFT_MONTH = 28
+
+    def byte_to_dst_datetime(byte, year = Time.now.year)
+      # Bits 0 - 11: seconds 0 - 3599
+      seconds = byte & BITMASK_SECOND
+
+      # Bits 12 - 16: hours 0 - 23
+      hour = (byte & BITMASK_HOUR) >> BITSHIFT_HOUR
+
+      # Bits 17 - 19: day of the week; 0 = NA, 1 - 7 (Monday = 1)
+      weekday = (byte & BITMASK_DAY_OF_WEEK) >> BITSHIFT_DAY_OF_WEEK
+
+      # Bits 20 - 24: day of the month; 0 = NA, 1 - 31
+      day = (byte & BITMASK_DAY_OF_MONTH) >> BITSHIFT_DAY_OF_MONTH
+
+      # Bits 25 - 27: DST rule 0 - 7
+      dst_rule = (byte & BITMASK_DST_RULE) >> BITSHIFT_DST_RULE
+
+      # Bits 28 - 31: month 1 - 12
+      month = (byte & BITMASK_MONTH) >> BITSHIFT_MONTH
+
+      # Raise an error unless all the values are in valid range
+      seconds.between?(0, 3599) and hour.between?(0, 23) and
+      weekday.between?(1, 7) and day.between?(0, 31) and
+      dst_rule.between?(0, 7) and month.between?(1, 12) or
+      raise RangeError, 'Invalid value range'
+
+      # In Ruby, Sunday = 0 not 7
+      weekday = weekday == 7 ? 0 : weekday
+
+      # Check the DST rule
+      dst_day = if dst_rule == 1
+        # Rule 1: DST starts/ends on Day of Week on or after the Day of Month
+        day_of_month = DateTime.new year, month, day
+        day_offset = if weekday >= day_of_month.wday
+          weekday - day_of_month.wday
+        else
+          7 + weekday - day_of_month.wday
+        end
+
+        day_of_month + day_offset
+      elsif dst_rule.between?(2, 6)
+        # Rule 2 - 6: DST starts/ends on Nth Day of Week in given month
+        # Nth Day of Week (e.g. third Friday of July)
+        nth_weekday_of year, month, weekday, dst_rule - 1
+      elsif dst_rule == 7
+        # Rule 7: DST starts/ends on last Day of Week in given month
+        last_weekday_of year, month, weekday
+      else
+        # Rule 0: DST starts/ends on the Day of Month
+        DateTime.new year, month, day
+      end
+
+      # Add the hour and seconds component to the day
+      dst_day + Rational(hour * 3600 + seconds, 86400)
+    end
   end
 end

data/lib/green-button-data/entry.rb

@@ -0,0 +1,87 @@
+module GreenButtonData
+  class Entry
+    include Fetchable
+
+    attr_reader :id
+    attr_accessor :token
+
+    def initialize(attributes)
+      # Automagically sets instance variables from attribute hash parsed from
+      # the GreenButtonData::Parser classes
+      attributes.each do |key, value|
+        self.instance_variable_set :"@#{key}", value
+      end
+
+      # Handle relations via related_urls
+      @related_urls.is_a?(Hash) and @related_urls.each do |key, value|
+        self.instance_variable_set :"@#{key}_url", value
+        singleton_class.class_eval do
+          attr_accessor "#{key}_url".to_sym
+        end
+
+        # Define accessor methods from pluralized resource names
+        self.class.send :define_method, "#{key.to_s.pluralize}" do |*args|
+          id = args[0]
+          options = args[1]
+
+          klazz_name = "GreenButtonData::#{key.to_s.camelize}"
+
+          # Handle deprecations
+          klazz_name.gsub! /ElectricPowerUsageSummary/, 'UsageSummary'
+
+          klazz = klazz_name.split('::')
+                            .inject(Object) { |obj, cls| obj.const_get cls }
+
+          collection = self.instance_variable_get "@#{key.to_s.pluralize}"
+          url = self.instance_variable_get "@#{key}_url"
+
+          # Make the ID argument optional
+          options ||= if id.is_a?(Hash)
+            id
+          else
+            {}
+          end
+
+          result = if id.is_a?(Numeric) || id.is_a?(String) || id.is_a?(Symbol)
+            # Try returning cached results first
+            collection and instance = collection.find_by_id(id)
+            cache_miss = instance.nil?
+
+            # On cache miss or forced reload, send API request
+            instance = if !options[:reload] && instance
+              instance
+            else
+              klazz.find "#{url}/#{id}", options
+            end
+
+            # Cache the result
+            collection ||= ModelCollection.new
+            collection << instance if cache_miss
+
+            instance
+          else
+            if !options[:reload] && collection
+              collection
+            else
+              collection = klazz.all url, options
+            end
+          end
+
+          self.instance_variable_set :"@#{key.to_s.pluralize}", collection
+
+          return result
+        end
+      end
+    end # initialize
+
+    protected
+
+    def get_enum_symbol(enum, value)
+      if value.is_a? Numeric
+        enum[value]
+      else
+        value
+      end
+    end
+  end # Entry
+end # GreenButtonData

data/lib/green-button-data/feed.rb

@@ -1,5 +1,10 @@
 module GreenButtonData
   class Feed
+    def self.fetch(url, options)
+      block = block_given? ? Proc.new : nil
+      conn = Faraday.new url, options, &block
+    end
+
     def self.parse(xml)
       GreenButtonData::Parser::Feed.parse xml
     end

data/lib/green-button-data/fetchable.rb

@@ -0,0 +1,242 @@
+require 'uri'
+
+module GreenButtonData
+  module Fetchable
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      include Relations
+      include Utilities
+
+      ##
+      # Returns all entries
+      #
+      # ==== Arguments
+      #
+      # * +url+ (OPTIONAL) - URL to fetch from. If not supplied, it defaults to
+      #                      the URLs in configuration.
+      # * +options+ - Options hash
+      def all(url = nil, options = nil)
+        if url.is_a?(Hash)
+          # Assume it is an options Hash
+          options = url
+          url = nil
+        end
+
+        url_options = url_options(options)
+
+        url ||= if url_options.keys.size > 0
+          GreenButtonData.configuration.send(
+            "#{class_name.underscore}_url", url_options(options)
+          )
+        else
+          GreenButtonData.configuration.send "#{class_name.underscore}_url"
+        end
+
+        @url = url
+        @options = options
+        return records
+      end
+
+      ##
+      # Returns the first item in the ModelCollection from all entries returned
+      # by the API endpoint
+      #
+      # ==== Arguments
+      #
+      # * +url+ (OPTIONAL) - URL to fetch from. If not supplied, it defaults to
+      #                      the URLs in configuration.
+      # * +options+ - Options hash
+      def first(url = nil, options = nil)
+        return all(url, options).first
+      end
+
+      ##
+      # Finds an entry that matches the {id} in the URL of the form:
+      # https://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/{model_name}/{id}
+      #
+      # ==== Arguments
+      #
+      # * +id+ - ID of the entry content. URL matching a single entry content
+      #          can be supplied in place of ID.
+      # * +url+ (OPTIONAL) - If specified, this URL is used to fetch data in
+      #                      place of global configuration.
+      # * +options+ - Options hash
+      #
+      # ==== Examples
+      #
+      # The following fetches data identically.
+      #
+      # ReadingType.find(1, token: "12345678-1024-2048-abcdef001234") # use global config
+      # ReadingType.find("https://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/ReadingType/1", token: "12345678-1024-2048-abcdef001234") # override global config and use specific url
+      def find(id = nil, options = nil)
+        # If +id+ argument is a URL, set the url
+        url = if id =~ /\A#{URI::regexp}\z/
+          id
+        else
+          url_options = url_options options
+
+          path_prefix = if url_options.keys.size > 0
+            GreenButtonData.configuration.send(
+              "#{class_name.underscore}_url", url_options(options)
+            )
+          else
+            GreenButtonData.configuration.send "#{class_name.underscore}_url"
+          end
+
+          URI.join(path_prefix, "#{id}/").to_s
+        end
+
+        return populate_models(fetch(url, options)).first
+      end
+
+      def last(url = nil, options = nil)
+        return all(url, options).last
+      end
+
+      def fetch(url = nil, options = nil)
+        url or raise ArgumentError.new "url is required to fetch data"
+
+        connection_options = {}
+
+        options ||= {}
+        connection_options[:ssl] = options[:ssl] if options[:ssl]
+
+        conn = Faraday.new connection_options do |connection|
+          connection.response :logger
+          connection.adapter Faraday.default_adapter
+        end
+        conn.authorization :Bearer, options[:token] if options[:token]
+
+        response = conn.get do |req|
+          req.url url
+          req.params = build_query_params options
+        end
+
+        if response.status == 200
+          GreenButtonData::Feed.parse response.body
+        elsif response.status == 401
+          raise "Unauthorized API call; check authorization token and try again"
+        elsif response.status == 500
+          raise "500 Server Error:\n#{response.body}"
+        else
+          raise "Status: #{response.status}"
+        end
+      end
+
+      def feed
+        if !options[:reload] && @feed
+          @feed
+        else
+          @feed = fetch url, options
+        end
+      end
+
+      def records
+        if !options[:reload] && @records
+          @records
+        else
+          @records = populate_models(feed)
+        end
+      end
+
+      def options
+        @options
+      end
+
+      def url
+        @url
+      end
+
+      private
+
+      def class_name
+        self.name.split('::').last
+      end
+
+      def each_entry_content(feed)
+        entry_content = nil
+
+        feed.entries.each do |entry|
+          match_data = /\/(([a-zA-Z]+)|([a-zA-Z]+)\/(\w+=*|(\d+,*\d*)+))\/*\z/.
+                       match(entry.self)
+
+          unless match_data.nil?
+            id = match_data[4] || entry.id
+            type = match_data[2] || match_data[3]
+
+            entry_content = case type.downcase
+
+            when 'applicationinformation'
+              entry.content.application_information
+            when 'authorization'
+              entry.content.authorization
+            when 'electricpowerusagesummary'
+              entry.content.electric_power_usage_summary
+            when 'intervalblock'
+              entry.content.interval_block
+            when 'localtimeparameters'
+              entry.content.local_time_parameters
+            when 'readingtype'
+              entry.content.reading_type
+            when 'usagepoint'
+              entry.content.usage_point
+            when 'usagesummary'
+              entry.content.usage_summary
+            else
+              nil
+            end
+
+            yield id, entry_content, entry
+          end
+        end
+      end
+
+      def populate_models(feed)
+        models = GreenButtonData::ModelCollection.new
+
+        each_entry_content feed do |id, content, entry|
+          attributes_hash = attributes_to_hash(content)
+          attributes_hash[:id] = id
+
+          attributes_hash[:related_urls] = construct_related_urls entry
+          models << self.new(attributes_hash)
+        end
+
+        return models
+      end
+
+      def build_query_params(options)
+        params = {}
+
+        options.each do |key, value|
+          if key == :published_min || key == :published_max
+            if value.respond_to? :to_time
+              value = value.to_time.to_i
+            end
+          end
+
+          unless key == :ssl || key == :token || key == :subscription_id
+            params[key.to_s.dasherize] = value
+          end
+        end
+
+        return params
+      end
+
+      def url_options(options)
+        url_options = {}
+
+        options.each do |key, value|
+          if /_id$/ =~ key
+            url_options[key] = value
+          end
+        end
+
+        return url_options
+      end
+    end # ClassMethods
+  end # Fetchable
+end # GreenButtonData