fantasy_faker 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: babf067689eb2d336f310659e548a6e4bd91cb3526adc40123b16c057f052590
-  data.tar.gz: 44d2c5e41e728adfd32654050608fb506ad3c0a87d9f7b9107cd83d3bf33a71f
+  metadata.gz: 0f0049ad8d6fbde0f3813c16ade4afca229428ad9ab6754914de5a98ae640114
+  data.tar.gz: e66524a426cc3c357511a4537cfbd5b4da7c01b8bb69cd8eda43a07b4c5050c0
 SHA512:
-  metadata.gz: 74493db82cf1d264d9217350c3dd75496ecc46899396426050d24abfa82ddffb42f0ee3494b71b37b5a109b37937d09e2d0ea9443155dc34f9163feb3c655ace
-  data.tar.gz: 3ccd876fa0ef30915fd0199285cdb8b08feb7358f24e01305163926f21fa0084798a3cc0f8f809f2bf9f096013473b23238306db5cc117346fcbb48edf44ba43
+  metadata.gz: a62d8cbbad60bc9bf5b8e0f868b218d42d57d7ced05cdbb36b701cfdfc310d4ae2796cd2f8f0825e5b72f1484a5863757c95310ecbb5f2fc983ee1c8fd86e610
+  data.tar.gz: 9b25c3b7dc00ddff98d867aece0bda0274db9469766064bb241922fcf1e184103cef7d028b411e234939e62d423ac2979838b4e41e1137921d5b9e3d136f35de

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.4.0 - November 11, 2026
+
+- Add `FantasyFaker::Location` with 16 location categories and a general-purpose `.name` generator.
+- Add a shared pool of 1,000 invented location names, with English and Polish landmark templates and dark fantasy prefixes and suffixes.
+- Share location `.unique` history across all categories, `.name`, and locales, reserving the proper name regardless of decorative variants; keep character uniqueness unchanged.
+- Add `FantasyFaker::Location.unique.clear` to reset the shared location history.
+
+## 0.3.0 - October 24, 2026
+
+- Add `.unique` to all character name and nickname generators, with per-method tracking across locale changes.
+- Raise `FantasyFaker::UniqueGenerator::RetryLimitExceeded` after 10,000 unsuccessful attempts to generate a new value.
+- Add `FantasyFaker::Character.unique.clear` to reset uniqueness tracking.
+
 ## 0.2.0 - October 21, 2026
 
 - Expand the first-name dictionaries from 2,499 to 5,040 distinct male names and from 1,380 to 2,795 distinct female names.

data/README.md

@@ -50,13 +50,106 @@ FantasyFaker.use_locale(:pl) do
 end
 ```
 
+### Locations
+
+`FantasyFaker::Location` uses a shared pool of 1,000 invented proper names across
+16 categories, with English (`:en`) and Polish (`:pl`) landmark descriptions:
+
+Cities return the proper name alone. Other categories combine it with a localized
+landmark type and optional prefixes or suffixes, mixing neutral and dark fantasy styles:
+`Alador Forest`, `Dark Alador Forest`, `Las Alador` or `Puszcza Alador Czarnych Cierni`.
+Proper names are shared between locales; changing language changes the description,
+not the underlying proper-name pool.
+
+| Method | Category |
+| --- | --- |
+| `city` | Cities |
+| `sewer` | Urban sewers |
+| `meadow` | Meadows and wetlands |
+| `forest` | Forests |
+| `swamp` | Swamps |
+| `waters` | Rivers and lakes |
+| `desert` | Deserts and dunes |
+| `cave` | Caves |
+| `mine` | Mines |
+| `mountain` | Mountains |
+| `volcanic_field` | Volcanic fields |
+| `ruins` | Ruins |
+| `stronghold` | Strongholds |
+| `graveyard` | Graveyards |
+| `abandoned_monastery` | Abandoned monasteries |
+| `labyrinth_or_arena` | Labyrinths and arenas |
+
+Use `name` to choose a random category and generate a name from it:
+
+```ruby
+FantasyFaker::Location.city # => "Alador"
+FantasyFaker::Location.forest # => "Dark Alador Forest"
+FantasyFaker::Location.name # => a name from any location category
+
+FantasyFaker.use_locale(:pl) do
+  FantasyFaker::Location.city # => "Alador"
+  FantasyFaker::Location.forest # => "Mroczny Las Alador"
+  FantasyFaker::Location.waters # => "Jezioro Alador Zatopionych Dzwonów"
+end
+```
+
+### Unique values
+
+Use `.unique` with any character or location generator.
+
+```ruby
+FantasyFaker::Character.unique.male_name
+FantasyFaker::Character.unique.female_nickname
+FantasyFaker::Location.unique.city
+FantasyFaker::Location.unique.name
+
+# Reset all character generators' uniqueness history (for example, between tests)
+FantasyFaker::Character.unique.clear
+
+# Location history is separate from character history
+FantasyFaker::Location.unique.clear
+```
+
+In FactoryBot (formerly FactoryGirl), use it inside the attribute block:
+
+```ruby
+factory :character do
+  name { FantasyFaker::Character.unique.male_name }
+end
+
+factory :location do
+  name { FantasyFaker::Location.unique.forest }
+end
+```
+
+Character generators track values separately for each method. Location generators share
+one proper-name history across **all categories, `.name`, and both locales**. For example,
+after `.unique.city` returns `Alador`, no other unique location generator can return
+`Las Alador`, `Dark Alador Forest` or any other variant containing that proper name.
+Prefixes and suffixes do not count as new proper names.
+
+Character and location histories are separate. Ordinary calls without `.unique` are not
+tracked and can still reuse names. Tracking happens within the current Ruby process;
+it does not check existing database records or coordinate separate processes.
+
+If no new value is found after 10,000 attempts, generation raises
+`FantasyFaker::UniqueGenerator::RetryLimitExceeded` rather than returning a duplicate.
+Because generation is random, this can happen before every possible value has been used.
+The shared location pool contains 1,000 proper names in total, not 1,000 per category
+or language. Use `FantasyFaker::Location.unique.clear` between tests when names can be reused;
+this resets the history for all location categories at once.
+
 ## Development
 
 Dictionary data is stored in YAML files under `locales/`:
-- `locales/common.yml`: language-independent lists (e.g. name prefixes and suffixes), grouped by module name (`character:`)
+- `locales/common.yml`: language-independent character name components (`character:`) and location proper names (`location:`)
 - `locales/en/<module>.yml`: English entries for a module
 - `locales/pl/<module>.yml`: Polish entries for a module
 
+Location locale files contain templates with a single `%{name}` placeholder, including
+neutral landmark types and dark fantasy prefixes and suffixes.
+
 ```sh
 bundle install
 bundle exec rspec

data/lib/fantasy_faker/location.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module FantasyFaker
+  module Location
+    extend BaseModule
+    extend self
+
+    CATEGORIES = %i[
+      city sewer meadow forest swamp waters desert cave mine mountain volcanic_field
+      ruins stronghold graveyard abandoned_monastery labyrinth_or_arena
+    ].freeze
+
+    CATEGORIES.each do |category|
+      define_method(category) { fetch_data(category).rand % { name: fetch_data(:proper_names).rand } }
+    end
+
+    def unique
+      @unique_generator ||= begin
+        proper_name = /\b#{Regexp.union(fetch_data(:proper_names))}\b/
+        UniqueGenerator.new(self) { |name| name[proper_name] }
+      end
+    end
+
+    def name
+      public_send(CATEGORIES.sample)
+    end
+  end
+end

data/lib/fantasy_faker/unique_generator.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module FantasyFaker
+  class UniqueGenerator
+    class RetryLimitExceeded < RuntimeError; end
+
+    def initialize(generator, &key)
+      @generator = generator
+      @key = key
+      @previous_results = Hash.new { |results, method| results[method] = Set.new }
+    end
+
+    def clear
+      @previous_results.clear
+    end
+
+    private
+
+    def method_missing(method, ...)
+      return super unless @generator.respond_to?(method)
+
+      # Custom keys identify values across methods, not within one method.
+      previous_results = @previous_results[@key ? nil : method]
+      10_000.times do
+        result = @generator.public_send(method, ...)
+        key = @key ? @key.call(result) : result
+        return result if previous_results.add?(key)
+      end
+
+      raise RetryLimitExceeded, "Unable to generate a unique #{method} after 10,000 attempts"
+    end
+
+    def respond_to_missing?(method, include_private = false)
+      @generator.respond_to?(method) || super
+    end
+  end
+end

data/lib/fantasy_faker/utils/base_module.rb

@@ -5,6 +5,10 @@ require_relative 'array_utils'
 
 module FantasyFaker
   module BaseModule
+    def unique
+      @unique_generator ||= UniqueGenerator.new(self)
+    end
+
     def const_missing(const_name)
       fetch_data(const_name)
     end

data/lib/fantasy_faker/version.rb

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

data/lib/fantasy_faker.rb

@@ -2,8 +2,10 @@
 
 require_relative 'fantasy_faker/version'
 require_relative 'fantasy_faker/utils/array_utils'
+require_relative 'fantasy_faker/unique_generator'
 require_relative 'fantasy_faker/utils/base_module'
 require_relative 'fantasy_faker/character'
+require_relative 'fantasy_faker/location'
 
 module FantasyFaker
   DEFAULT_LOCALE = :en