aipp 0.2.4 → 1.0.0

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,55 +35,132 @@ 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
     #
-    # Depending on whether a local copy of the file exists, either:
-    # * download from URL to local storage and read from local archive
-    # * read from local archive
+    # 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
     #
     # @param feature [AIXM::Feature] e.g. airport or airspace
+    # @return [AIXM::Feature] added feature
     def add(feature)
-      verbose_info "Adding #{feature.inspect}"
-      aixm.features << feature
+      verbose_info "adding #{feature.inspect}"
+      aixm.add_feature feature
+      feature
     end
 
-    # Search features previously written to AIXM and return those matching the
-    # given class and attribute values
+    # @!method find_by(klass, attributes={})
+    #   Find objects of the given class and optionally with the given attribute
+    #   values previously written to AIXM.
+    #
+    #   @note This method is delegated to +AIXM::Association::Array+.
+    #   @see https://www.rubydoc.info/gems/aixm/AIXM/Association/Array#find_by-instance_method
+    #
+    # @!method find(object)
+    #   Find equal objects previously written to AIXM.
+    #
+    #   @note This method is delegated to +AIXM::Association::Array+.
+    #   @see https://www.rubydoc.info/gems/aixm/AIXM/Association/Array#find-instance_method
+    %i(find_by find).each do |method|
+      define_method method do |*args|
+        aixm.features.send(method, *args)
+      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
-    #   select(:airport, id: "LFNT")
-    #
-    # @param klass [Class, Symbol] feature class like AIXM::Feature::Airport or
-    #   AIXM::Feature::NavigationalAid::VOR, shorthand notations as symbols
-    #   e.g. :airport or :vor as listed in AIXM::CLASSES are recognized as well
-    # @param attributes [Hash] filter by these attributes and their values
-    # @return [Array<AIXM::Feature>]
-    def select(klass, attributes={})
-      klass = AIXM::CLASSES.fetch(klass) if klass.is_a? Symbol
-      aixm.features.select do |feature|
-        if feature.is_a? klass
-          attributes.reduce(true) do |memo, (attribute, value)|
-            memo && feature.send(attribute) == value
-          end
+    #   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
 end

data/lib/aipp/border.rb

@@ -1,51 +1,90 @@
 module AIPP
 
-  # Border GeoJSON file reader
+  # Custom border geometries
   #
-  # The border GeoJSON files must be a geometry collection of one or more
-  # line strings:
-  #
-  #   {
-  #     "type": "GeometryCollection",
-  #     "geometries": [
-  #       {
-  #         "type": "LineString",
-  #         "coordinates": [
-  #           [6.009531650000042, 45.12013319700009],
-  #           [6.015747738000073, 45.12006702600007]
-  #         ]
-  #       }
-  #     ]
-  #   }
-  #
-  # @example
-  #   border = AIPP::Border.new("/path/to/file.geojson")
-  #   border.geometries
-  #   # => [[#<AIXM::XY 45.12013320N 006.00953165E>, <AIXM::XY 45.12006703N 006.01574774E>]]
+  # The border consists of one ore more open or closed geometries which are
+  # defined by either a GeoJSON file or arrays of coordinate pairs.
   class Border
-    attr_reader :file
+
+    # @return [Array<AIXM::XY>]
     attr_reader :geometries
 
-    def initialize(file)
-      @file = file.is_a?(Pathname) ? file : Pathname(file)
-      fail(ArgumentError, "file must have extension .geojson") unless @file.extname == '.geojson'
-      @geometries = load_geometries
+    def initialize(geometries)
+      @geometries = geometries
     end
 
-    # @return [String]
-    def inspect
-      %Q(#<#{self.class} file=#{@file}>)
+    class << self
+      undef_method :new
+
+      # New border object from GeoJSON file
+      #
+      # The border GeoJSON files must be a geometry collection of one or more
+      # line strings:
+      #
+      #   {
+      #     "type": "GeometryCollection",
+      #     "geometries": [
+      #       {
+      #         "type": "LineString",
+      #         "coordinates": [
+      #           [6.009531650000042, 45.12013319700009],
+      #           [6.015747738000073, 45.12006702600007]
+      #         ]
+      #       }
+      #     ]
+      #   }
+      #
+      # Please note that GeoJSON orders coordinate tuples in mathematical order
+      # as `[longitude, latitude]`!
+      #
+      # @param file [Pathname, String] GeoJSON file
+      #
+      # @example
+      #   border = AIPP::Border.from_file("/path/to/national_park.geojson")
+      #   border.geometries
+      #   # => [[#<AIXM::XY 45.12013320N 006.00953165E>, <AIXM::XY 45.12006703N 006.01574774E>]]
+      def from_file(file)
+        file = Pathname(file) unless file.is_a? Pathname
+        fail(ArgumentError, "file must have extension .geojson") unless file.extname == '.geojson'
+        geometries = JSON.load(file)['geometries'].map do |collection|
+          collection['coordinates'].map do |long, lat|
+            AIXM.xy(lat: lat, long: long)
+          end
+        end
+        allocate.instance_eval do
+          initialize(geometries)
+          self
+        end
+      end
+
+      # New border object from array of points
+      #
+      # The array must contain coordinate tuples in geographical order as
+      # `latitude longitude` separated by whitespace and/or commas.
+      #
+      # @param array [Array<Array<String>>] one or more arrays of coordinate pairs
+      #
+      # @example
+      #   border = AIPP::Border.from_array([["45.1201332 6.00953165", "45.12006703 6.01574774"]])
+      #   border.geometries
+      #   # => [[#<AIXM::XY 45.12013320N 006.00953165E>, <AIXM::XY 45.12006703N 006.01574774E>]]
+      def from_array(array)
+        geometries = array.map do |collection|
+          collection.map do |coordinates|
+            lat, long = coordinates.split(/[\s,]+/)
+            AIXM.xy(lat: lat.to_f, long: long.to_f)
+          end
+        end
+        allocate.instance_eval do
+          initialize(geometries)
+          self
+        end
+      end
     end
 
-    # Name of the border
-    #
-    # By convention, the name of the border is taken from the filename with
-    # both the extension .geojson and all non alphanumeric characters dropped
-    # and the resulting string upcased.
-    #
     # @return [String]
-    def name
-      @file.basename('.geojson').to_s.gsub(/\W/, '').upcase
+    def inspect
+      %Q(#<#{self.class} #{@geometries.count} geometries>)
     end
 
     # Whether the given geometry is closed or not
@@ -72,7 +111,7 @@ module AIPP
       @geometries.each.with_index do |geometry, g_index|
         next unless geometry_index.nil? || geometry_index == g_index
         geometry.each.with_index do |coordinates, c_index|
-          distance = xy.distance(coordinates).dist
+          distance = xy.distance(coordinates).dim
           if distance < min_distance
             position = Position.new(geometries: geometries, geometry_index: g_index, coordinates_index: c_index)
             min_distance = distance
@@ -107,14 +146,6 @@ module AIPP
 
     private
 
-    def load_geometries
-      JSON.load(@file)['geometries'].map do |line_string|
-        line_string['coordinates'].map do |long, lat|
-          AIXM.xy(long: long, lat: lat)
-        end
-      end
-    end
-
     # Position defines an exact point on a border
     #
     # @example

data/lib/aipp/debugger.rb

@@ -0,0 +1,101 @@
+module AIPP
+  module Debugger
+
+    # Start a debugger session and watch for warnings etc
+    #
+    # @note The debugger session persists beyond the scope of the given block
+    #   because there's no +DEBUGGER__.stop+ as of now.
+    #
+    # @example
+    #   include AIPP::Debugger
+    #   with_debugger(verbose: true) do
+    #     (...)
+    #     warn("all hell broke loose", severe: true)
+    #   end
+    #
+    # @overload with_debugger(debug_on_warning:, debug_on_error:, verbose:, &block)
+    #   @param debug_on_warning [Boolean, Integer] start a debugger session
+    #     which opens a console on the warning with the given integer ID or on
+    #     all warnings if +true+ is given
+    #   @param debug_on_error [Boolean] start a debugger session which opens
+    #     a console when an error is raised (postmortem)
+    #   @param verbose [Boolean] print verbose info, print unsevere warnings
+    #     and re-raise rescued errors
+    #   @yield Block the debugger is watching
+    def with_debugger(**options, &)
+      DEBUGGER__.instance_variable_set(:@options__, options.merge(counter: 0))
+      case
+      when id = debugger_options[:debug_on_warning]
+        puts instructions_for(@id == true ? 'warning' : "warning #{id}")
+        DEBUGGER__::start(no_sigint_hook: true, nonstop: true)
+        call_with_rescue(&)
+      when debugger_options[:debug_on_error]
+        puts instructions_for('error')
+        DEBUGGER__::start(no_sigint_hook: true, nonstop: true, postmortem: true)
+        call_without_rescue(&)
+      else
+        DEBUGGER__::start(no_sigint_hook: true, nonstop: true)
+        call_with_rescue(&)
+      end
+    end
+
+    def self.included(*)
+      DEBUGGER__.instance_variable_set(:@options__, {})
+    end
+
+    # Issue a warning and maybe open a debug session.
+    #
+    # @param message [String] warning message
+    # @param severe [Boolean] whether this problem must be fixed or not
+    alias_method :original_warn, :warn
+    def warn(message, severe: true)
+      if severe || debugger_options[:verbose]
+        debugger_options[:counter] += 1
+        original_warn "WARNING #{debugger_options[:counter]}: #{message.upcase_first} #{'(unsevere)' unless severe}".red
+        debugger if debugger_options[:debug_on_warning] == true || debugger_options[:debug_on_warning] == debugger_options[:counter]
+      end
+    end
+
+    # Issue an informational message.
+    #
+    # @param message [String] informational message
+    # @param color [Symbol] message color
+    def info(message, color: nil)
+      puts color ? message.upcase_first.send(color) : message.upcase_first
+    end
+
+    # Issue a verbose informational message.
+    #
+    # @param message [String] verbose informational message
+    # @param color [Symbol] message color
+    def verbose_info(message, color: :blue)
+      info(message, color: color) if debugger_options[:verbose]
+    end
+
+    private
+
+    def debugger_options
+      DEBUGGER__.instance_variable_get(:@options__)
+    end
+
+    def call_with_rescue(&block)
+      block.call
+    rescue => error
+      message = error.respond_to?(:original_message) ? error.original_message : error.message
+      puts "ERROR: #{message}".magenta
+      raise if debugger_options[:verbose]
+    end
+
+    def call_without_rescue(&block)
+      block.call
+    end
+
+    def instructions_for(trigger)
+      <<~END.strip.red
+        Debug on #{trigger} enabled.
+        Remember: Type "up" to enter caller frames.
+      END
+    end
+
+  end
+end

data/lib/aipp/downloader.rb

@@ -3,15 +3,15 @@ module AIPP
   # AIP downloader infrastructure
   #
   # The downloader operates in the +storage+ directory where it creates two
-  # subdirectories "archive" and "work". The initializer looks for +archive+
-  # in "archives" and (if found) unzips its contents into "work". When reading
-  # a +document+, the downloader looks for the +document+ in "work" and
+  # subdirectories "sources" and "work". The initializer looks for the +source+
+  # archive in "sources" and (if found) unzips its contents into "work". When
+  # reading a +document+, the downloader looks for the +document+ in "work" and
   # (unless found) downloads it from +url+. HTML documents are parsed to
   # +Nokogiri::HTML5::Document+, PDF documents are parsed to +AIPP::PDF+.
-  # Finally, the contents of "work" are written back to +archive+.
+  # Finally, the contents of "work" are written back to the +source+ archive.
   #
   # @example
-  #   AIPP::Downloader.new(storage: options[:storage], archive: "2018-11-08") do |downloader|
+  #   AIPP::Downloader.new(storage: options[:storage], source: "2018-11-08") do |downloader|
   #     html = downloader.read(
   #       document: 'ENR-5.1',
   #       url: 'https://www.sia.aviation-civile.gouv.fr/dvd/eAIP_08_NOV_2018/FRANCE/AIRAC-2018-11-08/html/eAIP/FR-ENR-5.1-fr-FR.html'
@@ -22,51 +22,62 @@ module AIPP
   #     )
   #   end
   class Downloader
+    extend Forwardable
+    include AIPP::Debugger
+
+    # Error when URL results in "404 Not Found" HTTP status
+    class NotFoundError < StandardError; end
 
     # @return [Pathname] directory to operate within
     attr_reader :storage
 
-    # @return [String] name of the archive (without extension ".zip")
-    attr_reader :archive
+    # @return [String] name of the source archive (without extension ".zip")
+    attr_reader :source
 
-    # @return [Pathname] full path to the archive
-    attr_reader :archive_file
+    # @return [Pathname] full path to the source archive
+    attr_reader :source_file
 
     # @param storage [Pathname] directory to operate within
-    # @param archive [String] name of the archive (without extension ".zip")
-    def initialize(storage:, archive:)
-      @storage, @archive = storage, archive
+    # @param source [String] name of the source archive (without extension ".zip")
+    def initialize(storage:, source:)
+      @storage, @source = storage, source
       fail(ArgumentError, 'bad storage directory') unless Dir.exist? storage
-      @archive_file = archives_path.join("#{@archive}.zip")
+      @source_file = sources_path.join("#{@source}.zip")
       prepare
-      unzip if @archive_file.exist?
+      unzip if @source_file.exist?
       yield self
       zip
     ensure
       teardown
     end
 
+    # @return [String]
+    def inspect
+      "#<AIPP::Downloader>"
+    end
+
     # Download and read +document+
     #
     # @param document [String] document to read (without extension)
     # @param url [String] URL to download the document from
     # @param type [Symbol, nil] document type: +nil+ (default) to derive it from
-    #   the URL, :html, or :pdf
-    # @return [Nokogiri::HTML5::Document, AIPP::PDF]
+    #   the URL, :html, :pdf, :xlsx, :ods or :csv
+    # @return [Nokogiri::HTML5::Document, AIPP::PDF, Roo::Spreadsheet]
     def read(document:, url:, type: nil)
       type ||= Pathname(URI(url).path).extname[1..-1].to_sym
       file = work_path.join([document, type].join('.'))
       unless file.exist?
-        verbose_info "Downloading #{document}"
-        IO.copy_stream(Kernel.open(url), file)
+        verbose_info "downloading #{document}"
+        uri = URI.open(url)
+        IO.copy_stream(uri, file)
       end
       convert file
     end
 
     private
 
-    def archives_path
-      @storage.join('archives')
+    def sources_path
+      @storage.join('sources')
     end
 
     def work_path
@@ -75,7 +86,7 @@ module AIPP
 
     def prepare
       teardown
-      archives_path.mkpath
+      sources_path.mkpath
       work_path.mkpath
     end
 
@@ -87,15 +98,15 @@ module AIPP
     end
 
     def unzip
-      Zip::File.open(archive_file).each do |entry|
+      Zip::File.open(source_file).each do |entry|
         entry.extract(work_path.join(entry.name))
       end
     end
 
     def zip
-      backup_file = archive_file.sub(/$/, '.old') if archive_file.exist?
-      archive_file.rename(backup_file) if backup_file
-      Zip::File.open(archive_file, Zip::File::CREATE) do |zip|
+      backup_file = source_file.sub(/$/, '.old') if source_file.exist?
+      source_file.rename(backup_file) if backup_file
+      Zip::File.open(source_file, Zip::File::CREATE) do |zip|
         work_path.children.each do |entry|
           zip.add(entry.basename.to_s, entry) unless entry.basename.to_s[0] == '.'
         end
@@ -105,8 +116,10 @@ module AIPP
 
     def convert(file)
       case file.extname
-        when '.html' then Nokogiri.HTML5(file)
+        when '.xml' then Nokogiri.XML(File.open(file))
+        when '.html' then Nokogiri.HTML5(File.open(file))
         when '.pdf' then AIPP::PDF.new(file)
+        when '.xlsx', '.ods', '.csv' then Roo::Spreadsheet.open(file.to_s)
       else
         fail(ArgumentError, "invalid document type")
       end