aixm 1.1.0 → 1.2.0

data/lib/aixm/schedule/date.rb

@@ -0,0 +1,181 @@
+using AIXM::Refinements
+
+module AIXM
+  module Schedule
+
+    # Dates suitable for schedules
+    #
+    # This class implements the bare minimum of stdlib +Date+ and adds some
+    # extensions:
+    #
+    # * yearless dates
+    # * {covered_by?} to check whether (yearless) date falls within (yearless)
+    #   date range
+    #
+    # @example
+    #   date = AIXM.date('2022-04-20')               # => 2022-04-20
+    #   from = AIXM.date('03-20')                    # => XXXX-03-20
+    #   date.covered_by?(from..AIXM.date('05-20'))   # => true
+    class Date
+      include AIXM::Concerns::HashEquality
+      include Comparable
+      extend Forwardable
+
+      YEARLESS_YEAR = 0
+
+      # @api private
+      attr_accessor :date
+
+      # Parse the given representation of (yearless) date.
+      #
+      # @param date [Date, Time, String] either stdlib Date/Time, "YYYY-MM-DD",
+      #   "XXXX-MM-DD" or "MM-DD" (yearless date)
+      def initialize(date)
+        @date = case date.to_s[0, 10]
+        when /\A\d{4}-\d{2}-\d{2}\z/
+          ::Date.strptime(date.to_s)
+        when /\A(?:XXXX-)?(\d{2}-\d{2})\z/
+          ::Date.strptime("#{YEARLESS_YEAR}-#{$1}")
+        else
+          fail ArgumentError
+        end
+      rescue ::Date::Error
+        raise ArgumentError
+      end
+
+      # Human readable representation such as "2002-05-19" or "XXXX-05-19"
+      #
+      # All formats from {strftime}[https://www.rubydoc.info/stdlib/date/Date#strftime-instance_method]
+      # are supported, however, +%Y+ is replaced with "XXXX" for yearless dates.
+      # Any other formats containing the year won't do so and should be avoided!
+      #
+      # @param format [String] see {strftime}[https://www.rubydoc.info/stdlib/date/Date#strftime-instance_method]
+      # @return [String]
+      def to_s(format='%Y-%m-%d')
+        @date.strftime(yearless? ? format.gsub('%Y', 'XXXX') : format)
+      end
+
+      def inspect
+        %Q(#<#{self.class} #{to_s}>)
+      end
+
+      # Creates a new date with the given parts altered.
+      #
+      # @example
+      #   date = AIXM.date('2000-12-22')
+      #   date.at(month: 4)               # => 2000-04-22
+      #   date.at(year: 2020, day: 5)     # => 2020-12-05
+      #   date.at(month: 1)               # => 2020-01-22
+      #   date.at(month: 1, wrap: true)   # => 2021-01-22 (year incremented)
+      #
+      # @param year [Integer] new year
+      # @param month [Integer] new month
+      # @param day [Integer] new day
+      # @param wrap [Boolean] whether to increment month when crossing month
+      #   boundary and year when crossing year boundary
+      # @return [AIXM::Schedule::Date]
+      def at(year: nil, month: nil, day: nil, wrap: false)
+        return self unless year || month || day
+        wrap_month, wrap_year = day&.<(date.day), month&.<(date.month)
+        date = ::Date.new(year || self.year || YEARLESS_YEAR, month || self.month, day || self.day)
+        date = date.next_month if wrap && wrap_month && !month
+        date = date.next_year if wrap && wrap_year && !year
+        self.class.new(date.strftime(yearless? ? '%m-%d' : '%F'))
+      end
+
+      # Create new date one day after this one.
+      #
+      # @return [AIXM::Schedule::Date]
+      def succ
+        self.class.new(date.next_day).at(year: (YEARLESS_YEAR if yearless?))
+      end
+
+      # Convert date to day
+      #
+      # @raise [RuntimeError] if date is yearless
+      # @return [AIXM::Schedule::Day]
+      def to_day
+        fail "cannot convert yearless date" if yearless?
+        AIXM.day(date.wday)
+      end
+
+      # Stdlib Date equivalent using the value of {YEARLESS_YEAR} to represent a
+      # yearless date.
+      #
+      # @return [Date]
+      def to_date
+        @date
+      end
+
+      # Whether the other schedule date can be compared to this one.
+      #
+      # @param other [AIXM::Schedule::Date]
+      # @return [Boolean]
+      def comparable_to?(other)
+        other.instance_of?(self.class) && yearless? == other.yearless?
+      end
+
+      def <=>(other)
+        fail "not comparable" unless comparable_to? other
+        @date.jd <=> other.to_date.jd
+      end
+
+      # @see Object#hash
+      def hash
+         [self.class, @date.jd].hash
+      end
+
+      # Whether this schedule date is yearless or not.
+      #
+      # @return [Boolean]
+      def yearless?
+        @date.year == YEARLESS_YEAR
+      end
+
+      # Yearless duplicate of self
+      #
+      # @return [AIXM::Schedule::Date]
+      def to_yearless
+        yearless? ? self : self.class.new(to_s[5..])
+      end
+
+      # @return [Integer] year or +nil+ if yearless
+      def year
+        @date.year unless yearless?
+      end
+
+      # @!method month
+      #   @return [Integer]
+      # @!method day
+      #   @return [Integer] day of month
+      def_delegators :@date, :month, :day
+
+      # Whether this schedule date falls within the given range of schedule dates
+      #
+      # @note It is possible to compare dates as well as days.
+      #
+      # @param other [AIXM::Schedule::Date, Range<AIXM::Schedule::Date>,
+      #   AIXM::Schedule::Day, Range<AIXM::Schedule::Day>] single schedule
+      #   date/day or range of schedule dates/days
+      # @return [Boolean]
+      def covered_by?(other)
+        range = Range.from(other)
+        case
+        when range.first.instance_of?(AIXM::Schedule::Day)
+          range.first.any? || to_day.covered_by?(range)
+        when range.first.yearless?
+          yearless? ? covered_by_yearless_date?(range) : to_yearless.covered_by?(range)
+        else
+          yearless? ? covered_by_yearless_date?(range.first.to_yearless..range.last.to_yearless) : range.cover?(self)
+        end
+      end
+
+      private
+
+      def covered_by_yearless_date?(range)
+        range.min ? range.cover?(self) : range.first <= self || self <= range.last
+      end
+    end
+
+  end
+end

data/lib/aixm/schedule/day.rb

@@ -0,0 +1,114 @@
+using AIXM::Refinements
+
+module AIXM
+  module Schedule
+
+    # Days suitable for schedules
+    #
+    # @example
+    #   from = AIXM.day(:monday)                   # => :monday
+    #   to = AIXM.day(4)                           # => :thursday
+    #   AIXM.day(:tuesday).covered_by?(from..to)   # => true
+    class Day
+      include AIXM::Concerns::HashEquality
+      include Comparable
+
+      DAYS = %i(sunday monday tuesday wednesday thursday friday saturday workday day_preceding_workday day_following_workday holiday day_preceding_holiday day_following_holiday any).freeze
+      SORTABLE_DAYS = DAYS[0, 7]
+
+      # Day of the week or special named day
+      #
+      # @return [Symbol] any from {DAYS}
+      attr_reader :day
+
+      # Set the given day of the week or special named day.
+      #
+      # @param day [Symbol, String, Integer] any from {DAYS} or 0=Monday to
+      #   6=Sunday
+      def initialize(day=:any)
+        case day
+        when Symbol, String
+          self.day = day
+        when Integer
+          fail ArgumentError unless day.between?(0, 6)
+          self.day = SORTABLE_DAYS[day]
+        else
+          fail ArgumentError
+        end
+      end
+
+      # Human readable representation such as "monday" or "day preceding workday"
+      #
+      # @return [String]
+      def to_s
+        day.to_s.gsub('_', ' ')
+      end
+
+      def inspect
+        %Q(#<#{self.class} #{to_s}>)
+      end
+
+      # Whether two days are equal.
+      #
+      # @return [Boolean]
+      def ==(other)
+        day == other.day
+      end
+
+      # @see Object#hash
+      def hash
+        [self.class, day].hash
+      end
+
+      # Whether the day is set to :any
+      #
+      # @return [Boolean]
+      def any?
+        day == :any
+      end
+
+      # Whether this schedule day sortable.
+      #
+      # @return [Boolean]
+      def sortable?
+        SORTABLE_DAYS.include? day
+      end
+
+      # Whether this schedule day falls within the given range of schedule
+      # days.
+      #
+      # @note Only weekdays and +:any+ can be computed!
+      #
+      # @param other [AIXM::Schedule::Day, Range<AIXM::Schedule::Day>] single
+      #   schedule day or range of schedule days
+      # @raise RuntimeError if anything but workdays or +:any+ are involved
+      # @return [Boolean]
+      def covered_by?(other)
+        range = Range.from other
+        case
+        when any? || range.first.any? || range.last.any?
+          true
+        when !sortable? || !range.first.sortable? || !range.last.sortable?
+          fail "includes unsortables"
+        when range.min
+          range.cover? self
+        else
+          range.first <= self || self <= range.last
+        end
+      end
+
+      private
+
+      def day=(value)
+        @day = value.to_s.to_sym
+        fail ArgumentError unless DAYS.include? @day
+      end
+
+      # @note Necessary to use this class in Range.
+      def <=>(other)
+        DAYS.index(day) <=> DAYS.index(other.day) || day.to_s <=> other.to_s
+      end
+    end
+
+  end
+end

data/lib/aixm/schedule/time.rb

@@ -0,0 +1,255 @@
+using AIXM::Refinements
+
+module AIXM
+  module Schedule
+
+    # Times suitable for schedules
+    #
+    # This class implements the bare minimum of stdlib +Time+ and adds some
+    # extensions:
+    #
+    # * converts to UTC
+    # * date, seconds and milliseconds are ignored
+    # * {covered_by?} to check whether schedule time falls within range of times
+    #
+    # @note The {DATELESS_DATE} is used to mark the date of the internal +Time"
+    #   object irrelevant. However, Ruby does not persist end of days as 24:00,
+    #   therefore {DATELESS_DATE} + 1 marks this case.
+    #
+    # @example
+    #   time = AIXM.time('21:30')                                  # => 21:30
+    #   time.covered_by?(AIXM.time('20:00')..AIXM.time('02:00'))   # => true
+    class Time
+      include AIXM::Concerns::HashEquality
+      extend Forwardable
+
+      EVENTS = %i(sunrise sunset).freeze
+      PRECEDENCES = { first: :min, last: :max }.freeze
+      DATELESS_DATE = ::Date.parse('0000-01-01').freeze
+
+      # @api private
+      attr_accessor :time
+
+      # Event or alternative to time
+      #
+      # @return [Symbol, nil] any from {EVENTS}
+      attr_reader :event
+
+      # Minutes added or subtracted from event
+      #
+      # @return [Integer, nil]
+      attr_reader :delta
+
+      # Precedence of time vs. event
+      #
+      # @return [Symbol, nil] any key of {PRECEDENCES}
+      attr_reader :precedence
+
+      # Parse the given representation of time.
+      #
+      # @example
+      #   AIXM.time('08:00')
+      #   AIXM.time(:sunrise)
+      #   AIXM.time(:sunrise, plus: 30)
+      #   AIXM.time('08:00', or: :sunrise)
+      #   AIXM.time('08:00', or: :sunrise, plus: 30)
+      #   AIXM.time('08:00', or: :sunrise, minus: 15)
+      #   AIXM.time('08:00', or: :sunrise, whichever_comes: :last)
+      #
+      # @param time_or_event [Time, DateTime, String, Symbol] either time as
+      #   stdlib Time or DateTime, "HH:MM" (implicitly UTC), "HH:MM [+-]00:00",
+      #   "HH:MM UTC" or event from {EVENTS} as Symbol
+      # @param or [Symbol] alternative event from {EVENTS}
+      # @param plus [Integer] minutes added to event
+      # @param minus [Integer] minutes subtracted from event
+      # @param whichever_comes [Symbol] any key from {PRECEDENCES}
+      def initialize(time_or_event, or: nil, plus: 0, minus: 0, whichever_comes: :first)
+        alternative_event = binding.local_variable_get(:or)   # necessary since "or" is a keyword
+        @time = @event = @precedence = nil
+        case time_or_event
+        when Symbol
+          self.event = time_or_event
+        when ::Time, DateTime
+          time_or_event = time_or_event.to_time
+          set_time(time_or_event.hour, time_or_event.min, time_or_event.utc_offset)
+        when /\A(\d{2}):?(\d{2}) ?([+-]\d{2}:?\d{2}|UTC)?\z/
+          set_time($1, $2, $3)
+        else
+          fail(ArgumentError, "time or event not recognized")
+        end
+        fail(ArgumentError, "only one event allowed") if event && alternative_event
+        self.event ||= alternative_event
+        @delta = event ? plus - minus : 0
+        if @time && event
+          self.precedence = whichever_comes
+          fail(ArgumentError, "mandatory precedence missing") unless precedence
+        end
+      end
+
+      # Human readable representation
+      #
+      # The format recognises does the following interpolations:
+      # * +%R+ - "HH:MM" in UTC if time is present, "" otherwise
+      # * +%z+ - "UTC" if time is present, "" otherwise
+      # * +%o+ - "or" if both time and event are present, "" otherwise
+      # * +%E+ - "sunrise-15min" if no event is present, "" otherwise
+      # * +%P+ - "whichever comes first" if precedence is present, "" otherwise
+      #
+      # @param format [String]
+      # @return [String]
+      def to_s(format='%R %z %o %E %P')
+        format.gsub(/%[RzoEP]/,
+          '%R' => (sprintf("%02d:%02d", hour, min) if @time),
+          '%z' => ('UTC' if @time),
+          '%o' => ('or' if @time && event),
+          '%E' => "#{event}#{sprintf("%+dmin", delta) unless delta.zero?}",
+          '%P' => ("whichever comes #{precedence}" if precedence)
+        ).compact
+      end
+
+      def inspect
+        %Q(#<#{self.class} #{to_s}>)
+      end
+
+      # Creates a new time with the given parts altered.
+      #
+      # @example
+      #   time = AIXM.time('22:12')
+      #   time.at(min: 0)               # => 22:00
+      #   time.at(min: 0 wrap: true)   # => 2021-01-22 (year incremented)
+      #
+      # @param hour [Integer] new hour
+      # @param min [Integer] new minutes
+      # @param wrap [Boolean] whether to increment hour when crossing minutes
+      #   boundary
+      # @return [AIXM::Schedule::Date]
+      def at(hour: nil, min: nil, wrap: false)
+        return self unless hour || min
+        min ||= time.min
+        hour ||= time.hour
+        hour = (hour + 1) % 24 if wrap && min < time.min
+        self.class.new("%02d:%02d" % [hour, min])
+      end
+
+      # Resolve event to simple time
+      #
+      # * If +self+ doesn't have any event, +self+ is returned.
+      # * Otherwise a new time is created with the event resolved for the
+      #   given date and geographical location.
+      #
+      # @example
+      #   time = AIXM.time('21:00', or: :sunset, minus: 30, whichever_cones: first)
+      #   time.resolve(on: AIXM.date('2000-08-01'), at: AIXM.xy(lat: 48.8584, long: 2.2945))
+      #   # => 20:50
+      #
+      # @param on [AIXM::Date] defaults to today
+      # @param xy [AIXM::XY]
+      # @return [AIXM::Schedule::Time, self]
+      def resolve(on:, xy:)
+        if resolved?
+          self
+        else
+          sun_time = self.class.new(Sun.send(event, on.to_date, xy.lat, xy.long).utc + (delta * 60))
+          if time
+            self.class.new([sun_time.time, self.time].send(PRECEDENCES.fetch(precedence)))
+          else
+            sun_time
+          end
+        end
+      end
+
+      # Whether this time is resolved and doesn't contain an event (anymore).
+      #
+      # @return [Boolean]
+      def resolved?
+        !event
+      end
+
+      # Stdlib Time equivalent using the value of {DATELESS_DATE} to represent a
+      # time only.
+      #
+      # @return [Time]
+      def to_time
+        @time
+      end
+
+      # Hour from 0 (beginning of day) to 24 (end of day)
+      #
+      # @return [Integer]
+      def hour
+        @time.hour + (end_of_day? ? 24 : 0)
+      end
+
+      # @!method min
+      #   @return [Integer]
+      def_delegators :@time, :min
+
+      # Whether two times are equal.
+      #
+      # @return [Boolean]
+      def ==(other)
+        to_s == other.to_s
+      end
+
+      # Whether this schedule time is sortable.
+      #
+      # @return [Boolean]
+      def sortable?
+        !event
+      end
+
+      # Whether this schedule time falls within the given range of schedule
+      # times.
+      #
+      # @param other [AIXM::Schedule::Time, Range<AIXM::Schedule::Time>] single
+      #   schedule time or range of schedule times
+      # @raise RuntimeError if either self is or the range contains an
+      #   unsortable time with event
+      # @return [Boolean]
+      def covered_by?(other)
+        range = Range.from(other)
+        case
+        when !sortable? || !range.first.sortable? || !range.last.sortable?
+          fail "includes unsortables"
+        when range.min
+          range.first.to_s <= self.to_s && self.to_s <= range.last.to_s
+        else
+          range.first.to_s <= self.to_s || self.to_s <= range.last.to_s
+        end
+      end
+
+      private
+
+      # Set the +@time+ instance variable.
+      #
+      # @param hour [Integer, String]
+      # @param min [Integer, String]
+      # @param offset [Integer, String] either UTC offset in seconds
+      #   (default: 0) or 'UTC'
+      # @return [Time]
+      def set_time(hour, min, offset)
+        @time = ::Time.new(DATELESS_DATE.year, DATELESS_DATE.month, DATELESS_DATE.day, hour, min, 0, offset || 0).utc
+      end
+
+      def event=(value)
+        fail ArgumentError if value && !EVENTS.include?(value)
+        @event = value
+      end
+
+      def precedence=(value)
+        fail ArgumentError if value && !PRECEDENCES.has_key?(value)
+        @precedence = value
+      end
+
+      def end_of_day?
+        @time.day > DATELESS_DATE.day
+      end
+
+      # @note Necessary to use this class in Range.
+      def <=>(other)
+        to_time <=> other.to_time || to_s <=> other.to_s
+      end
+    end
+
+  end
+end

data/lib/aixm/shortcuts.rb

@@ -18,4 +18,7 @@ module AIXM
   # Timetable used to signal "always active"
   H24 = timetable(code: :H24).freeze
 
+  # Day to signal "whatever date or day"
+  ANY_DAY = AIXM.day(:any).freeze
+
 end

data/lib/aixm/version.rb

@@ -1,3 +1,3 @@
 module AIXM
-  VERSION = "1.1.0".freeze
+  VERSION = "1.2.0".freeze
 end

data/lib/aixm/w.rb

@@ -7,6 +7,7 @@ module AIXM
   # @example
   #   AIXM.w(2.9, :t)
   class W
+    include AIXM::Concerns::HashEquality
     include Comparable
     extend Forwardable
 
@@ -17,16 +18,29 @@ module AIXM
       ton: { kg: 907.18474, t: 0.90718474, lb: 2000.00000013718828 }
     }.freeze
 
+    # Whether weight is zero.
+    #
     # @!method zero?
-    #   @return [Boolean] whether weight is zero
+    # @return [Boolean]
     def_delegator :@wgt, :zero?
 
-    # @return [Float] weight
+    # Weight
+    #
+    # @overload wgt
+    #   @return [Float]
+    # @overload wgt=(value)
+    #   @param value [Float]
     attr_reader :wgt
 
-    # @return [Symbol] unit (see {UNITS})
+    # Unit
+    #
+    # @overload unit
+    #   @return [Float] any of {UNITS}
+    # @overload unit=(value)
+    #   @param value [Float] any of {UNITS}
     attr_reader :unit
 
+    # See the {overview}[AIXM::W] for examples.
     def initialize(wgt, unit)
       self.wgt, self.unit = wgt, unit
     end
@@ -52,12 +66,13 @@ module AIXM
       fail(ArgumentError, "invalid unit") unless UNITS.has_key? @unit
     end
 
+    # Convert weight
+    #
     # @!method to_kg
     # @!method to_t
     # @!method to_lb
     # @!method to_ton
-    #
-    # @return [AIXM::W] convert weight
+    # @return [AIXM::W] converted weight
     UNITS.each_key do |target_unit|
       define_method "to_#{target_unit}" do
         return self if unit == target_unit
@@ -66,22 +81,14 @@ module AIXM
     end
 
     # @see Object#<=>
-    # @return [Integer]
     def <=>(other)
       wgt <=> other.send(:"to_#{unit}").wgt
     end
 
     # @see Object#==
-    # @return [Boolean]
     def ==(other)
       self.class === other  && (self <=> other).zero?
     end
-    alias_method :eql?, :==
 
-    # @see Object#hash
-    # @return [Integer]
-    def hash
-      to_s.hash
-    end
   end
 end