aixm 0.3.7 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bad5f1c431575562810faf541c197660e815e3652213dc8d6fedc8cde897f9d4
-  data.tar.gz: f1a750f511dc13146af92a25aea066a89a67d358534f2f4a582e415919855ef4
+  metadata.gz: 2f4efdae60e160732c8f30262673f01b49d6dd53d5c5e9bc2d8c395cf696ccae
+  data.tar.gz: 7b129a858e6c6d0eb7545d4a32910243e7a8ecd00a8895698f4ae69fcaed33f2
 SHA512:
-  metadata.gz: f587e9d97f7a1fdb21e38f79c2be3567a9a8a8a4c0bc692b74c19305db8b0c2c8fb734d0b90b7ba488916ca9bc23a2a60ba4e836510be6984d1bd95055ffbe28
-  data.tar.gz: ac70ee0a8c63f20f0fb0277ba075c0880ed2ad39ae32e6c5e38d9fa76d80943a7c8efb394bb33af52f5c6ce00081d066e59d9df9a1105812bfaf8bafc2a23596
+  metadata.gz: 98115e7b0f93f82e976235045afdff88b3b6a99b256620de733b4b4741ffa7fb769e6bb92aae86657d6ae57b5744aef5df82a634b22adb5ae81b9db18a7c1531
+  data.tar.gz: fd3bf40b77d4cfef51465b4e1806382465a4eee86abd8c74c3639763a627653a7832696395bab9673dd6433458bef8474871b7dcd121533891df3c911a429baf

data/CHANGELOG.md

@@ -1,3 +1,65 @@
+## 1.0.0
+
+#### Breaking Changes
+* Move `Ase->txtLocalType` up into `AseUid` for OFMX
+
+#### Additions
+* Add `AIXM::Component::Geometry::RhumbLine`
+
+## 0.3.11
+
+#### Breaking Changes
+* Renamed default git branch to `main`
+* Require Ruby 3.0
+* `Address#address` requires and returns `AIXM::F` for type `:radio_frequency`
+
+#### Changes
+* Fix `Obstacle#source` for OFMX
+
+#### Additions
+* Add `f#voice?` and `AIXM.config.voice_channel_separation` to check whether a
+  frequency belongs to the voice communication airband and use it to validate
+  `AIXM::Frequency`
+
+## 0.3.10
+
+#### Additions
+* Proper `has_many` and `has_one` associations
+* `AIXM::Association:Array#find_by|find|duplicate` on `has_many` associations
+* `AIXM.config.mid` now defines whether `mid` attributes are inserted or not
+  provided the selected schema is OFMX
+* `AIXM::Memoize` module
+* `AIXM::PayloadHash` class
+* `mkmid` executable to insert `mid` attributes into valid OFMX file
+* `ckmid` executable to check `mid` attributes in an OFMX file
+* `AIXM::Component::Geometry#point?|circle?|polygon?`
+* `AIXM::Component::Layer#services`
+
+#### Breaking Changes
+* Require Ruby 2.7
+* Moved `region` attribute from `Document` back to features again
+* Use `Document#add_feature` instead of `Document@features#<<`
+* Use `Document@features#find` instead of `Document#select_features`
+* Use `Airspace#add_layer` instead of `Airspace@layers#<<`
+* Use `Geometry#add_segment` instead of `Geometry#<<`
+* Renamed `VerticalLimits` to `VerticalLimit`
+* Moved `AIXM::Feature::Service` to `AIXM::Component::Service`
+* Refinements `String#insert_payload_hash` and `Array#to_uuid` removed again
+* Refinement `String#payload_hash` removed in favor of `AIXM::PayloadHash` class
+* Refinements `Array#find|duplicates` removed
+
+#### Changes
+* Renamed `AIXM.config.mid_region` to `AIXM.config.region`
+
+## 0.3.8
+
+#### Additions
+* `AIXM.config.mid_region` to insert `mid` attributes
+* Refinement `String#insert_payload_hash`
+
+#### Changes
+* Fix calculation of magnetic bearing
+
 ## 0.3.7
 
 #### Additions
@@ -37,14 +99,17 @@
 * `Runway#preparation`, `Runway#condition` and `Runway#vfr_pattern`
 * `Service#guessed_unit_type`
 * Surface for `Runway|Helipad#surface`
-* Extracted `AIXM::MIN`, `AIXM::SEC` and `AIXM::DMS_RE` to scan for coordinates in texts
-* Refinement `String#payload_hash`
+* Extracted `AIXM::MIN`, `AIXM::SEC` and `AIXM::DMS_RE` to scan for coordinates
+  in texts
+* Refinements `Array#to_uuid` and `String#payload_hash`
 
 #### Breaking Changes
 * Require Ruby 2.6
-* Renamed `AIXM::H` to `AIXM::A` (angle) and add simple arithmetics to make it more versatile
+* Renamed `AIXM::H` to `AIXM::A` (angle) and add simple arithmetics to make it
+  more versatile
 * `Runway|Helipad#composition` moved to `Runway|Helipad#surface`
-* DMS notation `{-}{DD}DMMSS{.SS}[NESW]` now requires compulsory cardinal direction (N, E, S or W) at the end
+* DMS notation `{-}{DD}DMMSS{.SS}[NESW]` now requires compulsory cardinal
+  direction (N, E, S or W) at the end
 
 #### Changes
 * Service is a feature now
@@ -56,7 +121,8 @@
 
 #### Changes
 * Updated OFMX schema URI
-* Added `eql?` and `hash` to `AIXM::XY|Z|D|H|F` to allow for instances of these classes to be used as Hash keys.
+* Added `eql?` and `hash` to `AIXM::XY|Z|D|H|F` to allow for instances of these
+  classes to be used as Hash keys.
 
 ## 0.3.2
 
@@ -81,7 +147,7 @@
 #### Breaking Changes
 * Renamed `Airport#code` to `Airport#id`
 * Renamed `Airspace#short_name` to `Airspace#local_type`
-* Moved `region` attribute from features to Document
+* Moved `region` attribute from features to `Document`
 
 #### Changes
 * Be more permissive on `Airport#id` in order to accomodate generated codes

data/README.md

@@ -1,38 +1,66 @@
 [![Version](https://img.shields.io/gem/v/aixm.svg?style=flat)](https://rubygems.org/gems/aixm)
-[![Continuous Integration](https://img.shields.io/travis/svoop/aixm/master.svg?style=flat)](https://travis-ci.org/svoop/aixm)
+[![Tests](https://img.shields.io/github/workflow/status/svoop/aixm/Test.svg?style=flat&label=tests)](https://github.com/svoop/aixm/actions?workflow=Test)
 [![Code Climate](https://img.shields.io/codeclimate/maintainability/svoop/aixm.svg?style=flat)](https://codeclimate.com/github/svoop/aixm/)
 [![Donorbox](https://img.shields.io/badge/donate-on_donorbox-yellow.svg)](https://donorbox.org/bitcetera)
 
 # AIXM
 
-Partial implementation of the [Aeronautical Information Exchange Model (AIXM 4.5)](http://aixm.aero) and it's dialect [Open FlightMaps eXchange format (OFMX 0)](https://github.com/openflightmaps/ofmx) for Ruby.
+Partial implementation of the [Aeronautical Information Exchange Model (AIXM 4.5)](http://aixm.aero) and it's dialect [Open FlightMaps eXchange format (OFMX 0)](https://gitlab.com/openflightmaps/ofmx/wikis) for Ruby.
 
 For now, only the parts needed to automize the AIP import of [open flightmaps](https://openflightmaps.org) are part of this gem. Most notably, the gem is only a builder for snapshot files and does not parse them.
 
 * [Homepage](https://github.com/svoop/aixm)
-* [API](http://www.rubydoc.info/gems/aixm)
+* [API](https://www.rubydoc.info/gems/aixm)
 * Author: [Sven Schwyn - Bitcetera](http://www.bitcetera.com)
 
 ## Install
 
-Add this to your `Gemfile`:
+### Security
+
+This gem is [cryptographically signed](https://guides.rubygems.org/security/#using-gems) in order to assure it hasn't been tampered with. Unless already done, please add the author's public key as a trusted certificate now:
+
+```
+gem cert --add <(curl -Ls https://raw.github.com/svoop/aixm/main/certs/svoop.pem)
+```
+
+### Bundler
+
+Add the following to the <tt>Gemfile</tt> or <tt>gems.rb</tt> of your [Bundler](https://bundler.io) powered Ruby project:
 
 ```ruby
 gem aixm
 ```
 
+And then install the bundle:
+
+```
+bundle install --trust-policy MediumSecurity
+```
+
+### Standalone
+
+If you're only going to use [the executables](#executables), make sure to have the [latest version of Ruby](https://www.ruby-lang.org/en/documentation/installation/) and then install this gem:
+
+```
+gem install aixm --trust-policy MediumSecurity
+```
+
 ## Usage
 
 Here's how to build a document object, populate it with a simple feature and then render it as AIXM:
 
 ```ruby
-document = AIXM.document
-document.features << AIXM.designated_point(
-  id: "ABIXI",
-  xy: AIXM.xy(lat: %q(46°31'54.3"N), long: %q(002°19'55.2"W)),
-  type: :icao
+document = AIXM.document(
+  region: 'LF'
 )
-document.aixm!   # not really necessary since AIXM is the default schema
+document.add_feature(
+  AIXM.designated_point(
+    id: "ABIXI",
+    xy: AIXM.xy(lat: %q(46°31'54.3"N), long: %q(002°19'55.2"W)),
+    type: :icao
+  )
+)
+AIXM.ofmx!
 document.to_xml
 ```
 
@@ -47,11 +75,12 @@ See `AIXM::CLASSES` for the complete list of shorthand names.
 
 ## Configuration
 
-The following configuration options are available for setting and getting:
+### AIXM.config.schema
+
+The schema is either `:aixm` (default) or `:ofmx`:
 
 ```ruby
-AIXM.config.schema           # either :aixm (default) or :ofmx
-AIXM.config.ignored_errors   # ignore XML schema errors which match this regex
+AIXM.config.schema = :ofmx   # =>:ofmx
 ```
 
 There are shortcuts to set and get the schema:
@@ -65,65 +94,174 @@ AIXM.schema             # => :ofmx
 AIXM.schema(:version)   # => 0
 ```
 
-## Validation
+### AIXM.config.region
 
-`AIXM::Document#valid?` validates the resulting AIXM or OFMX against its XML schema. If any, you find the errors in `AIXM::Document#errors`.
+The `:ofmx` schema requires the [region to be set on all core features](https://gitlab.com/openflightmaps/ofmx/wikis/Features#core-features). You can do so on individual features, however, you might want to configure a default region to simplify your life:
+
+```ruby
+AIXM.ofmx!
+AIXM.config.region = 'LF'
+```
+
+:warning: This setting has no effect when using the `:aixm` schema.
+
+### AIXM.voice_channel_separation
+
+Define which voice channel separation should be used to validate voice communication frequencies.
+
+```ruby
+AIXM.voice_channel_separation = :any   # both 25 and 8.33 kHz (default)
+AIXM.voice_channel_separation = 25     # 25 kHz only
+AIXM.voice_channel_separation = 833    # 8.33 kHz only
+```
+
+### AIXM.config.mid
+
+In order to insert [OFMX-compliant `mid` attributes](https://gitlab.com/openflightmaps/ofmx/wikis/Features#mid) into all `*Uid` elements, you have set the mid configuration option to `true`.
+
+```ruby
+AIXM.ofmx!
+AIXM.config.mid = false   # don't insert mid attributes (default)
+AIXM.config.mid = true    # insert mid attributes
+```
+
+:warning: This setting has no effect when using the `:aixm` schema.
+
+### AIXM.config.ignored_errors
+
+In case you want to ignore certain XML schema validation errors, set this configuration option to a regular expression which matches the error messages to ignore. By default, no errors are ignored.
+
+```ruby
+AIXM.config.ignored_errors = /invalid date/i
+```
 
-## Model
+## Models
 
 ### Fundamentals
-* [Document](http://www.rubydoc.info/gems/aixm/AIXM/Document.html)
-* [XY (longitude and latitude)](http://www.rubydoc.info/gems/aixm/AIXM/XY.html)
-* [Z (height, elevation or altitude)](http://www.rubydoc.info/gems/aixm/AIXM/Z.html)
-* [D (distance or length)](http://www.rubydoc.info/gems/aixm/AIXM/D.html)
-* [F (frequency)](http://www.rubydoc.info/gems/aixm/AIXM/F.html)
-* [A (angle)](http://www.rubydoc.info/gems/aixm/AIXM/A.html)
+* [Document](https://www.rubydoc.info/gems/aixm/AIXM/Document.html)
+* [XY (longitude and latitude)](https://www.rubydoc.info/gems/aixm/AIXM/XY.html)
+* [Z (height, elevation or altitude)](https://www.rubydoc.info/gems/aixm/AIXM/Z.html)
+* [D (distance or length)](https://www.rubydoc.info/gems/aixm/AIXM/D.html)
+* [F (frequency)](https://www.rubydoc.info/gems/aixm/AIXM/F.html)
+* [A (angle)](https://www.rubydoc.info/gems/aixm/AIXM/A.html)
 
 ### Features
-* [Address](http://www.rubydoc.info/gems/aixm/AIXM/Feature/Address.html)
-* [Organisation](http://www.rubydoc.info/gems/aixm/AIXM/Feature/Organisation.html)
-* [Unit](http://www.rubydoc.info/gems/aixm/AIXM/Feature/Unit.html)
-* [Service](http://www.rubydoc.info/gems/aixm/AIXM/Component/Service.html)
-* [Airport](http://www.rubydoc.info/gems/aixm/AIXM/Feature/Airport.html)
-* [Airspace](http://www.rubydoc.info/gems/aixm/AIXM/Feature/Airspace.html)
-* [Navigational aid](http://www.rubydoc.info/gems/aixm/AIXM/NavigationalAid.html)
-  * [Designated point](http://www.rubydoc.info/gems/aixm/AIXM/Feature/DesignatedPoint.html)
-  * [DME](http://www.rubydoc.info/gems/aixm/AIXM/Feature/DME.html)
-  * [Marker](http://www.rubydoc.info/gems/aixm/AIXM/Feature/Marker.html)
-  * [NDB](http://www.rubydoc.info/gems/aixm/AIXM/Feature/NDB.html)
-  * [TACAN](http://www.rubydoc.info/gems/aixm/AIXM/Feature/TACAN.html)
-  * [VOR](http://www.rubydoc.info/gems/aixm/AIXM/Feature/VOR.html)
-* [Obstacle and obstacle group](http://www.rubydoc.info/gems/aixm/AIXM/Feature/Obstacle.html)
+* [Address](https://www.rubydoc.info/gems/aixm/AIXM/Feature/Address.html)
+* [Organisation](https://www.rubydoc.info/gems/aixm/AIXM/Feature/Organisation.html)
+* [Unit](https://www.rubydoc.info/gems/aixm/AIXM/Feature/Unit.html)
+* [Service](https://www.rubydoc.info/gems/aixm/AIXM/Component/Service.html)
+* [Airport](https://www.rubydoc.info/gems/aixm/AIXM/Feature/Airport.html)
+* [Airspace](https://www.rubydoc.info/gems/aixm/AIXM/Feature/Airspace.html)
+* [Navigational aid](https://www.rubydoc.info/gems/aixm/AIXM/NavigationalAid.html)
+  * [Designated point](https://www.rubydoc.info/gems/aixm/AIXM/Feature/DesignatedPoint.html)
+  * [DME](https://www.rubydoc.info/gems/aixm/AIXM/Feature/DME.html)
+  * [Marker](https://www.rubydoc.info/gems/aixm/AIXM/Feature/Marker.html)
+  * [NDB](https://www.rubydoc.info/gems/aixm/AIXM/Feature/NDB.html)
+  * [TACAN](https://www.rubydoc.info/gems/aixm/AIXM/Feature/TACAN.html)
+  * [VOR](https://www.rubydoc.info/gems/aixm/AIXM/Feature/VOR.html)
+* [Obstacle and obstacle group](https://www.rubydoc.info/gems/aixm/AIXM/Feature/Obstacle.html)
 
 ### Components
-* [Frequency](http://www.rubydoc.info/gems/aixm/AIXM/Component/Frequency.html)
-* [Geometry](http://www.rubydoc.info/gems/aixm/AIXM/Component/Geometry.html)
-  * [Point](http://www.rubydoc.info/gems/aixm/AIXM/Component/Point.html)
-  * [Arc](http://www.rubydoc.info/gems/aixm/AIXM/Component/Arc.html)
-  * [Border](http://www.rubydoc.info/gems/aixm/AIXM/Component/Border.html)
-  * [Circle](http://www.rubydoc.info/gems/aixm/AIXM/Component/Circle.html)
-* [Runway](http://www.rubydoc.info/gems/aixm/AIXM/Component/Runway.html)
-* [Helipad](http://www.rubydoc.info/gems/aixm/AIXM/Component/Helipad.html)
-* [FATO](http://www.rubydoc.info/gems/aixm/AIXM/Component/FATO.html)
-* [Surface](http://www.rubydoc.info/gems/aixm/AIXM/Component/Surface.html)
-* [Layer](http://www.rubydoc.info/gems/aixm/AIXM/Component/Layer.html)
-* [Vertical limits](http://www.rubydoc.info/gems/aixm/AIXM/Component/VerticalLimits.html)
-* [Timetable](http://www.rubydoc.info/gems/aixm/AIXM/Component/Timetable.html)
+* [Frequency](https://www.rubydoc.info/gems/aixm/AIXM/Component/Frequency.html)
+* [Geometry](https://www.rubydoc.info/gems/aixm/AIXM/Component/Geometry.html)
+  * [Point](https://www.rubydoc.info/gems/aixm/AIXM/Component/Point.html)
+  * [Arc](https://www.rubydoc.info/gems/aixm/AIXM/Component/Arc.html)
+  * [Border](https://www.rubydoc.info/gems/aixm/AIXM/Component/Border.html)
+  * [Circle](https://www.rubydoc.info/gems/aixm/AIXM/Component/Circle.html)
+* [Runway](https://www.rubydoc.info/gems/aixm/AIXM/Component/Runway.html)
+* [Helipad](https://www.rubydoc.info/gems/aixm/AIXM/Component/Helipad.html)
+* [FATO](https://www.rubydoc.info/gems/aixm/AIXM/Component/FATO.html)
+* [Surface](https://www.rubydoc.info/gems/aixm/AIXM/Component/Surface.html)
+* [Layer](https://www.rubydoc.info/gems/aixm/AIXM/Component/Layer.html)
+* [Vertical limit](https://www.rubydoc.info/gems/aixm/AIXM/Component/VerticalLimit.html)
+* [Timetable](https://www.rubydoc.info/gems/aixm/AIXM/Component/Timetable.html)
+
+## Associations
+
+The different models are interwoven with [`has_many` and `has_one` associations](https://www.rubydoc.info/gems/aixm/AIXM/Association).
+
+Please note that `has_many` associations are instances `AIXM::Association::Array` which mostly behave like normal arrays. However, you must not add or remove elements on the array directly but use the corresponding method on the associating model instead:
+
+```ruby
+document.features << airport   # => NoMethodError
+document.add_feature airport   # okay
+```
+
+### find_by and find
+
+Use `find_by` on `has_many` to filter associations by class and optional attribute values:
+
+```ruby
+document.features.find_by(:airport)               # => [#<AIXM::Feature::Airport>, #<AIXM::Feature::Airport>]
+document.features.find_by(:airport, id: 'LFNT')   # => [#<AIXM::Feature::Airport>]
+```
+
+To search a `has_many` association for equal objects, use `find`:
+
+```ruby
+document.features.find(airport)   # => [#<AIXM::Feature::Airport>]
+```
+
+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!
+
+### duplicates
+
+Equally on `has_many` associations, use `duplicates` to find identical or equal associations:
+
+```ruby
+document.features.duplicates   # => [#<AIXM::Feature::Unit>, #<AIXM::Component::Service>, ...]
+```
+
+## Payload Hash
+
+OFMX defines a [payload hash function](https://gitlab.com/openflightmaps/ofmx/wikis/Functions) used to facilitate association and modification tracking. It is used internally, but you can also use it in your own code:
+
+```ruby
+# Payload hash of XML fragment string
+xml = '<xml><a></a></xml>'
+AIXM::PayloadHash.new(xml).to_uuid
+
+# Payload hash of Nokogiri XML fragment
+document = File.open("file.xml") { Nokogiri::XML(_1) }
+AIXM::PayloadHash.new(document).to_uuid
+```
+
+## Validation
+
+`AIXM::Document#valid?` validates the resulting AIXM or OFMX against its XML schema. If any, you find the errors in `AIXM::Document#errors`.
 
 ## Refinements
 
-By `using AIXM::Refinements` you get a few handy [extensions to Ruby core classes](http://www.rubydoc.info/gems/aixm/AIXM/Refinements.html).
+By `using AIXM::Refinements` you get a few handy [extensions to Ruby core classes](https://www.rubydoc.info/gems/aixm/AIXM/Refinements.html).
+
+## Executables
+
+### mkmid
+
+The `mkmid` executable reads an OFMX file, adds [OFMX-compliant `mid` values](https://gitlab.com/openflightmaps/ofmx/wikis/Features#mid) into all `*Uid` elements and validates the result against the schema.
+
+```
+mkmid --help
+```
+
+### ckmid
+
+The `chmid` executable reads an OFMX file, validates it against the schema and checks all `mid` attributes for [OFMX-compliance](https://gitlab.com/openflightmaps/ofmx/wikis/Features#mid).
+
+```
+ckmid --help
+```
 
 ## References
 
 ### AIXM
 * [AIXM](http://aixm.aero)
-* [AICM 4.5 documentation](https://openflightmaps.github.io/ofmx/aixm/4.5/manual/aicm/)
+* [AICM 4.5 documentation](https://openflightmaps.gitlab.io/ofmx/aixm/4.5/manual/aicm/)
 * [AIXM 4.5 specification](http://aixm.aero/document/aixm-45-specification)
 
 ### OFMX
-* [OFMX](https://github.com/openflightmaps/ofmx)
-* [OFMX documentation](https://github.com/openflightmaps/ofmx/wiki)
+* [OFMX](https://gitlab.com/openflightmaps/ofmx)
+* [OFMX documentation](https://gitlab.com/openflightmaps/ofmx/wikis)
 * [open flightmaps](https://openflightmaps.org)
 
 ## Tests

data/exe/ckmid

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+
+require 'bundler/inline'
+
+gemfile do
+  source 'https://rubygems.org'
+  ruby '>= 3.0'
+  gem 'aixm', '~> 0'
+end
+
+AIXM::Executables::Ckmid.new.run

data/exe/mkmid

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+
+require 'bundler/inline'
+
+gemfile do
+  source 'https://rubygems.org'
+  ruby '>= 3.0'
+  gem 'aixm', '~> 0'
+end
+
+AIXM::Executables::Mkmid.new.run