name_bank 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8bdb30000d395f629f88e6a14d346c067b39049295d999c13556ca36145b1923
-  data.tar.gz: a23fc5f83c129d4a1016be83766d4a3e4e496c634254d58ff3b2e8a1df2effd8
+  metadata.gz: 184aced32d90cfa194129bdb48895055b2738ed7bef92c1c1a42532421e6e4c6
+  data.tar.gz: 6305e8defeb53e8a6bbb2d7fd47e73a41c6e870cd83659dfad56f24a96f3ebd8
 SHA512:
-  metadata.gz: c93d2d4749bde09cbb3717118e827370acb2f6dcf7227d388e5a84b75273122606b9887b962c1908778f505cac3630a13f40c8054bb02c7837051813c6366020
-  data.tar.gz: 1d176535f0208a680571a2f0156e80425e2adfbe6458ac26f956f06b53d25af41bf328f1bd5eb6b1d7e4d22ff8a58395fba4ba1a3ce09842480226780942183e
+  metadata.gz: 4eae078ebdd3bab2e6c3d455d3c783a6d03b5d119c386017c81d76e5ead0312e066cc24911621506b8c3b7637a88f679a1f5b8b1dfd3202427c0f274a3d3ef87
+  data.tar.gz: 3c7ea3d49e618280f40734193e487c61fc5c6a9c762a16925843533099e7e727feb693dd9c22a1453a29d63316c962506199a493f7469a898ef559f5f5f3020a

data/CHANGELOG.md

@@ -4,6 +4,40 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-08-11
+
+Lookup, documentation and one platform bug. Sampling behaviour and the name
+data are unchanged — verified byte-identical over 1415 samples against 0.2.0.
+Nothing that worked before stops working; on Linux, one thing that failed now
+works.
+
+### Added
+- `scripts` takes an optional `variant:`. A variant can offer different script
+  forms from the country it is layered on; previously `scripts(country:)` only
+  ever reported the country's own.
+
+### Fixed
+- Country and variant names now resolve against the directory listing instead
+  of being handed to `File.exist?`, so lookup no longer inherits the
+  filesystem's case-sensitivity. `country: "de"` found `DE.yml` on macOS and
+  raised `UnknownCountry` on Linux; it now finds it on both. An exact match
+  still wins, and names that differ only in case are reported as ambiguous
+  rather than guessed at.
+- README: a pool with no names was documented as raising
+  `NameBank::UnknownScript`. It has raised `NameBank::EmptyPool` since 0.2.0.
+
+### Documented
+- The pool file format: the directory layout `NameBank.new(data_dir:)` expects,
+  which keys a file must carry, how `_native` pools are named, and which
+  failures a malformed file produces. Variant files may carry `_native` pools —
+  supported by the reader since 0.1.4, now stated and covered by a spec.
+- `NameBank::PoolSchema` is now documented in the README and is supported
+  public API: `KEYS`, `GIVEN_MALE`, `GIVEN_FEMALE`, `SURNAMES`, `native_key`
+  and `gender_key`. It shipped before but was described nowhere. Callers
+  building pool files for `NameBank.new(data_dir:)` should address the YAML
+  keys through it. The key names are covered by semantic versioning from here
+  on: renaming one is a breaking change.
+
 ## [0.2.0] - 2026-08-08
 
 An interface release. Sampling behaviour and the name data are unchanged — the

data/README.md

@@ -163,7 +163,15 @@ NameBank.scripts(country: "DE")   # => [:latin]
 Germany's script is Latin, so `DE` reports `:latin` only.
 `:latin` and `:native` sample from independent pools. For Latin-script countries
 `:native` returns the same (Latin) pool. Requesting a script with no names
-raises `NameBank::UnknownScript`.
+raises `NameBank::EmptyPool`; a `script:` that is neither `:latin` nor
+`:native` raises `NameBank::UnknownScript`.
+
+`scripts` takes an optional `variant:`, because a variant can offer different
+forms from the country it is layered on:
+
+```ruby
+NameBank.scripts(country: "US", variant: "african_american")   # => [:latin]
+```
 
 ## Variants
 
@@ -204,6 +212,94 @@ rescue NameBank::UnknownCountry => e
 end
 ```
 
+## Pool file format
+
+`NameBank.new(data_dir:)` reads pools from a directory of your own. It holds
+two subdirectories:
+
+```
+my_names/
+  countries/
+    DE.yml
+    RU.yml
+  variants/
+    US/
+      african_american.yml
+```
+
+- `countries/<code>.yml` — the basename is what you pass as `country:`, and
+  what `countries` lists.
+- `variants/<code>/<name>.yml` — the basename is what you pass as `variant:`.
+  No directory for a country means `variants(country:)` returns `[]`.
+- Files that do not end in `.yml` are ignored, and codes are not validated
+  against ISO 3166 — any basename works.
+
+Names resolve the same way on every filesystem: an exact match wins, otherwise
+a unique match ignoring case, so `country: "de"` finds `DE.yml` on Linux as
+well as macOS. Two files whose basenames differ only in case are ambiguous, and
+raise `NameBank::UnknownCountry` rather than being guessed at.
+
+A pool file must carry the three keys in `NameBank::PoolSchema::KEYS`, each a
+list. Any of them may have a native-script counterpart under the same key plus
+`_native`:
+
+```yaml
+firstnames_male:   [Dmitry, Ivan]
+firstnames_female: [Anna, Olga]
+lastnames:         [Ivanov, Petrov]
+
+firstnames_male_native: [Дмитрий, Иван]
+lastnames_native:       [Иванов, Петров]
+```
+
+Variant files are validated the same way and need all three keys too. They may
+carry `_native` pools, which `script: :native` will use — the shipped variants
+do not, because the build pipeline strips them.
+
+Missing a required key, or holding something other than a list under it, raises
+`NameBank::MalformedPool` when the file is read. A key that is present but
+empty is accepted at read time and raises `NameBank::EmptyPool` when sampled.
+Any other key is ignored; the shipped files carry `source:`, which nothing
+reads at runtime.
+
+Sampling is uniform over the whole list, so order does not weight anything. It
+is preserved, and visible through `first_names` and `last_names`.
+
+## Pool schema
+
+`NameBank::PoolSchema` names the YAML keys a pool file uses. It is supported
+public API from 0.2.0 on: the constants and their values will not change
+without a version bump. Use it when you build pool files for
+`NameBank.new(data_dir:)`, so you are not typing key names by hand.
+
+```ruby
+NameBank::PoolSchema::KEYS
+# => ["firstnames_male", "firstnames_female", "lastnames"]
+
+NameBank::PoolSchema::GIVEN_MALE     # => "firstnames_male"
+NameBank::PoolSchema::GIVEN_FEMALE   # => "firstnames_female"
+NameBank::PoolSchema::SURNAMES       # => "lastnames"
+```
+
+`KEYS` is frozen and lists the three pools every file must carry. A file may
+also carry a native-script pool for any of them, under the same key with a
+`_native` suffix:
+
+```ruby
+NameBank::PoolSchema.native_key("lastnames")   # => "lastnames_native"
+```
+
+`gender_key` maps a `gender:` argument to its key, and raises
+`NameBank::UnknownGender` for anything else:
+
+```ruby
+NameBank::PoolSchema.gender_key(:female)   # => "firstnames_female"
+NameBank::PoolSchema.gender_key(:x)        # raises NameBank::UnknownGender
+```
+
+Reading a file that is missing one of `KEYS`, or that holds something other
+than a list under it, raises `NameBank::MalformedPool`.
+
 ## Supported countries
 
 106 countries: Afghanistan, Albania, Algeria, Angola, Argentina, Austria,

data/lib/name_bank/pool_schema.rb

@@ -5,8 +5,13 @@ require_relative "errors"
 # Declared as a class, not a module: NameBank itself is one (see lib/name_bank.rb).
 class NameBank
   # The pool-key schema: the base YAML keys, how native-script keys are named,
-  # and how a gender maps to its key. Shared by the runtime NameBank and the
-  # build-time SplitScripts tool so the key names live in one place.
+  # and how a gender maps to its key. One home for the key names, shared by the
+  # runtime NameBank and the build-time SplitScripts tool.
+  #
+  # Supported public API from 0.2.0 on, documented in the README — callers
+  # building pool files for NameBank.new(data_dir:) address them through here.
+  # The constants and their values are therefore covered by semantic
+  # versioning: changing a key name is a breaking change.
   module PoolSchema
     GIVEN_MALE = "firstnames_male"
     GIVEN_FEMALE = "firstnames_female"

data/lib/name_bank/pool_store.rb

@@ -11,6 +11,10 @@ class NameBank
   # shape against PoolSchema, memoizing them, and listing what a data dir holds.
   # NameBank itself never opens a file. Files are read once per instance, and
   # validated once when read rather than on every pool access.
+  #
+  # Country and variant names are resolved against the directory listing rather
+  # than handed to File.exist?, so the result does not depend on whether the
+  # filesystem happens to be case-sensitive.
   class PoolStore
     def initialize(data_dir)
       @data_dir = data_dir
@@ -28,27 +32,49 @@ class NameBank
     end
 
     def variants(country)
-      @variant_names[country] ||= yml_basenames(File.join(@data_dir, "variants", country))
+      code = resolve(country, variant_countries)
+      return [] if code.nil?
+
+      @variant_names[code] ||= yml_basenames(File.join(@data_dir, "variants", code))
     end
 
     private
 
+    # An exact match wins; otherwise a unique case-insensitive one; otherwise
+    # nil, because guessing between DE and de would be worse than refusing.
+    def resolve(name, candidates)
+      return name if candidates.include?(name)
+
+      hits = matches(name, candidates)
+      hits.size == 1 ? hits.first : nil
+    end
+
+    def matches(name, candidates)
+      candidates.select { |candidate| candidate.casecmp?(name) }
+    end
+
+    # What to put in the error: the name alone when nothing matched, or the
+    # rival spellings when several did.
+    def unresolved(name, candidates)
+      hits = matches(name, candidates)
+      hits.empty? ? name : "#{name} matches #{hits.join(", ")}"
+    end
+
     def country_pools(country)
-      @country_pools[country] ||= begin
-        path = File.join(@data_dir, "countries", "#{country}.yml")
-        raise UnknownCountry, country unless File.exist?(path)
+      code = resolve(country, countries)
+      raise UnknownCountry, unresolved(country, countries) if code.nil?
 
-        read(path)
-      end
+      @country_pools[code] ||= read(File.join(@data_dir, "countries", "#{code}.yml"))
     end
 
     def variant_pools(country, variant)
-      @variant_pools[[country, variant]] ||= begin
-        path = File.join(@data_dir, "variants", country, "#{variant}.yml")
-        raise UnknownVariant, "#{country}/#{variant}" unless File.exist?(path)
+      code = resolve(country, variant_countries)
+      raise UnknownVariant, "#{country}/#{variant}" if code.nil?
 
-        read(path)
-      end
+      name = resolve(variant, variants(code))
+      raise UnknownVariant, "#{country}/#{unresolved(variant, variants(code))}" if name.nil?
+
+      @variant_pools[[code, name]] ||= read(File.join(@data_dir, "variants", code, "#{name}.yml"))
     end
 
     def read(path)
@@ -59,6 +85,16 @@ class NameBank
       data
     end
 
+    def variant_countries
+      @variant_countries ||= subdirectories(File.join(@data_dir, "variants"))
+    end
+
+    def subdirectories(dir)
+      return [] unless Dir.exist?(dir)
+
+      Dir.children(dir).select { |child| File.directory?(File.join(dir, child)) }.sort
+    end
+
     def yml_basenames(dir)
       return [] unless Dir.exist?(dir)
 

data/lib/name_bank/version.rb

@@ -2,5 +2,5 @@
 
 # Declared as a class, not a module: NameBank itself is one (see lib/name_bank.rb).
 class NameBank
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/name_bank.rb

@@ -71,8 +71,9 @@ class NameBank
   end
 
   # The script forms this country offers, not writing systems — see CONTEXT.md.
-  def scripts(country:)
-    data = @store.pools(country, nil)
+  # With a variant, the forms that variant offers, which may differ.
+  def scripts(country:, variant: nil)
+    data = @store.pools(country, variant)
     PoolSchema::KEYS.any? { |k| data[PoolSchema.native_key(k)]&.any? } ? %i[latin native] : %i[latin]
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: name_bank
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Patrick Bartels