unlocodes 0.1.4 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a6607eb57e2219a161a11a3a5504d8b5ba3ba727b6a89c27d2a0de65b20dc36
-  data.tar.gz: 43fc8e683ac3af63d1f2a126313c6a9ec935ff6bacd03ecaa3fda39909bcef13
+  metadata.gz: c49275437cb1ae79a0be87613f9c19d1fc3e55220eff15960a0e472f2142f706
+  data.tar.gz: 687ae112bbf72c14fdc636ed54470360fde096625b645e3b57afc3611bfeea84
 SHA512:
-  metadata.gz: 4e6da102b2aea85d965a601c2539400a4d978ac04723cbc989f8bd867628352ce26d03fa26b181a66ccd652d618f68e13ee5d668a3dac41971058fcacdca25d8
-  data.tar.gz: 9fa6a655a4c2ed962975e2311920264ba3657311163156843be590e639592fa480715493bfee7e7c9f59019d8ccee60c4c29f95cae65e8fec7828b17ef53f7be
+  metadata.gz: 548af19b13e7fe5d350556cb31f8afe7638327893eb18654a79cdccbde8c5b0dabdfa5f8b872fbfbfefe273fc22f570a83d8f3290e584c63f0f8b37e2a3b6c06
+  data.tar.gz: 278fd26249d2af1836f735b0007d57aab354b31f123db08d29d4855406ea0a7deb32b5108ea9c97aac30bf1097eabafe00d42edb6f6c615da83fa033025a0825

data/README.adoc

@@ -28,40 +28,54 @@ gem install unlocodes
 
 == Usage
 
+Construct a `Unlocodes::Registry` once, hold onto it, and call its query methods. The gem ships a default registry backed by the bundled data file.
+
 [source,ruby]
 ----
 require 'unlocodes'
 
+registry = Unlocodes::Registry.load_default
+
 # Lookup by 5-char LOCODE (case-insensitive)
-Unlocodes.find('CNSHA')                    # => #<Unlocodes::Entry code="CNSHA" name="Shanghai Hongqiao International Apt">
-Unlocodes['NLRTM'].name                    # => "Rotterdam" ([] is an alias for find)
+registry.find('CNSHA')                       # => #<Unlocodes::Entry code="CNSHA" name="...">
+registry['NLRTM'].name                       # => "Rotterdam" ([] is an alias for find)
 
 # Filters — single value or array (any-of)
-Unlocodes.where(country: 'CN').count       # => 1670
-Unlocodes.where(country: %w[CN HK]).count  # => entries in China OR Hong Kong
-Unlocodes.where(function: 'B').count       # => 17912 (sea ports)
-Unlocodes.where(function: 'A').count       # => 9009  (airports)
-Unlocodes.where(function: %w[B A]).count   # => 25136 (port OR airport)
-Unlocodes.where(subdivision: 'CNSH').count # => entries in the Shanghai subdivision
+registry.where(country: 'CN').count          # => 1670
+registry.where(country: %w[CN HK]).count     # => entries in China OR Hong Kong
+registry.where(function: 'B').count          # => 17912 (sea ports)
+registry.where(function: 'A').count          # => 9009  (airports)
+registry.where(function: %w[B A]).count      # => 25136 (port OR airport)
+registry.where(subdivision: 'CNSH').count    # => entries in the Shanghai subdivision
 
 # Filters combine
-Unlocodes.where(country: 'CN', function: 'A').count  # => CN airports
+registry.where(country: 'CN', function: 'A').count  # => CN airports
 
 # Name search — Regexp (substring) or String (case-insensitive equality)
-Unlocodes.where(name: /shanghai/i).map(&:code)
-Unlocodes.where(name: 'rotterdam').map(&:code)
+registry.where(name: /shanghai/i).map(&:code)
+registry.where(name: 'rotterdam').map(&:code)
 
 # Iteration
-Unlocodes.each { |e| puts e.code if e.port? }
+registry.each { |e| puts e.code if e.port? }
 
 # Country listing
-Unlocodes.countries                        # => ["AD", "AE", ..., "ZW"] (249 codes)
-Unlocodes.counts_by_country.first(5)       # => [["US", 20852], ["FR", 14325], ...]
+registry.countries                           # => ["AD", "AE", ..., "ZW"] (249 codes)
+registry.counts_by_country.first(5)          # => [["US", 20852], ["FR", 14325], ...]
 
 # Indexed lookups (faster than `where` for a single value)
-Unlocodes.registry.by_country('CN').size   # => 1670
-Unlocodes.registry.by_function('B').size   # => 17912
+registry.by_country('CN').size               # => 1670
+registry.by_function('B').size               # => 17912
+----
+
+To load from a different source (custom file, in-memory entries, etc.):
+
+[source,ruby]
 ----
+registry = Unlocodes::Registry.load_file('path/to/custom.jsonld')
+registry = Unlocodes::Registry.from_entries([Unlocodes::Entry.new(code: 'CNSHA', ...)])
+----
+
+NOTE: The module-level shortcuts `Unlocodes.find(...)`, `Unlocodes.where(...)`, etc. still work as of 0.2.0 but emit a deprecation warning and will be removed in 0.3.0. Migrate to holding your own `Registry` instance.
 
 === What's in an Entry
 
@@ -82,15 +96,15 @@ Convenience predicates and value-type accessors:
 
 [source,ruby]
 ----
-entry = Unlocodes.find('NLRTM')
+entry = registry.find('NLRTM')
 
 entry.port?             # => true  (function code B)
 entry.airport?          # => true  (function code A)
 entry.rail_terminal?    # => true  (function code R)
 entry.road_terminal?    # => true  (function code T)
-entry.functions.map(&:code)        # => ["B", "R", "T", "A", "P"]
-entry.functions.first.description  # => "Port (sea)"
-entry.coordinates       # => #<Unlocodes::Coordinates ...>
+entry.function_codes                       # => ["B", "R", "T", "A", "P"]
+Unlocodes::Entry.function_description('B') # => "Port (sea)"
+entry.coordinates                          # => #<Unlocodes::Coordinates ...>
 ----
 
 === Function codes
@@ -115,18 +129,18 @@ Use the letters in `where(function: ...)`. Passing an array matches any-of (OR),
 
 [source,ruby]
 ----
-Unlocodes.where(function: 'B').count             # sea ports
-Unlocodes.where(function: %w[B A]).count         # port OR airport (union)
+registry.where(function: 'B').count             # sea ports
+registry.where(function: %w[B A]).count         # port OR airport (union)
 # For AND (entries that are BOTH port AND airport), filter in Ruby:
-Unlocodes.entries.count { |e| e.port? && e.airport? }  # => 1785
+registry.count { |e| e.port? && e.airport? }    # => 1785
 ----
 
 === Coordinates and distances
 
 [source,ruby]
 ----
-shanghai = Unlocodes.find('CNPDG').coordinates   # Shanghai Pudong
-rotterdam = Unlocodes.find('NLRTM').coordinates
+shanghai = registry.find('CNPDG').coordinates   # Shanghai Pudong
+rotterdam = registry.find('NLRTM').coordinates
 
 shanghai.to_s              # => "31.2333 121.5000"
 shanghai.distance_to(rotterdam)  # => 8922.7 (km, great-circle via haversine)
@@ -192,7 +206,7 @@ bundle exec rspec spec/path/to_spec.rb:42   # one example
 bundle exec rake unlocodes:fetch     # refresh bundled data
 ----
 
-The 39 MB dataset at `lib/unlocodes/data/locode.jsonld` is committed so the gem works offline. The first call to `Unlocodes.registry` in a process pays the parse cost (~3-5 s); subsequent calls are cached.
+The 39 MB dataset at `lib/unlocodes/data/locode.jsonld` is committed so the gem works offline. The first call to `Unlocodes::Registry.load_default` in a process pays the parse cost (~3-5 s); subsequent calls reuse the same Registry instance if you hold onto it.
 
 == License
 

data/lib/unlocodes/entry.rb

@@ -1,24 +1,36 @@
 # frozen_string_literal: true
 
 require 'lutaml/model'
-require_relative 'status'
-require_relative 'function'
 require_relative 'coordinates'
 
 module Unlocodes
   # A single UN/LOCODE entry.
   #
   # Stores wire-level fields as `lutaml-model` attributes and exposes typed
-  # helpers (#functions, #coordinates) that convert to {Function} and
-  # {Coordinates} value types on demand. The LOCODE itself is the 5-character
-  # composite of `country` (ISO 3166-1 alpha-2) + the 3-character location
-  # alpha. The `code` attribute is the canonical 5-char string.
+  # helpers (#coordinates, .function_description) for ergonomic queries. The
+  # LOCODE itself is the 5-character composite of `country` (ISO 3166-1
+  # alpha-2) + the 3-character location alpha. The `code` attribute is the
+  # canonical 5-char string.
   #
   # `latitude` and `longitude` are decimal degrees (WGS-84), populated when
-  # the source vocabulary provides `geo:lat` / `geo:long`. Older editions
-  # published a single coordinate string ("DDMMNDDDMMME"); see
-  # {Coordinates.parse} when converting from that form.
+  # the source vocabulary provides `geo:lat` / `geo:long`.
   class Entry < Lutaml::Model::Serializable
+    # UN/LOCODE manual function classifier letters and their human-readable
+    # descriptions. Source: UN/LOCODE manual, "Code list for function".
+    FUNCTION_DESCRIPTIONS = {
+      'B' => 'Port (sea)',
+      'R' => 'Rail terminal',
+      'T' => 'Road terminal',
+      'A' => 'Airport',
+      'P' => 'Postal exchange office',
+      'I' => 'Inland water transport (river)',
+      'F' => 'Ferry port',
+      'V' => 'Pipeline',
+      'O' => 'Other (border crossing, etc.)',
+      '0' => 'Function not known',
+      '1' => 'Not provided'
+    }.freeze
+
     attribute :code, :string
     attribute :country, :string
     attribute :subdivision, :string
@@ -27,8 +39,11 @@ module Unlocodes
     attribute :latitude, :float
     attribute :longitude, :float
 
-    def functions
-      (function_codes || []).map { |code| Function.cast(code) }
+    # Look up the human-readable description for a function letter.
+    # @param letter [String] single-letter function code (case-insensitive)
+    # @return [String, nil] description, or nil if the letter is unknown
+    def self.function_description(letter)
+      FUNCTION_DESCRIPTIONS[letter.to_s.upcase]
     end
 
     def function?(letter)

data/lib/unlocodes/registry.rb

@@ -1,18 +1,42 @@
 # frozen_string_literal: true
 
 require 'forwardable'
-require_relative 'loader'
+require 'json'
+require_relative 'entry'
 
 module Unlocodes
   # In-memory, lazily-indexed registry over a set of {Entry} instances.
   #
-  # The default registry is loaded from the vendored dataset bundled with the
-  # gem (see {.load_default}). Callers can also construct a registry from any
-  # other source via {.from_entries} or {.load_file}.
+  # The Registry owns three concerns end-to-end:
+  #
+  #   1. Loading — turning the bundled JSON-LD file into Entry instances.
+  #   2. Indexing — building fast lookups by code, country, function.
+  #   3. Querying — the public find/where/countries surface.
+  #
+  # Loading and indexing are private; callers (and tests) cross the seam
+  # at the query methods. The bundled dataset is parsed once per
+  # Registry instance; construct a new Registry from a different source
+  # via {.from_entries} or {.load_file}.
   class Registry
     include Enumerable
     extend Forwardable
 
+    # UN/LOCODE function digit (used in `unlcdf:1`..`unlcdf:9` references
+    # in the JSON-LD) → letter per the UN/LOCODE manual.
+    FUNCTION_DIGIT_TO_LETTER = {
+      '1' => 'B', # sea port
+      '2' => 'R', # rail terminal
+      '3' => 'T', # road terminal
+      '4' => 'A', # airport
+      '5' => 'P', # postal exchange office
+      '6' => 'I', # inland water transport
+      '7' => 'F', # ferry port
+      '8' => 'V', # pipeline
+      '9' => 'O'  # other / border crossing
+    }.freeze
+
+    UNLOCODE_TYPE_SUFFIX = 'UNLOCODE'
+
     attr_reader :entries
 
     def_delegators :@entries, :size, :count, :to_a, :empty?
@@ -39,14 +63,14 @@ module Unlocodes
       # Load the bundled dataset shipped inside the gem.
       # @return [Registry]
       def load_default
-        from_entries(Loader.load_file(default_data_path))
+        load_file(default_data_path)
       end
 
       # Load a specific JSON-LD file from disk.
       # @param path [String]
       # @return [Registry]
       def load_file(path)
-        from_entries(Loader.load_file(path))
+        from_entries(parse_json(File.read(path)))
       end
 
       # Build a registry from an existing list of entries.
@@ -56,11 +80,100 @@ module Unlocodes
         new(entries)
       end
 
+      # Parse a JSON-LD string into Entry instances.
+      # @param json [String]
+      # @return [Array<Unlocodes::Entry>]
+      def parse_json(json)
+        parse_hash(JSON.parse(json, symbolize_names: false))
+      end
+
+      # Parse a pre-parsed JSON-LD hash into Entry instances.
+      # @param data [Hash]
+      # @return [Array<Unlocodes::Entry>]
+      def parse_hash(data)
+        extract_graph(data).filter_map { |node| build_entry(node) if unlocode_node?(node) }
+      end
+
       private
 
       def default_data_path
         File.expand_path('data/locode.jsonld', __dir__)
       end
+
+      def extract_graph(data)
+        return [] unless data.is_a?(Hash)
+
+        graph = data['@graph']
+        if graph.is_a?(Array)
+          graph
+        elsif data.key?('@id') || data.key?('rdf:value')
+          [data]
+        else
+          []
+        end
+      end
+
+      def unlocode_node?(node)
+        return false unless node.is_a?(Hash)
+
+        types = Array(node['@type']).flat_map { |t| t.to_s.split(/[,\s]+/) }
+        types.empty? || types.any? { |t| t.end_with?(UNLOCODE_TYPE_SUFFIX) }
+      end
+
+      def build_entry(node)
+        Entry.new(
+          code: strip_id(node['rdf:value']) || strip_id(node['@id']),
+          country: strip_prefixed_id(node['unlcdv:countryCode']),
+          subdivision: strip_prefixed_id(node['unlcdv:countrySubdivision']),
+          name: pick_label(node['rdfs:label']) || pick_label(node['rdfs:seeAlso']),
+          function_codes: pick_function_codes(node['unlcdv:functions']),
+          latitude: pick_float(node['geo:lat']),
+          longitude: pick_float(node['geo:long'])
+        )
+      end
+
+      def strip_prefixed_id(value)
+        return nil if value.nil?
+
+        case value
+        when Hash then strip_id(value['@id'])
+        when Array then strip_id(value.first&.dig('@id'))
+        when String then strip_id(value)
+        end
+      end
+
+      def strip_id(value)
+        return nil if value.nil? || value.to_s.empty?
+
+        value.to_s.split(':').last
+      end
+
+      def pick_label(value)
+        return value unless value.is_a?(Hash) || value.is_a?(Array)
+
+        entries = value.is_a?(Array) ? value : [value]
+        picked = entries.find { |v| v.is_a?(Hash) && v['@language'] == 'en' } || entries.first
+        picked.is_a?(Hash) ? picked['@value'] : picked
+      end
+
+      def pick_function_codes(value)
+        return [] if value.nil?
+
+        entries = value.is_a?(Array) ? value : [value]
+        entries.filter_map do |entry|
+          id = strip_prefixed_id(entry)
+          next if id.nil?
+
+          FUNCTION_DIGIT_TO_LETTER.fetch(id, id)
+        end
+      end
+
+      def pick_float(value)
+        return nil if value.nil?
+        return value['@value']&.to_f if value.is_a?(Hash)
+
+        value.to_f
+      end
     end
 
     # Exact-code lookup.

data/lib/unlocodes/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Unlocodes
-  VERSION = '0.1.4'
+  VERSION = '0.2.0'
 end

data/lib/unlocodes.rb

@@ -10,47 +10,107 @@ require_relative 'unlocodes/version'
 #
 # The dataset is sourced from the UNECE/UNCEFACT LOCODE vocabulary published at
 # https://opensource.unicc.org/un/unece/uncefact/vocab-locode and distributed
-# by this gem as a bundled, offline JSON-LD representation. The registry loads
-# once per process and exposes a typed query API over `Unlocodes::Entry`
-# instances.
+# by this gem as a bundled, offline JSON-LD representation.
 #
-# Which edition is bundled? See {Unlocodes.data_tag} (read from
+# Each caller should construct and hold its own {Unlocodes::Registry}:
+#
+#   registry = Unlocodes::Registry.load_default
+#   registry.find('CNSHA')
+#
+# The module-level `Unlocodes.find` / `Unlocodes.where` / etc. shortcuts are
+# deprecated since 0.2.0 (they rely on a process-wide singleton). They still
+# work today but emit a `Kernel#warn` deprecation and will be removed in
+# 0.3.0.
+#
+# Which edition is bundled? See {.data_tag} (read from
 # `lib/unlocodes/data/SOURCE_TAG`).
 module Unlocodes
-  extend SingleForwardable
+  DEPRECATION_SUGGESTION = 'Use Unlocodes::Registry.load_default instead ' \
+                           '(or construct from a custom data source). ' \
+                           'Removal targeted for 0.3.0.'
 
   SOURCE_TAG_PATH = File.expand_path('unlocodes/data/SOURCE_TAG', __dir__)
 
+  # The upstream UNCEFACT vocabulary tag bundled with this gem version
+  # (e.g. "2025-1"). Read from `lib/unlocodes/data/SOURCE_TAG` at runtime.
+  # Pure function over a known file location — does not touch the registry.
+  # @return [String, nil]
+  def self.data_tag
+    return @data_tag if defined?(@data_tag)
+
+    @data_tag = File.read(SOURCE_TAG_PATH, encoding: 'UTF-8').strip
+  rescue Errno::ENOENT
+    nil
+  end
+
   class << self
-    # @return [Unlocodes::Registry] the process-wide registry, loaded lazily
+    # @deprecated Use `Unlocodes::Registry.load_default` and hold the
+    #   instance yourself. Removal targeted for 0.3.0.
     def registry
-      @registry ||= Registry.load_default
+      warn "Unlocodes.registry is deprecated. #{DEPRECATION_SUGGESTION}", category: :deprecated, uplevel: 1
+      default_registry
     end
 
-    # Reset the process-wide registry. Used by specs to swap fixtures.
+    # @deprecated Tests that swap the global registry should construct a
+    #   `Unlocodes::Registry` directly and inject it. Removal targeted for 0.3.0.
     def reset_registry!
+      warn "Unlocodes.reset_registry! is deprecated. #{DEPRECATION_SUGGESTION}", category: :deprecated, uplevel: 1
       @registry = nil
     end
 
-    # The upstream UNCEFACT vocabulary tag bundled with this gem version
-    # (e.g. "2025-1"). Read from `lib/unlocodes/data/SOURCE_TAG` at runtime.
-    # @return [String, nil]
-    def data_tag
-      return @data_tag if defined?(@data_tag)
+    # @deprecated Forwarded to the global registry; construct your own and
+    #   call `registry.find(code)`. Removal targeted for 0.3.0.
+    def find(code)
+      warn "Unlocodes.find is deprecated. #{DEPRECATION_SUGGESTION}", category: :deprecated, uplevel: 1
+      default_registry.find(code)
+    end
 
-      @data_tag = File.read(SOURCE_TAG_PATH, encoding: 'UTF-8').strip
-    rescue Errno::ENOENT
-      nil
+    # @deprecated Construct your own registry and call `registry.where(filters)`.
+    #   Removal targeted for 0.3.0.
+    def where(filters)
+      warn "Unlocodes.where is deprecated. #{DEPRECATION_SUGGESTION}", category: :deprecated, uplevel: 1
+      default_registry.where(filters)
+    end
+
+    # @deprecated Construct your own registry and call `registry.each`.
+    #   Removal targeted for 0.3.0.
+    def each(&)
+      warn "Unlocodes.each is deprecated. #{DEPRECATION_SUGGESTION}", category: :deprecated, uplevel: 1
+      default_registry.each(&)
     end
-  end
 
-  def_delegators :registry, :find, :where, :each, :size, :count, :countries
+    # @deprecated Construct your own registry and call `registry.size`.
+    #   Removal targeted for 0.3.0.
+    def size
+      warn "Unlocodes.size is deprecated. #{DEPRECATION_SUGGESTION}", category: :deprecated, uplevel: 1
+      default_registry.size
+    end
+
+    # @deprecated Construct your own registry and call `registry.count`.
+    #   Removal targeted for 0.3.0.
+    def count
+      warn "Unlocodes.count is deprecated. #{DEPRECATION_SUGGESTION}", category: :deprecated, uplevel: 1
+      default_registry.count
+    end
+
+    # @deprecated Construct your own registry and call `registry.countries`.
+    #   Removal targeted for 0.3.0.
+    def countries
+      warn "Unlocodes.countries is deprecated. #{DEPRECATION_SUGGESTION}", category: :deprecated, uplevel: 1
+      default_registry.countries
+    end
+
+    private
+
+    # Internal memoised default registry. Used by the deprecated module-level
+    # shortcuts. Direct callers should construct their own Registry instead.
+    def default_registry
+      @default_registry ||= Registry.load_default
+    end
+  end
 
-  autoload :Status, 'unlocodes/status'
-  autoload :Function, 'unlocodes/function'
   autoload :Coordinates, 'unlocodes/coordinates'
   autoload :Entry, 'unlocodes/entry'
-  autoload :Loader, 'unlocodes/loader'
   autoload :Registry, 'unlocodes/registry'
   autoload :Data, 'unlocodes/data'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: unlocodes
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.2.0
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-02 00:00:00.000000000 Z
+date: 2026-07-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -59,10 +59,7 @@ files:
 - lib/unlocodes/data/fetcher.rb
 - lib/unlocodes/data/locode.jsonld
 - lib/unlocodes/entry.rb
-- lib/unlocodes/function.rb
-- lib/unlocodes/loader.rb
 - lib/unlocodes/registry.rb
-- lib/unlocodes/status.rb
 - lib/unlocodes/version.rb
 homepage: https://github.com/metanorma/unlocodes
 licenses:

data/lib/unlocodes/function.rb

@@ -1,72 +0,0 @@
-# frozen_string_literal: true
-
-module Unlocodes
-  # UN/LOCODE function classifier.
-  #
-  # Single-letter codes identifying the transport function a LOCODE serves.
-  # A single LOCODE entry can carry several function codes simultaneously
-  # (e.g. "BA" = sea port and airport).
-  # Source: UN/LOCODE manual, "Code list for function".
-  #
-  # Plain value wrapper rather than a `Lutaml::Model::Type::Value` subclass:
-  # the wire-level code letters live on the {Entry} as a `:string` collection,
-  # and {Entry#functions} wraps each on demand.
-  class Function
-    DESCRIPTIONS = {
-      'B' => 'Port (sea)',
-      'R' => 'Rail terminal',
-      'T' => 'Road terminal',
-      'A' => 'Airport',
-      'P' => 'Postal exchange office',
-      'I' => 'Inland water transport (river)',
-      'F' => 'Ferry port',
-      'V' => 'Pipeline',
-      'O' => 'Other (border crossing, etc.)',
-      '0' => 'Function not known',
-      '1' => 'Not provided'
-    }.freeze
-
-    attr_reader :code
-
-    def initialize(code)
-      @code = code.to_s.upcase
-    end
-
-    class << self
-      # @return [Function, nil] nil for nil input
-      def cast(value)
-        return nil if value.nil?
-        return value if value.is_a?(Function)
-
-        new(value)
-      end
-
-      def description(code)
-        DESCRIPTIONS[code.to_s.upcase]
-      end
-
-      def known?(code)
-        DESCRIPTIONS.key?(code.to_s.upcase)
-      end
-    end
-
-    def description
-      self.class.description(@code)
-    end
-
-    def known?
-      self.class.known?(@code)
-    end
-
-    def to_s
-      @code
-    end
-
-    def ==(other)
-      other.is_a?(Function) && code == other.code
-    end
-
-    alias eql? ==
-    alias hash code
-  end
-end

data/lib/unlocodes/loader.rb

@@ -1,139 +0,0 @@
-# frozen_string_literal: true
-
-require 'json'
-require_relative 'entry'
-
-module Unlocodes
-  # Parses a UN/LOCODE JSON-LD vocabulary file into {Entry} instances.
-  #
-  # The UNCEFACT vocabulary (`vocab/unlocode.jsonld`) is a single JSON-LD
-  # document whose `@graph` array contains one `unlcdv:UNLOCODE` resource per
-  # LOCODE. Each resource uses these wire names:
-  #
-  #   @id                       → "unlcd:CNSHA"
-  #   @type                     → "unlcdv:UNLOCODE"
-  #   rdf:value                 → "CNSHA"                         (5-char LOCODE)
-  #   rdfs:label                → {"@language":"en","@value":..}  (sometimes an array)
-  #   unlcdv:countryCode        → {"@id":"unlcdc:CN"}             (strip prefix)
-  #   unlcdv:countrySubdivision → {"@id":"unlcds:CNSH"}           (strip prefix)
-  #   unlcdv:functions          → {"@id":"unlcdf:4"} or [...]     (strip prefix; numeric → letter)
-  #   geo:lat / geo:long        → {"@type":"xsd:float","@value":"42.5"}
-  #
-  # When UNCEFACT publishes new wire names, update the constants below — the
-  # Entry model itself does not change.
-  class Loader
-    FUNCTION_DIGIT_TO_LETTER = {
-      '1' => 'B', # sea port
-      '2' => 'R', # rail terminal
-      '3' => 'T', # road terminal
-      '4' => 'A', # airport
-      '5' => 'P', # postal exchange office
-      '6' => 'I', # inland water transport
-      '7' => 'F', # ferry port
-      '8' => 'V', # pipeline
-      '9' => 'O' # other / border crossing
-    }.freeze
-
-    UNLOCODE_TYPE_SUFFIX = 'UNLOCODE'
-
-    class << self
-      # Load entries from a file path on disk.
-      # @param path [String] absolute or relative path to a JSON-LD file
-      # @return [Array<Unlocodes::Entry>]
-      def load_file(path)
-        load_json(File.read(path))
-      end
-
-      # Load entries from a JSON-LD string.
-      # @param json [String] a JSON-LD document
-      # @return [Array<Unlocodes::Entry>]
-      def load_json(json)
-        parse(JSON.parse(json, symbolize_names: false))
-      end
-
-      # Load entries from a pre-parsed JSON-LD hash.
-      # @param data [Hash] parsed JSON-LD
-      # @return [Array<Unlocodes::Entry>]
-      def parse(data)
-        extract_graph(data).filter_map { |node| build_entry(node) if unlocode_node?(node) }
-      end
-
-      private
-
-      def extract_graph(data)
-        return [] unless data.is_a?(Hash)
-
-        graph = data['@graph']
-        if graph.is_a?(Array)
-          graph
-        elsif data.key?('@id') || data.key?('rdf:value')
-          [data]
-        else
-          []
-        end
-      end
-
-      def unlocode_node?(node)
-        return false unless node.is_a?(Hash)
-
-        types = Array(node['@type']).flat_map { |t| t.to_s.split(/[,\s]+/) }
-        types.empty? || types.any? { |t| t.end_with?(UNLOCODE_TYPE_SUFFIX) }
-      end
-
-      def build_entry(node)
-        Entry.new(
-          code: strip_id(node['rdf:value']) || strip_id(node['@id']),
-          country: strip_prefixed_id(node['unlcdv:countryCode']),
-          subdivision: strip_prefixed_id(node['unlcdv:countrySubdivision']),
-          name: pick_label(node['rdfs:label']) || pick_label(node['rdfs:seeAlso']),
-          function_codes: pick_function_codes(node['unlcdv:functions']),
-          latitude: pick_float(node['geo:lat']),
-          longitude: pick_float(node['geo:long'])
-        )
-      end
-
-      def strip_prefixed_id(value)
-        return nil if value.nil?
-
-        case value
-        when Hash then strip_id(value['@id'])
-        when Array then strip_id(value.first&.dig('@id'))
-        when String then strip_id(value)
-        end
-      end
-
-      def strip_id(value)
-        return nil if value.nil? || value.to_s.empty?
-
-        value.to_s.split(':').last
-      end
-
-      def pick_label(value)
-        return value unless value.is_a?(Hash) || value.is_a?(Array)
-
-        entries = value.is_a?(Array) ? value : [value]
-        picked = entries.find { |v| v.is_a?(Hash) && v['@language'] == 'en' } || entries.first
-        picked.is_a?(Hash) ? picked['@value'] : picked
-      end
-
-      def pick_function_codes(value)
-        return [] if value.nil?
-
-        entries = value.is_a?(Array) ? value : [value]
-        entries.filter_map do |entry|
-          id = strip_prefixed_id(entry)
-          next if id.nil?
-
-          FUNCTION_DIGIT_TO_LETTER.fetch(id, id)
-        end
-      end
-
-      def pick_float(value)
-        return nil if value.nil?
-        return value['@value']&.to_f if value.is_a?(Hash)
-
-        value.to_f
-      end
-    end
-  end
-end

data/lib/unlocodes/status.rb

@@ -1,74 +0,0 @@
-# frozen_string_literal: true
-
-module Unlocodes
-  # UN/LOCODE status (change indicator).
-  #
-  # Two-letter codes documenting how a LOCODE entry was last amended relative
-  # to the previous edition. Source: UN/LOCODE manual, "Code list for status".
-  #
-  # Plain value wrapper rather than a `Lutaml::Model::Type::Value` subclass:
-  # the wire-level code string lives on the {Entry} as a `:string` attribute,
-  # and {Entry#status} wraps it on demand.
-  class Status
-    DESCRIPTIONS = {
-      'AA' => 'Approved',
-      'AC' => 'Added, alternate name',
-      'AD' => 'Added, different name',
-      'AM' => 'Added, modified name',
-      'AQ' => 'Approved, alternate name',
-      'AS' => 'Approved, secondary name',
-      'RL' => 'Replaced, linked',
-      'RN' => 'Replaced, not linked',
-      'RS' => 'Replaced, secondary name',
-      'RT' => 'Replaced, temporary',
-      'UA' => 'Updated, alternate name',
-      'UX' => 'Updated, secondary name',
-      'XX' => 'Deleted, no replacement',
-      'RJ' => 'Rejected',
-      'RQ' => 'Requested'
-    }.freeze
-
-    attr_reader :code
-
-    def initialize(code)
-      @code = code.to_s.upcase
-    end
-
-    class << self
-      # @return [Status, nil] nil for nil input
-      def cast(value)
-        return nil if value.nil?
-        return value if value.is_a?(Status)
-
-        new(value)
-      end
-
-      def description(code)
-        DESCRIPTIONS[code.to_s.upcase]
-      end
-
-      def known?(code)
-        DESCRIPTIONS.key?(code.to_s.upcase)
-      end
-    end
-
-    def description
-      self.class.description(@code)
-    end
-
-    def known?
-      self.class.known?(@code)
-    end
-
-    def to_s
-      @code
-    end
-
-    def ==(other)
-      other.is_a?(Status) && code == other.code
-    end
-
-    alias eql? ==
-    alias hash code
-  end
-end