aixm 1.1.0 → 1.2.0

data/lib/aixm/feature/obstacle.rb

@@ -43,6 +43,7 @@ module AIXM
     class Obstacle < Feature
       include AIXM::Association
       include AIXM::Memoize
+      include AIXM::Concerns::Remarks
 
       public_class_method :new
 
@@ -67,63 +68,138 @@ module AIXM
       #   @return [AIXM::Feature::ObstacleGroup] group this obstacle belongs to
       belongs_to :obstacle_group
 
-      # @return [String] full name
+      # Full name.
+      #
+      # @overload name
+      #   @return [String]
+      # @overload name=(value)
+      #   @param value [String]
       attr_reader :name
 
-      # @return [Symbol] type of obstacle
+      # Type of obstacle.
+      #
+      # @overload type
+      #   @return [Symbol] any of {TYPES}
+      # @overload type=(value)
+      #   @param value [Symbol] any of {TYPES}
       attr_reader :type
 
-      # @return [AIXM::XY] circular base center point
+      # Circular base center point.
+      #
+      # @overload xy
+      #   @return [AIXM::XY]
+      # @overload xy=(value)
+      #   @param value [AIXM::XY]
       attr_reader :xy
 
-      # @return [AIXM::D] circular base radius
+      # Circular base radius.
+      #
+      # @overload radius
+      #   @return [AIXM::D]
+      # @overload radius=(value)
+      #   @param value [AIXM::D]
       attr_reader :radius
 
-      # @return [AIXM::Z] elevation of the top point in +:qnh+
+      # Elevation of the top point in +:qnh+.
+      #
+      # @overload z
+      #   @return [AIXM::Z]
+      # @overload z=(value)
+      #   @param value [AIXM::Z]
       attr_reader :z
 
-      # @return [Boolean, nil] lighting (e.g. strobes)
-      #   true => lighting present, false => no lighting, nil => unknown
+      # Presence of lighting (e.g. strobes).
+      #
+      # @overload lighting
+      #   @return [Boolean, nil] +nil+ means unknown
+      # @overload lighting=(value)
+      #   @param value [Boolean, nil] +nil+ means unknown
       attr_reader :lighting
 
-      # @return [String, nil] detailed description of the lighting
+      # Detailed description of the lighting.
+      #
+      # @overload lighting_remarks
+      #   @return [String, nil]
+      # @overload lighting_remarks=(value)
+      #   @param value [String, nil]
       attr_reader :lighting_remarks
 
-      # @return [Boolean, nil] marking (e.g. red/white paint)
-      #  true => marking present, false => no marking, nil => unknown
+      # Presence of marking (e.g. red/white paint).
+      #
+      # @overload marking
+      #   @return [Boolean, nil] +nil+ means unknown
+      # @overload marking=(value)
+      #   @param value [Boolean, nil] +nil+ means unknown
       attr_reader :marking
 
-      # @return [String, nil] detailed description of the marking
+      # Detailed description of the marking.
+      #
+      # @overload marking_remarks
+      #   @return [String nil]
+      # @overload marking_remarks=(value)
+      #   @param value [String, nil]
       attr_reader :marking_remarks
 
-      # @return [AIXM::D, nil] height from ground to top point
+      # Height from ground to top point.
+      #
+      # @overload height
+      #   @return [AIXM::D, nil]
+      # @overload height=(value)
+      #   @param value [AIXM::D, nil]
       attr_reader :height
 
-      # @return [Boolean, nil] height accuracy
-      #   true => height measured, false => height estimated, nil => unknown
+      # Height accuracy.
+      #
+      # @overload height_accurate
+      #   @return [Boolean, nil] +nil+ means unknown
+      # @overload height_accurate=(value)
+      #   @param value [Boolean, nil] +nil+ means unknown
       attr_reader :height_accurate
 
-      # @return [AIXM::D, nil] margin of error for circular base center point
+      # Margin of error for circular base center point.
+      #
+      # @overload xy_accuracy
+      #   @return [AIXM::D, nil]
+      # @overload xy_accuracy=(value)
+      #   @param value [AIXM::D, nil]
       attr_reader :xy_accuracy
 
-      # @return [AIXM::D, nil] margin of error for top point
+      # Margin of error for top point.
+      #
+      # @overload z_accuracy
+      #   @return [AIXM::D, nil]
+      # @overload z_accuracy=(value)
+      #   @param value [AIXM::D, nil]
       attr_reader :z_accuracy
 
-      # @return [Time, Date, String, nil] effective after this point in time
+      # Effective after this point in time.
+      #
+      # @overload valid_from
+      #   @return [Time, Date, String, nil]
+      # @overload valid_from=(value)
+      #   @param value [Time, Date, String, nil]
       attr_reader :valid_from
 
-      # @return [Time, Date, String, nil] effective until this point in time
+      # Effective until this point in time.
+      #
+      # @overload valid_until
+      #   @return [Time, Date, String, nil]
+      # @overload valid_until=(value)
+      #   @param value [Time, Date, String, nil]
       attr_reader :valid_until
 
-      # @return [String, nil] free text remarks
-      attr_reader :remarks
-
-      # @return [Symbol, nil] another obstacle to which a physical link exists
+      # Another obstacle to which a physical link exists.
+      #
+      # @return [AIXM::Feature::Obstacle, nil]
       attr_reader :linked_to
 
-      # @return [Symbol, nil] type of physical link between this and another obstacle
+      # Type of physical link between this and another obstacle.
+      #
+      # @return [Symbol, nil] any of {LINK_TYPES}
       attr_reader :link_type
 
+      # See the {cheat sheet}[AIXM::Feature::Obstacle] for examples on how to
+      # create instances of this class.
       def initialize(source: nil, region: nil, name: nil, type:, xy:, z:, radius: nil)
         super(source: source, region: region)
         self.name, self.type, self.xy, self.z, self.radius = name, type, xy, z, radius
@@ -205,10 +281,6 @@ module AIXM
         @valid_until = value&.to_time
       end
 
-      def remarks=(value)
-        @remarks = value&.to_s
-      end
-
       def linked_to=(value)
         fail(ArgumentError, "invalid linked to") unless value.is_a?(AIXM::Feature::Obstacle)
         @linked_to = value
@@ -220,12 +292,16 @@ module AIXM
       end
       private :link_type=
 
-      # @return [Boolean] whether part of an obstacle group
+      # Whether part of an obstacle group.
+      #
+      # @return [Boolean]
       def grouped?
         obstacle_group && obstacle_group.obstacles.count > 1
       end
 
-      # @return [Boolean] whether obstacle is linked to another one
+      # Whether obstacle is linked to another one.
+      #
+      # @return [Boolean]
       def linked?
         !!linked_to
       end

data/lib/aixm/feature/obstacle_group.rb

@@ -40,6 +40,7 @@ module AIXM
     class ObstacleGroup < Feature
       include AIXM::Association
       include AIXM::Memoize
+      include AIXM::Concerns::Remarks
 
       public_class_method :new
 
@@ -78,9 +79,8 @@ module AIXM
         end
       end
 
-      # @return [String, nil] free text remarks
-      attr_reader :remarks
-
+      # See the {cheat sheet}[AIXM::Feature::ObstacleGroup] for examples on how
+      # to create instances of this class.
       def initialize(source: nil, region: nil, name: nil)
         super(source: source, region: region)
         self.name = name
@@ -106,10 +106,6 @@ module AIXM
         @z_accuracy = value
       end
 
-      def remarks=(value)
-        @remarks = value&.to_s
-      end
-
       # @return [String] UID markup
       def to_uid
         builder = Builder::XmlMarkup.new(indent: 2)

data/lib/aixm/feature/organisation.rb

@@ -20,6 +20,7 @@ module AIXM
     class Organisation < Feature
       include AIXM::Association
       include AIXM::Memoize
+      include AIXM::Concerns::Remarks
 
       public_class_method :new
 
@@ -36,29 +37,41 @@ module AIXM
       }.freeze
 
       # @!method members
-      #   @return [Array<AIXM::Feature::Airport,
-      #     AIXM::Feature::Unit,
+      #   @return [Array<AIXM::Feature::Airport, AIXM::Feature::Unit,
       #     AIXM::Feature::NavigationalAid>] aiports, units or navigational aids
       #
       # @!method add_member(member)
-      #   @param member [AIXM::Feature::Airport,
-      #     AIXM::Feature::Unit,
+      #   @param member [AIXM::Feature::Airport, AIXM::Feature::Unit,
       #     AIXM::Feature::NavigationalAid]
       #   @return [self]
       has_many :members, accept: [:airport, :unit, 'AIXM::Feature::NavigationalAid']
 
-      # @return [String] name of organisation (e.g. "FRANCE")
+      # Name of organisation (e.g. "FRANCE")
+      #
+      # @overload name
+      #   @return [String]
+      # @overload name=(value)
+      #   @param value [String]
       attr_reader :name
 
-      # @return [Symbol] type of organisation (see {TYPES})
+      # Type of organisation
+      #
+      # @overload type
+      #   @return [Symbol] any of {TYPES}
+      # @overload type=(value)
+      #   @param value [Symbol] any of {TYPES}
       attr_reader :type
 
-      # @return [String, nil] code of the organisation (e.g. "LF")
+      # Code of the organisation (e.g. "LF")
+      #
+      # @overload id
+      #   @return [String, nil]
+      # @overload id=(value)
+      #   @param value [String, nil]
       attr_reader :id
 
-      # @return [String, nil] free text remarks
-      attr_reader :remarks
-
+      # See the {cheat sheet}[AIXM::Feature::Organisation] for examples on how to
+      # create instances of this class.
       def initialize(source: nil, region: nil, name:, type:)
         super(source: source, region: region)
         self.name, self.type = name, type
@@ -83,10 +96,6 @@ module AIXM
         @id = value&.upcase
       end
 
-      def remarks=(value)
-        @remarks = value&.to_s
-      end
-
       # @return [String] UID markup
       def to_uid
         builder = Builder::XmlMarkup.new(indent: 2)

data/lib/aixm/feature/unit.rb

@@ -23,6 +23,7 @@ module AIXM
     class Unit < Feature
       include AIXM::Association
       include AIXM::Memoize
+      include AIXM::Concerns::Remarks
 
       public_class_method :new
 
@@ -95,15 +96,24 @@ module AIXM
       #   @return [AIXM::Feature::Airport, nil] airport
       belongs_to :airport
 
-      # @return [String] name of unit (e.g. "MARSEILLE ACS")
+      # Name of unit (e.g. "MARSEILLE ACS")
+      #
+      # @overload name
+      #   @return [String]
+      # @overload name=(value)
+      #   @param value [String]
       attr_reader :name
 
-      # @return [Symbol] type of unit (see {TYPES})
+      # Type of unit
+      #
+      # @overload type
+      #   @return [Symbol] any of {TYPES}
+      # @overload type=(value)
+      #   @param value [Symbol] any of {TYPES}
       attr_reader :type
 
-      # @return [String, nil] free text remarks
-      attr_reader :remarks
-
+      # See the {cheat sheet}[AIXM::Feature::Unit] for examples on how to create
+      # instances of this class.
       def initialize(source: nil, region: nil, organisation:, name:, type:, class:)
         super(source: source, region: region)
         self.organisation, self.name, self.type = organisation, name, type
@@ -124,9 +134,15 @@ module AIXM
         @type = TYPES.lookup(value&.to_s&.to_sym, nil) || fail(ArgumentError, "invalid type")
       end
 
-      # @!attribute class
+      # Class of unit.
+      #
       # @note Use +Object#__class__+ alias to query the Ruby object class.
-      # @return [Symbol] class of unit (see {CLASSES})
+      #
+      # @!attribute class
+      # @overload class
+      #   @return [Symbol] any of {CLASSES}
+      # @overload class=(value)
+      #   @param value [Symbol] any of {CLASSES}
       def class
         @klass
       end
@@ -135,10 +151,6 @@ module AIXM
         @klass = CLASSES.lookup(value&.to_s&.to_sym, nil) || fail(ArgumentError, "invalid class")
       end
 
-      def remarks=(value)
-        @remarks = value&.to_s
-      end
-
       # @return [String] UID markup
       def to_uid
         builder = Builder::XmlMarkup.new(indent: 2)

data/lib/aixm/feature.rb

@@ -2,17 +2,31 @@ module AIXM
 
   # @abstract
   class Feature
+    include AIXM::Concerns::HashEquality
+
     REGION_RE = /\A[A-Z]{2}\z/.freeze
 
     private_class_method :new
 
-    # @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
 
-    # @return [String] reference to source of the feature data
+    # Reference to source of the feature data.
+    #
+    # @overload source
+    #   @return [String]
+    # @overload source=(value)
+    #   @param value [String]
     attr_reader :source
 
-    # @return [String] OFMX region all features in this document belong to
+    # OFMX region all features in this document belong to.
+    #
+    # @overload region
+    #   @return [String]
+    # @overload region=(value)
+    #   @param value [String]
     attr_reader :region
 
     def initialize(source: nil, region: nil)
@@ -30,10 +44,15 @@ module AIXM
       @region = value&.upcase
     end
 
-    # @return [Boolean]
+    # @see Object#==
     def ==(other)
       self.__class__ === other && self.to_uid == other.to_uid
     end
+
+    # @see Object#eql?
+    def hash
+      [self.__class__, to_uid].hash
+    end
   end
 
 end

data/lib/aixm/memoize.rb

@@ -79,8 +79,8 @@ module AIXM
         @cache = {}
       end
 
-      def method(method, &)
-        send(:"call_with#{:out if cached?(method)}_cache", method, &)
+      def method(method, &block)   # TODO: [ruby-3.1] use anonymous block "&" on this and next line
+        send(:"call_with#{:out if cached?(method)}_cache", method, &block)
       end
 
       private
@@ -99,7 +99,7 @@ module AIXM
       ensure
         cache.delete(method)
       end
-
     end
+
   end
 end

data/lib/aixm/p.rb

@@ -7,6 +7,7 @@ module AIXM
   # @example
   #   AIXM.d(14, :bar)
   class P
+    include AIXM::Concerns::HashEquality
     include Comparable
     extend Forwardable
 
@@ -18,16 +19,29 @@ module AIXM
       torr: { p: 133.322, mpa: 0.000133322, psi: 0.019336721305636, bar: 0.00133322 }
     }.freeze
 
+    # Whether pressure is zero.
+    #
     # @!method zero?
-    #   @return [Boolean] whether pressure is zero
+    # @return [Boolean]
     def_delegator :@pres, :zero?
 
-    # @return [Float] pressure
+    # Pressure
+    #
+    # @overload pres
+    #   @return [Float]
+    # @overload pres=(value)
+    #   @param value [Float]
     attr_reader :pres
 
-    # @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::P] for examples.
     def initialize(pres, unit)
       self.pres, self.unit = pres, unit
     end
@@ -53,13 +67,14 @@ module AIXM
       fail(ArgumentError, "invalid unit") unless UNITS.has_key? @unit
     end
 
+    # Convert pressure
+    #
     # @!method to_p
     # @!method to_mpa
     # @!method to_psi
     # @!method to_bar
     # @!method to_torr
-    #
-    # @return [AIXM::P] convert pressure
+    # @return [AIXM::P] converted pressure
     UNITS.each_key do |target_unit|
       define_method "to_#{target_unit}" do
         return self if unit == target_unit
@@ -68,22 +83,13 @@ module AIXM
     end
 
     # @see Object#<=>
-    # @return [Integer]
     def <=>(other)
       pres <=> other.send(:"to_#{unit}").pres
     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/payload_hash.rb

@@ -16,7 +16,8 @@ module AIXM
   class PayloadHash
     IGNORED_ATTRIBUTES = %w(mid source).freeze
 
-    # @param fragment [Nokogiri::XML::DocumentFragment, Nokogiri::XML::Element, String] XML fragment
+    # @param fragment [Nokogiri::XML::DocumentFragment, Nokogiri::XML::Element,
+    #   String] XML fragment
     def initialize(fragment)
       @fragment = case fragment
         when Nokogiri::XML::DocumentFragment then fragment
@@ -25,7 +26,9 @@ module AIXM
       end
     end
 
-    # @return [String] UUIDv3
+    # UUIDv3
+    #
+    # @return [String]
     def to_uuid
       uuid_for payload_array
     end

data/lib/aixm/r.rb

@@ -8,13 +8,25 @@ module AIXM
   #   AIXM.r(AIXM.d(25, :m), AIXM.d(20, :m))   # rectangle
   #   AIXM.r(AIXM.d(25, :m))                   # square
   class R
+    include AIXM::Concerns::HashEquality
 
-    # @return [AIXM::D] rectangle length
+    # Rectangle length
+    #
+    # @overload length
+    #   @return [AIXM::D]
+    # @overload length=(value)
+    #   @param value [AIXM::D]
     attr_reader :length
 
-    # @return [AIXM::D] rectangle width
+    # Rectangle width
+    #
+    # @overload width
+    #   @return [AIXM::D]
+    # @overload width=(value)
+    #   @param value [AIXM::D]
     attr_reader :width
 
+    # See the {overview}[AIXM::R] for examples.
     def initialize(length, width=nil)
       self.length, self.width = length, (width || length)
     end
@@ -37,7 +49,7 @@ module AIXM
       end
     end
 
-    # Calculate the surface in square meters
+    # Calculate the surface in square meters.
     #
     # @return [Float]
     def surface
@@ -45,18 +57,9 @@ module AIXM
     end
 
     # @see Object#==
-    # @return [Boolean]
     def ==(other)
       self.class === other && length == other.length && width == other.width
     end
-    alias_method :eql?, :==
-
-    # @see Object#hash
-    # @return [Integer]
-    def hash
-      to_s.hash
-    end
 
   end
-
 end

data/lib/aixm/refinements.rb

@@ -128,8 +128,30 @@ module AIXM
     #   @note This is a refinement for +Object+
     #   @return [Object]
     refine Object do
-      def then_if(condition, &)
-        condition ? self.then(&) : self
+      def then_if(condition, &block)   # TODO: [ruby-3.1] use anonymous block "&" on this and next line
+        condition ? self.then(&block) : self
+      end
+    end
+
+    # @!method Range.from
+    #   Returns a Range covering the given object.
+    #
+    #   To ease coverage tests in mixed arrays of single objects and object
+    #   ranges, this method assures you're always dealing with objects. It
+    #   returns self if it is already a Range, otherwise builds one with the
+    #   given single object as both beginning and end.
+    #
+    #   @example
+    #     Range.from(5)      # => (5..5)
+    #     Range.from(1..3)   # => (1..3)
+    #
+    #   @note This is a refinement for +Range+
+    #   @param object [Object]
+    #   @return [Range]
+    #refine Range do
+    refine Range.singleton_class do
+      def from(object)
+        object.is_a?(Range) ? object : (object..object)
       end
     end
 
@@ -140,6 +162,7 @@ module AIXM
     #     /^(foo)(?<name>bar)/.decapture   # => /^(?:foo)(?:bar)/
     #
     #   @note This is a refinement for +Regexp+
+    #   @return [Regexp]
     refine Regexp do
       def decapture
         Regexp.new(to_s.gsub(/\(\?<\w+>|(?<![^\\]\\)\((?!\?)/, '(?:'))
@@ -154,6 +177,7 @@ module AIXM
     #     # => AIXM::Feature::NavigationalAid
     #
     #   @note This is a refinement for +String+
+    #   @return [Class]
     refine String do
       def to_class
         Object.const_get(self)
@@ -170,6 +194,7 @@ module AIXM
     #
     #   @see https://www.rubydoc.info/gems/dry-inflector
     #   @note This is a refinement for +String+
+    #   @return [String]
     refine String do
       def inflect(*inflections)
         inflections.inject(self) do |memo, inflection|
@@ -178,6 +203,21 @@ module AIXM
       end
     end
 
+    # @!method compact
+    #   Collapse whitespace to one space, but leave +\n+ untouched, then strip
+    #   what's left.
+    #
+    #   @example
+    #     "  foo\n\nbar  baz \r".compact   # => "foo\n\nbar baz"
+    #
+    #   @note This is a refinement for +String+
+    #   @return [String] compacted string
+    refine String do
+      def compact
+        split("\n").map { _1.gsub(/\s+/, ' ') }.join("\n").strip
+      end
+    end
+
     # @!method indent(number)
     #   Indent every line of a string with +number+ spaces.
     #