aixm 0.3.8 → 0.3.10

data/lib/aixm/association.rb

@@ -0,0 +1,369 @@
+using AIXM::Refinements
+
+module AIXM
+
+  # Associate features and components with a minimalistic implementation of
+  # +has_many+, +has_one+ and +belongs_to+ associations.
+  #
+  # When adding or assigning an object on the associator (where the +has_many+
+  # or +has_one+ declaration is made), the object is verified and must be an
+  # instance of the declared class or a superclass thereof.
+  #
+  # When assigning an object on the associated (where the +belongs_to+
+  # declaration is made), the object is not verified. However, since the actual
+  # assignment is always delegated to the associator, unacceptable objects will
+  # raise errors.
+  #
+  # @example Simple +has_many+ association
+  #   class Blog
+  #     has_many :posts   # :post has to be a key in AIXM::CLASSES
+  #   end
+  #   class Post
+  #     belongs_to :blog
+  #   end
+  #   blog, post = Blog.new, Post.new
+  #   # --either--
+  #   blog.add_post(post)
+  #   blog.posts.count           # => 1
+  #   blog.posts.first == post   # => true
+  #   post.blog == blog          # => true
+  #   blog.remove_post(post)
+  #   blog.posts.count           # => 0
+  #   # --or--
+  #   post.blog = blog
+  #   blog.posts.count           # => 1
+  #   blog.posts.first == post   # => true
+  #   post.blog == blog          # => true
+  #   post.blog = nil
+  #   blog.posts.count           # => 0
+  #   # --or--
+  #   post_2 = Post.new
+  #   blog.add_posts([post, post_2])
+  #   blog.posts.count                    # => 2
+  #   blog.posts == [post, post_2]        # => true
+  #   blog.remove_posts([post_2, post])
+  #   blog.posts.count                    # => 0
+  #
+  # @example Simple +has_one+ association
+  #   class Blog
+  #     has_one :posts   # :post has to be a key in AIXM::CLASSES
+  #   end
+  #   class Post
+  #     belongs_to :blog
+  #   end
+  #   blog, post = Blog.new, Post.new
+  #   # --either--
+  #   blog.post = post
+  #   blog.post == post   # => true
+  #   post.blog == blog   # => true
+  #   blog.post = nil
+  #   blog.post           # => nil
+  #   post.blog           # => nil
+  #   # --or--
+  #   post.blog = blog
+  #   post.blog == blog   # => true
+  #   blog.post == post   # => true
+  #   post.blog = nil
+  #   post.blog           # => nil
+  #   blog.post           # => nil
+  #
+  # @example Association with readonly +belongs_to+ (idem for +has_one+)
+  #   class Blog
+  #     has_many :posts   # :post has to be a key in AIXM::CLASSES
+  #   end
+  #   class Post
+  #     belongs_to :blog, readonly: true
+  #   end
+  #   blog, post = Blog.new, Post.new
+  #   post.blog = blog           # => NoMethodError
+  #
+  # @example Association with explicit class (idem for +has_one+)
+  #   class Blog
+  #     include AIXM::Association
+  #     has_many :posts, accept: 'Picture'
+  #   end
+  #   class Picture
+  #     include AIXM::Association
+  #     belongs_to :blog
+  #   end
+  #   blog, picture = Blog.new, Picture.new
+  #   blog.add_post(picture)
+  #   blog.posts.first == picture   # => true
+  #
+  # @example Polymorphic associator (idem for +has_one+)
+  #   class Blog
+  #     has_many :posts, as: :postable
+  #   end
+  #   class Feed
+  #     has_many :posts, as: :postable
+  #   end
+  #   class Post
+  #     belongs_to :postable
+  #   end
+  #   blog, feed, post_1, post_2, post_3 = Blog.new, Feed.new, Post.new, Post.new, Post.new
+  #   blog.add_post(post_1)
+  #   post_1.postable == blog   # => true
+  #   feed.add_post(post_2)
+  #   post_2.postable == feed   # => true
+  #   post_3.postable = blog    # => NoMethodError
+  #
+  # @example Polymorphic associated (idem for +has_one+)
+  #   class Blog
+  #     include AIXM::Association
+  #     has_many :items, accept: ['Post', :picture]
+  #   end
+  #   class Post
+  #     include AIXM::Association
+  #     belongs_to :blog, as: :item
+  #   end
+  #   class Picture
+  #     include AIXM::Association
+  #     belongs_to :blog, as: :item
+  #   end
+  #   blog, post, picture = Blog.new, Post.new, Picture.new
+  #   blog.add_item(post)
+  #   blog.add_item(picture)
+  #   blog.items.count             # => 2
+  #   blog.items.first == post     # => true
+  #   blog.items.last == picture   # => true
+  #   post.blog == blog            # => true
+  #   picture.blog == blog         # => true
+  #
+  # @example Add method which enriches passed associated object (+has_many+ only)
+  #   class Blog
+  #     has_many :posts do |post, related_to: nil|      # this defines the signature of add_post
+  #       post.related_to = related_to || @posts.last   # executes in the context of the current blog
+  #     end
+  #   end
+  #   class Post
+  #     belongs_to :blog
+  #     attr_accessor :related_to
+  #   end
+  #   blog, post_1, post_2, post_3 = Blog.new, Post.new, Post.new, Post.new
+  #   blog.add_post(post_1)
+  #   post_1.related_to             # => nil
+  #   blog.add_post(post_2)
+  #   post_2.related_to == post_1   # => true
+  #   blog.add_post(post_3, related_to: post_1)
+  #   post_3.related_to == post_1   # => true
+  #
+  # @example Add method which builds and yields new associated object (+has_many+ only)
+  #   class Blog
+  #     include AIXM::Association
+  #     has_many :posts do |post, title:| end
+  #   end
+  #   class Post
+  #     include AIXM::Association
+  #     belongs_to :blog
+  #     attr_accessor :title, :text
+  #     def initialize(title:)   # same signature as "has_many" block above
+  #       @title = title
+  #     end
+  #   end
+  #   blog = Blog.new
+  #   blog.add_post(title: "title") do |post|   # note that no post instance is passed
+  #     post.text = "text"
+  #   end
+  #   blog.posts.first.title   # => "title"
+  #   blog.posts.first.text    # => "text"
+  module Association
+    module ClassMethods
+      attr_reader :has_many_attributes, :has_one_attributes, :belongs_to_attributes
+
+      def has_many(attribute, as: nil, accept: nil, &association_block)
+        association = attribute.to_s.inflect(:singularize)
+        inversion = as || self.to_s.inflect(:demodulize, :tableize, :singularize)
+        class_names = [accept || association].flatten.map { AIXM::CLASSES[_1.to_sym] || _1 }
+        (@has_many_attributes ||= []) << attribute
+        # features
+        define_method(attribute) do
+          instance_eval("@#{attribute} ||= AIXM::Association::Array.new")
+        end
+        # add_feature
+        define_method(:"add_#{association}") do |object=nil, **options, &add_block|
+          unless object
+            fail(ArgumentError, "must pass object to add") if class_names.count > 1
+            object = class_names.first.to_class.new(**options)
+            add_block.call(object) if add_block
+          end
+          instance_exec(object, **options, &association_block) if association_block
+          fail(ArgumentError, "#{object.__class__} not allowed") unless class_names.reduce(false){ |m, c| m || object.is_a?(c.to_class) }
+          send(attribute).send(:push, object)
+          object.instance_variable_set(:"@#{inversion}", self)
+          self
+        end
+        # add_features
+        define_method(:"add_#{attribute}") do |objects=[], **options, &add_block|
+          objects.each { send(:"add_#{association}", _1, **options, &add_block) }
+          self
+        end
+        # remove_feature
+        define_method(:"remove_#{association}") do |object|
+          send(attribute).send(:delete, object)
+          object.instance_variable_set(:"@#{inversion}", nil)
+          self
+        end
+        # remove_features
+        define_method(:"remove_#{attribute}") do |objects=[]|
+          objects.each { send(:"remove_#{association}", _1) }
+          self
+        end
+      end
+
+      def has_one(attribute, as: nil, accept: nil, allow_nil: false)
+        association = attribute.to_s
+        inversion = (as || self.to_s.inflect(:demodulize, :tableize, :singularize)).to_s
+        class_names = [accept || association].flatten.map { AIXM::CLASSES[_1.to_sym] || _1 }
+        class_names << 'NilClass' if allow_nil
+        (@has_one_attributes ||= []) << attribute
+        # feature
+        attr_reader attribute
+        # feature= / add_feature
+        define_method(:"#{association}=") do |object|
+          fail(ArgumentError, "#{object.__class__} not allowed") unless class_names.reduce(false){ |m, c| m || object.is_a?(c.to_class) }
+          instance_variable_get(:"@#{attribute}")&.instance_variable_set(:"@#{inversion}", nil)
+          instance_variable_set(:"@#{attribute}", object)
+          object&.instance_variable_set(:"@#{inversion}", self)
+        end
+        alias_method(:"add_#{association}", :"#{association}=")
+        # remove_feature
+        define_method(:"remove_#{association}") do |_|
+          send(:"#{association}=", nil)
+          self
+        end
+      end
+
+      def belongs_to(attribute, as: nil, readonly: false)
+        association = self.to_s.inflect(:demodulize, :tableize, :singularize)
+        inversion = (as || association).to_s
+        (@belongs_to_attributes ||= []) << attribute
+        # feature
+        attr_reader attribute
+        # feature=
+        unless readonly
+          define_method(:"#{attribute}=") do |object|
+            instance_variable_get(:"@#{attribute}")&.send(:"remove_#{inversion}", self)
+            object&.send(:"add_#{inversion}", self)
+          end
+        end
+      end
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    class Array < ::Array
+      private :<<, :push, :append, :unshift, :prepend
+      private :delete, :pop, :shift
+
+      # Find objects of the given class and optionally with the given
+      # attribute values on a has_many association.
+      #
+      # The class can either be declared by passing the class itself or by
+      # passing a shortcut symbol as listed in +AIXM::CLASSES+.
+      #
+      # @example
+      #   class Blog
+      #     include AIXM::Association
+      #     has_many :items, accept: %i(post picture)
+      #   end
+      #   class Post
+      #     include AIXM::Association
+      #     belongs_to :blog, as: :item
+      #     attr_accessor :title
+      #   end
+      #   class Picture
+      #     include AIXM::Association
+      #     belongs_to :blog, as: :item
+      #   end
+      #   blog, post, picture = Blog.new, Post.new, Picture.new
+      #   post.title = "title"
+      #   blog.add_item(post)
+      #   blog.add_item(picture)
+      #   blog.items.find_by(:post) == [post]                    # => true
+      #   blog.items.find_by(Post) == [post]                     # => true
+      #   blog.items.find_by(:post, title: "title") == [post]    # => true
+      #   blog.items.find_by(Object) == [post, picture]          # => true
+      #
+      # @param klass [Class, Symbol] class (e.g. AIXM::Feature::Airport,
+      #   AIXM::Feature::NavigationalAid::VOR) or shortcut symbol (e.g.
+      #   :airport or :vor) as listed in AIXM::CLASSES
+      # @param attributes [Hash] search attributes by their values
+      # @return [AIXM::Association::Array]
+      def find_by(klass, attributes={})
+        if klass.is_a? Symbol
+          klass = AIXM::CLASSES[klass]&.to_class || fail(ArgumentError, "unknown class shortcut `#{klass}'")
+        end
+        self.class.new(
+          select do |element|
+            if element.kind_of? klass
+              attributes.reduce(true) do |memo, (attribute, value)|
+                memo && element.send(attribute) == value
+              end
+            end
+          end
+        )
+      end
+
+      # Find equal objects on a has_many association.
+      #
+      # This may seem redundant at first, but keep in mind that two instances
+      # of +AIXM::CLASSES+ which implement `#to_uid` are considered equal if
+      # they are instances of the same class and both their UIDs as calculated
+      # by `#to_uid` are equal. Attributes which are not part of the `#to_uid`
+      # calculation are irrelevant!
+      #
+      # @example
+      #   class Blog
+      #     include AIXM::Association
+      #     has_many :items, accept: %i(post picture)
+      #   end
+      #   class Post
+      #     include AIXM::Association
+      #     belongs_to :blog, as: :item
+      #     attr_accessor :title
+      #   end
+      #   blog, post = Blog.new, Post.new
+      #   blog.add_item(post)
+      #   blog.items.find(post) == [post]   # => true
+      #
+      # @param object [Object] instance of class listed in AIXM::CLASSES
+      # @return [AIXM::Association::Array]
+      def find(object)
+        klass = object.__class__
+        self.class.new(
+          select do |element|
+            element.kind_of?(klass) && element == object
+          end
+        )
+      end
+
+      # Find equal or identical duplicates on a has_many association.
+      #
+      # @example
+      #   class Blog
+      #     include AIXM::Association
+      #     has_many :posts
+      #   end
+      #   class Post
+      #     include AIXM::Association
+      #     belongs_to :blog
+      #   end
+      #   blog, post = Blog.new, Post.new
+      #   blog.add_posts([post, post])
+      #   blog.posts.duplicates   # => [post]
+      #
+      # @return [AIXM::Association::Array]
+      def duplicates
+        AIXM::Memoize.method :to_uid do
+          self.class.new(
+            select.with_index do |element, index|
+              index != self.index(element)
+            end
+          )
+        end
+      end
+    end
+  end
+end

data/lib/aixm/classes.rb

@@ -0,0 +1,43 @@
+module AIXM
+
+  # Manifest of shorthand names and their corresponding AIXM class names
+  CLASSES = {
+    document: 'AIXM::Document',
+    xy: 'AIXM::XY',
+    z: 'AIXM::Z',
+    d: 'AIXM::D',
+    f: 'AIXM::F',
+    a: 'AIXM::A',
+    w: 'AIXM::W',
+    p: 'AIXM::P',
+    address: 'AIXM::Feature::Address',
+    organisation: 'AIXM::Feature::Organisation',
+    unit: 'AIXM::Feature::Unit',
+    service: 'AIXM::Component::Service',
+    frequency: 'AIXM::Component::Frequency',
+    airport: 'AIXM::Feature::Airport',
+    runway: 'AIXM::Component::Runway',
+    fato: 'AIXM::Component::FATO',
+    helipad: 'AIXM::Component::Helipad',
+    surface: 'AIXM::Component::Surface',
+    lighting: 'AIXM::Component::Lighting',
+    airspace: 'AIXM::Feature::Airspace',
+    layer: 'AIXM::Component::Layer',
+    geometry: 'AIXM::Component::Geometry',
+    vertical_limit: 'AIXM::Component::VerticalLimit',
+    arc: 'AIXM::Component::Geometry::Arc',
+    border: 'AIXM::Component::Geometry::Border',
+    circle: 'AIXM::Component::Geometry::Circle',
+    point: 'AIXM::Component::Geometry::Point',
+    dme: 'AIXM::Feature::NavigationalAid::DME',
+    designated_point: 'AIXM::Feature::NavigationalAid::DesignatedPoint',
+    marker: 'AIXM::Feature::NavigationalAid::Marker',
+    tacan: 'AIXM::Feature::NavigationalAid::TACAN',
+    ndb: 'AIXM::Feature::NavigationalAid::NDB',
+    vor: 'AIXM::Feature::NavigationalAid::VOR',
+    obstacle: 'AIXM::Feature::Obstacle',
+    obstacle_group: 'AIXM::Feature::ObstacleGroup',
+    timetable: 'AIXM::Component::Timetable'
+  }.freeze
+
+end

data/lib/aixm/component/fato.rb

@@ -1,7 +1,7 @@
 using AIXM::Refinements
 
 module AIXM
-  class Component
+  module Component
 
     # FATO (final approach and take-off area) for vertical take-off aircraft
     # such as helicopters.
@@ -24,8 +24,11 @@ module AIXM
     #     direction.remarks = String or nil
     #   end
     #
-    # @see https://github.com/openflightmaps/ofmx/wiki/Airport#fto-fato
+    # @see https://gitlab.com/openflightmaps/ofmx/wikis/Airport#fto-fato
     class FATO
+      include AIXM::Association
+      include AIXM::Memoize
+
       STATUSES = {
         CLSD: :closed,
         WIP: :work_in_progress,          # e.g. construction work
@@ -35,8 +38,26 @@ module AIXM
         OTHER: :other                    # specify in remarks
       }.freeze
 
-      # @return [AIXM::Feature::Airport] airport this FATO belongs to
-      attr_reader :airport
+      # @!method surface
+      #   @return [AIXM::Component::Surface] surface of the FATO
+      # @!method surface=(surface)
+      #   @param surface [AIXM::Component::Surface]
+      has_one :surface
+
+      # @!method directions
+      #   @return [Array<AIXM::Component::FATO::Direction>] maps added direction names to full FATO directions
+      # @!method add_direction(direction)
+      #   @param direction [AIXM::A] name of the FATO direction (e.g. "12" or "16L")
+      #   @return [self]
+      has_many :directions, accept: 'AIXM::Component::FATO::Direction' do |direction, name:| end
+
+      # @!method airport
+      #   @return [AIXM::Feature::Airport] airport this FATO belongs to
+      belongs_to :airport
+
+      # @!method helipad
+      #   @return [AIXM::Component::Helipad] helipad situated on this FATO
+      belongs_to :helipad
 
       # @return [String] full name (e.g. "H1")
       attr_reader :name
@@ -47,9 +68,6 @@ module AIXM
       # @return [AIXM::D, nil] width
       attr_reader :width
 
-      # @return [AIXM::Component::Surface] surface of the FATO
-      attr_reader :surface
-
       # @return [String, nil] markings
       attr_reader :marking
 
@@ -62,13 +80,9 @@ module AIXM
       # @return [String, nil] free text remarks
       attr_reader :remarks
 
-      # @return [Hash{String => AIXM::Component::FATO::Direction}] maps added direction names to full FATO directions
-      attr_reader :directions
-
       def initialize(name:)
         self.name = name
-        @surface = AIXM.surface
-        @directions = {}
+        self.surface = AIXM.surface
       end
 
       # @return [String]
@@ -76,12 +90,6 @@ module AIXM
         %Q(#<#{self.class} airport=#{airport&.id.inspect} name=#{name.inspect}>)
       end
 
-      def airport=(value)
-        fail(ArgumentError, "invalid airport") unless value.is_a? AIXM::Feature::Airport
-        @airport = value
-      end
-      private :airport=
-
       def name=(value)
         fail(ArgumentError, "invalid name") unless value.is_a? String
         @name = value.uptrans
@@ -119,20 +127,15 @@ module AIXM
         @remarks = value&.to_s
       end
 
-      def add_direction(name:)
-        direction = Direction.new(fato: self, name: name)
-        yield direction
-        @directions[name] = direction
-      end
-
       # @return [String] UID markup
       def to_uid
         builder = Builder::XmlMarkup.new(indent: 2)
         builder.FtoUid do |fto_uid|
           fto_uid << airport.to_uid.indent(2)
           fto_uid.txtDesig(name)
-        end.insert_payload_hash(region: AIXM.config.mid_region)
+        end
       end
+      memoize :to_uid
 
       # @return [String] AIXM or OFMX markup
       def to_xml
@@ -151,7 +154,7 @@ module AIXM
           fto.codeSts(STATUSES.key(status).to_s) if status
           fto.txtRmk(remarks) if remarks
         end
-        directions.values.each do |direction|
+        directions.each do |direction|
           builder << direction.to_xml
         end
         builder.target!
@@ -159,11 +162,20 @@ module AIXM
 
       # FATO directions further describe each direction to and from the FATO.
       #
-      # @see https://github.com/openflightmaps/ofmx/wiki/Airport#fdn-fato-direction
+      # @see https://gitlab.com/openflightmaps/ofmx/wikis/Airport#fdn-fato-direction
       class Direction
+        include AIXM::Association
+        include AIXM::Memoize
+
+        # @!method lightings
+        #   @return [Array<AIXM::Component::Lighting>] installed lighting systems
+        # @!method add_lighting(lighting)
+        #   @param lighting [AIXM::Component::Lighting]
+        has_many :lightings, as: :lightable
 
-        # @return [AIXM::Component::FATO] FATO the FATO direction is further describing
-        attr_reader :fato
+        # @!method fato
+        #   @return [AIXM::Component::FATO] FATO the FATO direction is further describing
+        belongs_to :fato
 
         # @return [AIXM::A] name of the FATO direction (e.g. "12" or "16L")
         attr_reader :name
@@ -174,12 +186,8 @@ module AIXM
         # @return [String, nil] free text remarks
         attr_reader :remarks
 
-        # @return [Array<AIXM::Component::Lighting>] installed lighting systems
-        attr_reader :lightings
-
-        def initialize(fato:, name:)
-          self.fato, self.name = fato, name
-          @lightings = []
+        def initialize(name:)
+          self.name = name
         end
 
         # @return [String]
@@ -187,12 +195,6 @@ module AIXM
           %Q(#<#{self.class} airport=#{fato&.airport&.id.inspect} name=#{name.inspect}>)
         end
 
-        def fato=(value)
-          fail(ArgumentError, "invalid FATO") unless value.is_a? AIXM::Component::FATO
-          @fato = value
-        end
-        private :fato
-
         def name=(value)
           fail(ArgumentError, "invalid name") unless value.is_a? String
           @name = AIXM.a(value)
@@ -208,17 +210,6 @@ module AIXM
           @remarks = value&.to_s
         end
 
-        # Add a lighting system to the FATO direction.
-        #
-        # @param lighting [AIXM::Component::Lighting] lighting instance
-        # @return [self]
-        def add_lighting(lighting)
-          fail(ArgumentError, "invalid lighting") unless lighting.is_a? AIXM::Component::Lighting
-          lighting.send(:lightable=, self)
-          @lightings << lighting
-          self
-        end
-
         # @return [AIXM::A] magnetic orientation (magnetic bearing) in degrees
         def magnetic_orientation
           if geographic_orientation && fato.airport.declination
@@ -232,8 +223,9 @@ module AIXM
           builder.FdnUid do |fdn_uid|
             fdn_uid << fato.to_uid.indent(2)
             fdn_uid.txtDesig(name)
-          end.insert_payload_hash(region: AIXM.config.mid_region)
+          end
         end
+        memoize :to_uid
 
         # @return [String] AIXM or OFMX markup
         def to_xml