aipp 0.2.6 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 11e3df230b0b8dcafdef31e97ed97e2bbf7d6c45f75cb86949ee92a3980e07f4
-  data.tar.gz: 9fe425721151ec0c99677813ac283de61f274f97a6d103cbce8d4d178e8f794d
+  metadata.gz: '09151e277b537c1529951cd69b38bb5d6fc47f855e6041ca3537d36462f93907'
+  data.tar.gz: f0b9d43b940ced7998a079cf6dce602386d52ad90995b7e77a6b6429f09f798e
 SHA512:
-  metadata.gz: 000f611816b7d7b7112649830b3cd1ae383fd9b2a6defcc554715bfbabb9c3008c1f90f3f8062d3c43630c06f7642cd8e8f3c559a99e6bb7ccc4e045062333b5
-  data.tar.gz: c29e73e68318fe197e06d07a08c79fd5cfcb6be9aff3c5fbb96150f0385682e5a51284caf311026b8623d342a77b73485db1509a844de3217161656b52e8818c
+  metadata.gz: 205b609c8aad3999495447f7c55aba98282b5b6347a4f89caef3e06e3edc8f8e28c4e523cc48737522f895813309fe9d4f7b8d3d2d0db37a12d5808c41509137
+  data.tar.gz: 9a228dd7a152dfd5e0bbbd22b8a068e8de404ba9a4d48f4a30f7b3f0b352c694f12b4a45b543880b20884645fbd52fa475dd738f7385541113462dcadce1fc29

data/CHANGELOG.md

@@ -1,3 +1,24 @@
+## Main
+
+Nothing so far
+
+## 1.0.0
+
+#### Breaking Changes
+* Switch from individual AIP HTML section files to the comprehensive AIP XML
+  database dump for the LF region reference implementation.
+* Drop the mandatory `URL` helper in favour of a mandatory `url_for` method.
+* Renamed default git branch to `main`
+* Improve calculation of short feature hash in manifest in order to include
+  e.g. geometries of airspaces.
+
+#### Changes
+* Switch from `pry` to `debug`
+
+#### Additions
+* Unsevere warnings
+* Support for .xlsx, .ods and .csv files
+
 ## 0.2.6
 
 #### Additions

data/README.md

@@ -6,7 +6,7 @@
 
 Parser for Aeronautical Information Publication (AIP) available online.
 
-This gem incluces two executables to download and parse aeronautical data as HTML or PDF, then build and export is as [AIXM](https://github.com/svoop/aixm) or [OFMX](https://github.com/openflightmaps/ofmx/wiki).
+This gem incluces two executables to download and parse aeronautical data as HTML, PDF, XSLX, ODS and CSV, then build and export is as [AIXM](https://github.com/svoop/aixm) or [OFMX](https://github.com/openflightmaps/ofmx/wiki).
 
 * [Homepage](https://github.com/svoop/aipp)
 * [Rubydoc](https://www.rubydoc.info/gems/aipp/AIPP)
@@ -18,9 +18,8 @@ This gem incluces two executables to download and parse aeronautical data as HTM
 [Usage](#usage)<br>
 [Storage](#storage)<br>
 [Regions](#regions)<br>
-[AIP Parsers](#aip-parsers)<br>
-[References](#references)<br>
 [AIRAC Date Calculations](#airac-date-calculations)<br>
+[References](#references)<br>
 [Development](#development)
 
 ## Install
@@ -30,7 +29,7 @@ This gem incluces two executables to download and parse aeronautical data as HTM
 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/aipp/master/certs/svoop.pem)
+gem cert --add <(curl -Ls https://raw.github.com/svoop/aipp/main/certs/svoop.pem)
 ```
 
 ### Standalone
@@ -124,6 +123,24 @@ module AIPP
 
       DEPENDS = %w(ENR-2.1 ENR-2.2)   # declare dependencies to other AIPs
 
+    end
+  end
+end
+```
+
+The class has to implement some methods either in the class itself or in a [helper](#Helpers) included by the class.
+
+⚠️ Parser files usually follow AIP naming conventions such as `ENR-4.3`. However, you're free to use arbitrary naming for parser files e.g. if you're working with one big data source which contains the full AIP dataset.
+
+#### Mandatory `parse` Method
+
+The class must implement the `parse` method which contains the code to read, parse and write the data:
+
+```ruby
+module AIPP
+  module LF
+    class ENR43 < AIP
+
       def parse
         html = read             # read the Nokogiri::HTML5 document
         feature = (...)         # build the feature
@@ -144,8 +161,8 @@ module AIPP
 
       def parse
         %i(one two three).each do |part|
-          html = read(aip_file: "#{aip}.#{part}")   # read with a non-standard name
-          support_html = read(aip_file: 'AD-0.6')        # maybe read necessary support documents
+          html = read("#{aip}.#{part}")   # read with a non-standard name
+          support_html = read('AD-0.6')   # maybe read necessary support documents
           (...)
         end
       end
@@ -157,26 +174,85 @@ end
 
 Inside the `parse` method, you have access to the following methods:
 
-* [`read`](https://www.rubydoc.info/gems/aipp/AIPP/AIP#read-instance_method) – download and read an AIP file
-* [`add`](https://www.rubydoc.info/gems/aipp/AIPP/AIP#add-instance_method) – add a [`AIXM::Feature`](https://www.rubydoc.info/gems/aixm/AIXM/Feature)
-* [`find`](https://www.rubydoc.info/gems/aipp/AIPP/AIP#find-instance_method) – find previously written [`AIXM::Feature`s](https://www.rubydoc.info/gems/aixm/AIXM/Feature) by object
-* [`find_by`](https://www.rubydoc.info/gems/aipp/AIPP/AIP#find_by-instance_method) – find previously written [`AIXM::Feature`s](https://www.rubydoc.info/gems/aixm/AIXM/Feature) by class and attribute values
-* [`unique`](https://www.rubydoc.info/gems/aipp/AIPP/AIP#unique-instance_method) – prevent duplicate [`AIXM::Feature`s](https://www.rubydoc.info/gems/aixm/AIXM/Feature)
-* some core extensions from ActiveSupport – [`Object#blank`](https://www.rubydoc.info/gems/activesupport/Object#blank%3F-instance_method) and [`String`](https://www.rubydoc.info/gems/activesupport/String)
-* core extensions from this gem – [`Object`](https://www.rubydoc.info/gems/aipp/Object), [`NilClass`](https://www.rubydoc.info/gems/aipp/NilClass), [`Integer`](https://www.rubydoc.info/gems/aipp/Integer), [`String`](https://www.rubydoc.info/gems/aipp/String), [`Hash`](https://www.rubydoc.info/gems/aipp/Hash) and [`Enumerable`](https://www.rubydoc.info/gems/aipp/Enumerable)
+Method | Description
+-------|------------
+[`read`](https://www.rubydoc.info/gems/aipp/AIPP/AIP#read-instance_method) | download and read an AIP file
+[`add`](https://www.rubydoc.info/gems/aipp/AIPP/AIP#add-instance_method) | add a [`AIXM::Feature`](https://www.rubydoc.info/gems/aixm/AIXM/Feature)
+[`find`](https://www.rubydoc.info/gems/aipp/AIPP/AIP#find-instance_method) | find previously written [`AIXM::Feature`](https://www.rubydoc.info/gems/aixm/AIXM/Feature)s by object
+[`find_by`](https://www.rubydoc.info/gems/aipp/AIPP/AIP#find_by-instance_method) | find previously written [`AIXM::Feature`](https://www.rubydoc.info/gems/aixm/AIXM/Feature)s by class and attribute values
+[`unique`](https://www.rubydoc.info/gems/aipp/AIPP/AIP#unique-instance_method) | prevent duplicate [`AIXM::Feature`](https://www.rubydoc.info/gems/aixm/AIXM/Feature)s
+[`given`](https://www.rubydoc.info/gems/aipp/AIPP/AIP#given-instance_method) | inline condition for assignments
+[`link_to`](https://www.rubydoc.info/gems/aipp/AIPP/AIP#link_to-instance_method) | optionally checked Markdown link
+[`Object#blank`](https://www.rubydoc.info/gems/activesupport/Object#blank%3F-instance_method) and [`String`](https://www.rubydoc.info/gems/activesupport/String) | some core extensions from ActiveSupport
+[`aip`](https://www.rubydoc.info/gems/aipp/AIPP%2FAIP:aip) | AIP name (equal to the parser file name without its file extension such as "ENR-2.1" implemented in the file "ENR-2.1.rb")
+[`aip_file`](https://www.rubydoc.info/gems/aipp/AIPP%2FAIP:aip_file) | AIP file as passed and possibly renamed by `url_for`
+[`options`](https://www.rubydoc.info/gems/aipp/AIPP/Parser#options-instance_method) | arguments read from <tt>aip2aixm</tt> or <tt>aip2ofmx</tt> respectively
+[`config`](https://www.rubydoc.info/gems/aipp/AIPP/Parser#config-instance_method) | configuration read from <tt>config.yml</tt>
+[`borders`](https://www.rubydoc.info/gems/aipp/AIPP/Parser#borders-instance_method) | borders defined as GeoJSON read from the region (see below)
+[`cache`](https://www.rubydoc.info/gems/aipp/AIPP/Parser#cache-instance_method) | `OStruct` instance to make objects available across AIPs
+
+To make the parser code more readable, this gem provides a few useful core extensions as well:
+
+* [`NilClass`](https://www.rubydoc.info/gems/aipp/NilClass)
+* [`Integer`](https://www.rubydoc.info/gems/aipp/Integer)
+* [`String`](https://www.rubydoc.info/gems/aipp/String)
+* [`Hash`](https://www.rubydoc.info/gems/aipp/Hash)
+* [`Enumerable`](https://www.rubydoc.info/gems/aipp/Enumerable)
+* [`Nokogiri`](https://www.rubydoc.info/gems/aipp/Nokogiri)
+
+#### Mandatory `url_for` Method
+
+The class must implement the `url_for` method which returns the URL from where to download the AIP file:
+
+```ruby
+module AIPP
+  module LF
+    class AD2 < AIP
+
+      def url_for(aip_file)
+        # build and return the download URL for the aip file
+      end
+
+    end
+  end
+end
+```
+
+There are a few things to note about `url_for`:
+
+* If the returned string begins with a protocol like `https:`, the downloader will fetch the file from there.
+* If the returned string is just a file name, the downloader will look for this exact file in the current local directory.
+* The passed `aip_file` will be used as the file name for the local copy in the sources directory. You can rename it on the fly by assigning a new value to this variable.
+
+#### Optional `setup` Method
+
+The class may implement the `setup` method. If present, it will be called when this parser is instantiated:
 
-As well as the following methods:
 
-* [`options`](https://www.rubydoc.info/gems/aipp/AIPP/Parser#options-instance_method) – arguments read from <tt>aip2aixm</tt> or <tt>aip2ofmx</tt> respectively
-* [`config`](https://www.rubydoc.info/gems/aipp/AIPP/Parser#config-instance_method) – configuration read from <tt>config.yml</tt>
-* [`borders`](https://www.rubydoc.info/gems/aipp/AIPP/Parser#borders-instance_method) – borders defined as GeoJSON read from the region (see below)
-* [`cache`](https://www.rubydoc.info/gems/aipp/AIPP/Parser#cache-instance_method) – virgin `OStruct` instance to make objects available across AIPs
+```ruby
+module AIPP
+  module LF
+    class AD2 < AIP
+
+      def setup
+        AIXM.config.voice_channel_separation = :any
+        cache.setup_at ||= Time.now
+      end
+
+    end
+  end
+end
+```
 
 ### Borders
 
-AIXM knows named borders for country boundaries. However, you might need additional borders which don't exist as named boarders.
+AIXM knows named borders for country boundaries. However, you might need additional borders which don't exist as named borders.
+
+You can define additional borders as [`AIPP::Border`](https://www.rubydoc.info/gems/aipp/AIPP/Border) objects in two ways.
 
-To define additional borders, create simple GeoJSON files in the <tt>lib/aipp/regions/{REGION}/borders/</tt> directory, for example this `custom_border.geojson`:
+#### From GeoJSON
+
+Create simple GeoJSON files in the <tt>lib/aipp/regions/{REGION}/borders/</tt> directory, for example this `my_border_1.geojson`:
 
 ```json
 {
@@ -188,6 +264,13 @@ To define additional borders, create simple GeoJSON files in the <tt>lib/aipp/re
         [6.009531650000042, 45.12013319700009],
         [6.015747738000073, 45.12006702600007]
       ]
+    },
+    {
+      "type": "LineString",
+      "coordinates": [
+        [4.896732957592112, 43.95662950764992],
+        [4.005739165537195, 44.10769266295027]
+      ]
     }
   ]
 }
@@ -195,73 +278,44 @@ To define additional borders, create simple GeoJSON files in the <tt>lib/aipp/re
 
 ⚠️ The GeoJSON file must consist of exactly one `GeometryCollection` which may contain any number of `LineString` geometries. Only `LineString` geometries are recognized! To define a closed polygon, the first coordinates of a `LineString` must be identical to the last coordinates.
 
-The [`borders`](https://www.rubydoc.info/gems/aipp/AIPP/Parser#borders-instance_method) method gives you access to a map from the border name (upcased file name) to the corresponding [`AIPP::Border`](https://www.rubydoc.info/gems/aipp/AIPP/Border) object:
+#### From Coordinates
+
+It's also possible to create a [`AIPP::Border`](https://www.rubydoc.info/gems/aipp/AIPP/Border) objects on the fly:
 
 ```ruby
-borders   # => { "CUSTOM_BORDER" => #<AIPP::Border file=custom_border.geojson> }
+my_border_2 = AIPP::Border.from_array(
+  [
+    ["6.009531650000042 45.12013319700009", "6.015747738000073 45.12006702600007"],
+    ["4.896732957592112 43.95662950764992", "4.005739165537195 44.10769266295027"]
+  ]
+)
 ```
 
-The border object implements simple nearest point and segment calculations to create arrays of [`AIXM::XY`](https://www.rubydoc.info/gems/aixm/AIXM/XY) which can be used with [`AIXM::Component::Geometry`](https://www.rubydoc.info/gems/aixm/AIXM/Component/Geometry).
-
-See [`AIPP::Border`](https://www.rubydoc.info/gems/aipp/AIPP/Border) for more on this.
-
-### Helpers
-
-Helpers are modules defined in the <tt>lib/aipp/regions/{REGION}/helpers/</tt> directory. All helper modules are required automatically in alphabetic order.
-
-There is one mandatory helper called `URL.rb` which must define the following method to build URLs from which to download AIPs:
+The coordinate pairs must be separated with whitespaces and/or commas. If you want to use this border everywhere, make sure you add it to the others:
 
 ```ruby
-module AIPP
-  module LF
-    module Helpers
-      module URL
-
-        def url_for(aip_file)
-          # build and return the download URL for the aip file
-        end
-
-      end
-    end
-  end
-end
+  borders["my_border_2"] = my_border_2
 ```
 
-Feel free to add more helpers to DRY code which is shared by multiple AIP parsers. Say you want to extract methods which are used by all AIP parsers:
-
-```ruby
-module AIPP
-  module LF
-    module Helpers
-      module Base
+#### Usage in Parsers
 
-        def source(position:, aip_file: nil)
-          (...)
-        end
+In the parser, the [`borders`](https://www.rubydoc.info/gems/aipp/AIPP/Parser#borders-instance_method) method gives you access to all borders read from GeoJSON files:
 
-      end
-    end
-  end
-end
+```ruby
+borders   # => { "my_border_1" => #<AIPP::Border>, "my_border_2" => #<AIPP::Border> }
 ```
 
-To use this `source` method, simply include the helper module in the AIP parser:
+The border object implements simple nearest point and segment calculations to create arrays of [`AIXM::XY`](https://www.rubydoc.info/gems/aixm/AIXM/XY) which can be used with [`AIXM::Component::Geometry`](https://www.rubydoc.info/gems/aixm/AIXM/Component/Geometry).
 
-```ruby
-module AIPP
-  module LF
-    class AD2 < AIP
+See [`AIPP::Border`](https://www.rubydoc.info/gems/aipp/AIPP/Border) for more on this.
 
-      include AIPP::LF::Helpers::Base
+### Helpers
 
-    end
-  end
-end
-```
+Helpers are modules defined in the <tt>lib/aipp/regions/{REGION}/helpers/</tt> directory. All helper modules are required automatically in alphabetic order.
 
 ### Fixtures and Patches
 
-Fixtures is static data defined as YAML in the <tt>lib/aipp/regions/{REGION}/fixtures/</tt> directory. All fixtures are read automatically. Please note that the name of the AIP parser (e.g. `AD-1.3.rb`) must match the name of the corresponding fixture (e.g. `fixtures/AD-1.3.yml`).
+Fixtures are static YAML data files in the <tt>lib/aipp/regions/{REGION}/fixtures/</tt> directory. All fixtures are read automatically. Please note that the name of the AIP parser (e.g. `AD-1.3.rb`) must match the name of the corresponding fixture (e.g. `fixtures/AD-1.3.yml`).
 
 When parsed data is faulty or missing, you may fall back to such static data instead. This is where patches come in. You can patch any AIXM attribute setter by defining a patch block inside the AIP parser and accessing the static data via `parser.fixture`:
 
@@ -270,14 +324,10 @@ module AIPP
   module LF
     class AD2 < AIP
 
-      patch AIXM::Component::Runway::Direction, :xy do |parser, object, value|
-        throw :abort unless value.nil?
-        @fixtures ||= YAML.load_file(Pathname(__FILE__).dirname.join('AD-1.3.yml'))
-        airport_id = parser.instance_variable_get(:@airport).id
-        direction_name = object.name.to_s
-        throw :abort if (xy = parser.fixture.dig('runways', airport_id, direction_name, 'xy')).nil?
-        lat, long = xy.split(/\s+/)
-        AIXM.xy(lat: lat, long: long)
+      patch AIXM::Feature::Airport, :z do |parser, object, value|
+        throw(:abort) unless value.nil?
+        throw(:abort, 'fixture missing') unless z = parser.fixture.dig(object.id, 'z')
+        AIXM.z(z, :qnh)
       end
 
     end
@@ -285,7 +335,17 @@ module AIPP
 end
 ```
 
-The patch block receives the object and the current value. If this value is okay, `throw :abort` to leave the patch block without touching anything. Otherwise, have the patch block return a new value which will be used instead.
+The patch receives the object and the value which is about to be assigned. It should implement something along these lines:
+
+* If the value is okay, `throw(:abort)` to leave the patch block without touching anything.
+* Otherwise, try to fetch a better value e.g. from the fixtures. If no better value can be found (e.g. outdated fixtures), `throw(:abort, "reason")` to leave the patch block and fail with a useful error message which contains the reason thrown.
+* At last, build and return the value object which will be assigned instead of the original value.
+
+In case the `object` does not carry enough details, you can access instance variables of the parser like so:
+
+```ruby
+parser.instance_variable_get(:@instance_variable)
+```
 
 ### Source File Line Numbers
 
@@ -295,11 +355,9 @@ In order to reference the source of an AIXM/OFMX feature, it's necessary to know
 tr.line
 ```
 
-⚠️ Make sure you have build Nokogumbo `--with-libxml2`. Otherwise, all elements will report line number `0` and therefore render OFMX documents invalid. See the [Nokogumbo README](https://github.com/rubys/nokogumbo/blob/master/README.md#flavors-of-nokogumbo) for more on this.
-
 ### Errors
 
-You should `fail` on fatal problems. The `-e` command line argument will open a Pry session when such an error occurs. Issue errors as usual:
+You should `fail` on fatal problems which must be fixed. The `--debug-on-error` command line argument will open a debug session when such an error occurs. Issue errors as usual:
 
 ```ruby
 fail "my message"
@@ -307,11 +365,11 @@ fail "my message"
 
 ### Warnings
 
-You should `warn` on non-fatal problems. The `-w ID` command line argument will open a Pry session when then warning with the given ID occurs. To issue a warning:
+You should `warn` on non-fatal problems which should be fixed (default) or might be ignored (`severe: false`). The `--debug-on-warning ID` command line argument will open a debug session when then warning with the given ID occurs. To issue a warning:
 
 ```ruby
-warn("my message", pry: binding)   # open Pry attached to the binding
-warn("my message", pry: error)     # open Pry attached to the error
+warn("my message")
+warn("my message", severe: false)   # show warning only when --unsevere-warn argument is set
 ```
 
 ### Messages
@@ -333,11 +391,13 @@ Use `verbose_info` for in-depth info messages which are only shown if the `--ver
 verbose_info("my message")   # displays "my message" in blue
 ```
 
-### Pry
+#### debug
 
-Pry is loaded with stack explorer support. Type `help` in the Pry console to see all available commands. The most useful command in the context of this gem is `up` which beams you one frame up in the caller stack.
+The [default Ruby debugger](https://github.com/ruby/debug#debug-command-on-the-debug-console) is enabled by default, you can add a breakpoint as usual with:
 
-Note: It's not currently possible to use pry-byebug at this time since it [interferes with pry-rescue](https://github.com/ConradIrwin/pry-rescue/issues/71).
+```ruby
+debugger
+```
 
 ## AIRAC Date Calculations
 
@@ -353,10 +413,6 @@ airac.next_id     # => 1801
 
 ## References
 
-* LF - France
-  * [SIA – AIP publisher](https://www.sia.aviation-civile.gouv.fr)
-  * [OpenData – public data files](https://www.data.gouv.fr)
-  * [Protected Planet – protected area data files](https://www.protectedplanet.net)
 * [Geo Maps – programmatically generated GeoJSON maps](https://github.com/simonepri/geo-maps)
 * [open flightmaps – open-source aeronautical maps](https://openflightmaps.org)
 * [AIXM Rubygem – AIXM/OFMX generator for Ruby](https://github.com/svoop/aixm)

data/exe/aip2aixm

@@ -4,8 +4,8 @@ require 'bundler/inline'
 
 gemfile do
   source 'https://rubygems.org'
-  ruby '>= 2.7'
-  gem 'aipp', '~> 0'
+  ruby '>= 3.0.0'
+  gem 'aipp', '~> 1'
 end
 
 AIPP::Executable.new(schema: File.basename($0)[4..-1].to_sym).run

data/exe/aip2ofmx

@@ -4,8 +4,8 @@ require 'bundler/inline'
 
 gemfile do
   source 'https://rubygems.org'
-  ruby '>= 2.7'
-  gem 'aipp', '~> 0'
+  ruby '>= 3.0.0'
+  gem 'aipp', '~> 1'
 end
 
 AIPP::Executable.new(schema: File.basename($0)[4..-1].to_sym).run

data/lib/aipp/aip.rb

@@ -3,13 +3,18 @@ module AIPP
   # @abstract
   class AIP
     extend Forwardable
+    include AIPP::Debugger
     include AIPP::Patcher
 
     DEPENDS = []
 
-    # @return [String] AIP name (e.g. "ENR-2.1")
+    # @return [String] AIP name (equal to the parser file name without its
+    #   file extension such as "ENR-2.1" implemented in the file "ENR-2.1.rb")
     attr_reader :aip
 
+    # @return [String] AIP file as passed and possibly updated by `url_for`
+    attr_reader :aip_file
+
     # @return [Object] Fixture read from YAML file
     attr_reader :fixture
 
@@ -30,7 +35,12 @@ module AIPP
 
     def initialize(aip:, downloader:, fixture:, parser:)
       @aip, @downloader, @fixture, @parser = aip, downloader, fixture, parser
-      self.class.include ("AIPP::%s::Helpers::URL" % options[:region]).constantize
+      setup if respond_to? :setup
+    end
+
+    # @return [String]
+    def inspect
+      "#<AIPP::AIP #{aip}>"
     end
 
     # Read an AIP source file
@@ -38,15 +48,18 @@ module AIPP
     # Read the cached source file if it exists in the source archive. Otherwise,
     # download it from URL and cache it.
     #
-    # An URL builder method +url_for(aip_file)+ must be defined either in
-    # +helper.rb+ or in the AIP parser definition (e.g. +ENR-2.1.rb+).
+    # An URL builder method +url_for(aip_file)+ must be implemented by the AIP
+    # parser definition (e.g. +ENR-2.1.rb+).
     #
-    # @param aip_file [String] e.g. "ENR-2.1" or "AD-2.LFMV" (default: +aip+)
-    # @return [Nokogiri::HTML5::Document, String] HTML as Nokogiri document,
-    #   PDF or TXT as String
+    # @param aip_file [String] e.g. "ENR-2.1" or "AD-2.LFMV" (default: +aip+
+    #   with section stripped e.g. "AD-1.3-2" -> "AD-1.3")
+    # @return [Nokogiri::XML::Document, Nokogiri::HTML5::Document,
+    #   Roo::Spreadsheet, String] XML/HTML as Nokogiri document, XLSX/ODS/CSV
+    #   as Roo document, PDF and TXT as String
     def read(aip_file=nil)
-      aip_file ||= aip
-      @downloader.read(document: aip_file, url: url_for(aip_file))
+      @aip_file = aip_file || aip.remove(/(?<![A-Z])-\d+$/)
+      url = url_for(@aip_file)   # may update aip_file string
+      @downloader.read(document: @aip_file, url: url)
     end
 
     # Add feature to AIXM
@@ -54,7 +67,7 @@ module AIPP
     # @param feature [AIXM::Feature] e.g. airport or airspace
     # @return [AIXM::Feature] added feature
     def add(feature)
-      verbose_info "Adding #{feature.inspect}"
+      verbose_info "adding #{feature.inspect}"
       aixm.add_feature feature
       feature
     end
@@ -76,6 +89,78 @@ module AIPP
         aixm.features.send(method, *args)
       end
     end
-  end
 
+    # @overload given(*objects)
+    #   Return +objects+ unless at least one of them equals nil
+    #
+    #   @example
+    #     # Instead of this:
+    #     first, last = unless ((first = expensive_first).nil? || (last = expensive_last).nil?)
+    #       [first, last]
+    #     end
+    #
+    #     # Use the following:
+    #     first, last = given(expensive_first, expensive_last)
+    #
+    #   @param *objects [Array<Object>] any objects really
+    #   @return [Object] nil if at least one of the objects is nil, given
+    #     objects otherwise
+    #
+    # @overload given(*objects)
+    #   Yield +objects+ unless at least one of them equals nil
+    #
+    #   @example
+    #     # Instead of this:
+    #     name = unless ((first = expensive_first.nil? || (last = expensive_last.nil?)
+    #       "#{first} #{last}"
+    #     end
+    #
+    #     # Use any of the following:
+    #     name = given(expensive_first, expensive_last) { |f, l| "#{f} #{l}" }
+    #     name = given(expensive_first, expensive_last) { "#{_1} #{_2}" }
+    #
+    #   @param *objects [Array<Object>] any objects really
+    #   @yield [Array<Object>] objects passed as parameter
+    #   @return [Object] nil if at least one of the objects is nil, return of
+    #     block otherwise
+    def given(*objects)
+      if objects.none?(&:nil?)
+        block_given? ? yield(*objects) : objects
+      end
+    end
+
+    # Build and optionally check a Markdown link
+    #
+    # @example
+    #   options[:check_links] = false
+    #   link_to('foo', 'https://bar.com/exists')      # => "[foo](https://bar.com/exists)"
+    #   link_to('foo', 'https://bar.com/not-found')   # => "[foo](https://bar.com/not-found)"
+    #   options[:check_links] = true
+    #   link_to('foo', 'https://bar.com/exists')      # => "[foo](https://bar.com/exists)"
+    #   link_to('foo', 'https://bar.com/not-found')   # => nil
+    #
+    # @params body [String] body text of the link
+    # @params url [String] URL of the link
+    # @return [String, nil] Markdown link
+    def link_to(body, url)
+      "[#{body}](#{url})" if !options[:check_links] || url_exists?(url)
+    end
+
+    private
+
+    def url_exists?(url)
+      uri = URI.parse(url)
+      Net::HTTP.new(uri.host, uri.port).tap do |request|
+        request.use_ssl = (uri.scheme == 'https')
+        path = uri.path.present? ? uri.path : '/'
+        result = request.request_head(path)
+        if result.kind_of? Net::HTTPRedirection
+          url_exist?(result['location'])
+        else
+          result.code == '200'
+        end
+      end
+    end
+
+  end
 end