aixm 0.2.3 → 0.3.0

data/lib/aixm/component/service.rb

@@ -0,0 +1,170 @@
+using AIXM::Refinements
+
+module AIXM
+  class Component
+
+    # Service provided by a unit.
+    #
+    # ===Cheat Sheet in Pseudo Code:
+    #   service = AIXM.service(
+    #     name: String
+    #     type: TYPES
+    #   )
+    #   service.timetable = AIXM.timetable or nil
+    #   service.remarks = String or nil
+    #   service.add_frequency(AIXM.frequency)
+    #
+    # @see https://github.com/openflightmaps/ofmx/wiki/Organisation#ser-service
+    class Service
+      TYPES = {
+        ACS: :area_control_service,
+        ADS: :automatic_dependent_surveillance_service,
+        ADVS: :advisory_service,
+        AFIS: :aerodrome_flight_information_service,
+        AFS: :aeronautical_fixed_service,
+        AIS: :aeronautical_information_service,
+        ALRS: :alerting_service,
+        AMS: :aeronautical_mobile_service,
+        AMSS: :aeronautical_mobile_satellite_service,
+        APP: :approach_control_service,
+        'APP-ARR': :approach_control_service_for_arrival,
+        'APP-DEP': :approach_control_service_for_departure,
+        ARTCC: :air_route_traffic_control_centre_service,
+        ATC: :air_traffic_control_service,
+        ATFM: :air_traffic_flow_management_service,
+        ATIS: :automated_terminal_information_service,
+        'ATIS-ARR': :automated_terminal_information_service_for_arrival,
+        'ATIS-DEP': :automated_terminal_information_service_for_departure,
+        ATM: :air_traffic_management_service,
+        ATS: :air_traffic_service,
+        BOF: :briefing_service,
+        BS: :commercial_broadcasting_service,
+        COM: :communications_service,
+        CTAF: :common_traffic_advisory_frequency_service,
+        DVDF: :doppler_vdf_service,
+        EFAS: :en_route_flight_advisory_service,
+        ENTRY: :entry_clearance_service,
+        EXIT: :exit_clearance_service,
+        FCST: :forecasting_service,
+        FIS: :flight_information_service,
+        FISA: :automated_flight_information_service,
+        FSS: :flight_service_station_service,
+        GCA: :ground_controlled_approach_service,
+        INFO: :information_provision_service,
+        MET: :meteorological_service,
+        NOF: :international_notam_service,
+        OAC: :oceanic_area_control_service,
+        OVERFLT: :overflight_clearance_service,
+        PAR: :precision_approach_radar_service,
+        RAC: :rules_of_the_air_and_air_traffic_services,
+        RADAR: :radar_service,
+        RAF: :regional_area_forecasting_service,
+        RCC: :rescue_coordination_service,
+        SAR: :search_and_rescue_service,
+        SIGMET: :sigmet_service,
+        SMC: :surface_movement_control_service,
+        SMR: :surface_movement_radar_service,
+        SRA: :surveillance_radar_approach_service,
+        SSR: :secondary_surveillance_radar_service,
+        TAR: :terminal_area_radar_service,
+        TWEB: :transcribed_weather_broadcast_service,
+        TWR: :aerodrome_control_tower_service,
+        UAC: :upper_area_control_service,
+        UDF: :uhf_direction_finding_service,
+        VDF: :vhf_direction_finding_service,
+        VOLMET: :volmet_service,
+        VOT: :vor_test_facility,
+        OTHER: :other   # specify in remarks
+      }.freeze
+
+      # @return [AIXM::Feature::Unit] unit providing this service
+      attr_reader :unit
+
+      # @return [String] full name
+      attr_reader :name
+
+      # @return [Symbol] type of service (see {TYPES})
+      attr_reader :type
+
+      # @return [AIXM::Component::Timetable, nil] operating hours
+      attr_reader :timetable
+
+      # @return [String, nil] free text remarks
+      attr_reader :remarks
+
+      # @return [Array<AIXM::Component::Frequency>] frequencies used by this service
+      attr_reader :frequencies
+
+      def initialize(name:, type:)
+        self.name, self.type = name, type
+        @frequencies = []
+      end
+
+      # @return [String]
+      def inspect
+        %Q(#<#{self.class} type=#{type.inspect}>)
+      end
+
+      def unit=(value)
+        fail(ArgumentError, "invalid unit") unless value.is_a? AIXM::Feature::Unit
+        @unit = value
+      end
+      private :unit=
+
+      def name=(value)
+        fail(ArgumentError, "invalid name") unless value.is_a? String
+        @name = value.uptrans
+      end
+
+      def type=(value)
+        @type = TYPES.lookup(value&.to_s&.to_sym, nil) || fail(ArgumentError, "invalid type")
+      end
+
+      def timetable=(value)
+        fail(ArgumentError, "invalid timetable") unless value.nil? || value.is_a?(AIXM::Component::Timetable)
+        @timetable = value
+      end
+
+      def remarks=(value)
+        @remarks = value&.to_s
+      end
+
+      # Add a frequency used by this service.
+      #
+      # @param frequency [AIXM::Component::Frequency] frequency instance
+      # @return [self]
+      def add_frequency(frequency)
+        fail(ArgumentError, "invalid frequency") unless frequency.is_a? AIXM::Component::Frequency
+        frequency.send(:service=, self)
+        @frequencies << frequency
+        self
+      end
+
+      # @return [String] UID markup
+      def to_uid
+        builder = Builder::XmlMarkup.new(indent: 2)
+        builder.SerUid do |ser_uid|
+          ser_uid << unit.to_uid.indent(2)
+          ser_uid.codeType(TYPES.key(type).to_s)
+          ser_uid.noSeq(@sequence)
+        end
+      end
+
+      # @return [String] AIXM or OFMX markup
+      def to_xml(sequence=1)
+        @sequence = sequence
+        builder = Builder::XmlMarkup.new(indent: 2)
+        builder.Ser do |ser|
+          ser << to_uid.indent(2)
+          ser << timetable.to_xml(as: :Stt).indent(2) if timetable
+          ser.txtRmk(remarks) if remarks
+        end
+        frequencies.each do |frequency|
+          builder << frequency.to_xml
+        end
+        builder.target!
+      end
+    end
+
+  end
+end

data/lib/aixm/component/timetable.rb

@@ -0,0 +1,65 @@
+using AIXM::Refinements
+
+module AIXM
+  class Component
+
+    # 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
+    #   )
+    #   timetable.remarks = String or nil
+    #
+    # ===Shortcuts:
+    # * +AIXM::H24+ - continuous, all day and all night
+    #
+    # @see https://github.com/openflightmaps/ofmx/wiki/Timetable#predefined-timetable
+    class Timetable
+      CODES = {
+        H24: :continuous,           # all day and all night
+        HJ: :sunrise_to_sunset,     # all day
+        HN: :sunset_to_sunrise,     # all night
+        HX: :unspecified,
+        HO: :operational_request,   # on request only
+        NOTAM: :notam,              # see NOTAM
+        OTHER: :other               # specify in remarks
+      }.freeze
+
+      # @return [Symbol] predefined timetable code (see {CODES})
+      attr_reader :code
+
+      # @return [String, nil] free text remarks
+      attr_reader :remarks
+
+      def initialize(code:)
+        self.code = code
+      end
+
+      # @return [String]
+      def inspect
+        %Q(#<#{self.class} code=#{code.inspect}>)
+      end
+
+      def code=(value)
+        @code = CODES.lookup(value&.to_s&.to_sym, nil) || fail(ArgumentError, "invalid code")
+      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)
+          tag.txtRmkWorkHr(remarks) if remarks
+        end
+      end
+    end
+
+  end
+end

data/lib/aixm/component/vertical_limits.rb

@@ -1,49 +1,85 @@
+using AIXM::Refinements
+
 module AIXM
-  module Component
+  class Component
 
-    ##
-    # Vertical limits define a 3D airspace vertically. They are normally noted
-    # as follows:
+    # Vertical limits define a 3D airspace vertically. They are often noted in
+    # AIP as follows:
     #
-    #   +upper z+ (or +max_z+ whichever is higher)
-    #   ---------
-    #   +lower_z+ (or +min_z+ whichever is lower)
+    #   upper_z (or max_z whichever is higher)
+    #   -------
+    #   lower_z (or min_z whichever is lower)
     #
-    # Shortcuts:
-    # * +AIXM::GROUND+ - surface (aka: 0ft QFE)
-    # * +AIXM::UNLIMITED+ - no upper limit (aka: FL 999)
-    class VerticalLimits < Base
-      using AIXM::Refinements
-
+    # ===Cheat Sheet in Pseudo Code:
+    #   vertical_limits = AIXM.vertical_limits(
+    #     upper_z: AIXM.z
+    #     lower_z: AIXM.z
+    #     max_z: AIXM.z or nil
+    #     min_z: AIXM.z or nil
+    #   )
+    #
+    # ===Shortcuts:
+    # * +AIXM::GROUND+ - surface expressed as "0 ft QFE"
+    # * +AIXM::UNLIMITED+ - no upper limit expressed as "FL 999"
+    #
+    # @see https://github.com/openflightmaps/ofmx/wiki/Airspace#ase-airspace
+    class VerticalLimits
+      # @api private
       TAGS = { upper: :Upper, lower: :Lower, max: :Max, min: :Mnm }.freeze
+
+      # @api private
       CODES = { qfe: :HEI, qnh: :ALT, qne: :STD }.freeze
 
-      attr_reader :upper_z, :lower_z, :max_z, :min_z
+      # @return [AIXM::Z] upper limit
+      attr_reader :upper_z
+
+      # @return [AIXM::Z] lower limit
+      attr_reader :lower_z
+
+      # @return [AIXM::Z] alternative upper limit ("whichever is higher")
+      attr_reader :max_z
+
+      # @return [AIXM::Z] alternative lower limit ("whichever is lower")
+      attr_reader :min_z
+
+      def initialize(upper_z:, lower_z:, max_z: nil, min_z: nil)
+        self.upper_z, self.lower_z, self.max_z, self.min_z = upper_z, lower_z, max_z, min_z
+      end
+
+      # @return [String]
+      def inspect
+        %Q(#<#{self.class} upper_z="#{upper_z.to_s}" lower_z="#{lower_z.to_s}">)
+      end
+
+      def upper_z=(value)
+        fail(ArgumentError, "invalid upper_z") unless value.is_a? AIXM::Z
+        @upper_z = value
+      end
+
+      def lower_z=(value)
+        fail(ArgumentError, "invalid lower_z") unless value.is_a? AIXM::Z
+        @lower_z = value
+      end
 
-      def initialize(max_z: nil, upper_z:, lower_z:, min_z: nil)
-        fail(ArgumentError, "invalid upper_z") unless upper_z.is_a? AIXM::Z
-        fail(ArgumentError, "invalid lower_z") unless lower_z.is_a? AIXM::Z
-        fail(ArgumentError, "invalid max_z") unless max_z.nil? || max_z.is_a?(AIXM::Z)
-        fail(ArgumentError, "invalid min_z") unless min_z.nil? || min_z.is_a?(AIXM::Z)
-        @upper_z, @lower_z, @max_z, @min_z = upper_z, lower_z, max_z, min_z
+      def max_z=(value)
+        fail(ArgumentError, "invalid max_z") unless value.nil? || value.is_a?(AIXM::Z)
+        @max_z = value
       end
 
-      ##
-      # Digest to identify the payload
-      def to_digest
-        [upper_z.alt, upper_z.code, lower_z.alt, lower_z.code, max_z&.alt, max_z&.code, min_z&.alt, min_z&.code].to_digest
+      def min_z=(value)
+        fail(ArgumentError, "invalid min_z") unless value.nil? || value.is_a?(AIXM::Z)
+        @min_z = value
       end
 
-      ##
-      # Render AIXM markup
-      def to_aixm(*extensions)
+      # @return [String] AIXM or OFMX markup
+      def to_xml
         %i(upper lower max min).each_with_object(Builder::XmlMarkup.new(indent: 2)) do |limit, builder|
           if z = send(:"#{limit}_z")
             builder.tag!(:"codeDistVer#{TAGS[limit]}", CODES[z.code].to_s)
             builder.tag!(:"valDistVer#{TAGS[limit]}", z.alt.to_s)
-            builder.tag!(:"uomDistVer#{TAGS[limit]}", z.unit.to_s)
+            builder.tag!(:"uomDistVer#{TAGS[limit]}", z.unit.upcase.to_s)
           end
-        end.target!   # see https://github.com/jimweirich/builder/issues/42
+        end.target!
       end
     end
 

data/lib/aixm/config.rb

@@ -0,0 +1,87 @@
+module AIXM
+
+  SCHEMAS = {
+    aixm: {
+      version: '4.5',
+      namespace: 'http://www.aixm.aero/schema/4.5/AIXM-Snapshot.xsd',
+      xsd: Pathname(__dir__).join('..', '..', 'schemas', 'aixm', '4.5', 'AIXM-Snapshot.xsd'),
+      root: 'AIXM-Snapshot'
+    },
+    ofmx: {
+      version: '0',
+      namespace: 'http://openflightmaps.org/schema/0/OFMX-Snapshot.xsd',
+      xsd: Pathname(__dir__).join('..', '..', 'schemas', 'ofmx', '0', 'OFMX-Snapshot.xsd'),
+      root: 'OFMX-Snapshot'
+    }
+  }.freeze
+
+  class << self
+
+    # Access the configuration (e.g. +AIXM.config.schema+)
+    # @return [OpenStruct] configuration struct
+    def config
+      @@config
+    end
+
+    # Currently active schema
+    #
+    # @example Get the schema identifyer
+    #   AIXM.schema   # => :aixm
+    #
+    # @example Get schema details
+    #   AIXM.schema(:version)   # => '4.5'
+    #   AIXM.schema(:root)      # => 'AIXM-Snapshot'
+    #
+    # @param key [Symbol, nil] schema detail key (see {SCHEMAS})
+    # @return [Object] schema detail value
+    def schema(key = nil)
+      key ? SCHEMAS.dig(@@config.schema, key) : @@config.schema
+    end
+
+    # Shortcuts to set the schema.
+    #
+    # @example
+    #   AIXM.aixm!   # => :aixm
+    #   AIXM.ofmx?   # => false
+    #   AIXM.ofmx!   # => :ofmx
+    #   AIXM.ofmx?   # => true
+    #
+    # @!method aixm!
+    # @!method ofmx!
+    # @return [Symbol] schema key
+    SCHEMAS.each_key do |schema|
+      define_method("#{schema}!") { @@config.schema = schema }
+    end
+
+    # Shortcuts to query the schema.
+    #
+    # @example
+    #   AIXM.aixm!   # => :aixm
+    #   AIXM.ofmx?   # => false
+    #   AIXM.ofmx!   # => :ofmx
+    #   AIXM.ofmx?   # => true
+    #
+    # @!method aixm?
+    # @!method ofmx?
+    # @return [Boolean]
+    SCHEMAS.each_key do |schema|
+      define_method("#{schema}?") { @@config.schema == schema }
+    end
+
+    private
+
+    # Configuration defaults (view source for more).
+    #
+    # @!visibility public
+    # @api private
+    # @return [OpenStruct]
+    def initialize_config
+      @@config = OpenStruct.new(
+        schema: :aixm
+      )
+    end
+
+  end
+end
+
+AIXM.send(:initialize_config)

data/lib/aixm/document.rb

@@ -1,63 +1,89 @@
+using AIXM::Refinements
+
 module AIXM
-  class Document < Base
-    using AIXM::Refinements
 
-    IGNORE_ERROR_PATTERN = %r(OrgUid)
+  # The AIXM-Snapshot or OFMX-Snapshot document is the root container for
+  # aeronautical information such as airports or airspaces.
+  #
+  # ===Cheat Sheet in Pseudo Code:
+  #   document = AIXM.document(
+  #     namespace: String (UUID)
+  #     created_at: Time or Date or String
+  #     effective_at: Time or Date or String
+  #   )
+  #   document.features << AIXM::Feature
+  #
+  # @see https://github.com/openflightmaps/ofmx/wiki/Snapshot
+  class Document
+    NAMESPACE_PATTERN = /\A[a-f\d]{8}-[a-f\d]{4}-[a-f\d]{4}-[a-f\d]{4}-[a-f\d]{12}\z/.freeze
+
+    # @return [String] UUID to namespace the data contained in this document
+    attr_reader :namespace
+
+    # @return [Time] creation date and time (default: {#effective_at} or now)
+    attr_reader :created_at
+
+    # @return [Time] effective after date and time (default: {#created_at} or now)
+    attr_reader :effective_at
 
-    attr_reader :created_at, :effective_at
+    # @return [Array<AIXM::Feature>] airspaces, airports and other features
     attr_accessor :features
 
-    ##
-    # Define a AIXM-Snapshot document
-    #
-    # Options:
-    # * +created_at+ - creation date and time (default: now)
-    # * +effective_at+ - snapshot effective after date and time (default: now)
-    def initialize(created_at: nil, effective_at: nil)
-      @created_at, @effective_at = parse_time(created_at), parse_time(effective_at)
+    def initialize(namespace: nil, created_at: nil, effective_at: nil)
+      self.namespace, self.created_at, self.effective_at = namespace, created_at, effective_at
       @features = []
     end
 
-    ##
-    # Check whether the document is complete (extensions excluded)
-    def complete?
-      features.any? && features.none? { |f| f.respond_to?(:complete?) && !f.complete? }
+    # @return [String]
+    def inspect
+      %Q(#<#{self.class} created_at=#{created_at.inspect}>)
+    end
+
+    def namespace=(value)
+      fail(ArgumentError, "invalid namespace") unless value.nil? || value.match?(NAMESPACE_PATTERN)
+      @namespace = value || SecureRandom.uuid
     end
 
-    ##
-    # Validate atainst the XSD and return +true+ if no errors were found
+    def created_at=(value)
+      @created_at = parse_time(value) || effective_at || Time.now
+    end
+
+    def effective_at=(value)
+      @effective_at = parse_time(value) || created_at || Time.now
+    end
+
+    # Validate the generated AIXM or OFMX atainst it's XSD.
+    #
+    # @return [Boolean] whether valid or not
     def valid?
       errors.none?
     end
 
-    ##
-    # Validate against the XSD and return an array of errors
+    # Validate the generated AIXM or OFMX atainst it's XSD and return the
+    # errors found.
+    #
+    # @return [Array<String>] validation errors
     def errors
-      xsd = Nokogiri::XML::Schema(File.open(AIXM::SCHEMA))
-      xsd.validate(Nokogiri::XML(to_aixm)).reject do |error|
-        error.message =~ IGNORE_ERROR_PATTERN
+      xsd = Nokogiri::XML::Schema(File.open(AIXM.schema(:xsd)))
+      xsd.validate(Nokogiri::XML(to_xml)).reject do |error|
+        AIXM.config.ignored_errors && error.message.match?(AIXM.config.ignored_errors)
       end
     end
 
-    ##
-    # Render AIXM markup
-    #
-    # Extensions:
-    # * +:ofm+ - Open Flightmaps
-    def to_aixm(*extensions)
-      now = Time.now.xmlschema
+    # @return [String] AIXM or OFMX markup
+    def to_xml
       meta = {
-        'xmlns:xsi': 'http://www.aixm.aero/schema/4.5/AIXM-Snapshot.xsd',
-        version: '4.5',
-        origin: "AIXM #{AIXM::VERSION} Ruby gem",
-        created: @created_at&.xmlschema || now,
-        effective: @effective_at&.xmlschema || now
-      }
-      meta[:version] += ' + OFM extensions of version 0.1' if extensions >> :ofm
+        'xmlns:xsi': AIXM.schema(:namespace),
+        version: AIXM.schema(:version),
+        origin: "rubygem aixm-#{AIXM::VERSION}",
+        namespace: (namespace if AIXM.ofmx?),
+        created: @created_at.xmlschema,
+        effective: @effective_at.xmlschema
+      }.compact
       builder = Builder::XmlMarkup.new(indent: 2)
       builder.instruct!
-      builder.tag!('AIXM-Snapshot', meta) do |aixm_snapshot|
-        aixm_snapshot << features.map { |f| f.to_aixm(*extensions) }.join.indent(2)
+      builder.tag!(AIXM.schema(:root), meta) do |root|
+        root << features.map { |f| f.to_xml }.join.indent(2)
       end
     end
 
@@ -69,10 +95,8 @@ module AIXM
         when Date then value.to_time
         when Time then value
         when nil then nil
-        else fail ArgumentError
+        else fail(ArgumentError, "invalid date or time")
       end
-    rescue ArgumentError
-      raise(ArgumentError, "`#{value}' is not a valid date and time")
     end
 
   end