random-words 1.0.17 → 1.0.20

data/docs/superpowers/specs/2026-10-29-who-dictionary-design.md

@@ -0,0 +1,118 @@
+# Doctor Who (`who`) Dictionary Design
+
+**Date:** 2026-10-29  
+**Status:** Approved for implementation planning  
+**Trigger:** `who` (also `doctorwho`, `tardis`)
+
+## Goal
+
+Add a Doctor Who themed dictionary under `lib/random-words/words/who/`, focused on dialog and characters, discovered like every other source (no generator code changes). Medical `doctor` remains separate and unchanged.
+
+## Decisions
+
+| Topic | Choice |
+|-------|--------|
+| Era | Mostly New Who (2005–present), light Classic sprinkle |
+| Quote density | Medium — solid iconic set; bulk is themed vocabulary |
+| Size | Large (~Walken / 2500+ lines total) |
+| Character weight | Even spread across NuWho Doctors; Classic icons (Fourth Doctor, Sarah Jane, UNIT, etc.) get more of the sprinkle |
+| Approach | Hybrid: names/phrases/clauses carry dialog & characters; nouns/verbs/adjectives supply franchise lexicon bulk |
+
+## Layout
+
+New directory mirroring existing dictionaries:
+
+```
+lib/random-words/words/who/
+  config.yml
+  adjectives.txt
+  adverbs.txt
+  articles-plural.txt
+  articles-singular.txt
+  clauses.txt
+  conjunctions-coordinating.txt
+  conjunctions-subordinate.txt
+  names.txt
+  nouns-plural.txt
+  nouns-singular.txt
+  numbers.yml
+  phrases.txt
+  prepositions.txt
+  terminators.txt
+  verbs-passive.txt
+  verbs-plural.txt
+  verbs-singular.txt
+```
+
+### config.yml
+
+```yaml
+---
+name: who
+description: Doctor Who (New Who-forward, Classic sprinkle)
+triggers: [who, doctorwho, tardis]
+```
+
+No changes to `generator.rb` or other Ruby sources; dictionaries are loaded by directory name / triggers.
+
+## Content design
+
+### names.txt (~80–120)
+
+Sentence-friendly character labels:
+
+- NuWho Doctors: Ninth through Fifteenth, The Doctor, War Doctor
+- Companions across NuWho (Rose, Martha, Donna, Amy, Rory, Clara, Bill, Yaz, Dan, Ruby, and peers)
+- Villains and monsters: Master / Missy, Daleks, Cybermen, Weeping Angels, Silence, and similar
+- Classic sprinkle: Fourth Doctor, Sarah Jane, Brigadier, UNIT, K-9
+
+Prefer names that work as subjects (`Rose Tyler`, `The Doctor`, `Donna Noble`) over actor names.
+
+### phrases.txt (~50–70)
+
+Recognizable lines and catchphrases without becoming a quote dump. Mix Doctor catchphrases, companion beats, monster slogans, and a few Classic classics (e.g. jelly babies, Exterminate!).
+
+### clauses.txt (~180–250)
+
+Show-voice fragments used as clause inserts: TARDIS arrivals, regenerations, Dalek/Cyberman threats, timey-wimey explanations, companion loyalty, UNIT briefings. First- and third-person mix (Walken-style), Who-flavored.
+
+### Lexicon bulk (Walken-scale)
+
+| File | Target | Focus |
+|------|--------|--------|
+| nouns-singular | ~400–500 | TARDIS, sonic screwdriver, regeneration, Gallifrey, Skaro, vortex, paradox, Time Lord, species, tech, places |
+| nouns-plural | ~300–400 | Matching plurals |
+| verbs-singular / verbs-plural | ~250–300 each | regenerate, dematerialize, exterminate, travel, warn, convert, reverse… |
+| verbs-passive | ~200–350 | was regenerated by, was converted by, was chased by… |
+| adjectives | ~130–200 | timey-wimey, ancient, doomed, brilliant, impossible… |
+| adverbs | ~130–200 | suddenly, brilliantly, bravely, paradoxically… |
+
+Tone: adventurous, ominous, witty. Not medical vocabulary.
+
+### Structural files
+
+Articles, coordinating/subordinate conjunctions, prepositions, terminators, and `numbers.yml` copied from `english` or `walken` with little or no Who flavor (same pattern as other themed dictionaries).
+
+### Size target
+
+Roughly **2500+ lines** across all word files combined.
+
+## Out of scope
+
+- Changes to sentence templates or generator logic
+- Renaming or altering the medical `doctor` dictionary
+- Torchwood / Sarah Jane Adventures as full separate dictionaries (individual characters may appear in `names` where familiar)
+- Exhaustive quote catalogs or copyrighted script dumps beyond short iconic phrases
+
+## Verification
+
+1. `RandomWords::Generator.new(:who)` initializes without error
+2. Trigger aliases (`who`, `doctorwho`, `tardis`) resolve to this source
+3. Sample sentences/paragraphs feel Who-themed (characters, tech, dialog fragments appear)
+4. Line counts land near the targets above (especially names/phrases/clauses and noun/verb bulk)
+
+## Implementation notes
+
+- Reuse structural lists from `english`/`walken` to avoid reinventing grammar glue
+- Prefer franchise-common terms over obscure one-off episode props unless they are culturally iconic
+- Keep singular/plural and singular/plural verb pairs consistent where both files exist

data/lib/random-words/config.rb

@@ -39,6 +39,7 @@ module RandomWords
     # @raise [RuntimeError] if no dictionary is found for the given language
     def initialize(lang)
       @lang = lang.to_s
+      @requested_lang = lang.to_s # Store the requested language
       FileUtils.mkdir_p(config_dir) unless File.directory?(config_dir)
 
       @source_dir = user_dictionary_exist? ? user_lang_dir : builtin_lang_dir
@@ -222,13 +223,19 @@ module RandomWords
       config_file = File.join(config_dir, 'config.yml')
       if File.exist?(config_file)
         config = YAML.load_file(config_file).symbolize_keys
-        return handle_config(config)
+        config_hash = handle_config(config)
+        # Override with the language passed to initialize
+        config_hash[:source] = @requested_lang.to_sym if @requested_lang
+        return config_hash
       end
       # If the config file doesn't exist, create it
       # and return the default configuration
       create_base_config(config_file)
       config = YAML.load_file(config_file).symbolize_keys
-      handle_config(config)
+      config_hash = handle_config(config)
+      # Override with the language passed to initialize
+      config_hash[:source] = @requested_lang.to_sym if @requested_lang
+      config_hash
     end
 
     # Look for a config.yml file in the config directory

data/lib/random-words/generator.rb

@@ -39,6 +39,58 @@ module RandomWords
     # These parts will be used to generate random sentences and character strings
     SENTENCE_PARTS = %w[random_article random_adjective random_noun random_adverb random_verb random_adjective
                         random_verb random_adverb random_phrase].freeze
+    TEMPLATES = [
+      # Simple declarative
+      %i[random_article random_adjective random_noun random_verb],
+      %i[random_plural_article random_adjective random_plural_noun random_plural_verb],
+
+      # With adverb
+      %i[random_article random_adjective random_noun random_adverb random_verb],
+      %i[random_name random_adverb random_verb],
+
+      # Passive voice
+      %i[random_article random_noun random_passive_verb random_preposition random_article random_noun],
+
+      # With prepositional phrase
+      %i[random_article random_adjective random_noun random_verb random_preposition random_article random_noun],
+
+      # Compound sentence
+      %i[random_article random_noun random_verb random_coordinating_conjunction random_article random_noun random_verb],
+
+      # Subordinate clause
+      %i[random_clause random_article random_noun random_verb],
+
+      # With phrase
+      %i[random_phrase],
+
+      # Name as subject
+      %i[random_name random_verb random_article random_noun],
+
+      # Plural with adverb and preposition
+      %i[random_plural_article random_plural_noun random_adverb random_plural_verb random_preposition random_article random_noun],
+
+      # Coordinating conjunction joining two clauses
+      %i[random_article random_noun random_verb random_coordinating_conjunction random_plural_article random_plural_noun random_plural_verb
+         random_phrase],
+
+      # Subordinate conjunction
+      %i[random_subordinate_conjunction random_article random_noun random_verb random_article random_noun random_verb],
+
+      # With random_adjective and random_adverb in various places
+      %i[random_adverb random_article random_adjective random_noun random_verb],
+      %i[random_article random_noun random_verb random_adverb],
+
+      # Name with phrase
+      %i[random_name random_verb random_phrase],
+
+      # Plural passive
+      %i[random_plural_article random_plural_noun random_passive_verb random_preposition random_article random_noun],
+
+      # Name with subordinate clause
+      %i[random_name random_verb random_subordinate_conjunction random_article random_noun random_verb]
+    ].freeze
+
+    OPTIONAL_PARTS = %i[adjectives adverbs].freeze
 
     # Initialize the generator with a source and options
     # @param source [Symbol] The source of the words (e.g., :english)
@@ -649,13 +701,14 @@ module RandomWords
 
     # Generate a random set of separators
     def random_separators
-      [',', ',', ',', ';', ':', ' —']
+      [',', ',', ',', ';', ':']
     end
 
     # Generate a random separator
     # @return [String] A randomly selected separator
     def random_separator
-      "#{dbg('SEP')}#{random_separators.sample}"
+      sep = random_separators.sample
+      "#{dbg('SEP')}#{sep}"
     end
 
     # Generate a random subordinate conjunction
@@ -726,18 +779,16 @@ module RandomWords
                     "#{random_number_with_plural} #{random_adverb} #{random_plural_verb}"
                   when 4..5
                     random_name
-                  when 6..7
-                    noun = random_noun
-                    "#{random_adverb}, #{random_article_for_word(noun)} #{noun} #{random_verb}"
+                  when 6
+                    "#{random_adverb}, #{random_article_for_word(random_noun)} #{random_noun} #{random_verb}"
                   else
-                    noun = random_noun
-                    adjective = random_adjective
-                    "#{random_article_for_word(adjective)} #{adjective} #{noun} #{random_adverb} #{random_verb}"
+                    TEMPLATES.sample.map { |part| send(part.to_sym) }.join(' ')
                   end
       tail = roll(50) ? " #{random_prepositional_phrase}" : ''
       separator = random_separator
+
       tail += roll(10) ? "#{separator} #{random_clause}" : ''
-      "#{beginning.strip.sub(/[#{Regexp.escape(separator)}]*$/, separator)}#{tail}"
+      "#{beginning.strip.sub(/([#{Regexp.escape(separator)}]|#{Regexp.escape(separator)})*$/, separator)}#{tail}"
     end
 
     # Simplified generate_additional_clauses

data/lib/random-words/version.rb

@@ -1,4 +1,4 @@
 module RandomWords
   # The version of the RandomWords gem.
-  VERSION = '1.0.17'
+  VERSION = '1.0.20'
 end

data/lib/random-words/words/1984/articles-singular.txt

@@ -1,5 +1,3 @@
-a
-an
 the
 each
 every

data/lib/random-words/words/alice/articles-singular.txt

@@ -1,5 +1,3 @@
-a
-an
 the
 each
 every

data/lib/random-words/words/bacon/articles-singular.txt

@@ -1,5 +1,3 @@
-a
-an
 the
 each
 every

data/lib/random-words/words/corporate/articles-singular.txt

@@ -1,5 +1,3 @@
-a
-an
 the
 each
 every

data/lib/random-words/words/doctor/articles-singular.txt

@@ -1,5 +1,3 @@
-a
-an
 the
 each
 every

data/lib/random-words/words/english/articles-singular.txt

@@ -1,5 +1,3 @@
-a
-an
 the
 each
 every

data/lib/random-words/words/foulmouth/articles-singular.txt

@@ -1,5 +1,3 @@
-a
-an
 the
 each
 every

data/lib/random-words/words/hipster/articles-singular.txt

@@ -1,5 +1,3 @@
-a
-an
 the
 each
 every

data/lib/random-words/words/veggie/articles-singular.txt

@@ -1,5 +1,3 @@
-a
-an
 the
 each
 every

data/lib/random-words/words/walken/articles-singular.txt

@@ -1,5 +1,3 @@
-a
-an
 the
 each
 every

data/lib/random-words/words/who/adjectives.txt

@@ -0,0 +1,199 @@
+abandoned
+alien
+ancient
+angry
+arcane
+armoured
+astonishing
+atomic
+bewildering
+bizarre
+bold
+brave
+bright
+brilliant
+broken
+brutal
+cautious
+celestial
+chaotic
+clever
+cold
+colossal
+confused
+corrupted
+cosmic
+crafty
+crumbling
+cryptic
+curious
+cybernetic
+dangerous
+dark
+dazzling
+deadly
+defiant
+desperate
+destroyed
+devious
+dimensional
+distant
+doomed
+dormant
+dreadful
+dusty
+eccentric
+eerie
+electric
+elusive
+empty
+endless
+enormous
+eternal
+exiled
+exploding
+fantastic
+fearless
+ferocious
+fierce
+fiery
+fixed
+flickering
+foolish
+forbidden
+forgotten
+fractured
+frantic
+frozen
+furious
+future
+galactic
+gallifreyan
+ghostly
+gigantic
+glittering
+gloomy
+golden
+gorgeous
+grim
+haunted
+heroic
+hidden
+hollow
+hostile
+humble
+hungry
+hypnotic
+icy
+immortal
+impossible
+incredible
+infinite
+insane
+intergalactic
+invisible
+irresistible
+last
+lethal
+lonely
+lost
+luminous
+mad
+magnificent
+malevolent
+massive
+menacing
+metallic
+mighty
+mischievous
+monstrous
+mysterious
+nervous
+noble
+notorious
+obsolete
+ominous
+orbital
+ordinary
+outlandish
+paradoxical
+peculiar
+perilous
+persistent
+phantom
+planetary
+playful
+poisonous
+powerful
+primitive
+proud
+puzzling
+quantum
+quiet
+radiant
+rampant
+rebellious
+reckless
+relentless
+remarkable
+restless
+reversed
+rogue
+ruined
+rusty
+sacred
+savage
+scarred
+secret
+sentient
+shadowy
+shattered
+shimmering
+silent
+sinister
+sleepless
+slippery
+solitary
+sonic
+spectacular
+spooky
+stalwart
+stellar
+stolen
+strange
+stubborn
+sudden
+supreme
+suspicious
+temporal
+terrible
+terrifying
+thrilling
+timeless
+timey-wimey
+tireless
+tough
+treacherous
+tricky
+trusty
+twisted
+unbreakable
+undaunted
+unearthly
+unexpected
+unknown
+unstoppable
+vanishing
+vast
+vengeful
+vicious
+vigilant
+villainous
+wandering
+weary
+weeping
+wibbly-wobbly
+wicked
+wild
+wise
+wonderful

data/lib/random-words/words/who/adverbs.txt

@@ -0,0 +1,175 @@
+abruptly
+adventurously
+angrily
+anxiously
+awkwardly
+bitterly
+blindly
+boldly
+bravely
+brightly
+brilliantly
+brutally
+calmly
+carefully
+cautiously
+chaotically
+cheerfully
+cleverly
+coldly
+confidently
+cosmically
+courageously
+craftily
+cruelly
+curiously
+cynically
+dangerously
+daringly
+darkly
+dauntlessly
+deadly
+defiantly
+deliberately
+desperately
+determinedly
+devilishly
+diligently
+dramatically
+dreadfully
+eagerly
+eerily
+elegantly
+endlessly
+eternally
+excitedly
+fearlessly
+ferociously
+fiercely
+foolishly
+forever
+fortunately
+frantically
+furiously
+gallantly
+gently
+gleefully
+gloomily
+gracefully
+gravely
+grimly
+happily
+hastily
+heroically
+hopefully
+hopelessly
+hurriedly
+hysterically
+ignorantly
+immediately
+impatiently
+impossibly
+incessantly
+incredibly
+innocently
+instantly
+intensely
+irresistibly
+jauntily
+joyfully
+keenly
+kindly
+lazily
+loudly
+loyally
+madly
+magnificently
+mercilessly
+mischievously
+mysteriously
+nervously
+nimbly
+nobly
+obstinately
+oddly
+ominously
+openly
+paradoxically
+patiently
+perilously
+playfully
+politely
+powerfully
+promptly
+proudly
+quickly
+quietly
+rapidly
+rashly
+recklessly
+relentlessly
+reluctantly
+remarkably
+repeatedly
+resolutely
+restlessly
+ridiculously
+rudely
+ruthlessly
+sadly
+safely
+savagely
+secretly
+selflessly
+sensibly
+shamelessly
+sharply
+shrewdly
+silently
+sleepily
+slowly
+smartly
+smoothly
+softly
+solemnly
+solidly
+spectacularly
+speedily
+splendidly
+steadily
+stealthily
+strangely
+stubbornly
+suddenly
+suspiciously
+swiftly
+tenderly
+terribly
+theatrically
+thoroughly
+thoughtfully
+tirelessly
+tragically
+treacherously
+triumphantly
+truly
+uncannily
+unexpectedly
+unfortunately
+unwisely
+urgently
+vaguely
+valiantly
+vengefully
+viciously
+vigilantly
+violently
+warily
+wearily
+wickedly
+wildly
+wisely
+wistfully
+wonderfully
+worriedly
+zealously

data/lib/random-words/words/who/articles-plural.txt

@@ -0,0 +1,10 @@
+all
+either
+few
+many
+several
+some
+these
+those
+three
+two