fantasy_faker 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b2564d8293a91c1c0572693b78d0a2d472b9bada33506defd0af70015cb7de5f
-  data.tar.gz: '00709549331b1fd21196009a36c9baa8d1c1c497868b5a68320e70b8e5562f30'
+  metadata.gz: 0f0049ad8d6fbde0f3813c16ade4afca229428ad9ab6754914de5a98ae640114
+  data.tar.gz: e66524a426cc3c357511a4537cfbd5b4da7c01b8bb69cd8eda43a07b4c5050c0
 SHA512:
-  metadata.gz: dba61364fc29ce55098bc2610f02c5c993faeb348112acbd20b1de42f3a112f60f7fdec2c78d8f3ef4112c7dbd67480fc2d49edfc43622754174fe26dac85acb
-  data.tar.gz: 6bb6a69246f54fc860840f45e96d80a3d80f52e55dfaf21b775ae036d2d08e57ef2fc9469d6947e9eee5eaa7b5b6ac44c83fce2d83888833790de6b4f2dc7e77
+  metadata.gz: a62d8cbbad60bc9bf5b8e0f868b218d42d57d7ced05cdbb36b701cfdfc310d4ae2796cd2f8f0825e5b72f1484a5863757c95310ecbb5f2fc983ee1c8fd86e610
+  data.tar.gz: 9b25c3b7dc00ddff98d867aece0bda0274db9469766064bb241922fcf1e184103cef7d028b411e234939e62d423ac2979838b4e41e1137921d5b9e3d136f35de

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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.

data/README.md

@@ -50,17 +50,65 @@ 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 generator: `male_first_name`, `female_first_name`,
-`male_nickname`, `female_nickname`, `male_name`, or `female_name`.
+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:
@@ -69,23 +117,39 @@ In FactoryBot (formerly FactoryGirl), use it inside the attribute block:
 factory :character do
   name { FantasyFaker::Character.unique.male_name }
 end
+
+factory :location do
+  name { FantasyFaker::Location.unique.forest }
+end
 ```
 
-Values are tracked separately for each method within the current Ruby process,
-including across locale changes. Ordinary calls without `.unique` are not tracked.
-This does not check existing database records or coordinate separate processes.
+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

@@ -6,8 +6,9 @@ module FantasyFaker
   class UniqueGenerator
     class RetryLimitExceeded < RuntimeError; end
 
-    def initialize(generator)
+    def initialize(generator, &key)
       @generator = generator
+      @key = key
       @previous_results = Hash.new { |results, method| results[method] = Set.new }
     end
 
@@ -20,9 +21,12 @@ module FantasyFaker
     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, ...)
-        return result if @previous_results[method].add?(result)
+        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"

data/lib/fantasy_faker/version.rb

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

data/lib/fantasy_faker.rb

@@ -5,6 +5,7 @@ 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