aipp 0.2.6 → 1.0.0

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

@@ -22,6 +22,11 @@ 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
@@ -46,19 +51,25 @@ module AIPP
       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(URI.open(url), file)
+        verbose_info "downloading #{document}"
+        uri = URI.open(url)
+        IO.copy_stream(uri, file)
       end
       convert file
     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

data/lib/aipp/executable.rb

@@ -2,31 +2,40 @@ module AIPP
 
   # Executable instantiated by the console tools
   class Executable
+    include AIPP::Debugger
+
     attr_reader :options
 
     def initialize(**options)
-      @options = options
-      @options[:airac] = AIPP::AIRAC.new
-      @options[:storage] = Pathname(Dir.home).join('.aipp')
-      @options[:force] = @options[:mid] = false
-      $VERBOSE_INFO = $PRY_ON_WARN = $PRY_ON_ERROR = false
+      @options = options.merge(
+        airac: AIRAC::Cycle.new,
+        region_options: [],
+        storage: Pathname(Dir.home).join('.aipp'),
+        force: false,
+        mid: false,
+        verbose: false,
+        debug_on_warning: false,
+        debug_on_error: false
+      )
       OptionParser.new do |o|
         o.banner = <<~END
           Download online AIP and convert it to #{options[:schema].upcase}.
           Usage: #{File.basename($0)} [options]
         END
-        o.on('-d', '--airac DATE', String, %Q[AIRAC date (default: "#{@options[:airac].date.xmlschema}")]) { @options[:airac] = AIPP::AIRAC.new(_1) }
+        o.on('-d', '--airac (DATE|INTEGER)', String, %Q[AIRAC date or delta e.g. "+1" (default: "#{@options[:airac].date.xmlschema}")]) { @options[:airac] = airac_for(_1) }
         o.on('-r', '--region STRING', String, 'region (e.g. "LF")') { @options[:region] = _1.upcase }
-        o.on('-a', '--aip STRING', String, 'process this AIP only (e.g. "ENR-5.1")') { @options[:aip] = _1.upcase }
+        o.on('-a', '--aip STRING', String, 'process this AIP only (e.g. "ENR-5.1")') { @options[:aip] = _1 }
         if options[:schema] == :ofmx
-          o.on('-g', '--[no-]grouped-obstacles', 'group obstacles (time-consuming!)') { @options[:grouped_obstacles] = _1 }
+          o.on('-g', '--[no-]grouped-obstacles', 'group obstacles (default: false)') { @options[:grouped_obstacles] = _1 }
           o.on('-m', '--[no-]mid', 'insert mid attributes into all Uid elements (default: false)') { @options[:mid] = _1 }
         end
+        o.on('-o', '--region-options STRING', String, %Q[comma separated region specific options]) { @options[:region_options] = _1.split(',') }
         o.on('-s', '--storage DIR', String, 'storage directory (default: "~/.aipp")') { @options[:storage] = Pathname(_1) }
+        o.on('-h', '--[no-]check-links', 'check all links with HEAD requests') { @options[:check_links] = _1 }
         o.on('-f', '--[no-]force', 'ignore XML schema validation (default: false)') { @options[:force] = _1 }
-        o.on('-v', '--[no-]verbose', 'verbose output (default: false)') { $VERBOSE_INFO = _1 }
-        o.on('-w', '--pry-on-warn [ID]', Integer, 'open pry on warn with ID (default: nil)') { $PRY_ON_WARN = _1 || true }
-        o.on('-e', '--[no-]pry-on-error', 'open pry on error (default: false)') { $PRY_ON_ERROR = _1 }
+        o.on('-v', '--[no-]verbose', 'verbose output including unsevere warnings (default: false)') { @options[:verbose] = _1 }
+        o.on('-w', '--debug-on-warning [ID]', Integer, 'open debug session on warning with ID (default: false)') { @options[:debug_on_warning] = _1 || true }
+        o.on('-e', '--[no-]debug-on-error', 'open debug session on error (default: false)') { @options[:debug_on_error] = _1 }
         o.on('-A', '--about', 'show author/license information and exit') { about }
         o.on('-R', '--readme', 'show README and exit') { readme }
         o.on('-L', '--list', 'list implemented regions and AIPs') { list }
@@ -34,12 +43,9 @@ module AIPP
       end.parse!
     end
 
-    # Load necessary files and execute the parser.
-    #
-    # @raise [RuntimeError] if the region does not exist
     def run
-      Pry.rescue do
-        fail(OptionParser::MissingArgument, :region) unless options[:region]
+      with_debugger(**options.slice(:verbose, :debug_on_warning, :debug_on_error)) do
+        starting = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         AIPP::Parser.new(options: options).tap do |parser|
           parser.read_config
           parser.read_region
@@ -49,14 +55,21 @@ module AIPP
           parser.write_aixm
           parser.write_config
         end
-      rescue => error
-        puts "ERROR: #{error.message}".magenta
-        Pry::rescued(error) if $PRY_ON_ERROR
+        ending = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        info("finished after %s" % Time.at(ending - starting).utc.strftime("%H:%M:%S"))
       end
     end
 
     private
 
+    def airac_for(argument)
+      if argument.match?(/^[+-]\d+$/)   # delta
+        AIRAC::Cycle.new + argument.to_i
+      else   # date
+        AIRAC::Cycle.new(argument)
+      end
+    end
+
     def about
       puts 'Written by Sven Schwyn (bitcetera.com) and distributed under MIT license.'
       exit
@@ -83,6 +96,6 @@ module AIPP
       puts AIPP::VERSION
       exit
     end
-  end
 
+  end
 end

data/lib/aipp/parser.rb

@@ -2,7 +2,8 @@ module AIPP
 
   # AIP parser infrastructure
   class Parser
-
+    extend Forwardable
+    include AIPP::Debugger
     using AIXM::Refinements
 
     # @return [Hash] passed command line arguments
@@ -37,42 +38,47 @@ module AIPP
       AIXM.config.region = options[:region]
     end
 
+    # @return [String]
+    def inspect
+      "#<AIPP::Parser>"
+    end
+
     # Read the configuration from config.yml.
     def read_config
-      info("Reading config.yml")
-      @config = YAML.load_file(config_file, fallback: {}).transform_keys(&:to_sym) if config_file.exist?
+      info("reading config.yml")
+      @config = YAML.load_file(config_file, symbolize_names: true, fallback: {}) if config_file.exist?
       @config[:namespace] ||= SecureRandom.uuid
       @aixm.namespace = @config[:namespace]
     end
 
     # Read the region directory and build the dependency list.
     def read_region
-      info("Reading region #{options[:region]}")
+      info("reading region #{options[:region]}")
       dir = Pathname(__FILE__).dirname.join('regions', options[:region])
       fail("unknown region `#{options[:region]}'") unless dir.exist?
       # Fixtures
       dir.glob('fixtures/*.yml').each do |file|
-        verbose_info "Reading fixture fixtures/#{file.basename}"
+        verbose_info "reading fixture fixtures/#{file.basename}"
         fixture = YAML.load_file(file)
         @fixtures[file.basename('.yml').to_s] = fixture
       end
       # Borders
       dir.glob('borders/*.geojson').each do |file|
-        verbose_info "Reading border borders/#{file.basename}"
-        border = AIPP::Border.new(file)
-        @borders[border.name] = border
+        verbose_info "reading border borders/#{file.basename}"
+        border = AIPP::Border.from_file(file)
+        @borders[file.basename] = border
       end
       # Helpers
       dir.glob('helpers/*.rb').each do |file|
-        verbose_info "Reading helper helpers/#{file.basename}"
+        verbose_info "reading helper helpers/#{file.basename}"
         require file
       end
       # Parsers
       dir.glob('*.rb').each do |file|
-        verbose_info "Requiring #{file.basename}"
+        verbose_info "requiring #{file.basename}"
         require file
         aip = file.basename('.*').to_s
-        @dependencies[aip] = ("AIPP::%s::%s::DEPENDS" % [options[:region], aip.remove(/\W/).classify]).constantize
+        @dependencies[aip] = ("AIPP::%s::%s::DEPENDS" % [options[:region], aip.remove(/\W/).camelcase]).constantize
       end
     end
 
@@ -81,8 +87,8 @@ module AIPP
       info("AIRAC #{options[:airac].id} effective #{options[:airac].date}", color: :green)
       AIPP::Downloader.new(storage: options[:storage], source: options[:airac].date.xmlschema) do |downloader|
         @dependencies.tsort(options[:aip]).each do |aip|
-          info("Parsing #{aip}")
-          ("AIPP::%s::%s" % [options[:region], aip.remove(/\W/).classify]).constantize.new(
+          info("parsing #{aip}")
+          ("AIPP::%s::%s" % [options[:region], aip.remove(/\W/).camelcase]).constantize.new(
             aip: aip,
             downloader: downloader,
             fixture: @fixtures[aip],
@@ -91,34 +97,34 @@ module AIPP
         end
       end
       if options[:grouped_obstacles]
-        info("Grouping obstacles")
+        info("grouping obstacles")
         aixm.group_obstacles!
       end
-      info("Counting #{aixm.features.count} features")
+      info("counting #{aixm.features.count} features")
     end
 
     # Validate the AIXM document.
     #
     # @raise [RuntimeError] if the document is not valid
     def validate_aixm
-      info("Detecting duplicates")
+      info("detecting duplicates")
       if (duplicates = aixm.features.duplicates).any?
         message = "duplicates found:\n" + duplicates.map { "#{_1.inspect} from #{_1.source}" }.join("\n")
-        @options[:force] ? warn(message, pry: binding) : fail(message)
+        @options[:force] ? warn(message) : fail(message)
       end
-      info("Validating #{options[:schema].upcase}")
+      info("validating #{options[:schema].upcase}")
       unless aixm.valid?
         message = "invalid #{options[:schema].upcase} document:\n" + aixm.errors.map(&:message).join("\n")
-        @options[:force] ? warn(message, pry: binding) : fail(message)
+        @options[:force] ? warn(message) : fail(message)
       end
     end
 
     # Write the AIXM document and context information.
     def write_build
       if @options[:aip]
-        info ("Skipping build")
+        info ("skipping build")
       else
-        info("Writing build")
+        info("writing build")
         builds_path.mkpath
         build_file = builds_path.join("#{@options[:airac].date.xmlschema}.zip")
         Dir.mktmpdir do |tmp_dir|
@@ -135,20 +141,19 @@ module AIPP
             }.to_yaml
           )
           # Manifest
-          manifest, buffer, feature, aip, uid, comment = [], '', '', '', '', ''
-          File.open(tmp_dir.join(aixm_file)).each do |line|
-            buffer << line
-            case line
-            when /^ {2}<(\w{3}).*source=".*?\|.*?\|(.*?)\|/ then buffer, feature, aip = line, $1, $2
-            when /^ {4}<#{feature}Uid[^>]+?mid="(.*?)"/ then uid = $1
-            when /^ {2}<!-- (.*) -->/ then comment = $1
-            when /^ {2}<\/#{feature}>/
-              manifest << [aip, feature, uid[0,8], AIXM::PayloadHash.new(buffer).to_uuid[0,8], comment].to_csv
-              feature, aip, uid = '', '', ''
-            end
-          end
-          manifest = manifest.sort.prepend "AIP,Feature,Short Uid Hash,Short Feature Hash,Comment\n"
-          File.write(tmp_dir.join('manifest.csv'), manifest.join)
+          manifest = ['AIP','Feature', 'Comment', 'Short Uid Hash', 'Short Feature Hash'].to_csv
+          manifest += aixm.features.map do |feature|
+            xml = feature.to_xml
+            element = xml.first_match(/<(\w{3})\s/)
+            [
+              feature.source.split('|')[2],
+              element,
+              xml.match(/<!-- (.*?) -->/)[1],
+              AIXM::PayloadHash.new(xml.match(%r(<#{element}Uid\s.*?</#{element}Uid>)m).to_s).to_uuid[0,8],
+              AIXM::PayloadHash.new(xml).to_uuid[0,8]
+            ].to_csv
+          end.sort.join
+          File.write(tmp_dir.join('manifest.csv'), manifest)
           # Zip it
           build_file.delete if build_file.exist?
           Zip::File.open(build_file, Zip::File::CREATE) do |zip|
@@ -162,14 +167,14 @@ module AIPP
 
     # Write the AIXM document.
     def write_aixm
-      info("Writing #{aixm_file}")
+      info("writing #{aixm_file}")
       AIXM.config.mid = options[:mid]
       File.write(aixm_file, aixm.to_xml)
     end
 
     # Write the configuration to config.yml.
     def write_config
-      info("Writing config.yml")
+      info("writing config.yml")
       File.write(config_file, config.to_yaml)
     end
 

data/lib/aipp/patcher.rb

@@ -18,14 +18,16 @@ module AIPP
 
     def attach_patches
       parser = self
+      verbose_info_method = method(:verbose_info)
       self.class.patches[self.class]&.each do |(klass, attribute, block)|
         klass.instance_eval do
           alias_method :"original_#{attribute}=", :"#{attribute}="
           define_method(:"#{attribute}=") do |value|
-            catch :abort do
+            error = catch :abort do
               value = block.call(parser, self, value)
-              verbose_info("PATCH: #{self.inspect}", color: :magenta)
+              verbose_info_method.call("Patching #{self.inspect} with #{attribute}=#{value.inspect}", color: :magenta)
             end
+            fail "patching #{self.inspect} with #{attribute}=#{value.inspect} failed: #{error}" if error
             send(:"original_#{attribute}=", value)
           end
         end
@@ -36,6 +38,7 @@ module AIPP
     def detach_patches
       self.class.patches[self.class]&.each do |(klass, attribute, _)|
         klass.instance_eval do
+          remove_method :"#{attribute}="
           alias_method :"#{attribute}=", :"original_#{attribute}="
           remove_method :"original_#{attribute}="
         end

data/lib/aipp/regions/LF/README.md

@@ -0,0 +1,49 @@
+# AIP LF – Mainland France
+
+## Prerequisites
+
+This parser requires the XML data dump from SIA. It is available free of charge, but has to be ordered before it can be downloaded. It's therefore necessary to perform the following steps before running the parser for any given AIRAC for the first time:
+
+1. Browse to the [SIA web shop](https://www.sia.aviation-civile.gouv.fr/produits-numeriques-en-libre-disposition/les-bases-de-donnees-sia.html).
+2. Shop the desired dump named «données aéronautiques XML AIRAC ii/yy».
+3. Browse to [your customer page](https://www.sia.aviation-civile.gouv.fr/customer/account/#orders-and-proposals).
+4. In section «mes produits téléchargeables» download the desired dump.
+5. Unzip the downloaded ZIP archive.
+6. Move the file «XML_SIA_yyyy-mm-dd.xml» to the directory in which you will execute the parser.
+
+⚠️ The SIA web shop misbehaves with some browsers, you should try Brave or Chrome.
+
+## Region Options
+
+### Obstacles XLSX
+
+While the XML data dump contains all obstacles, some details of the source XLSX file are omitted. Unfortunately, the latter is only available for the current AIRAC cycle, therefore the XML data dump is used by default. Add `-o lf_obstacles_xlsx` to use the source XLSX file instead.
+
+## Charset
+
+The XML data dump from SIA is ISO-8859-1 encoded. Nokogiri which parses the XML converts this to UTF-8 on the fly, however, when grepping the dump on a shell, you might run into trouble:
+
+```shell
+grep "<Revetement>" XML_SIA_2021-12-02.xml | sort | uniq
+
+sort: Illegal byte sequence
+```
+
+For this to work, you have to convert the dump to UTF-8 and use this converted dump for grepping:
+
+```shell
+iconv -f ISO-8859-1 -t UTF-8 XML_SIA_2021-12-02.xml >XML_SIA_2021-12-02_UTF.xml
+grep "<Revetement>" XML_SIA_2021-12-02_UTF.xml | sort | uniq
+
+<Revetement>Aluminium</Revetement>
+<Revetement>Asphalte</Revetement>
+<Revetement>Béton ( 4t )</Revetement>
+(...)
+```
+
+## References
+
+* [SIA – AIP publisher](https://www.sia.aviation-civile.gouv.fr)
+* [SIA XML usage guide](https://www.sia.aviation-civile.gouv.fr/faqs)
+* [OpenData – public data files](https://www.data.gouv.fr)
+* [Protected Planet – protected area data files](https://www.protectedplanet.net)