iev 0.4.1 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d7d47000d44c3dcf02934083f9d05b0a195491d6ef130cdc9ca198feeb0d8ad
-  data.tar.gz: 84b2da3efd17c94b8278bdbe963f1d356433fb0d20ccc6e06e1c2bffd05e8851
+  metadata.gz: 5100fcef07e984496be43178ab8ebaf48fb6b77a2144ccd722a1d7acc1135e57
+  data.tar.gz: 724f02e6431f8a3534a1f28e6894dd5462d65ad67ce736695b8e5f8c1b7f04ad
 SHA512:
-  metadata.gz: ba7fbe8bbdcbdec627b43aa62288d2b282a5476a2616ae74a56afcc81c7b983c0190dd43e92378024ad11155c0c9f9b5cf2f2ae4042c4c2536c68cecb4380262
-  data.tar.gz: ee080f35c1d17e1309217def4db29acc019e58c5ad3d104efbfc351155addc43c38a1e0602033024d213e91ce13692084f868cc1f1b64521145d90a763ae2f85
+  metadata.gz: c239187ba2d7d06645dbebca3478bda513dd5e6da8937ff4c9fc51be1647bf2866338d6b79f865e9b3462359b45dce67999e78e8d0cd486c2264c3d3060b6abc
+  data.tar.gz: 88aded4d4dcedc76afb3160f7adb7f1746088d250a34750bb681bb69bc8c4f3d025b8d2f4c2d50df4aa66dfb4543e8699c9261ef5a3fd31ee84a6f5600828d52

data/README.adoc

@@ -85,19 +85,21 @@ Electropedia administrator.
 Iev.get("103-01-02", "en")
 => "functional"
 
-# If code not found
+# If code not found, returns nil (does not raise)
 Iev.get("111-11-11", "en")
-=> ""
+=> nil
 
-# If language not found
+# If language not found, returns nil
 Iev.get("103-01-02", "eee")
 => nil
 
 # Fetch full concept data (all languages)
+# Raises Iev::DataSource::NotFoundError if code not found
 Iev.fetch_concept("103-01-02")
 => { "id" => "103-01-02", "data" => { ... } }
 
 # Fetch localized term data
+# Raises Iev::DataSource::NotFoundError if code not found
 Iev.fetch_term("103-01-02", "en")
 => { "term" => "functional", ... }
 ----

data/lib/iev/cli/command.rb

@@ -8,6 +8,11 @@ module Iev
     class Command < Thor
       include CommandHelper
 
+      desc "version", "Show iev gem version"
+      def version
+        puts "iev #{Iev::VERSION}"
+      end
+
       desc "export FILE", "Export IEV data to Glossarist YAML format"
       long_desc <<~DESC
         Exports IEV data from an Excel (.xlsx/.xls) or SQLite (.sqlite3/.sqlite/.db)
@@ -39,18 +44,25 @@ module Iev
       def export(file)
         handle_generic_options(options)
 
-        Iev::Exporter.new(
+        exporter = Iev::Exporter.new(
           file,
           output_dir: options[:output],
           only_concepts: options[:only_concepts],
           only_languages: options[:only_languages],
           fetch_relaton_links: options[:relaton],
-        ).export
-
-        info "Done!"
+          on_progress: method(:export_progress),
+        )
+        exporter.export
+        print_export_summary(exporter.stats)
+      rescue ArgumentError => e
+        error e.message
+        exit 1
+      rescue Sequel::Error => e
+        error "Database error: #{e.message}"
+        exit 1
       end
 
-      desc "xlsx2yaml FILE", "Converts Excel IEV exports to YAMLs."
+      desc "xlsx2yaml FILE", "[DEPRECATED] Use 'export' instead."
       option :output, desc: "Output directory", aliases: :o, default: Dir.pwd
       option :only_concepts,
              desc: "Only process concepts with IEVREF matching this argument, " \
@@ -69,6 +81,7 @@ module Iev
       option :debug_sources, type: :boolean, default: false
       option :debug_relaton, type: :boolean, default: false
       def xlsx2yaml(file)
+        warn "[DEPRECATED] 'xlsx2yaml' is deprecated. Use 'export' instead."
         handle_generic_options(options)
 
         Iev::Exporter.new(
@@ -81,7 +94,7 @@ module Iev
         summary
       end
 
-      desc "db2yaml DB_FILE", "Exports SQLite to IEV YAMLs."
+      desc "db2yaml DB_FILE", "[DEPRECATED] Use 'export' instead."
       option :output, desc: "Output directory", aliases: :o, default: Dir.pwd
       option :only_concepts,
              desc: "Only process concepts with IEVREF matching this argument, " \
@@ -100,6 +113,7 @@ module Iev
       option :debug_sources, type: :boolean, default: false
       option :debug_relaton, type: :boolean, default: false
       def db2yaml(dbfile)
+        warn "[DEPRECATED] 'db2yaml' is deprecated. Use 'export' instead."
         handle_generic_options(options)
 
         Iev::Exporter.new(
@@ -138,13 +152,14 @@ module Iev
                 DataSource.fetch_concept(code)
               end
 
-        unless raw
-          warn "IEV: concept #{code} not found."
-          exit 1
-        end
-
         concept = build_concept_from_raw(code, raw)
         print_concept_grouped_yaml(concept)
+      rescue Iev::DataSource::NotFoundError
+        error "IEV concept not found: #{code}"
+        exit 1
+      rescue Ferrum::Error => e
+        error "Scraping failed: #{e.message}"
+        exit 1
       end
 
       def self.exit_on_failure?

data/lib/iev/cli/command_helper.rb

@@ -24,6 +24,36 @@ module Iev
         info "Done!"
       end
 
+      def export_progress(current, total)
+        return unless $IEV_PROGRESS
+        return if total <= 1 # single-row dataset, skip progress
+
+        if current == total
+          Ui.info "" # clear progress line
+        else
+          Ui.progress "Processing #{current}/#{total}..."
+        end
+      end
+
+      def print_export_summary(stats)
+        return unless stats
+
+        s = stats
+        elapsed = format_elapsed(s[:elapsed_seconds])
+        info "Exported #{s[:concept_count]} concepts " \
+             "(#{s[:localized_count]} localized) in #{elapsed}"
+      end
+
+      def format_elapsed(seconds)
+        if seconds < 60
+          "%.1fs" % seconds
+        else
+          mins = (seconds / 60).to_i
+          secs = (seconds % 60).round
+          "#{mins}m #{secs}s"
+        end
+      end
+
       def handle_generic_options(options)
         $IEV_PROFILE = options[:profile]
         $IEV_PROGRESS = options.fetch(:progress, !ENV["CI"])

data/lib/iev/cli/ui.rb

@@ -32,6 +32,11 @@ module Iev
         print "#{Helper.clear_progress}#{message}\n"
       end
 
+      # Prints error message to stderr.
+      def error(message)
+        Kernel.warn "Error: #{message}"
+      end
+
       # Sets an UI tag which will be prepended to messages printed with
       # #debug and #warn.
       def set_ui_tag(str)

data/lib/iev/data_source.rb

@@ -12,19 +12,21 @@ module Iev
       # Fetch full concept data (all languages) for a given IEV code.
       #
       # @param code [String] IEV code, e.g. "103-01-02"
-      # @return [Hash, nil] concept data hash or nil if not found
+      # @return [Hash] concept data hash
+      # @raise [NotFoundError] if the concept does not exist
       def fetch_concept(code)
-        fetch_concept_data(code)
+        fetch_concept_data(code) ||
+          raise(NotFoundError, "IEV concept not found: #{code}")
       end
 
       # Fetch localized term data for a given IEV code and language.
       #
       # @param code [String] IEV code, e.g. "103-01-02"
       # @param lang [String] language code, e.g. "en" or "eng"
-      # @return [Hash, nil] localized concept data or nil
+      # @return [Hash, nil] localized concept data or nil if language not found
+      # @raise [NotFoundError] if the concept does not exist
       def fetch_term(code, lang)
         concept = fetch_concept(code)
-        return nil unless concept
 
         lang_key = normalize_lang(lang)
         concept[lang_key]
@@ -35,7 +37,8 @@ module Iev
       #
       # @param code [String] IEV code, e.g. "103-01-02"
       # @param lang [String] language code, e.g. "en"
-      # @return [String, nil] term designation or nil
+      # @return [String, nil] term designation or nil if not found
+      # @raise [NotFoundError] if the concept does not exist
       def fetch_term_designation(code, lang)
         term_data = fetch_term(code, lang)
         return nil unless term_data

data/lib/iev/exporter.rb

@@ -27,15 +27,18 @@ module Iev
     # @param output_dir [String, Pathname] destination for YAML files
     # @param only_concepts [String, nil] SQL LIKE pattern for IEVREF filtering
     # @param only_languages [String, nil] comma-separated language codes
-    # @param fetch_relaton_links [Boolean] whether to fetch source URLs via Relaton
+    # @param fetch_relaton_links [Boolean] fetch source URLs via Relaton
+    # @param on_progress [Proc, nil] callback (current, total) during build
     def initialize(input_path, output_dir: Dir.pwd,
                    only_concepts: nil, only_languages: nil,
-                   fetch_relaton_links: false)
+                   fetch_relaton_links: false,
+                   on_progress: nil)
       @input_path = Pathname.new(input_path)
       validate_input!
 
       @output_dir = Pathname.new(output_dir)
       @fetch_relaton_links = fetch_relaton_links
+      @on_progress = on_progress
       @filters = {
         only_concepts: only_concepts,
         only_languages: only_languages,
@@ -45,12 +48,23 @@ module Iev
     # Run the export pipeline: load → transform → save.
     # @return [Glossarist::ManagedConceptCollection]
     def export
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       dataset = load_dataset
       collection = build_collection(dataset)
       save_collection(collection)
+      elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+
+      @stats = {
+        concept_count: collection.count,
+        localized_count: localized_count(collection),
+        elapsed_seconds: elapsed,
+      }
       collection
     end
 
+    # @return [Hash, nil] stats from last export, or nil if export hasn't run
+    attr_reader :stats
+
     private
 
     def supported_format?
@@ -111,8 +125,13 @@ module Iev
       # Glossarist's O(n) fetch_or_initialize which does linear scan.
       concept_index = {}
       collection = Glossarist::ManagedConceptCollection.new
+      row_count = dataset.count
+      current = 0
 
       dataset.each do |row|
+        current += 1
+        @on_progress&.call(current, row_count)
+
         term = TermBuilder.build_from(row)
         next unless term
 
@@ -134,5 +153,9 @@ module Iev
       FileUtils.mkdir_p(concepts_dir)
       collection.save_to_files(concepts_dir.to_s)
     end
+
+    def localized_count(collection)
+      collection.sum { |c| c.localized_concepts.count }
+    end
   end
 end

data/lib/iev/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Iev
-  VERSION = "0.4.1"
+  VERSION = "0.4.2"
 end

data/lib/iev.rb

@@ -45,17 +45,19 @@ module Iev
   # @param [String] lang language code, for example "en"
   #
   # @return [String, nil] if found then term,
-  # if code not found then nil,
-  #   if language not found then nil.
+  #   if code or language not found then nil.
   #
   def self.get(code, lang)
     DataSource.fetch_term_designation(code, lang)
+  rescue DataSource::NotFoundError
+    nil
   end
 
   # Fetch full concept data (all languages) for a given IEV code.
   #
   # @param [String] code IEV code, e.g. "103-01-02"
-  # @return [Hash, nil] concept data hash with all languages
+  # @return [Hash] concept data hash with all languages
+  # @raise [DataSource::NotFoundError] if concept not found
   def self.fetch_concept(code)
     DataSource.fetch_concept(code)
   end
@@ -64,7 +66,8 @@ module Iev
   #
   # @param [String] code IEV code, e.g. "103-01-02"
   # @param [String] lang language code, e.g. "en" or "eng"
-  # @return [Hash, nil] localized concept data
+  # @return [Hash, nil] localized concept data or nil if not found
+  # @raise [DataSource::NotFoundError] if concept not found
   def self.fetch_term(code, lang)
     DataSource.fetch_term(code, lang)
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: iev
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.4.2
 platform: ruby
 authors:
 - Ribose Inc.