green-button-data 0.1.0

data/lib/green-button-data/parser/authorization.rb

@@ -0,0 +1,45 @@
+module GreenButtonData
+  module Parser
+    class Authorization
+      include SAXMachine
+      include Utilities
+
+      element :authorizedPeriod, class: Interval, as: :authorized_period
+      element :publishedPeriod, class: Interval, as: :published_period
+
+      element :expires_at, class: Integer do |epoch|
+        Time.at(normalize_epoch(epoch)).utc.to_datetime
+      end
+
+      element :status, class: Integer
+
+      def active?
+        @status > 0
+      end
+
+      # TODO: Add scope parser
+      element :scope
+
+      element :resourceURI, as: :resource_uri
+      element :authorizationURI, as: :authorization_uri
+
+      # ESPI Namespacing
+      element :'espi:authorizedPeriod', class: Interval, as: :authorized_period
+      element :'espi:publishedPeriod', class: Interval, as: :published_period
+      element :'espi:expires_at', class: Integer, as: :expires_at
+      element :'espi:status', class: Integer, as: :status
+      element :'espi:scope', as: :scope
+      element :'espi:resourceURI', as: :resource_uri
+      element :'espi:authorizationURI', as: :authorization_uri
+
+      # Special case for PG&E which uses generic namespacing
+      element :'ns0:authorizedPeriod', class: Interval, as: :authorized_period
+      element :'ns0:publishedPeriod', class: Interval, as: :published_period
+      element :'ns0:expires_at', class: Integer, as: :expires_at
+      element :'ns0:status', class: Integer, as: :status
+      element :'ns0:scope', as: :scope
+      element :'ns0:resourceURI', as: :resource_uri
+      element :'ns0:authorizationURI', as: :authorization_uri
+    end
+  end
+end

data/lib/green-button-data/parser/content.rb

@@ -0,0 +1,36 @@
+module GreenButtonData
+  module Parser
+    class Content
+      include SAXMachine
+
+      element :ApplicationInformation, class: ApplicationInformation,
+              as: :application_information
+      element :Authorization, class: Authorization, as: :authorization
+      element :IntervalBlock, class: IntervalBlock, as: :interval_block
+      element :LocalTimeParameters, class: LocalTimeParameters,
+              as: :local_time_parameters
+      element :ReadingType, class: ReadingType, as: :reading_type
+      element :UsagePoint, class: UsagePoint, as: :usage_point
+
+      # ESPI Namespacing
+      element :'espi:ApplicationInformation', class: ApplicationInformation,
+              as: :application_information
+      element :'espi:Authorization', class: Authorization, as: :authorization
+      element :'espi:IntervalBlock', class: IntervalBlock, as: :interval_block
+      element :'espi:LocalTimeParameters', class: LocalTimeParameters,
+              as: :local_time_parameters
+      element :'espi:ReadingType', class: ReadingType, as: :reading_type
+      element :'espi:UsagePoint', class: UsagePoint, as: :usage_point
+
+      # Special case for PG&E generic namespaces
+      element :'ns0:ApplicationInformation', class: ApplicationInformation,
+              as: :application_information
+      element :'ns0:Authorization', class: Authorization, as: :authorization
+      element :'ns0:IntervalBlock', class: IntervalBlock, as: :interval_block
+      element :'ns0:LocalTimeParameters', class: LocalTimeParameters,
+              as: :local_time_parameters
+      element :'ns0:ReadingType', class: ReadingType, as: :reading_type
+      element :'ns0:UsagePoint', class: UsagePoint, as: :usage_point
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+module GreenButtonData
+  module Parser
+    class Entry
+      include SAXMachine
+      include Utilities
+
+      element :id, as: :entry_id
+
+      def id
+        @entry_id ||= @self
+      end
+
+      element :link, as: :up, value: :href, with: { rel: 'up' }
+      element :link, as: :self, value: :href, with: { rel: 'self' }
+      element :link, as: :related, value: :href, with: { rel: 'related' }
+
+      element :content, class: Content, as: :content
+
+      # Published Date
+      element :published
+
+      def published
+        @published ||= @updated
+      end
+
+      def published=(val)
+        @published = parse_datetime val
+      end
+
+      # Updated Date
+      element :updated
+
+      def updated=(val)
+        @updated = parse_datetime val
+      end
+
+      # Handle PG&E namespacing
+      element :'ns1:id', as: :entry_id
+      element :'ns1:link', as: :up, value: :href, with: { rel: 'up' }
+      element :'ns1:link', as: :self, value: :href, with: { rel: 'self' }
+      element :'ns1:link', as: :related, value: :href, with: { rel: 'related' }
+      element :'ns1:content', class: Content, as: :content
+      element :'ns1:published', as: :published
+      element :'ns1:updated', as: :updated
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+module GreenButtonData
+  module Parser
+    class Feed
+      include SAXMachine
+      include Utilities
+
+      element :id, as: :feed_id
+
+      def id
+        @feed_id ||= @feed_url
+      end
+
+      element :title
+      element :subtitle, as: :description
+
+      element :link, as: :url, value: :href, with: { type: 'text/html' }
+      element :link, as: :feed_url, value: :href, with: { rel: 'self' }
+      element :link, as: :links, value: :href
+
+      def url
+        @url || (links - [feed_url]).last || links.last
+      end
+
+      def feed_url
+        @feed_url ||= links.first
+      end
+
+      elements :entry, class: Entry, as: :entries
+
+      element :updated
+
+      def updated=(val)
+        @updated = parse_datetime val
+      end
+
+      # PG&E's generic namespace
+      element :'ns1:id', as: :feed_id
+      element :'ns1:title', as: :title
+      element :'ns1:subtitle', as: :description
+      element :'ns1:link', as: :url, value: :href, with: { type: 'text/html' }
+      element :'ns1:link', as: :feed_url, value: :href, with: { rel: 'self' }
+      element :'ns1:links', as: :links, value: :href
+      element :'ns1:entry', class: Entry, as: :entries
+      element :'ns1:updated', as: :updated
+    end
+  end
+end

data/lib/green-button-data/parser/interval.rb

@@ -0,0 +1,32 @@
+module GreenButtonData
+  module Parser
+    class Interval
+      include SAXMachine
+      include Utilities
+
+      element :duration, class: Integer do |t|
+        normalize_epoch t
+      end
+
+      element :start, class: Integer do |t|
+        normalize_epoch t
+      end
+
+      def starts_at
+        Time.at(normalize_epoch(@start)).utc.to_datetime
+      end
+
+      def ends_at
+        Time.at(normalize_epoch(@start + @duration)).utc.to_datetime
+      end
+
+      # Standard ESPI namespacing
+      element :'espi:duration', class: Integer, as: :duration
+      element :'espi:start', class: Integer, as: :start
+
+      # Special case for PG&E which uses generic namespacing
+      element :'ns0:duration', class: Integer, as: :duration
+      element :'ns0:start', class: Integer, as: :start
+    end
+  end
+end

data/lib/green-button-data/parser/interval_block.rb

@@ -0,0 +1,32 @@
+module GreenButtonData
+  module Parser
+    class IntervalBlock
+      include SAXMachine
+
+      element :interval, class: Interval
+      elements :IntervalReading, class: IntervalReading, as: :interval_readings
+
+      def duration
+        @interval.duration
+      end
+
+      def starts_at
+        @interval.starts_at
+      end
+
+      def ends_at
+        @interval.ends_at
+      end
+
+      # Standard ESPI namespacing
+      element :'espi:interval', class: Interval, as: :interval
+      elements :'espi:IntervalReading', class: IntervalReading,
+              as: :interval_readings
+
+      # Special case for PG&E which uses generic namespacing
+      element :'ns0:interval', class: Interval, as: :interval
+      elements :'ns0:IntervalReading', class: IntervalReading,
+              as: :interval_readings
+    end
+  end
+end

data/lib/green-button-data/parser/interval_reading.rb

@@ -0,0 +1,30 @@
+module GreenButtonData
+  module Parser
+    class IntervalReading
+      include SAXMachine
+
+      element :cost, class: Integer
+      element :timePeriod, class: Interval, as: :time_period
+      element :value, class: Integer
+      element :consumptionTier, class: Integer, as: :consumption_tier
+      element :tou, class: Integer
+      element :cpp, class: Integer
+
+      # Standard ESPI namespacing
+      element :'espi:cost', class: Integer, as: :cost
+      element :'espi:timePeriod', class: Interval, as: :time_period
+      element :'espi:value', class: Integer, as: :value
+      element :'espi:consumptionTier', class: Integer, as: :consumption_tier
+      element :'espi:tou', class: Integer, as: :tou
+      element :'espi:cpp', class: Integer, as: :cpp
+
+      # Special case for PG&E which uses generic namespacing
+      element :'ns0:cost', class: Integer, as: :cost
+      element :'ns0:timePeriod', class: Interval, as: :time_period
+      element :'ns0:value', class: Integer, as: :value
+      element :'ns0:consumptionTier', class: Integer, as: :consumption_tier
+      element :'ns0:tou', class: Integer, as: :tou
+      element :'ns0:cpp', class: Integer, as: :cpp
+    end
+  end
+end

data/lib/green-button-data/parser/local_time_parameters.rb

@@ -0,0 +1,105 @@
+module GreenButtonData
+  module Parser
+    class LocalTimeParameters
+      include SAXMachine
+      include Dst
+      include Utilities
+
+      element :dstStartRule, as: :dst_start_rule do |string|
+        string.to_i 16
+      end
+
+      element :dstEndRule, as: :dst_end_rule do |string|
+        string.to_i 16
+      end
+
+      def dst_starts_at(year = Time.now.year)
+        byte_to_dst_datetime @dst_start_rule, year
+      end
+
+      def dst_ends_at(year = Time.now.year)
+        byte_to_dst_datetime @dst_end_rule, year
+      end
+
+      element :dstOffset, class: Integer, as: :dst_offset
+      element :tzOffset, class: Integer, as: :tz_offset
+
+      def total_offset
+        @dst_offset + @tz_offset
+      end
+
+      def total_offset_hours
+        total_offset / 3600
+      end
+
+      # ESPI Namespacing
+      element :'espi:dstStartRule', as: :dst_start_rule
+      element :'espi:dstEndRule', as: :dst_end_rule
+      element :'espi:dstOffset', class: Integer, as: :dst_offset
+      element :'espi:tzOffset', class: Integer, as: :tz_offset
+
+      # Special case for PG&E which uses generic namespacing
+      element :'ns0:dstStartRule', as: :dst_start_rule
+      element :'ns0:dstEndRule', as: :dst_end_rule
+      element :'ns0:dstOffset', class: Integer, as: :dst_offset
+      element :'ns0:tzOffset', class: Integer, as: :tz_offset
+
+      private
+
+      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
+end

data/lib/green-button-data/parser/rational_number.rb

@@ -0,0 +1,22 @@
+module GreenButtonData
+  module Parser
+    class RationalNumber
+      include SAXMachine
+
+      element :numerator, class: Integer
+      element :denominator, class: Integer
+
+      def to_f
+        @numerator / @denominator
+      end
+
+      # ESPI Namespacing
+      element :'espi:numerator', class: Integer, as: :numerator
+      element :'espi:denominator', class: Integer, as: :denominator
+
+      # Special case for PG&E which uses generic namespacing
+      element :'ns0:numerator', class: Integer, as: :numerator
+      element :'ns0:denominator', class: Integer, as: :denominator
+    end
+  end
+end

data/lib/green-button-data/parser/reading_type.rb

@@ -0,0 +1,134 @@
+module GreenButtonData
+  module Parser
+    class ReadingType
+      include SAXMachine
+      include Enumerations
+
+      element :accumulationBehaviour, class: Integer,
+              as: :accumulation_behaviour
+      element :commodity, class: Integer
+      element :consumptionTier, class: Integer, as: :consumption_tier
+      element :currency, class: Integer
+      element :dataQualifier, class: Integer, as: :data_qualifier
+      element :defaultQuality, class: Integer, as: :default_quality
+      element :flowDirection, class: Integer, as: :flow_direction
+      element :intervalLength, class: Integer, as: :interval_length
+      element :kind, class: Integer
+      element :phase, class: Integer
+      element :powerOfTenMultiplier, class: Integer,
+              as: :power_of_ten_multiplier
+      element :timeAttribute, class: Integer, as: :time_attribute
+      element :tou, class: Integer
+      element :uom, class: Integer
+      element :cpp, class: Integer
+      element :interharmonic, class: RationalNumber
+      element :measuringPeriod, class: Integer, as: :measuring_period
+      element :argument, class: RationalNumber
+
+      def accumulation_behaviour
+        ACCUMULATION[@accumulation_behaviour]
+      end
+
+      def argument
+        if @argument && @argument.denominator != 0
+          @argument.numerator / @argument.denominator
+        end
+      end
+
+      def commodity
+        COMMODITY[@commodity]
+      end
+
+      def currency
+        CURRENCY[@currency]
+      end
+
+      def data_qualifier
+        DATA_QUALIFIER[@data_qualifier]
+      end
+
+      def default_quality
+        QUALITY_OF_READING[@default_quality]
+      end
+
+      def flow_direction
+        FLOW_DIRECTION[@flow_direction]
+      end
+
+      def interharmonic
+        # Prevent blackholes from forming
+        if @interharmonic && @interharmonic.denominator != 0
+          @interharmonic.numerator / @interharmonic.denominator
+        end
+      end
+
+      def kind
+        MEASUREMENT[@kind]
+      end
+
+      def measuring_period
+        TIME_ATTRIBUTE[@measuring_period]
+      end
+
+      def phase
+        PHASE_CODE[@phase]
+      end
+
+      def power_of_ten_multiplier
+        10.0 ** @power_of_ten_multiplier
+      end
+
+      def time_attribute
+        TIME_PERIOD_OF_INTEREST[@time_attribute]
+      end
+
+      def uom
+        UNIT_SYMBOL[@uom]
+      end
+
+      # ESPI Namespacing
+      element :'espi:accumulationBehaviour', class: Integer,
+              as: :accumulation_behaviour
+      element :'espi:commodity', class: Integer, as: :commodity
+      element :'espi:consumptionTier', class: Integer, as: :consumption_tier
+      element :'espi:currency', class: Integer, as: :currency
+      element :'espi:dataQualifier', class: Integer, as: :data_qualifier
+      element :'espi:defaultQuality', class: Integer, as: :default_quality
+      element :'espi:flowDirection', class: Integer, as: :flow_direction
+      element :'espi:intervalLength', class: Integer, as: :interval_length
+      element :'espi:kind', class: Integer, as: :kind
+      element :'espi:phase', class: Integer, as: :phase
+      element :'espi:powerOfTenMultiplier', class: Integer,
+              as: :power_of_ten_multiplier
+      element :'espi:timeAttribute', class: Integer, as: :time_attribute
+      element :'espi:tou', class: Integer, as: :tou
+      element :'espi:uom', class: Integer, as: :uom
+      element :'espi:cpp', class: Integer, as: :cpp
+      element :'espi:interharmonic', class: RationalNumber, as: :interharmonic
+      element :'espi:measuringPeriod', class: Integer, as: :measuring_period
+      element :'espi:argument', class: RationalNumber, as: :argument
+
+      # Special case for PG&E which uses generic namespacing
+      element :'ns0:accumulationBehaviour', class: Integer,
+              as: :accumulation_behaviour
+      element :'ns0:commodity', class: Integer, as: :commodity
+      element :'ns0:consumptionTier', class: Integer, as: :consumption_tier
+      element :'ns0:currency', class: Integer, as: :currency
+      element :'ns0:dataQualifier', class: Integer, as: :data_qualifier
+      element :'ns0:defaultQuality', class: Integer, as: :default_quality
+      element :'ns0:flowDirection', class: Integer, as: :flow_direction
+      element :'ns0:intervalLength', class: Integer, as: :interval_length
+      element :'ns0:kind', class: Integer, as: :kind
+      element :'ns0:phase', class: Integer, as: :phase
+      element :'ns0:powerOfTenMultiplier', class: Integer,
+              as: :power_of_ten_multiplier
+      element :'ns0:timeAttribute', class: Integer, as: :time_attribute
+      element :'ns0:tou', class: Integer, as: :tou
+      element :'ns0:uom', class: Integer, as: :uom
+      element :'ns0:cpp', class: Integer, as: :cpp
+      element :'ns0:interharmonic', class: RationalNumber, as: :interharmonic
+      element :'ns0:measuringPeriod', class: Integer, as: :measuring_period
+      element :'ns0:argument', class: RationalNumber, as: :argument
+    end
+  end
+end

data/lib/green-button-data/parser/service_category.rb

@@ -0,0 +1,17 @@
+module GreenButtonData
+  module Parser
+    class ServiceCategory
+      include SAXMachine
+
+      element :kind, class: Integer do |kind|
+        GreenButtonData::Enumerations::SERVICE[kind]
+      end
+
+      # ESPI Namespacing
+      element :'espi:kind', class: Integer, as: :kind
+
+      # Special case for PG&E which uses generic namespacing
+      element :'ns0:kind', class: Integer, as: :kind
+    end
+  end
+end

data/lib/green-button-data/parser/usage_point.rb

@@ -0,0 +1,20 @@
+module GreenButtonData
+  module Parser
+    class UsagePoint
+      include SAXMachine
+      include Enumerations
+
+      element :kind, class: Integer
+
+      def service_category
+        SERVICE[@kind]
+      end
+
+      # ESPI Namespacing
+      element :'espi:kind', class: Integer, as: :kind
+
+      # Special case for PG&E which uses generic namespacing
+      element :'ns0:kind', class: Integer, as: :kind
+    end
+  end
+end

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

@@ -0,0 +1,2 @@
+module GreenButtonData::Parser
+end

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

@@ -0,0 +1,106 @@
+module GreenButtonData
+  module Utilities
+
+    def parse_datetime(string)
+      begin
+        DateTime.parse(string).utc
+      rescue
+        warn "Parsing failed for string: #{string.inspect}"
+        nil
+      end
+    end
+
+    ##
+    # Normalizes UNIX +epoch+ ticks to seconds.
+    #
+    # If the number of digits for +epoch+ are greater than or equal to 15
+    # decimal digits, it assumes that the +epoch+ is in microseconds.
+    #
+    # If the number of digits for +epoch+ are less than 15 but greater than or
+    # equal to 13 decimal digits, it assumes that +epoch+ is in milliseconds.
+    #
+    # Less than 13 digits is assumed to be in seconds.
+    #
+    # ==== Arguments
+    #
+    # * +epoch+ - Amount of seconds/milliseconds/microseconds since 1970-01-01
+    def normalize_epoch(epoch)
+      if epoch.digits >= 15
+        epoch / 100000
+      elsif epoch.digits >= 13
+        epoch / 1000
+      else
+        epoch
+      end
+    end
+
+    ##
+    # Retrieves the first Sunday of the month
+    #
+    # ==== Arguments
+    #
+    # * +year+ - year
+    # * +month+ - month
+    def first_sunday_of(year = Time.now.year, month = Time.now.month)
+      first_day = DateTime.new(year, month, 1)
+      first_weekday = first_day.wday
+
+      # If today is Sunday, no offset, otherwise, calculate number of days that
+      # need to be added before hitting the first Sunday of month
+      day_offset = first_weekday == 0 ? 0 : 7 - first_weekday
+
+      # Return first Monday of the month
+      first_day + day_offset
+    end
+
+    ##
+    # Returns the Nth weekday in the given month
+    #
+    # ==== Arguments
+    #
+    # * +year+ - year
+    # * +month+ - month
+    # * +weekday+ - day of week; 0 = Sunday, 6 = Saturday
+    # * +week+ - Nth week of month
+    #
+    # ==== Examples
+    #
+    # To retrieve third Friday of July 2015,
+    #     nth_weekday_of 2015, 7, 5, 3
+    def nth_weekday_of(year = Time.now.year, month = Time.now.month,
+                             weekday = 0, week = 1)
+
+      # Day offset needed for Nth day of the week
+      first_sunday_of(year, month) + weekday + (week - 1) * 7
+    end
+
+    ##
+    # Returns the last weekday in the given month
+    #
+    # ==== Arguments
+    #
+    # * +year+ - year
+    # * +month+ - month
+    # * +weekday+ - day of week; 0 = Sunday, 6 = Saturday
+    #
+    # ==== Examples
+    #
+    # To retrieve the last Wednesday of September 2015,
+    #     last_weekday_of 2015, 9, 3
+    def last_weekday_of(year = Time.now.year, month = Time.now.month,
+                        weekday = 0)
+
+      # Get the last day of month
+      last_day = DateTime.new year, month, -1
+      last_weekday = last_day.wday
+
+      day_offset = if last_weekday >= weekday
+        last_weekday - weekday
+      else
+        7 + last_weekday - weekday
+      end
+
+      last_day - day_offset
+    end
+  end
+end

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

@@ -0,0 +1,3 @@
+module GreenButtonData
+  VERSION = '0.1.0'
+end