aixm 1.2.1 → 1.3.0

data/lib/aixm/concerns/association.rb

@@ -0,0 +1,381 @@
+using AIXM::Refinements
+
+module AIXM
+  module Concerns
+
+    # 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
+    #   blog.posts.count           # => 1
+    #   blog.posts.first == post   # => true
+    #   post.blog == blog          # => true
+    #   blog.remove_post(post)     # => Blog
+    #   blog.posts.count           # => 0
+    #   # --or--
+    #   post.blog = blog           # => Blog
+    #   blog.posts.count           # => 1
+    #   blog.posts.first == post   # => true
+    #   post.blog == blog          # => true
+    #   post.blog = nil            # => 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      # => Post (standard assignment)
+    #   blog.add_post(post)   # => Blog (alternative for chaining)
+    #   blog.post == post     # => true
+    #   post.blog == blog     # => true
+    #   blog.post = nil       # => nil
+    #   blog.post             # => nil
+    #   post.blog             # => nil
+    #   # --or--
+    #   post.blog = blog      # => Blog (standard assignment)
+    #   post.add_blog(blog)   # => Post (alternative for chaining)
+    #   post.blog == blog     # => true
+    #   blog.post == post     # => true
+    #   post.blog = nil       # => 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::Concerns::Association
+    #     has_many :posts, accept: 'Picture'
+    #   end
+    #   class Picture
+    #     include AIXM::Concerns::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::Concerns::Association
+    #     has_many :items, accept: ['Post', :picture]
+    #   end
+    #   class Post
+    #     include AIXM::Concerns::Association
+    #     belongs_to :blog, as: :item
+    #   end
+    #   class Picture
+    #     include AIXM::Concerns::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::Concerns::Association
+    #     has_many :posts do |post, title:| end
+    #   end
+    #   class Post
+    #     include AIXM::Concerns::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_variable_get(:"@#{attribute}") || AIXM::Concerns::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.any? { |c| object.is_a?(c.to_class) }
+            instance_eval("@#{attribute} ||= AIXM::Concerns::Association::Array.new")
+            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=
+          define_method(:"#{association}=") do |object|
+            fail(ArgumentError, "#{object.__class__} not allowed") unless class_names.any? { |c| 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)
+            object
+          end
+          # add_feature
+          define_method(:"add_#{association}") do |object|
+            send("#{association}=", object)
+            self
+          end
+          # 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
+          unless readonly
+            # feature=
+            define_method(:"#{attribute}=") do |object|
+              instance_variable_get(:"@#{attribute}")&.send(:"remove_#{inversion}", self)
+              object&.send(:"add_#{inversion}", self)
+              object
+            end
+            # add_feature
+            define_method(:"add_#{attribute}") do |object|
+              send("#{attribute}=", object)
+              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::Concerns::Association
+        #     has_many :items, accept: %i(post picture)
+        #   end
+        #   class Post
+        #     include AIXM::Concerns::Association
+        #     belongs_to :blog, as: :item
+        #     attr_accessor :title
+        #   end
+        #   class Picture
+        #     include AIXM::Concerns::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::Concerns::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.all? { |a, v| element.send(a) == v }
+              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::Concerns::Association
+        #     has_many :items, accept: %i(post picture)
+        #   end
+        #   class Post
+        #     include AIXM::Concerns::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::Concerns::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::Concerns::Association
+        #     has_many :posts
+        #   end
+        #   class Post
+        #     include AIXM::Concerns::Association
+        #     belongs_to :blog
+        #   end
+        #   blog, post = Blog.new, Post.new
+        #   duplicate_post = post.dup
+        #   blog.add_posts([post, duplicate_post])
+        #   blog.posts.duplicates   # => [[post, duplicate_post]]
+        #
+        # @return [Array<Array<AIXM::Feature>>]
+        def duplicates
+          AIXM::Concerns::Memoize.method :to_uid do
+            group_by { _1.to_uid.to_s }.select { |_, a| a.count > 1 }.map(&:last)
+          end
+        end
+      end
+    end
+
+  end
+end

data/lib/aixm/concerns/memoize.rb

@@ -0,0 +1,107 @@
+module AIXM
+  module Concerns
+
+    # Memoize the return value of a specific method across multiple instances for
+    # the duration of a block.
+    #
+    # The method signature is taken into account, therefore calls of the same
+    # method with different positional and/or keyword arguments are cached
+    # independently. On the other hand, when calling the method with a block,
+    # no memoization is performed at all.
+    #
+    # Nested memoization of the same method is allowed and won't reset the
+    # memoization cache.
+    #
+    # @example
+    #   class Either
+    #     include AIXM::Concerns::Memoize
+    #
+    #     def either(argument=nil, keyword: nil, &block)
+    #       $entropy || argument || keyword || (block.call if block)
+    #     end
+    #     memoize :either
+    #   end
+    #
+    #   a, b, c = Either.new, Either.new, Either.new
+    #
+    #   # No memoization before the block
+    #   $entropy = nil
+    #   a.either(1)                 # => 1
+    #   b.either(keyword: 2)        # => 2
+    #   c.either { 3 }              # => 3
+    #   $entropy = :not_nil
+    #   a.either(1)                 # => :not_nil
+    #   b.either(keyword: 2)        # => :not_nil
+    #   c.either { 3 }              # => :not_nil
+    #
+    #   # Memoization inside the block
+    #   AIXM::Concerns::Memoize.method :either do
+    #     $entropy = nil
+    #     a.either(1)                 # => 1
+    #     b.either(keyword: 2)        # => 2
+    #     c.either { 3 }              # => 3
+    #     $entropy = :not_nil
+    #     a.either(1)                 # => 1          (memoized)
+    #     b.either(keyword: 2)        # => 2          (memoized)
+    #     c.either { 3 }              # => :not_nil   (cannot be memoized)
+    #   end
+    #
+    #   # No memoization after the block
+    #   $entropy = nil
+    #   a.either(1)                 # => 1
+    #   $entropy = :not_nil
+    #   a.either(1)                 # => :not_nil
+    module Memoize
+      module ClassMethods
+        def memoize(method)
+          unmemoized_method = :"unmemoized_#{method}"
+          alias_method unmemoized_method, method
+          define_method method do |*args, **kargs, &block|
+            if block || !AIXM::Concerns::Memoize.cache.has_key?(method)
+              send(unmemoized_method, *args, **kargs, &block)
+            else
+              cache = AIXM::Concerns::Memoize.cache[method]
+              id = object_id.hash ^ args.hash ^ kargs.hash
+              if cache.has_key?(id)
+                cache[id]
+              else
+                cache[id] = send(unmemoized_method, *args, **kargs)
+              end
+            end
+          end
+        end
+      end
+
+      class << self
+        attr_reader :cache
+
+        def included(base)
+          base.extend(ClassMethods)
+          @cache = {}
+        end
+
+        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
+
+        def cached?(method)
+          cache.has_key?(method)
+        end
+
+        def call_without_cache(method)
+          yield
+        end
+
+        def call_with_cache(method)
+          cache[method] = {}
+          yield
+        ensure
+          cache.delete(method)
+        end
+      end
+    end
+
+  end
+end

data/lib/aixm/concerns/xml_builder.rb

@@ -0,0 +1,34 @@
+module AIXM
+  module Concerns
+
+    # Adds the XML builder wrapped to generate a document fragment.
+    module XMLBuilder
+      include AIXM::Concerns::Memoize
+
+      # Build a XML document fragment.
+      #
+      # @yield [Nokogiri::XML::Builder]
+      # @return [Nokogiri::XML::DocumentFragment]
+      def build_fragment
+        Nokogiri::XML::DocumentFragment.parse('').tap do |document|
+          Nokogiri::XML::Builder.with(document) do |fragment|
+            yield fragment
+          end
+          document.elements.each { _1.add_next_sibling("\n") }   # add newline between tags on top level
+        end
+      end
+
+      # @return [Nokogiri::XML::DocumentFragment] UID fragment
+      def to_uid(...)
+        build_fragment { add_uid_to(_1, ...) }
+      end
+      memoize :to_uid
+
+      # @return [String] AIXM or OFMX fragment
+      def to_xml(...)
+        build_fragment { add_to(_1, ...) }.to_xml.strip.concat("\n")
+      end
+
+    end
+  end
+end

data/lib/aixm/document.rb

@@ -10,12 +10,13 @@ module AIXM
   #     namespace: String (UUID)
   #     created_at: Time or Date or String
   #     effective_at: Time or Date or String
+  #     expiration_at: Time or Date or String or nil
   #   )
   #   document.add_feature(AIXM::Feature)
   #
   # @see https://gitlab.com/openflightmaps/ofmx/wikis/Snapshot
   class Document
-    include AIXM::Association
+    include AIXM::Concerns::Association
 
     NAMESPACE_RE = /\A[a-f\d]{8}-[a-f\d]{4}-[a-f\d]{4}-[a-f\d]{4}-[a-f\d]{12}\z/.freeze
 
@@ -36,7 +37,7 @@ module AIXM
     #   @param value [String]
     attr_reader :namespace
 
-    # Creation date and time
+    # Creation date and UTC time
     #
     # @overload created_at
     #   @return [Time]
@@ -44,7 +45,7 @@ module AIXM
     #   @param value [Time] default: {#effective_at} or now
     attr_reader :created_at
 
-    # Effective after date and time
+    # Effective after date and UTC time
     #
     # @overload effective_at
     #   @return [Time]
@@ -52,10 +53,19 @@ module AIXM
     #   @param value [Time] default: {#created_at} or now
     attr_reader :effective_at
 
+    # Expiration after date and UTC time
+    #
+    # @overload expiration_at
+    #   @return [Time, nil]
+    # @overload expiration_at=(value)
+    #   @param value [Time, nil]
+    attr_reader :expiration_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
+    def initialize(namespace: nil, created_at: nil, effective_at: nil, expiration_at: nil)
+      self.namespace = namespace
+      self.created_at, self.effective_at, self.expiration_at = created_at, effective_at, expiration_at
     end
 
     # @return [String]
@@ -69,11 +79,29 @@ module AIXM
     end
 
     def created_at=(value)
-      @created_at = value&.to_time || effective_at || Time.now
+      @created_at = if time = value&.to_time
+        fail(ArgumentError, "must be UTC") unless time.utc_offset.zero?
+        time.round
+      else
+        Time.now.utc.round
+      end
     end
 
     def effective_at=(value)
-      @effective_at = value&.to_time || created_at || Time.now
+      @effective_at = if time = value&.to_time
+        fail(ArgumentError, "must be UTC") unless time.utc_offset.zero?
+        time.round
+      else
+        created_at || Time.now.utc.round
+      end
+    end
+
+    def expiration_at=(value)
+      @expiration_at = value&.to_time
+      @expiration_at = if time = value&.to_time
+        fail(ArgumentError, "must be UTC") unless time.utc_offset.zero?
+        time.round
+      end
     end
 
     # Regions used throughout this document.
@@ -128,8 +156,8 @@ module AIXM
       end
     end
 
-    # @return [String] AIXM or OFMX markup
-    def to_xml
+    # @return [Nokogiri::XML::Document] Nokogiri AIXM or OFMX document
+    def document
       meta = {
         'xmlns:xsi': AIXM.schema(:namespace),
         version: AIXM.schema(:version),
@@ -137,21 +165,24 @@ module AIXM
         namespace: (namespace if AIXM.ofmx?),
         regions: (regions.join(' '.freeze) if AIXM.ofmx?),
         created: @created_at.xmlschema,
-        effective: @effective_at.xmlschema
+        effective: @effective_at.xmlschema,
+        expiration: (@expiration_at&.xmlschema if AIXM.ofmx?)
       }.compact
-      builder = Builder::XmlMarkup.new(indent: 2)
-      builder.instruct!
-      builder.tag!(AIXM.schema(:root), meta) do |root|
-        AIXM::Memoize.method :to_uid do
-          root << features.map(&:to_xml).join.indent(2)
+      Nokogiri::XML::Builder.new do |builder|
+        builder.send(AIXM.schema(:root), meta) do |root|
+          AIXM::Concerns::Memoize.method :to_uid do
+            features.each { _1.add_to(root) }
+          end
+          if AIXM.ofmx? && AIXM.config.mid
+            AIXM::PayloadHash::Mid.new(builder.doc).insert_mid
+          end
         end
-      end
-      if AIXM.ofmx? && AIXM.config.mid
-        AIXM::PayloadHash::Mid.new(builder.target!).insert_mid.to_xml
-      else
-        builder.target!
-      end
+      end.doc
     end
 
+    # @return [String] AIXM or OFMX markup
+    def to_xml
+      document.pretty.to_xml
+    end
   end
 end