aixm 1.1.0 → 1.2.0

data/lib/aixm/component/timesheet.rb

@@ -0,0 +1,178 @@
+using AIXM::Refinements
+
+module AIXM
+  class Component
+
+    # Timesheets define customized activity time windows.
+    #
+    # AIXM supports only yearless dates whereas OFMX extends the model to
+    # accommodate years as well, therefore, the year part is ignored for AIXM.
+    #
+    # ===Cheat Sheat in Pseudo Code:
+    #   timesheet = AIXM.timesheet(
+    #     adjust_to_dst: Boolean
+    #     dates: (AIXM.date..AIXM.date)
+    #     days: (AIXM.day..AIXM..day)     # either: range of days
+    #     day: AIXM.day (default: :any)   # or: single day
+    #   )
+    #   timesheet.times = (AIXM.time..AIXM_time)
+    #
+    # @see https://gitlab.com/openflightmaps/ofmx/-/wikis/Timetable#custom-timetable
+    class Timesheet < Component
+
+      DAYS = {
+        MON: :monday,
+        TUE: :tuesday,
+        WED: :wednesday,
+        THU: :thursday,
+        FRI: :friday,
+        SAT: :saturday,
+        SUN: :sunday,
+        WD: :workday,
+        PWD: :day_preceding_workday,
+        AWD: :day_following_workday,
+        LH: :holiday,
+        PLH: :day_preceding_holiday,
+        ALH: :day_following_holiday,
+        ANY: :any
+      }
+
+      EVENTS = {
+        SR: :sunrise,
+        SS: :sunset
+      }
+
+      PRECEDENCES = {
+        E: :first,
+        L: :last
+      }
+
+      # Range of schedule dates for which this timesheet is active.
+      #
+      # @note Neither open beginning nor open ending is allowed.
+      #
+      # @overload dates
+      #   @return [Range<AIXM::Schedule::Date>]
+      # @overload dates=(value)
+      #   @param value [Range<AIXM::Schedule::Date>] range of schedule dates
+      #     either all with year or all yearless
+      attr_reader :dates
+
+      # Day or days for which this timesheet is active.
+      #
+      # @note Neither open beginning nor open ending is allowed.
+      #
+      # @overload day
+      #   @return [AIXM::Schedule::Day]
+      # @overload days
+      #   @return [Range<AIXM::Schedule::Day>]
+      # @overload day=(value)
+      #   @param value [AIXM::Schedule::Day] schedule day
+      # @overload days=(value)
+      #   @param value [Range<AIXM::Schedule::Day>] range of schedule days
+      attr_reader :days
+
+      # Range of schedule times for which this timesheet is active.
+      #
+      # @note Either open beginning or open ending is allowed.
+      #
+      # @overload times
+      #   @return [Range<AIXM::Schedule::Time>, nil] range of schedule times
+      # @overload times=(value)
+      #   @param value [Range<AIXM::Schedule::Time>, nil] range of schedule times
+      attr_reader :times
+
+      # See the {cheat sheet}[AIXM::Component::Timesheet] for examples on how to
+      # create instances of this class.
+      def initialize(adjust_to_dst:, dates:, days: nil, day: AIXM::ANY_DAY)
+        self.adjust_to_dst, self.dates = adjust_to_dst, dates
+        if days
+          self.days = days
+        else
+          self.day = day
+        end
+      end
+
+      # @return [String]
+      def inspect
+        %Q(#<#{self.class} dates=#{dates.inspect}>)
+      end
+
+      # Whether to adjust to dayight savings time.
+      #
+      # @note See the {OFMX docs}[https://gitlab.com/openflightmaps/ofmx/-/wikis/Timetable#custom-timetable]
+      #   for how exactly this affects dates and times.
+      #
+      # @!attribute adjust_to_dst
+      # @overload adjust_to_dst?
+      #   @return [Boolean]
+      # @overload adjust_to_dst=(value)
+      #   @param value [Boolean]
+      def adjust_to_dst?
+        @adjust_to_dst
+      end
+
+      def adjust_to_dst=(value)
+        fail(ArgumentError, "invalid adjust_to_dst") unless [true, false].include? value
+        @adjust_to_dst = value
+      end
+
+      def dates=(value)
+        fail(ArgumentError, 'invalid dates') unless value.instance_of?(Range) && value.begin && value.end
+        @dates = value
+      end
+
+      def days=(value)
+        fail(ArgumentError, 'invalid days') unless value.instance_of?(Range) && value.begin && value.end
+        @days = value
+      end
+
+      def times=(value)
+        fail(ArgumentError, 'invalid times') unless value.nil? || (value.instance_of?(Range) && value.begin && value.end)
+        @times = value
+      end
+
+      def day
+        @days unless @days.instance_of? Range
+      end
+
+      def day=(value)
+        fail(ArgumentError, 'invalid day') unless value.instance_of? AIXM::Schedule::Day
+        @days = value
+      end
+
+      # @return [String] AIXM or OFMX markup
+      def to_xml
+        builder = Builder::XmlMarkup.new(indent: 2)
+        builder.Timsh do |timsh|
+          timsh.codeTimeRef(adjust_to_dst? ? 'UTCW' : 'UTC')
+          timsh.dateValidWef(dates.begin.to_s('%d-%m'))
+          timsh.dateYearValidWef(dates.begin.year) if AIXM.ofmx? && !dates.begin.yearless?
+          timsh.dateValidTil(dates.end.to_s('%d-%m'))
+          timsh.dateYearValidTil(dates.end.year) if AIXM.ofmx? && !dates.end.yearless?
+          if days.instance_of? Range
+            timsh.codeDay(DAYS.key(days.begin.day).to_s)
+            timsh.codeDayTil(DAYS.key(days.end.day).to_s)
+          else
+            timsh.codeDay(DAYS.key(days.day).to_s)
+          end
+          if times
+            if times.begin
+              timsh.timeWef(times.begin.to_s('%R'))
+              timsh.codeEventWef(EVENTS.key(times.begin.event).to_s) if times.begin.event
+              timsh.timeRelEventWef(times.begin.delta) unless times.begin.delta.zero?
+              timsh.codeCombWef(PRECEDENCES.key(times.begin.precedence).to_s) if times.begin.precedence
+            end
+            if times.end
+              timsh.timeTil(times.end.to_s('%R'))
+              timsh.codeEventTil(EVENTS.key(times.end.event).to_s) if times.end.event
+              timsh.timeRelEventTil(times.end.delta) unless times.end.delta.zero?
+              timsh.codeCombTil(PRECEDENCES.key(times.end.precedence).to_s) if times.end.precedence
+            end
+          end
+        end
+      end
+    end
+
+  end
+end

data/lib/aixm/component/timetable.rb

@@ -5,12 +5,11 @@ module AIXM
 
     # Timetables define activity time windows.
     #
-    # @note As of now, only predefined timetables (see {CODES}) are imlemented.
-    #
     # ===Cheat Sheat in Pseudo Code:
     #   timetable = AIXM.timetable(
-    #     code: String or Symbol
+    #     code: String or Symbol (default: :timesheet)
     #   )
+    #   timetable.add_timesheet(AIXM.timesheet)
     #   timetable.remarks = String or nil
     #
     # ===Shortcuts:
@@ -19,7 +18,11 @@ module AIXM
     #
     # @see https://gitlab.com/openflightmaps/ofmx/wikis/Timetable#predefined-timetable
     class Timetable < Component
+      include AIXM::Association
+      include AIXM::Concerns::Remarks
+
       CODES = {
+        TIMSH: :timesheet,          # attached timesheet
         H24: :continuous,           # all day and all night
         HJ: :sunrise_to_sunset,     # all day
         HN: :sunset_to_sunrise,     # all night
@@ -29,13 +32,19 @@ module AIXM
         OTHER: :other               # specify in remarks
       }.freeze
 
-      # @return [Symbol] predefined timetable code (see {CODES})
-      attr_reader :code
+      # @!method timesheets
+      #   @return [Array<AIXM::Component::Timesheet>] timesheets attached to
+      #     this timetable
+      #
+      # @!method add_timesheet(timesheet)
+      #   @note The {#code} is forced to +:timesheet+ once at least one timesheet
+      #     has been added.
+      #   @param timesheet [AIXM::Component::Timesheet]
+      has_many :timesheets
 
-      # @return [String, nil] free text remarks
-      attr_reader :remarks
-
-      def initialize(code:)
+      # See the {cheat sheet}[AIXM::Component::Timetable] for examples on how to
+      # create instances of this class.
+      def initialize(code: :timesheet)
         self.code = code
       end
 
@@ -44,21 +53,31 @@ module AIXM
         %Q(#<#{self.class} code=#{code.inspect}>)
       end
 
+      # Timetable code
+      #
+      # @!attribute code
+      # @overload code
+      #   @return [Symbol] any of {CODES}
+      # @overload code=(value)
+      #   @param value [Symbol] any of {CODES}
+      def code
+        timesheets.any? ? :timesheet : @code
+      end
+
       def code=(value)
         @code = if value
           CODES.lookup(value&.to_s&.to_sym, nil) || fail(ArgumentError, "invalid code")
         end
       end
 
-      def remarks=(value)
-        @remarks = value&.to_s
-      end
-
       # @return [String] AIXM or OFMX markup
       def to_xml(as: :Timetable)
         builder = Builder::XmlMarkup.new(indent: 2)
         builder.tag!(as) do |tag|
           tag.codeWorkHr(CODES.key(code).to_s)
+          timesheets.each do |timesheet|
+           tag << timesheet.to_xml.indent(2)
+          end
           tag.txtRmkWorkHr(remarks) if remarks
         end
       end

data/lib/aixm/component/vasis.rb

@@ -35,22 +35,52 @@ module AIXM
         OTHER: :other   # specify in remarks
       }.freeze
 
-      # @return [Symbol, nil] type of VASIS (see {TYPES})
+      # Type of VASIS.
+      #
+      # @overload type
+      #   @return [Symbol, nil] any of {TYPES}
+      # @overload type=(value)
+      #   @param value [Symbol, nil] any of {TYPES}
       attr_reader :type
 
-      # @return [Symbol, nil] position relative to the runway (see {POSITIONS})
+      # Position relative to the runway.
+      #
+      # @overload position
+      #   @return [Symbol, nil] any of {POSITIONS}
+      # @overload position=(value)
+      #   @param value [Symbol, nil] any of {POSITIONS}
       attr_reader :position
 
-      # @return [Integer, nil] number of boxes
+      # Number of boxes.
+      #
+      # @overload boxes
+      #   @return [Integer, nil]
+      # @overload boxes=(value)
+      #   @param value [Integer, nil]
       attr_reader :boxes
 
-      # @return [Boolean, nil] whether the VASIS is portable
+      # Whether the VASIS is portable.
+      #
+      # @overload portable
+      #   @return [Boolean, nil] +nil+ means unknown
+      # @overload portable=(value)
+      #   @param value [Boolean, nil] +nil+ means unknown
       attr_reader :portable
 
-      # @return [AIXM::A, nil] appropriate approach slope angle
+      # Appropriate approach slope angle.
+      #
+      # @overload slope_angle
+      #   @return [AIXM::A, nil]
+      # @overload slope_angle=(value)
+      #   @param value [AIXM::A, nil]
       attr_reader :slope_angle
 
-      # @return [AIXM::Z, nil] minimum eye height over threshold (MEHT)
+      # Minimum eye height over threshold.
+      #
+      # @overload meht
+      #   @return [AIXM::Z, nil]
+      # @overload meht=(value)
+      #   @param value [AIXM::Z, nil]
       attr_reader :meht
 
       # @return [String]

data/lib/aixm/component/vertical_limit.rb

@@ -38,18 +38,40 @@ module AIXM
       #   @return [AIXM::Component::Layer] layer to which this vertical limit applies
       belongs_to :layer
 
-      # @return [AIXM::Z] upper limit
+      # Upper limit
+      #
+      # @overload upper_z
+      #   @return [AIXM::Z]
+      # @overload upper_z=(value)
+      #   @param value [AIXM::Z]
       attr_reader :upper_z
 
-      # @return [AIXM::Z] lower limit
+      # Lower limit
+      #
+      # @overload lower_z
+      #   @return [AIXM::Z]
+      # @overload lower_z=(value)
+      #   @param value [AIXM::Z]
       attr_reader :lower_z
 
-      # @return [AIXM::Z] alternative upper limit ("whichever is higher")
+      # Alternative upper limit ("whichever is higher")
+      #
+      # @overload max_z
+      #   @return [AIXM::Z, nil]
+      # @overload max_z=(value)
+      #   @param value [AIXM::Z, nil]
       attr_reader :max_z
 
-      # @return [AIXM::Z] alternative lower limit ("whichever is lower")
+      # Alternative lower limit ("whichever is lower")
+      #
+      # @overload min_z
+      #   @return [AIXM::Z, nil]
+      # @overload min_z=(value)
+      #   @param value [AIXM::Z, nil]
       attr_reader :min_z
 
+      # See the {cheat sheet}[AIXM::Component::VerticalLimit] for examples on
+      # how to create instances of this class.
       def initialize(upper_z:, max_z: nil, lower_z:, min_z: nil)
         self.upper_z, self.max_z, self.lower_z, self.min_z = upper_z, max_z, lower_z, min_z
       end

data/lib/aixm/component.rb

@@ -2,8 +2,11 @@ module AIXM
 
   # @abstract
   class Component
+    include AIXM::Concerns::HashEquality
 
-    # @return [Object] freely usable e.g. to find_by foreign keys
+    # Freely usable e.g. to +find_by+ foreign keys
+    #
+    # @return [Object]
     attr_accessor :meta
 
   end

data/lib/aixm/concerns/hash_equality.rb

@@ -0,0 +1,21 @@
+using AIXM::Refinements
+
+module AIXM
+  module Concerns
+
+    # Implements Hash equality
+    module HashEquality
+
+      # @see Object#hash
+      def hash
+        [self.__class__, to_s].hash
+      end
+
+      # @see Object#eql?
+      def eql?(other)
+        hash == other.hash
+      end
+
+    end
+  end
+end

data/lib/aixm/concerns/intensity.rb

@@ -0,0 +1,30 @@
+using AIXM::Refinements
+
+module AIXM
+  module Concerns
+
+    # Adds optional intensity of lights to features.
+    module Intensity
+
+      INTENSITIES = {
+        LIL: :low,
+        LIM: :medium,
+        LIH: :high,
+        OTHER: :other   # specify in remarks
+      }.freeze
+
+      # Intensity of lights
+      #
+      # @overload remarks
+      #   @return [AIXM::Component::Timetable, nil] any of {INTENSITIES}
+      # @overload remarks=(value)
+      #   @param value [AIXM::Component::Timetable, nil] any of {INTENSITIES}
+      attr_reader :intensity
+
+      def intensity=(value)
+        @intensity = value.nil? ? nil : INTENSITIES.lookup(value.to_s.to_sym, nil) || fail(ArgumentError, "invalid intensity")
+      end
+
+    end
+  end
+end

data/lib/aixm/concerns/marking.rb

@@ -0,0 +1,21 @@
+module AIXM
+  module Concerns
+
+    # Adds optional markings to features.
+    module Marking
+
+      # Markings
+      #
+      # @overload remarks
+      #   @return [String, nil]
+      # @overload remarks=(value)
+      #   @param value [String, nil]
+      attr_reader :marking
+
+      def marking=(value)
+        @marking = value&.to_s
+      end
+
+    end
+  end
+end

data/lib/aixm/concerns/remarks.rb

@@ -0,0 +1,21 @@
+module AIXM
+  module Concerns
+
+    # Adds optional free text remarks to features.
+    module Remarks
+
+      # Free text remarks
+      #
+      # @overload remarks
+      #   @return [String, nil]
+      # @overload remarks=(value)
+      #   @param value [String, nil]
+      attr_reader :remarks
+
+      def remarks=(value)
+        @remarks = value&.to_s
+      end
+
+    end
+  end
+end

data/lib/aixm/concerns/timetable.rb

@@ -0,0 +1,22 @@
+module AIXM
+  module Concerns
+
+    # Adds optional timetable to features.
+    module Timetable
+
+      # Operating hours
+      #
+      # @overload remarks
+      #   @return [AIXM::Component::Timetable, nil]
+      # @overload remarks=(value)
+      #   @param value [AIXM::Component::Timetable, nil]
+      attr_reader :timetable
+
+      def timetable=(value)
+        fail(ArgumentError, "invalid timetable") unless value.nil? || value.is_a?(AIXM::Component::Timetable)
+        @timetable = value
+      end
+
+    end
+  end
+end

data/lib/aixm/d.rb

@@ -7,6 +7,7 @@ module AIXM
   # @example
   #   AIXM.d(123, :m)
   class D
+    include AIXM::Concerns::HashEquality
     include Comparable
     extend Forwardable
 
@@ -17,16 +18,29 @@ module AIXM
       nm: { ft: 6076.11548554, km: 1.852, m: 1852 }
     }.freeze
 
+    # Whether dimension is zero.
+    #
     # @!method zero?
-    #   @return [Boolean] whether dimension is zero
+    # @return [Boolean]
     def_delegator :@dim, :zero?
 
-    # @return [Float] dimension
+    # Dimension
+    #
+    # @overload dim
+    #   @return [Float]
+    # @overload dim=(value)
+    #   @param value [Float]
     attr_reader :dim
 
-    # @return [Symbol] unit (see {UNITS})
+    # Unit
+    #
+    # @overload unit
+    #   @return [Symbol] any of {UNITS}
+    # @overload unit=(value)
+    #   @param value [Symbol] any of {UNITS}
     attr_reader :unit
 
+    # See the {overview}[AIXM::D] for examples.
     def initialize(dim, unit)
       self.dim, self.unit = dim, unit
     end
@@ -52,12 +66,13 @@ module AIXM
       fail(ArgumentError, "invalid unit") unless UNITS.has_key? @unit
     end
 
+    # Convert dimension
+    #
     # @!method to_ft
     # @!method to_km
     # @!method to_m
     # @!method to_nm
-    #
-    # @return [AIXM::D] convert dimension
+    # @return [AIXM::D] converted dimension
     UNITS.each_key do |target_unit|
       define_method "to_#{target_unit}" do
         return self if unit == target_unit
@@ -66,22 +81,13 @@ module AIXM
     end
 
     # @see Object#<=>
-    # @return [Integer]
     def <=>(other)
       dim <=> other.send(:"to_#{unit}").dim
     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

data/lib/aixm/document.rb

@@ -28,15 +28,32 @@ module AIXM
     #   @return [self]
     has_many :features, accept: ['AIXM::Feature']
 
-    # @return [String] UUID to namespace the data contained in this document
+    # UUID to namespace the data contained in this document
+    #
+    # @overload namespace
+    #   @return [String]
+    # @overload namespace=(value)
+    #   @param value [String]
     attr_reader :namespace
 
-    # @return [Time] creation date and time (default: {#effective_at} or now)
+    # Creation date and time
+    #
+    # @overload created_at
+    #   @return [Time]
+    # @overload created_at=(value)
+    #   @param value [Time] default: {#effective_at} or now
     attr_reader :created_at
 
-    # @return [Time] effective after date and time (default: {#created_at} or now)
+    # Effective after date and time
+    #
+    # @overload effective_at
+    #   @return [Time]
+    # @overload effective_at=(value)
+    #   @param value [Time] default: {#created_at} or now
     attr_reader :effective_at
 
+    # See the {cheat sheet}[AIXM::Document] for examples on how to create
+    # instances of this class.
     def initialize(namespace: nil, created_at: nil, effective_at: nil)
       self.namespace, self.created_at, self.effective_at = namespace, created_at, effective_at
     end
@@ -93,14 +110,14 @@ module AIXM
       end.count
     end
 
-    # Validate the generated AIXM or OFMX atainst it's XSD.
+    # Validate the generated AIXM or OFMX against its XSD.
     #
     # @return [Boolean] whether valid or not
     def valid?
       errors.none?
     end
 
-    # Validate the generated AIXM or OFMX atainst it's XSD and return the
+    # Validate the generated AIXM or OFMX against its XSD and return the
     # errors found.
     #
     # @return [Array<String>] validation errors