aixm 0.2.3 → 0.3.0

data/lib/aixm/refinements.rb

@@ -20,54 +20,81 @@ module AIXM
       ft: 0.0003048
     }.freeze
 
+    # @!method to_digest
+    #   Builds a 4 byte hex digest from the Array payload.
+    #
+    #   @example
+    #     ['foo', :bar, nil, [123]].to_digest
+    #     # => "f3920098"
+    #
+    #   @note This is a refinement for +Array+
+    #   @return [String] 4 byte hex
     refine Array do
-      ##
-      # Shortcut for +include?+
-      #
-      # Example:
-      #   extensions.include?(:ofm)   # => true
-      #   extensions >> :ofm          # => true
-      alias_method :>>, :include?
-
-      ##
-      # Build a 1 to 9 digit integer digest (which fits in signed 32bit) from payload
       def to_digest
-        ::Digest::SHA512.hexdigest(flatten.join('|')).gsub(/\D/, '')[0, 9].to_i
+        ::Digest::SHA512.hexdigest(flatten.map(&:to_s).join('|'))[0, 8]
       end
     end
 
+    # @!method lookup(key_or_value, fallback=omitted=true)
+    #   Fetch a value from the hash, but unlike +Hash#fetch+, if +key_or_value+
+    #   is no hash key, check whether +key_or_value+ is a hash value and if so
+    #   return it.
+    #
+    #   @example
+    #     h = { one: 1, two: 2, three: 3, four: :three }
+    #     h.lookup(:one)              # => 1
+    #     h.lookup(1)                 # => 1
+    #     h.lookup(:three)            # => 3 (key has priority over value)
+    #     h.lookup(:foo)              # => KeyError
+    #     h.lookup(:foo, :fallback)   # => :fallback
+    #     h.lookup(:foo, nil)         # => nil
+    #
+    #   @note This is a refinement for +Hash+
+    #   @param key_or_value [Object] key or value of the hash
+    #   @param fallback [Object] fallback value
+    #   @raise [KeyError] if neither a matching hash key nor hash value are
+    #     found and no fallback value has been passed
     refine Hash do
-      ##
-      # Fetch a value from the hash, but unlike +fetch+, if +key_or_value+ is
-      # no hash key, check whether +key_or_value+ is a hash value and if so
-      # return it.
-      #
-      # Examples:
-      #   h = { one: 1, two: 2, three: 3, four: :three }
-      #   h.lookup(:one)             # => 1
-      #   h.lookup(1)                # => 1
-      #   h.lookup(:three)           # => 3 (key has priority over value)
-      #   h.lookup(:foo)             # => KeyError
-      #   h.lookup(:foo, :default)   # => :default
-      #   h.lookup(:foo, nil)        # => nil
-      def lookup(key_or_value, default = omitted = true)
+      def lookup(key_or_value, fallback=omitted=true)
         self[key_or_value] ||
           (key_or_value if has_value?(key_or_value)) ||
-          (omitted ? fail(KeyError, "key or value `#{key_or_value}' not found") : default)
+          (omitted ? fail(KeyError, "key or value `#{key_or_value}' not found") : fallback)
       end
     end
 
+    # @!method indent(number)
+    #   Indent every line of a string with +number+ spaces.
+    #
+    #   @example
+    #     "foo\nbar".indent(2)
+    #     # => "  foo\n  bar"
+    #
+    #   @note This is a refinement for +String+
+    #   @param number [Integer] number of spaces
+    #   @return [String] line indended string
     refine String do
-      ##
-      # Indent every line of a string with +number+ spaces
       def indent(number)
         whitespace = ' ' * number
         gsub(/^/, whitespace)
       end
+    end
 
-      ##
-      # Upcase and transliterate to match the reduced character set for
-      # AIXM names and titles
+    # @!method uptrans
+    #   Upcase and transliterate to match the reduced character set for
+    #   AIXM names and titles.
+    #
+    #   See {UPTRANS_MAP} for supported diacryts and {UPTRANS_FILTER} for the
+    #   list of allowed characters in the returned value.
+    #
+    #   @example
+    #     "Nîmes-Alès".uptrans
+    #     # => "NIMES-ALES"
+    #     "Zürich".uptrans
+    #     # => "ZUERICH"
+    #
+    #   @note This is a refinement for +String+
+    #   @return [String] upcased and transliterated String
+    refine String do
       def uptrans
         self.dup.tap do |string|
           string.upcase!
@@ -76,14 +103,25 @@ module AIXM
           string.gsub!(UPTRANS_FILTER, '')
         end
       end
+    end
 
-      ##
-      # Convert DMS angle to DD or +nil+ if the format is not recognized
-      #
-      # Supported formats:
-      # * {-}{DD}D°MM'SS{.SS}"
-      # * {-}{DD}D MM SS{.SS}
-      # * {-}{DD}DMMSS{.SS}
+    # @!method to_dd
+    #   Convert DMS angle to DD or +nil+ if the notation is not recognized.
+    #
+    #   @example
+    #     %q(43°12'77.92").to_dd
+    #     # => 43.22164444444445
+    #     %q(-123).to_dd
+    #     # => nil
+    #
+    #   Supported notations:
+    #   * +{-}{DD}D°MM'SS{.SS}"+
+    #   * +{-}{DD}D MM SS{.SS}+
+    #   * +{-}{DD}DMMSS{.SS}+
+    #
+    #   @note This is a refinement for +String+
+    #   @return [Float] angle in DD notation
+    refine String do
       def to_dd
         if self =~ /\A(-)?(\d{1,3})[° ]?(\d{2})[' ]?(\d{2}\.?\d{0,2})"?\z/
           ("#{$1}1".to_i * ($2.to_f + ($3.to_f/60) + ($4.to_f/3600)))
@@ -91,18 +129,52 @@ module AIXM
       end
     end
 
+    # @!method trim
+    #   Convert whole numbers to Integer and leave all other untouched.
+    #
+    #   @example
+    #     3.0.trim
+    #     # => 3
+    #     3.3.trim
+    #     # => 3.3
+    #
+    #   @note This is a refinement for +Float+
+    #   @return [Integer, Float] converted Float
     refine Float do
-      ##
-      # Convert whole numbers to Integer and leave all other untouched
       def trim
         (self % 1).zero? ? self.to_i : self
       end
+    end
 
-      ##
-      # Convert DD angle to DMS with the degrees zero padded to +padding+ length
-      #
-      # Output format:
-      # * {-}D°MM'SS.SS"
+    # @!method to_rad
+    #   Convert an angle from degree to radian.
+    #
+    #   @example
+    #     45.to_rad
+    #     # => 0.7853981633974483
+    #
+    #   @note This is a refinement for +Float+
+    #   @return [Float] radian angle
+    refine Float do
+      def to_rad
+        self * Math::PI / 180
+      end
+    end
+
+    # @!method to_dms(padding=3)
+    #   Convert DD angle to DMS with the degrees zero padded to +padding+
+    #   length.
+    #
+    #   @example
+    #     43.22164444444445.to_dms(2)
+    #     # => "43°12'77.92\""
+    #     43.22164444444445.to_dms
+    #     # => "043°12'77.92\""
+    #
+    #   @note This is a refinement for +Float+
+    #   @param padding [Integer] number of digits for the degree part
+    #   @return [String] angle in DMS notation +{-}D°MM'SS.SS"+
+    refine Float do
       def to_dms(padding=3)
         degrees = self.abs.floor
         minutes = ((self.abs - degrees) * 60).floor
@@ -116,9 +188,22 @@ module AIXM
           seconds.abs
         ]
       end
+    end
 
-      ##
-      # Convert a distance +from+ unit (+:km+, +:m+, +:nm+ or +:ft+) to kilometers
+    # @!method to_km(from:)
+    #   Convert a distance from the source unit +from+ to kilometers.
+    #
+    #   @example
+    #     10.to_km(from: :nm)
+    #     # => 18.52
+    #     10.to_km(from: :foobar)
+    #     # => ArgumentError
+    #
+    #   @note This is a refinement for +Float+
+    #   @param from [Symbol] source unit (see {KM_FACTORS})
+    #   @raise [ArgumentError] if the specified unit is not supported
+    #   @return [Float] value converted to kilometers
+    refine Float do
       def to_km(from:)
         self * KM_FACTORS.fetch(from.downcase.to_sym)
       rescue KeyError

data/lib/aixm/shortcuts.rb

@@ -1,16 +1,20 @@
 module AIXM
 
-  SCHEMA = Pathname(__dir__).join('schemas', '4.5', 'AIXM-Snapshot.xsd').freeze
-
   ELEMENTS = {
     document: Document,
     xy: XY,
     z: Z,
     f: F,
+    organisation: Feature::Organisation,
+    unit: Feature::Unit,
+    service: Component::Service,
+    frequency: Component::Frequency,
+    airport: Feature::Airport,
+    runway: Component::Runway,
+    helipad: Component::Helipad,
     airspace: Feature::Airspace,
-    class_layer: Component::ClassLayer,
+    layer: Component::Layer,
     geometry: Component::Geometry,
-    schedule: Component::Schedule,
     vertical_limits: Component::VerticalLimits,
     arc: Component::Geometry::Arc,
     border: Component::Geometry::Border,
@@ -21,7 +25,8 @@ module AIXM
     marker: Feature::NavigationalAid::Marker,
     tacan: Feature::NavigationalAid::TACAN,
     ndb: Feature::NavigationalAid::NDB,
-    vor: Feature::NavigationalAid::VOR
+    vor: Feature::NavigationalAid::VOR,
+    timetable: Component::Timetable
   }.freeze
 
   ELEMENTS.each do |element, klass|
@@ -32,6 +37,6 @@ module AIXM
 
   GROUND = z(0, :qfe).freeze
   UNLIMITED = z(999, :qne).freeze
-  H24 = schedule(code: :H24).freeze
+  H24 = timetable(code: :H24).freeze
 
 end

data/lib/aixm/version.rb

@@ -1,3 +1,3 @@
 module AIXM
-  VERSION = "0.2.3".freeze
+  VERSION = "0.3.0".freeze
 end

data/lib/aixm/xy.rb

@@ -1,42 +1,86 @@
+using AIXM::Refinements
+
 module AIXM
 
-  ##
   # Geographical coordinates
   #
-  # The following notations for longitude and latitude are recognized:
+  # ===Recognized notations:
   # * DD - examples: 12.12345678 (north or east), -12.12345678 (south or west)
   # * DMS - examples: 11°22'33.44"N, 1112233.44W
-  class XY < Base
-    using AIXM::Refinements
+  #
+  # @example All of the below are equivalent
+  #   AIXM.xy(lat: %q(11°22'33.44"), long: %q(-111°22'33.44"))
+  #   AIXM.xy(lat: '112233.44N', long: '1112233.44W')
+  #   AIXM.xy(lat: 11.375955555555556, long: -111.37595555555555)
+  #
+  # @see https://github.com/openflightmaps/ofmx/wiki/Coordinates
+  class XY
+    EARTH_RADIUS = 6_371_008.8
 
     def initialize(lat:, long:)
-      @lat, @long = float_for(lat), float_for(long)
-      fail(ArgumentError, "illegal latitude") unless (-90..90).include? @lat
-      fail(ArgumentError, "illegal longitude") unless (-180..180).include? @long
+      self.lat, self.long = lat, long
+    end
+
+    # @return [String]
+    def inspect
+      %Q(#<#{self.class} #{to_s}>)
+    end
+
+    # @return [String] human readable representation
+    def to_s
+      [lat(:ofmx), long(:ofmx)].join(' ')
     end
 
-    def lat(format=nil)
-      case format
-        when :ofm then ("%.8f" % @lat.abs.round(8)) + (@lat.negative? ? 'S' : 'N')
+    # @!attribute lat
+    def lat=(value)
+      @lat = float_for value
+      fail(ArgumentError, "invalid lat") unless (-90..90).include? @lat
+    end
+
+    # @param schema [Symbol, nil] either nil, +:aixm+ or +:ofmx+
+    # @return [String, Float] latitude
+    def lat(schema=nil)
+      case schema
+        when :ofmx then ("%011.8f" % @lat.abs.round(8)) + (@lat.negative? ? 'S' : 'N')
         when :aixm then @lat.to_dms(2).gsub(/[^\d.]/, '') + (@lat.negative? ? 'S' : 'N')
         else @lat.round(8)
       end
     end
 
-    def long(format=nil)
-      case format
-        when :ofm then ("%.8f" % @long.abs.round(8)) + (@long.negative? ? 'W' : 'E')
+    # @!attribute long
+    def long=(value)
+      @long = float_for value
+      fail(ArgumentError, "invalid long") unless (-180..180).include? @long
+    end
+
+    # @param schema [Symbol, nil] either nil, +:aixm+ or +:ofmx+
+    # @return [Float, String] longitude
+    def long(schema=nil)
+      case schema
+        when :ofmx then ("%012.8f" % @long.abs.round(8)) + (@long.negative? ? 'W' : 'E')
         when :aixm then @long.to_dms(3).gsub(/[^\d.]/, '') + (@long.negative? ? 'W' : 'E')
         else @long.round(8)
       end
     end
 
-    def to_digest
-      [lat, long].to_digest
+    # @return [Boolean]
+    def ==(other)
+      other.is_a?(self.class) && lat == other.lat && long == other.long
     end
 
-    def ==(other)
-      other.is_a?(XY) && lat == other.lat && long == other.long
+    # @return [Float] distance in meters as calculated by use of the Haversine formula
+    def distance(other)
+      if self == other
+        0
+      else
+        2 * EARTH_RADIUS * Math.asin(
+          Math.sqrt(
+            Math.sin((other.lat.to_rad - lat.to_rad) / 2) ** 2 +
+              Math.cos(lat.to_rad) * Math.cos(other.lat.to_rad) *
+              Math.sin((other.long.to_rad - long.to_rad) / 2) ** 2
+          )
+        )
+      end.round
     end
 
     private
@@ -44,11 +88,11 @@ module AIXM
     def float_for(value)
       case value
         when Numeric then value.to_f
-        when String then value[0..-2].to_dd * (value =~ /[SW]$/ ? -1 : 1)
-        else fail(ArgumentError, "illegal value class `#{value.class}'")
+        when String then value[0..-2].to_dd * (value.match?(/[SW]$/) ? -1 : 1)
+        else fail(ArgumentError, "invalid value class `#{value.class}'")
       end
     rescue
-      fail(ArgumentError, "illegal value `#{value}'")
+      fail(ArgumentError, "invalid value `#{value}'")
     end
 
   end

data/lib/aixm/z.rb

@@ -1,48 +1,77 @@
+using AIXM::Refinements
+
 module AIXM
 
-  ##
-  # Elevation or altitude
+  # Height, elevation or altitude
   #
-  # The following Q codes are recognized:
-  # * +:qfe+ - height in feet
-  # * +:qnh+ - altitude in feet
-  # * +:qne+ - altitude as flight level
-  class Z < Base
-    using AIXM::Refinements
-
+  # @example
+  #   AIXM.z(1000, :qfe)   # height: 1000 ft above ground
+  #   AIXM.z(2000, :qnh)   # elevation or altitude: 2000 ft above mean sea level
+  #   AIXM.z(45, :qne)     # altitude: flight level 45
+  #
+  # ===Shortcuts:
+  # * +AIXM::GROUND+ - surface expressed as "0 ft QFE"
+  # * +AIXM::UNLIMITED+ - no upper limit expressed as "FL 999"
+  class Z
     CODES = %i(qfe qnh qne).freeze
 
-    attr_reader :alt, :code
+    # @return [Integer] elevation or altitude value
+    attr_reader :alt
+
+    # @return [Symbol] Q code - either +:qfe+ (height in feet), +:qnh+ (altitude in feet or +:qne+ (altitude as flight level)
+    attr_reader :code
 
     def initialize(alt, code)
-      @alt, @code = alt, code&.to_sym&.downcase
-      fail(ArgumentError, "unrecognized Q code `#{code}'") unless CODES.include? @code
+      self.alt, self.code = alt, code
+    end
+
+    # @return [String]
+    def inspect
+      %Q(#<#{self.class} #{to_s}>)
     end
 
-    ##
-    # Digest to identify the payload
-    def to_digest
-      [alt, code].to_digest
+    # @return [String] human readable representation (e.g. "FL045" or "1350 ft QNH")
+    def to_s
+      qne? ? "FL%03i" % alt : [alt, unit, code.upcase].join(' ')
     end
 
+    def alt=(value)
+      fail(ArgumentError, "invalid alt") unless value.is_a? Numeric
+      @alt = value.to_i
+    end
+
+    def code=(value)
+      fail(ArgumentError, "invalid code") unless value.respond_to? :to_sym
+      @code = value.to_sym.downcase
+      fail(ArgumentError, "invalid code") unless CODES.include? @code
+    end
+
+    # @return [Boolean]
     def ==(other)
-      other.is_a?(Z) && alt == other.alt && code == other.code
+      other.is_a?(self.class) && alt == other.alt && code == other.code
     end
 
+    # @example
+    #   z = AIXM.z(123, :qnh)
+    #   z.qnh?   # => true
+    #   z.qfe?   # => false
+    #
+    # @!method qfe?
+    # @!method qnh?
+    # @!method qne?
+    # @return [Boolean]
     CODES.each do |code|
       define_method(:"#{code}?") { @code == code }
     end
 
+    # @return [Boolean] whether ground level or not
     def ground?
       qfe? && @alt == 0
     end
 
-    def base
-      qfe? ? :ASFC : :AMSL
-    end
-
+    # @return [Symbol] unit - either +:fl+ (flight level) or +:ft+ (feet)
     def unit
-      qne? ? :FL : :FT
+      qne? ? :fl : :ft
     end
 
   end